@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/adapters/codex/reader.ts

@@ -0,0 +1,747 @@
+import { closeSync, openSync, readFileSync, readSync } from "node:fs"
+import { join } from "node:path"
+import { exists, findFiles, gitInfo, ls, mtime, readJson } from "../../fsutil.ts"
+import { keepImage, parseDataUrl } from "../../session/attachments.ts"
+import type { Attachment, Project, Session, SessionHeader, Turn, Usage } from "../../session/types.ts"
+import { clip, header, iso, lossCounter, noteModel, toolKindOf } from "../../session/util.ts"
+import { withSnapshot } from "../../sqlite.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { summaryBody } from "./native.ts"
+import { IMPORT_MARKER, LABEL, TOOL, idFromName, isContext, isImageLabel, isRolloutName, outputText, patchFiles } from "./records.ts"
+
+// Codex CLI sessions. Each thread is a rollout under ~/.codex/sessions/YYYY/MM/DD (archived ones under
+// archived_sessions/), one JSON record per line: {timestamp, ordinal?, type, payload}, starting with
+// session_meta. The model-visible history is the response_item stream; event_msg is what the UI showed
+// and mostly repeats it (user_message/agent_message in legacy rollouts, item_completed in 0.147's
+// paginated ones), so events become turns only when no response_item carries the same text. Cold
+// rollouts may be zstd-compressed (.jsonl.zst); very old sessions are single .json files. Titles live
+// only in the state_*.sqlite threads index, read through a snapshot.
+
+type Row = Record<string, any>
+
+const codexDir = (home: string) => join(home, ".codex")
+
+/** Records that hold no conversation: bookkeeping Codex needs to resume, not content. */
+const QUIET_RECORDS = new Set([
+  "world_state",
+  "inter_agent_communication_metadata",
+  "dynamic_tools_updated",
+  "token_usage_record",
+  "security_risk_score",
+  "retained_context",
+  "realtime_item",
+])
+
+/** Event types that repeat response items for the UI or carry no content (EventMsg in protocol.rs, plus older names). */
+const KNOWN_EVENTS = new Set(
+  (
+    "error warning guardian_warning realtime_conversation_started realtime_conversation_realtime realtime_conversation_closed " +
+    "realtime_conversation_sdp realtime_conversation_list_voices_response model_reroute model_verification turn_moderation_metadata " +
+    "safety_buffering context_compacted thread_rolled_back task_started turn_started thread_settings_applied task_complete " +
+    "turn_complete token_count agent_message user_message agent_reasoning agent_reasoning_raw_content agent_reasoning_section_break " +
+    "session_configured environment_connected environment_disconnected thread_goal_updated mcp_startup_update mcp_startup_complete " +
+    "mcp_tool_call_begin mcp_tool_call_end web_search_begin web_search_end image_generation_begin image_generation_end " +
+    "exec_command_begin exec_command_output_delta terminal_interaction exec_command_end view_image_tool_call exec_approval_request " +
+    "request_permissions request_user_input dynamic_tool_call_request dynamic_tool_call_response elicitation_request " +
+    "apply_patch_approval_request guardian_assessment deprecation_notice stream_error patch_apply_begin patch_apply_updated " +
+    "patch_apply_end turn_diff plan_update turn_aborted shutdown_complete entered_review_mode exited_review_mode raw_response_item " +
+    "raw_response_completed item_started item_completed hook_started hook_completed agent_message_content_delta plan_delta " +
+    "reasoning_content_delta reasoning_raw_content_delta collab_agent_spawn_begin collab_agent_spawn_end " +
+    "collab_agent_interaction_begin collab_agent_interaction_end collab_waiting_begin collab_waiting_end collab_close_begin " +
+    "collab_close_end collab_resume_begin collab_resume_end sub_agent_activity background_event agent_message_delta " +
+    "agent_reasoning_delta agent_reasoning_raw_content_delta"
+  ).split(" "),
+)
+
+const str = (v: unknown) => (typeof v === "string" && v ? v : undefined)
+const norm = (s: string) => s.replace(/\s+/g, " ").trim()
+
+/** How a user message is matched with its event copy: by its text, or, for a pasted image with no text, as such. */
+const IMAGE_ONLY = "\u0000image-only message"
+const userKey = (text: string | undefined, images: number) => (text?.trim() ? text : images ? IMAGE_ONLY : undefined)
+
+/** The readable texts of a reasoning item: its summary parts and its raw content parts (open-weight models). */
+function reasoningParts(p: Row): { summary: string[]; raw: string[] } {
+  const texts = (v: unknown) => (Array.isArray(v) ? v : []).map((s: Row) => s?.text).filter((s): s is string => typeof s === "string" && !!s.trim())
+  return { summary: texts(p.summary), raw: texts(p.content) }
+}
+
+/** A multiset of texts: what the response items already said, so repeated events are skipped once each. */
+function textBag() {
+  const m = new Map<string, number>()
+  return {
+    add(s: string) {
+      const k = norm(s)
+      if (k) m.set(k, (m.get(k) ?? 0) + 1)
+    },
+    take(s: string): boolean {
+      const k = norm(s)
+      const n = m.get(k) ?? 0
+      if (n > 0) m.set(k, n - 1)
+      return n > 0
+    },
+  }
+}
+
+function parseLines(text: string): { rows: Row[]; bad: number } {
+  const rows: Row[] = []
+  let bad = 0
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue
+    try {
+      const v = JSON.parse(line)
+      if (v && typeof v === "object") rows.push(v)
+      else bad++
+    } catch {
+      bad++
+    }
+  }
+  return { rows, bad }
+}
+
+/** Text parts of a message's content, without Codex's context fragments and image labels. */
+function messageParts(content: unknown): { text?: string; images: number; context: number; files: Attachment[] } {
+  const parts: Row[] = Array.isArray(content) ? content : typeof content === "string" ? [{ type: "input_text", text: content }] : []
+  const texts: string[] = []
+  let images = 0
+  let context = 0
+  const files: Attachment[] = []
+  for (const p of parts) {
+    if (p?.type === "input_image" || p?.type === "image" || p?.type === "local_image") {
+      images++
+      const d = parseDataUrl(p.image_url)
+      const kept = d ? keepImage(d.base64, d.mime) : undefined
+      if (kept) files.push(kept)
+    }
+    else if (typeof p?.text === "string") {
+      if (isContext(p.text)) context++
+      else if (!isImageLabel(p.text)) texts.push(p.text)
+    }
+  }
+  return { ...(texts.length ? { text: texts.join("\n") } : {}), images, context, files }
+}
+
+function parseArgs(args: unknown): unknown {
+  if (typeof args !== "string") return args ?? {}
+  try {
+    return JSON.parse(args)
+  } catch {
+    return args
+  }
+}
+
+function addUsage(a: Usage | undefined, b: Usage): Usage {
+  if (!a) return { ...b }
+  const out: Usage = {}
+  for (const k of ["input", "output", "cacheRead", "cacheWrite"] as const) {
+    const v = (a[k] ?? 0) + (b[k] ?? 0)
+    if (a[k] !== undefined || b[k] !== undefined) out[k] = v
+  }
+  return out
+}
+
+/**
+ * Builds the portable turns from Codex items in order. Shared by rollouts and legacy .json sessions, which
+ * hold the same response items (or, in the oldest files, Chat-Completions-style messages).
+ */
+function builder(h: SessionHeader) {
+  const turns: Turn[] = []
+  const lost = lossCounter()
+  const said = { user: textBag(), assistant: textBag(), reasoning: textBag() }
+  let model: string | undefined
+  let generated = 0
+  /** Calls still waiting for a result, for outputs that carry no call id. */
+  const pending: Array<{ id: string; name: string }> = []
+  /** File edits read from an apply_patch, placed after the call's result. */
+  const edits = new Map<string, Array<Extract<Turn, { kind: "file_edit" }>>>()
+  /** Calls whose edits came from patch_apply_end events: several events of one call add up. */
+  const editsFromEvents = new Set<string>()
+  /** Calls that an event says failed or were declined: the outputs themselves carry only text. */
+  const failed = new Set<string>()
+  /** Assistant turns since the last token count, and usage counted before any assistant text. */
+  let lastAssistant = -1
+  let unassigned: Usage | undefined
+  let lastTotal: number | undefined
+
+  const at = (t: string | undefined) => (t ? { at: t } : {})
+
+  function user(text: string | undefined, when: string | undefined, images = 0, files: Attachment[] = []) {
+    if (!text?.trim() && !images) return
+    if (images > files.length) lost.add("images", images - files.length)
+    const attachments: Attachment[] = [...files, ...Array.from({ length: Math.max(0, images - files.length) }, () => ({ kind: "image" as const }))]
+    turns.push({ kind: "user", ...at(when), text: text ?? "", ...(attachments.length ? { attachments } : {}) })
+  }
+
+  function assistant(text: string | undefined, when: string | undefined) {
+    if (!text?.trim()) return
+    const t: Extract<Turn, { kind: "assistant" }> = { kind: "assistant", ...at(when), text, ...(model ? { model } : {}) }
+    if (unassigned) {
+      t.usage = unassigned
+      unassigned = undefined
+    }
+    turns.push(t)
+    lastAssistant = turns.length - 1
+  }
+
+  function reasoning(text: string | undefined, when: string | undefined) {
+    if (text?.trim()) turns.push({ kind: "reasoning", ...at(when), text })
+  }
+
+  function call(id: string | undefined, name: string, input: unknown, when: string | undefined, namespace?: string) {
+    const callId = id ?? `codex-call-${++generated}`
+    // A namespaced tool (spawn_agent in "collaboration", an MCP tool in "mcp__server") is known by its
+    // namespace when its own name says nothing. The portable record has no place for the namespace itself.
+    let toolKind = toolKindOf(name)
+    if (namespace) {
+      if (toolKind === "other") toolKind = toolKindOf(namespace)
+      lost.add("tool namespaces (not carried)")
+    }
+    turns.push({ kind: "tool_call", ...at(when), id: callId, name, toolKind, input })
+    pending.push({ id: callId, name })
+    // apply_patch is how Codex edits files: freeform input (custom tool) or {input} (function tool).
+    const patch = typeof input === "string" ? input : typeof (input as Row)?.input === "string" ? (input as Row).input : undefined
+    if (name === "apply_patch" && patch) {
+      edits.set(callId, patchFiles(patch).map((f) => ({ kind: "file_edit", ...at(when), path: f.path, patch: f.patch, callId })))
+    }
+    return callId
+  }
+
+  function result(id: string | undefined, raw: unknown, when: string | undefined, name?: string) {
+    let callId = id
+    if (!callId) {
+      // An output without an id answers the latest open call of its kind.
+      const open = [...pending].reverse().find((p) => !name || p.name === name)
+      callId = open?.id ?? `codex-result-${++generated}`
+    }
+    const i = pending.findIndex((p) => p.id === callId)
+    if (i >= 0) pending.splice(i, 1)
+    const out = outputText(raw)
+    const ok = out.ok && !failed.has(callId)
+    if (out.images) lost.add("images in tool results", out.images)
+    const c = clip(out.text)
+    turns.push({ kind: "tool_result", ...at(when), callId, ok, output: c.text, ...(c.truncated ? { truncated: true } : {}) })
+    const fe = edits.get(callId)
+    if (fe) {
+      // A patch that was rejected or did not verify changed nothing.
+      if (ok) turns.push(...fe)
+      edits.delete(callId)
+    }
+  }
+
+  /** The file edits in a patch_apply_end's `changes`, which is how Codex records what an apply_patch changed, whatever tool ran it. */
+  function changeEdits(changes: Row, callId: string, when: string | undefined): Array<Extract<Turn, { kind: "file_edit" }>> {
+    const out: Array<Extract<Turn, { kind: "file_edit" }>> = []
+    for (const [path, c] of Object.entries(changes)) {
+      const ch = (c ?? {}) as Row
+      let patch: string | undefined
+      if (ch.type === "update" && typeof ch.unified_diff === "string") patch = `--- a/${path}\n+++ b/${path}\n${ch.unified_diff.replace(/\n$/, "")}`
+      else if ((ch.type === "add" || ch.type === "delete") && typeof ch.content === "string") {
+        const ls = ch.content.replace(/\n$/, "").split("\n")
+        const mark = ch.type === "add" ? "+" : "-"
+        patch = `--- a/${path}\n+++ b/${path}\n@@ ${ch.type === "add" ? `-0,0 +1,${ls.length}` : `-1,${ls.length} +0,0`} @@\n${ls.map((l) => `${mark}${l}`).join("\n")}`
+      }
+      out.push({ kind: "file_edit", ...(when ? { at: when } : {}), path, ...(patch ? { patch } : {}), callId })
+    }
+    return out
+  }
+
+  /** Learns from the events that carry a status (patch_apply_end, mcp_tool_call_end, completed items) which calls failed. */
+  function status(p: Row, when?: string) {
+    const bad = (s: unknown) => s === "failed" || s === "declined"
+    if (p.type === "patch_apply_end" && str(p.call_id)) {
+      if (p.success === false || bad(p.status)) failed.add(p.call_id)
+      // A patch run through exec_command (Codex intercepts it) has no apply_patch call to read the edit from.
+      if (p.changes && typeof p.changes === "object" && (!edits.has(p.call_id) || editsFromEvents.has(p.call_id))) {
+        const fe = changeEdits(p.changes as Row, p.call_id, when)
+        if (fe.length) {
+          edits.set(p.call_id, [...(edits.get(p.call_id) ?? []), ...fe])
+          editsFromEvents.add(p.call_id)
+        }
+      }
+    }
+    if (p.type === "mcp_tool_call_end" && str(p.call_id)) {
+      const r = (p.result ?? {}) as Row
+      if (r.Err !== undefined || r.Ok?.isError === true || r.Ok?.is_error === true) failed.add(p.call_id)
+    }
+    if (p.type === "item_completed") {
+      const it = (p.item ?? {}) as Row
+      const tool = it.type === "FileChange" || it.type === "CommandExecution" || it.type === "McpToolCall"
+      if (tool && str(it.id) && (bad(it.status) || (typeof it.exit_code === "number" && it.exit_code !== 0))) failed.add(it.id)
+    }
+  }
+
+  /** One response item: the model-visible history. */
+  function item(p: Row, when: string | undefined) {
+    switch (p.type) {
+      case "message": {
+        const m = messageParts(p.content)
+        if (p.role === "user") {
+          // A message can hold Codex's context next to what the person typed; only the latter is carried.
+          if (m.context) lost.add("Codex context and instructions (not carried)")
+          if (m.text || m.images) user(m.text, when, m.images, m.files)
+        } else if (p.role === "assistant") {
+          assistant(m.text, when)
+        } else {
+          lost.add("Codex context and instructions (not carried)")
+        }
+        break
+      }
+      case "reasoning": {
+        const { summary, raw } = reasoningParts(p)
+        reasoning((summary.length ? summary : raw).join("\n\n"), when)
+        if (summary.length && raw.length) lost.add("raw reasoning text, its summary kept")
+        if (p.encrypted_content) lost.add("encrypted reasoning")
+        break
+      }
+      case "function_call":
+        call(str(p.call_id), str(p.name) ?? "unknown", parseArgs(p.arguments), when, str(p.namespace))
+        if (Array.isArray(p.encrypted_function_args) && p.encrypted_function_args.length) lost.add("encrypted tool arguments")
+        break
+      case "custom_tool_call":
+        call(str(p.call_id), str(p.name) ?? "unknown", p.input ?? "", when, str(p.namespace))
+        break
+      case "local_shell_call": {
+        const id = call(str(p.call_id), "local_shell", p.action ?? {}, when)
+        // Without a call id no output can answer it; close it so the pair stays whole.
+        if (!str(p.call_id)) result(id, `(local shell call ${str(p.status) ?? "recorded"}; no output was recorded)`, when)
+        break
+      }
+      case "tool_search_call":
+        call(str(p.call_id), "tool_search", p.arguments ?? {}, when)
+        break
+      case "function_call_output":
+      case "custom_tool_call_output":
+        result(str(p.call_id), p.output, when)
+        break
+      case "tool_search_output":
+        result(str(p.call_id), JSON.stringify(p.tools ?? []), when, "tool_search")
+        break
+      case "web_search_call": {
+        // The search results went into the model's context on OpenAI's side and are not in the rollout.
+        const id = call(str(p.id), "web_search", p.action ?? {}, when)
+        result(id, `(web search ${str(p.status) ?? "ran"}; its results are not recorded)`, when)
+        lost.add("web search results")
+        break
+      }
+      case "image_generation_call":
+        lost.add("generated images")
+        break
+      case "compaction":
+      case "compaction_summary":
+      case "context_compaction":
+        lost.add("encrypted compaction state")
+        break
+      case "agent_message":
+        lost.add("messages between agents")
+        break
+      case "additional_tools":
+      case "compaction_trigger":
+        break
+      default:
+        lost.add(`unknown response items: ${String(p.type)}`)
+    }
+  }
+
+  /** Learns what the response items say before the walk, so their event copies are recognised. */
+  function remember(p: Row) {
+    if (p.type === "message") {
+      const m = messageParts(p.content)
+      const key = userKey(m.text, m.images)
+      if (key && p.role === "user") said.user.add(key)
+      if (m.text && p.role === "assistant") said.assistant.add(m.text)
+    } else if (p.type === "reasoning") {
+      // Events repeat a reasoning item part by part (agent_reasoning, agent_reasoning_raw_content) or whole
+      // (item_completed), summary and raw content alike, so every form is matched.
+      const { summary, raw } = reasoningParts(p)
+      for (const parts of [summary, raw]) {
+        for (const s of parts) said.reasoning.add(s)
+        if (parts.length > 1) said.reasoning.add(parts.join("\n\n"))
+      }
+    }
+  }
+
+  function usage(info: Row | null | undefined) {
+    const u = info?.last_token_usage as Row | undefined
+    if (!u) return
+    // The same totals are sometimes reported twice (a rate-limit refresh); count each request once.
+    const total = (info?.total_token_usage as Row | undefined)?.total_tokens
+    if (typeof total === "number" && total === lastTotal) return
+    if (typeof total === "number") lastTotal = total
+    const n = (v: unknown) => (typeof v === "number" ? v : 0)
+    // OpenAI counts cached tokens inside input_tokens; the portable record keeps them apart.
+    const cached = n(u.cached_input_tokens)
+    const step: Usage = { input: Math.max(0, n(u.input_tokens) - cached), output: n(u.output_tokens), cacheRead: cached }
+    if (n(u.cache_write_input_tokens)) step.cacheWrite = n(u.cache_write_input_tokens)
+    const t = turns[lastAssistant]
+    if (lastAssistant >= 0 && t?.kind === "assistant") t.usage = addUsage(t.usage, step)
+    else unassigned = addUsage(unassigned, step)
+    lastAssistant = -1
+  }
+
+  /** One UI event: used only for content no response item carries. */
+  function event(p: Row, when: string | undefined) {
+    switch (p.type) {
+      case "user_message": {
+        const text = str(p.message)
+        const images = (Array.isArray(p.images) ? p.images.length : 0) + (Array.isArray(p.local_images) ? p.local_images.length : 0)
+        const key = userKey(text, images)
+        if (key && said.user.take(key)) break
+        if (text && isContext(text)) break
+        const files = (Array.isArray(p.images) ? p.images : []).flatMap((u: unknown) => {
+          const d = parseDataUrl(u)
+          const kept = d ? keepImage(d.base64, d.mime) : undefined
+          return kept ? [kept] : []
+        })
+        user(text, when, images, files)
+        break
+      }
+      case "agent_message": {
+        const text = str(p.message)
+        if (!text || text === IMPORT_MARKER || said.assistant.take(text)) break
+        assistant(text, when)
+        break
+      }
+      case "agent_reasoning":
+      case "agent_reasoning_raw_content": {
+        const text = str(p.text)
+        if (text && !said.reasoning.take(text)) reasoning(text, when)
+        break
+      }
+      case "item_completed": {
+        const it = (p.item ?? {}) as Row
+        if (it.type === "UserMessage") {
+          const m = messageParts(it.content)
+          const key = userKey(m.text, m.images)
+          if (key && said.user.take(key)) break
+          if (m.text && isContext(m.text)) break
+          user(m.text, when, m.images, m.files)
+        } else if (it.type === "AgentMessage") {
+          const m = messageParts(it.content)
+          if (m.text && m.text !== IMPORT_MARKER && !said.assistant.take(m.text)) assistant(m.text, when)
+        } else if (it.type === "Reasoning") {
+          const texts = (v: unknown) => (Array.isArray(v) ? v : []).filter((s): s is string => typeof s === "string" && !!s.trim())
+          const parts = texts(it.summary_text).length ? texts(it.summary_text) : texts(it.raw_content)
+          const text = parts.join("\n\n")
+          if (text && !said.reasoning.take(text) && !parts.every((s) => said.reasoning.take(s))) reasoning(text, when)
+        }
+        // Other completed items (commands, patches, searches) are UI projections of response items.
+        break
+      }
+      case "token_count":
+        usage(p.info)
+        break
+      case "thread_rolled_back": {
+        // Codex drops the last N user turns from the model's context; so does the portable record.
+        let n = typeof p.num_turns === "number" ? p.num_turns : 0
+        let cut = -1
+        for (let i = turns.length - 1; i >= 0 && n > 0; i--) {
+          if (turns[i]!.kind === "user") {
+            cut = i
+            n--
+          }
+        }
+        if (cut >= 0) {
+          lost.add("turns rolled back in Codex", turns.slice(cut).filter((t) => t.kind === "user").length)
+          turns.splice(cut)
+          lastAssistant = -1
+        }
+        break
+      }
+      default:
+        if (!KNOWN_EVENTS.has(p.type)) lost.add(`unknown event types: ${String(p.type)}`)
+    }
+  }
+
+  function setModel(m: unknown) {
+    if (typeof m === "string" && m) {
+      model = m
+      noteModel(h, m)
+    }
+  }
+
+  function finish(): Turn[] {
+    // Edits whose call never got a result still happened as far as the record shows, unless an event says
+    // the patch failed. They go right after their call, where they happened, not at the end of the session.
+    for (const [callId, fe] of edits) {
+      if (failed.has(callId)) continue
+      const i = turns.findIndex((t) => t.kind === "tool_call" && t.id === callId)
+      if (i >= 0) turns.splice(i + 1, 0, ...fe)
+      else turns.push(...fe)
+    }
+    edits.clear()
+    lost.flush(h)
+    return turns
+  }
+
+  return { turns, lost, item, remember, status, event, usage, setModel, user, assistant, call, result, finish }
+}
+
+/** The portable session for a rollout's text (JSONL). */
+export function parseRollout(text: string, path?: string): Session {
+  const { rows, bad } = parseLines(text)
+  const metaRow = rows.find((r) => r.type === "session_meta")
+  const meta = (metaRow?.payload ?? {}) as Row
+  const id = str(meta.id) ?? (path ? idFromName(path) : undefined)
+  if (!id) throw new Error("not a Codex rollout: no session_meta id and no id in the file name")
+  const cwd = str(meta.cwd)
+  const git = meta.git as Row | undefined
+  const project: Project = { ...(cwd ? { cwd } : {}) }
+  if (git && (git.repository_url || git.branch || git.commit_hash)) {
+    if (str(git.repository_url)) project.gitRemote = git.repository_url
+    if (str(git.branch)) project.gitBranch = git.branch
+    if (str(git.commit_hash)) project.gitCommit = git.commit_hash
+  } else Object.assign(project, gitInfo(cwd))
+  const h = header(TOOL, id, {
+    ...(path ? { sourcePath: path } : {}),
+    ...(str(meta.cli_version) ? { toolVersion: meta.cli_version } : {}),
+    project,
+  })
+  const started = iso(meta.timestamp) ?? iso(rows[0]?.timestamp)
+  if (started) h.startedAt = started
+  const times = rows.map((r) => iso(r.timestamp)).filter((t): t is string => !!t)
+  if (times.length) h.updatedAt = times.reduce((a, b) => (b > a ? b : a))
+  if (str(meta.forked_from_id)) h.parent = { id: `${TOOL}:${meta.forked_from_id}`, kind: "fork" }
+  else if (str(meta.parent_thread_id)) h.parent = { id: `${TOOL}:${meta.parent_thread_id}`, kind: "subagent" }
+
+  const b = builder(h)
+  if (bad) b.lost.add("unreadable lines", bad)
+  // A paginated fork holds only its own turns; the inherited prefix stays in the parent's rollout.
+  if (meta.history_base) b.lost.add("history inherited from the parent thread (in the parent's file)")
+  for (const r of rows) {
+    if (r.type === "response_item" && r.payload) b.remember(r.payload)
+    else if (r.type === "event_msg" && r.payload) b.status(r.payload, iso(r.timestamp))
+  }
+
+  for (const r of rows) {
+    const when = iso(r.timestamp)
+    const p = (r.payload ?? {}) as Row
+    switch (r.type) {
+      case "session_meta":
+        // The first is the header; later ones were copied in from a forked parent.
+        break
+      case "response_item":
+        b.item(p, when)
+        break
+      case "event_msg":
+        if (p.type === "thread_settings_applied") b.setModel((p.thread_settings as Row | undefined)?.model)
+        b.event(p, when)
+        break
+      case "turn_context":
+        b.setModel(p.model)
+        if (!h.project.cwd && str(p.cwd)) h.project.cwd = p.cwd
+        break
+      case "compacted":
+        if (str(p.message)?.trim()) b.turns.push({ kind: "compaction", ...(when ? { at: when } : {}), summary: summaryBody(p.message) })
+        else b.lost.add("compactions without a readable summary")
+        if (Array.isArray(p.replacement_history) && p.replacement_history.some((i: Row) => /compaction/.test(String(i?.type))))
+          b.lost.add("encrypted compaction state")
+        break
+      case "inter_agent_communication":
+        b.lost.add("messages between agents")
+        break
+      default:
+        if (!QUIET_RECORDS.has(r.type)) b.lost.add(`unknown record types: ${String(r.type)}`)
+    }
+  }
+  return { header: h, turns: b.finish() }
+}
+
+/** The portable session for a legacy single-file session: {session {id, timestamp, instructions}, items[]}. */
+export function parseLegacyJson(data: unknown, path?: string): Session {
+  const d = (data ?? {}) as Row
+  const s = (d.session ?? {}) as Row
+  const id = str(s.id) ?? (path ? idFromName(path) : undefined)
+  if (!id || !Array.isArray(d.items)) throw new Error("not a legacy Codex session: expected {session, items}")
+  const h = header(TOOL, id, { ...(path ? { sourcePath: path } : {}) })
+  const started = iso(s.timestamp)
+  if (started) h.startedAt = started
+  const b = builder(h)
+  if (str(s.instructions)) b.lost.add("Codex context and instructions (not carried)")
+  for (const it of d.items as Row[]) if (it?.type) b.remember(it)
+  for (const it of d.items as Row[]) {
+    if (!it || typeof it !== "object") continue
+    if (it.type) {
+      b.item(it, undefined)
+      continue
+    }
+    // The oldest files hold Chat-Completions-style messages: {role, content, tool_calls, tool_call_id}.
+    const m = messageParts(it.content)
+    switch (it.role) {
+      case "user":
+        if (m.context) b.lost.add("Codex context and instructions (not carried)")
+        if (m.text || m.images) b.user(m.text, undefined, m.images, m.files)
+        break
+      case "assistant":
+        b.assistant(m.text, undefined)
+        for (const tc of (it.tool_calls ?? []) as Row[]) b.call(str(tc?.id), str(tc?.function?.name) ?? "unknown", parseArgs(tc?.function?.arguments), undefined)
+        break
+      case "tool":
+        b.result(str(it.tool_call_id), it.content, undefined)
+        break
+      case "system":
+      case "developer":
+        b.lost.add("Codex context and instructions (not carried)")
+        break
+      default:
+        b.lost.add(`unknown item roles: ${String(it.role)}`)
+    }
+  }
+  return { header: h, turns: b.finish() }
+}
+
+/** Decompressed text of a .jsonl.zst rollout, or undefined when this runtime has no zstd. */
+function unzstd(path: string): string | undefined {
+  if (typeof Bun.zstdDecompressSync !== "function") return undefined
+  return Bun.zstdDecompressSync(readFileSync(path)).toString("utf8")
+}
+
+/** The first line of a file, read in chunks: session_meta carries the base instructions, often tens of KB. */
+function headLine(path: string, max = 8 << 20): string | undefined {
+  if (path.endsWith(".zst")) return unzstd(path)?.split("\n", 1)[0]
+  const fd = openSync(path, "r")
+  try {
+    const chunks: Buffer[] = []
+    const buf = Buffer.alloc(64 * 1024)
+    let pos = 0
+    while (pos < max) {
+      const n = readSync(fd, buf, 0, buf.length, pos)
+      if (n <= 0) break
+      const nl = buf.subarray(0, n).indexOf(10)
+      chunks.push(Buffer.from(buf.subarray(0, nl >= 0 ? nl : n)))
+      if (nl >= 0) break
+      pos += n
+    }
+    return chunks.length ? Buffer.concat(chunks).toString("utf8") : undefined
+  } finally {
+    closeSync(fd)
+  }
+}
+
+interface ThreadRow {
+  title?: string
+  updatedAt?: string
+  cwd?: string
+}
+
+const oneLine = (s: string) => {
+  const line = s.trim().split("\n", 1)[0]!.trim()
+  return line.length > 120 ? `${line.slice(0, 119)}…` : line
+}
+
+/** Titles and times from Codex's thread index (state_<n>.sqlite, newest schema number), by thread id. */
+function threadIndex(home: string): Map<string, ThreadRow> {
+  const out = new Map<string, ThreadRow>()
+  const dbs = ls(codexDir(home))
+    .map((n) => ({ n, v: Number(n.match(/^state_(\d+)\.sqlite$/)?.[1]) }))
+    .filter((x) => Number.isFinite(x.v))
+    .sort((a, b) => b.v - a.v)
+  if (!dbs.length) return out
+  try {
+    withSnapshot(join(codexDir(home), dbs[0]!.n), (db) => {
+      for (const r of db.query("SELECT * FROM threads").all() as Row[]) {
+        const id = str(r.id)
+        if (!id) continue
+        // A name the person gave wins over Codex's title, which is the first message.
+        const title = str(r.name) ?? str(r.title) ?? str(r.first_user_message)
+        const updated = iso(r.updated_at_ms) ?? iso(r.updated_at)
+        out.set(id, { ...(title ? { title: oneLine(title) } : {}), ...(updated ? { updatedAt: updated } : {}), ...(str(r.cwd) ? { cwd: r.cwd } : {}) })
+      }
+    })
+  } catch {
+    // An index that cannot be read (locked, newer schema) only costs titles; the rollouts are the record.
+  }
+  return out
+}
+
+function listOne(path: string, archived: boolean, index: Map<string, ThreadRow>): SessionRef | undefined {
+  const format = path.endsWith(".zst") ? "jsonl.zst" : path.endsWith(".json") ? "json" : "jsonl"
+  let id = idFromName(path)
+  let cwd: string | undefined
+  let version: string | undefined
+  let title: string | undefined
+  if (format === "json") {
+    // Legacy sessions are small single files and the index never had them, so read the first request here.
+    const d = readJson<Row>(path)
+    id = str(d?.session?.id) ?? id
+    const first = ((d?.items ?? []) as Row[]).find((i) => i?.role === "user" && messageParts(i.content).text)
+    const text = first && messageParts(first.content).text
+    if (text) title = oneLine(text)
+  } else {
+    try {
+      const line = headLine(path)
+      const meta = line ? (JSON.parse(line) as Row) : undefined
+      if (meta?.type === "session_meta") {
+        id = str(meta.payload?.id) ?? id
+        cwd = str(meta.payload?.cwd)
+        version = str(meta.payload?.cli_version)
+      }
+    } catch {
+      // Listed from its file name; read() says what is wrong with it.
+    }
+  }
+  if (!id) return undefined
+  const row = index.get(id)
+  title = row?.title ?? title
+  cwd = cwd ?? row?.cwd
+  const updatedAt = row?.updatedAt ?? mtime(path)
+  return {
+    tool: TOOL,
+    sourceId: id,
+    path,
+    ...(title ? { title } : {}),
+    ...(cwd ? { cwd } : {}),
+    ...(updatedAt ? { updatedAt } : {}),
+    extra: { format, archived, ...(version ? { version } : {}) },
+  }
+}
+
+export const codexReader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+
+  async list(home) {
+    const roots = [
+      { dir: join(codexDir(home), "sessions"), archived: false },
+      { dir: join(codexDir(home), "archived_sessions"), archived: true },
+    ]
+    const files = roots.flatMap((r) => findFiles(r.dir, isRolloutName).map((p) => ({ p, archived: r.archived })))
+    if (!files.length) return []
+    const index = threadIndex(home)
+    const refs: SessionRef[] = []
+    for (const f of files) {
+      const ref = listOne(f.p, f.archived, index)
+      if (ref) refs.push(ref)
+    }
+    return refs.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+  },
+
+  async read(ref) {
+    const path = ref.path
+    if (!exists(path)) throw new Error(`the Codex session file is gone: ${path}`)
+    let s: Session
+    if (path.endsWith(".json")) {
+      const d = readJson(path)
+      if (d === undefined) throw new Error(`the Codex session file is not JSON: ${path}`)
+      s = parseLegacyJson(d, path)
+    } else if (path.endsWith(".zst")) {
+      const text = unzstd(path)
+      if (text === undefined) {
+        // Nothing to decompress with: say so rather than fail the whole listing.
+        s = { header: header(TOOL, ref.sourceId, { sourcePath: path, lost: ["compressed rollout not read, no zstd in this runtime (1)"] }), turns: [] }
+      } else s = parseRollout(text, path)
+    } else {
+      s = parseRollout(readFileSync(path, "utf8"), path)
+    }
+    if (!s.header.title && ref.title) s.header.title = ref.title
+    if (!s.header.title) {
+      const first = s.turns.find((t) => t.kind === "user" && t.text.trim()) as Extract<Turn, { kind: "user" }> | undefined
+      if (first) s.header.title = oneLine(first.text)
+    }
+    if (!s.header.updatedAt) {
+      const m = mtime(path)
+      if (m) s.header.updatedAt = m
+    }
+    if (!s.header.project.cwd && ref.cwd) s.header.project.cwd = ref.cwd
+    return s
+  },
+}