@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/codebuff/writer.ts

@@ -0,0 +1,383 @@
+import { randomBytes, randomUUID } from "node:crypto"
+import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { basename, extname, isAbsolute, join, relative, resolve } from "node:path"
+import { toolLabel } from "../../brief.ts"
+import { exists, isDir } from "../../fsutil.ts"
+import type { Session, Turn } from "../../session/types.ts"
+import { countTurns, unpaired } from "../../session/util.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { fileContext } from "./project.ts"
+import { readChat } from "./reader.ts"
+import { CHAT_MESSAGES, CHAT_META, LABEL, RUN_STATE, TESTED_VERSIONS, TOOL, chatId, chatsDir, continuedNote, installed, summaryMessageText, withSystemTags } from "./records.ts"
+
+// Continues a portable session in Codebuff / Freebuff as a new chat of the project: a folder
+// ~/.config/manicode/projects/<project folder name>/chats/<chat id>/ holding the three files the CLI saves
+// (run-storage saveChatState): run-state.json, chat-messages.json and chat-meta.json, written in that order
+// and each through a temp file and a rename, as the CLI writes them. `freebuff --continue <chat id>` run in the
+// project loads them (loadMostRecentChatState): the screen gets chat-messages.json, the model gets the run
+// state's messageHistory on the next prompt, and /history lists the chat from chat-meta.json.
+//
+// The model's history is written the way the runtime appends to it: the person's prompts as user messages
+// tagged USER_PROMPT, each assistant text, reasoning part and tool call as its own assistant message, and each
+// result as a tool message with a JSON result, right after the calls it answers. Shell, read, write and edit
+// calls become Codebuff's own run_terminal_command, read_files, write_file and str_replace, with results in
+// those tools' shapes; other calls keep their name. A compaction is the runtime's own <conversation_summary>
+// message: the model gets the summary and what follows, the screen keeps every turn. The note saying where the
+// chat came from is a <system> user message without USER_PROMPT, how the runtime adds its own notes, and a
+// notice on screen. The fileContext is a snapshot of the project made as for a new chat (project.ts).
+
+type Json = Record<string, unknown>
+type Call = Extract<Turn, { kind: "tool_call" }>
+type Result = Extract<Turn, { kind: "tool_result" }>
+
+const shellQuote = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+const IMAGE_TYPES: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" }
+const IMAGE_LIMIT = 5 * 1024 * 1024
+/** What the agent runtime starts every agent with (session-state.ts MAX_AGENT_STEPS_DEFAULT). */
+const MAX_AGENT_STEPS = 600
+
+/** The exit code a failed command's output states ("Exit code 2", "exited with code 2"), if it states one. */
+const exitCodeOf = (out: string) => {
+  const m = out.match(/exit(?:ed with)?(?: status| code)?:?\s*(-?\d+)\b/i)
+  return m && Number(m[1]) !== 0 ? Number(m[1]) : undefined
+}
+
+const pick = (o: Json, keys: string[]) => {
+  for (const k of keys) if (typeof o[k] === "string") return o[k] as string
+  return undefined
+}
+
+/** The time of day as the CLI stamps messages (helpers.ts formatTimestamp). */
+const clockTime = (ms: number) => {
+  try {
+    return new Intl.DateTimeFormat(undefined, { hour: "2-digit", minute: "2-digit" }).format(new Date(ms))
+  } catch {
+    return new Date(ms).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })
+  }
+}
+
+/**
+ * The call as Codebuff's own tool where one fits: its name and input, and its result as that tool's JSON.
+ * Paths inside the project become project-relative, as Codebuff's tools take them.
+ */
+export function mapCall(call: Call, roots: string[]): { name: string; input: Json; result: (ok: boolean, out: string) => unknown; native: boolean } {
+  const input = call.input && typeof call.input === "object" && !Array.isArray(call.input) ? (call.input as Json) : undefined
+  // The project folder as given and as resolved (/tmp and /private/tmp): paths in the session may use either.
+  const rel = (p: string) => {
+    const root = isAbsolute(p) ? roots.find((r) => !relative(r, p).startsWith("..")) : undefined
+    return root ? relative(root, p) || "." : p
+  }
+  if (input) {
+    const command = pick(input, ["command", "cmd"]) ?? (Array.isArray(input.command) ? (input.command as unknown[]).map(String).join(" ") : undefined)
+    if (call.toolKind === "shell" && command)
+      // A failure takes the exit code its output states, else 1 (the writer lists how many it guessed).
+      return { name: "run_terminal_command", input: { command }, result: (ok, out) => ({ command, stdout: out, exitCode: ok ? 0 : (exitCodeOf(out) ?? 1) }), native: true }
+    const raw = pick(input, ["file_path", "path", "filePath", "absolute_path", "target_file", "file"])
+    if (raw) {
+      const path = rel(raw)
+      if (call.toolKind === "read") return { name: "read_files", input: { paths: [path] }, result: (ok, out) => (ok ? [{ path, content: out }] : { errorMessage: out }), native: true }
+      const fileResult = (ok: boolean, out: string) => (ok ? { file: path, message: out } : { file: path, errorMessage: out })
+      const content = pick(input, ["content", "file_text", "contents"])
+      if (call.toolKind === "write" && content !== undefined) return { name: "write_file", input: { path, content }, result: fileResult, native: true }
+      const oldString = pick(input, ["old_string", "old_str", "oldText", "old_text", "oldString"])
+      const newString = pick(input, ["new_string", "new_str", "newText", "new_text", "newString"])
+      if (call.toolKind === "edit" && oldString !== undefined && newString !== undefined)
+        return { name: "str_replace", input: { path, replacements: [{ oldString, newString, allowMultiple: input.replace_all === true }] }, result: fileResult, native: true }
+    }
+  }
+  // Names the model APIs accept: letters, digits, _ and -, at most 64.
+  const name = call.name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) || "tool"
+  return { name, input: input ?? { input: call.input ?? null }, result: (ok, out) => (ok ? out : { errorMessage: out }), native: false }
+}
+
+export interface ChatPlan {
+  runState: Json
+  /** chat-messages.json: what the CLI shows. */
+  messages: Json[]
+  lost: string[]
+  /** What a read-back of the run state must find. */
+  expect: { users: number; calls: number }
+}
+
+/** The files of a new Codebuff chat continuing `session`. Pure apart from reading attached images. */
+export function planChat(session: Session, opts: { now: Date; cwd: string; given?: string; fileContext: Json }): ChatPlan {
+  const drops = new Map<string, number>()
+  const drop = (what: string, n = 1) => drops.set(what, (drops.get(what) ?? 0) + n)
+  const label = toolLabel(session.header.tool)
+  const results = new Map<string, Result>()
+  const callIds = new Set<string>()
+  for (const t of session.turns) {
+    if (t.kind === "tool_result" && !results.has(t.callId)) results.set(t.callId, t)
+    if (t.kind === "tool_call") callIds.add(t.id)
+  }
+  // The model's history starts at the last compaction; the screen keeps everything.
+  let start = -1
+  session.turns.forEach((t, i) => {
+    if (t.kind === "compaction") start = i
+  })
+
+  // Times that never go backwards: the turn's own where it has one.
+  const known = session.turns.map((t) => (t.at ? Date.parse(t.at) : Number.NaN)).find(Number.isFinite)
+  let clock = Math.floor(known ?? opts.now.getTime()) - 1
+  const tick = (at?: string) => {
+    const t = at ? Date.parse(at) : Number.NaN
+    clock = Number.isFinite(t) && t > clock ? Math.floor(t) : clock + 1
+    return clock
+  }
+
+  const ids = new Map<string, string>()
+  const usedIds = new Set<string>()
+  let remapped = 0
+  const toolCallId = (id: string) => {
+    let v = ids.get(id)
+    if (v) return v
+    const base = /^[A-Za-z0-9_-]{1,64}$/.test(id) ? id : `call_${id.replace(/[^A-Za-z0-9]/g, "").slice(-40) || "x"}`
+    v = base
+    for (let n = 2; usedIds.has(v); n++) v = `${base}_${n}`
+    ids.set(id, v)
+    usedIds.add(v)
+    if (v !== id) remapped++
+    return v
+  }
+
+  const history: Json[] = []
+  const screen: Json[] = []
+  const expect = { users: 0, calls: 0 }
+  let renamed = 0
+  let thinking = 0
+  let ai: { at: number; blocks: Json[] } | undefined
+  const aiMessage = (at?: string) => (ai ??= { at: tick(at), blocks: [] })
+  const flushAi = () => {
+    if (ai?.blocks.length) screen.push({ id: `ai-${ai.at}-${randomBytes(7).toString("hex").slice(0, 13)}`, variant: "ai", content: "", blocks: ai.blocks, timestamp: clockTime(ai.at), metadata: {}, isComplete: true })
+    ai = undefined
+  }
+  const notice = (text: string, at?: string) => {
+    const ms = tick(at)
+    screen.push({ id: `sys-${ms}`, variant: "ai", content: text, timestamp: clockTime(ms) })
+  }
+
+  // Calls since the last result; their results are written together right after them, as the runtime does.
+  let batch: Array<{ call: Call; id: string; mapped: ReturnType<typeof mapCall>; block: Json; model: boolean }> = []
+  const flushCalls = () => {
+    for (const b of batch) {
+      const r = results.get(b.call.id)
+      let out = r?.output ?? "No result was recorded for this call; the session moved on before it finished."
+      if (r?.fullPath) out += `\n\n[Full output: ${r.fullPath}]`
+      if (r && !out.trim()) out = "(no output)"
+      if (!r) drop("tool calls without a result (closed as errors)")
+      else if (!r.ok && b.mapped.name === "run_terminal_command" && exitCodeOf(out) === undefined) drop("exit codes of failed shell commands, recorded as 1")
+      b.block.output = out
+      if (b.model) history.push({ role: "tool", toolName: b.mapped.name, toolCallId: b.id, content: [{ type: "json", value: b.mapped.result(!!r?.ok, out) }] })
+    }
+    batch = []
+  }
+
+  history.push({ role: "user", content: [{ type: "text", text: withSystemTags(continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10))) }], sentAt: tick() })
+  notice(`Continued from ${label} session ${session.header.sourceId}${session.header.title ? ` (${session.header.title})` : ""}.`)
+
+  const seen = new Set<string>()
+  session.turns.forEach((t, i) => {
+    const model = i > start
+    switch (t.kind) {
+      case "user": {
+        flushCalls()
+        flushAi()
+        const content: Json[] = [{ type: "text", text: t.text }]
+        const attachments: Json[] = []
+        let body = t.text
+        for (const a of t.attachments ?? []) {
+          if (!a.path) continue
+          if (a.kind === "file") {
+            body += `\n\n[Attached file: ${a.path}]`
+            continue
+          }
+          const mediaType = a.mime ?? IMAGE_TYPES[extname(a.path).toLowerCase()]
+          let size = Number.POSITIVE_INFINITY
+          try {
+            size = statSync(a.path).size
+          } catch {}
+          if (mediaType && Object.values(IMAGE_TYPES).includes(mediaType) && size <= IMAGE_LIMIT) {
+            content.push({ type: "image", image: readFileSync(a.path).toString("base64"), mediaType })
+            attachments.push({ filename: basename(a.path), path: a.path, size })
+          } else drop("images that could not be attached")
+        }
+        content[0] = { type: "text", text: body }
+        if (!body.trim() && content.length === 1) break
+        const ms = tick(t.at)
+        screen.push({ id: `user-${ms}`, variant: "user", content: body, timestamp: clockTime(ms), ...(attachments.length ? { attachments } : {}) })
+        if (model) {
+          history.push({ role: "user", content, sentAt: ms, tags: ["USER_PROMPT"], keepDuringTruncation: true })
+          expect.users++
+        }
+        break
+      }
+      case "assistant":
+        flushCalls()
+        if (!t.text.trim()) break
+        aiMessage(t.at).blocks.push({ type: "text", content: t.text, textType: "text" })
+        if (model) history.push({ role: "assistant", content: [{ type: "text", text: t.text }], sentAt: tick(t.at) })
+        break
+      case "reasoning":
+        flushCalls()
+        if (!t.text.trim()) break
+        aiMessage(t.at).blocks.push({ type: "text", content: t.text, textType: "reasoning", thinkingCollapseState: "preview", thinkingId: `thinking-${++thinking}`, thinkingOpen: false })
+        if (model) history.push({ role: "assistant", content: [{ type: "reasoning", text: t.text }], sentAt: tick(t.at) })
+        break
+      case "tool_call": {
+        if (seen.has(t.id)) break
+        seen.add(t.id)
+        const mapped = mapCall(t, [opts.cwd, ...(opts.given && opts.given !== opts.cwd ? [opts.given] : [])])
+        if (!mapped.native && mapped.name !== t.name) renamed++
+        const id = toolCallId(t.id)
+        const block: Json = { type: "tool", toolCallId: id, toolName: mapped.name, input: mapped.input }
+        aiMessage(t.at).blocks.push(block)
+        if (model) {
+          history.push({ role: "assistant", content: [{ toolCallId: id, toolName: mapped.name, input: mapped.input, type: "tool-call" }], sentAt: tick(t.at) })
+          expect.calls++
+        }
+        batch.push({ call: t, id, mapped, block, model })
+        break
+      }
+      case "tool_result":
+        if (!callIds.has(t.callId)) drop("tool results without a call")
+        else if (batch.some((b) => b.call.id === t.callId)) flushCalls()
+        break
+      case "compaction":
+        flushCalls()
+        flushAi()
+        notice("Earlier messages were summarized; the model continues from the summary.", t.at)
+        if (i === start) history.push({ role: "user", content: [{ type: "text", text: summaryMessageText(t.summary) }], sentAt: tick(t.at) })
+        break
+      case "file_edit":
+        if (t.callId && callIds.has(t.callId)) break
+        flushCalls()
+        aiMessage(t.at).blocks.push({ type: "text", content: `[Edited ${t.path}]${t.patch ? `\n\n\`\`\`diff\n${t.patch}\n\`\`\`` : ""}`, textType: "text" })
+        if (model) history.push({ role: "assistant", content: [{ type: "text", text: `[Edited ${t.path}]${t.patch ? `\n\n\`\`\`diff\n${t.patch}\n\`\`\`` : ""}` }], sentAt: tick(t.at) })
+        drop("file edits outside a tool call, kept as text")
+        break
+      case "subagent":
+        drop("subagent sessions (their results stay in the parent's tool results)")
+        break
+    }
+  })
+  flushCalls()
+  flushAi()
+  if (!screen.some((m) => m.variant === "user")) throw new Error("nothing Codebuff can show: the session has no user messages")
+
+  // A finished run's output: the messages after the last prompt (output mode last_message).
+  let lastPrompt = -1
+  history.forEach((m, i) => {
+    if (m.role === "user" && (m.tags as string[] | undefined)?.includes("USER_PROMPT")) lastPrompt = i
+  })
+  const runState = {
+    sessionState: {
+      mainAgentState: {
+        agentId: "main-agent",
+        agentType: null,
+        agentContext: {},
+        ancestorRunIds: [],
+        subagents: [],
+        childRunIds: [],
+        messageHistory: history,
+        stepsRemaining: MAX_AGENT_STEPS,
+        creditsUsed: 0,
+        directCreditsUsed: 0,
+        systemPrompt: "",
+        toolDefinitions: {},
+        contextTokenCount: 0,
+      },
+      fileContext: opts.fileContext,
+    },
+    output: { type: "lastMessage", value: history.slice(lastPrompt + 1) },
+    traceSessionId: randomUUID(),
+    inference: { source: "codebuff" },
+  }
+
+  const lost = [...drops].map(([what, n]) => `${what} (${n})`)
+  if (remapped) lost.push(`tool call ids, remapped to ids model APIs accept (${remapped})`)
+  if (renamed) lost.push(`tool names changed to fit model APIs (${renamed})`)
+  lost.push("Freebuff's skill list and symbol index in this chat's project snapshot (the skill and search tools still read the disk)")
+  return { runState, messages: screen, lost, expect }
+}
+
+/** chat-meta.json for `messages`, bound to the messages file as written (chat-meta.ts writeChatMeta). */
+function chatMeta(dir: string, messages: Json[]) {
+  const first = messages.find((m) => m.variant === "user" && m.content)
+  const text = typeof first?.content === "string" ? first.content.trim() : ""
+  const st = statSync(join(dir, CHAT_MESSAGES))
+  return { messageCount: messages.length, firstPrompt: text ? (text.length > 100 ? `${text.slice(0, 97)}...` : text) : "(empty chat)", messagesSize: st.size, messagesMtimeMs: st.mtimeMs }
+}
+
+/** As write-file-atomic.ts: a private temp file renamed over the target. */
+function writeAtomic(path: string, text: string) {
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
+  writeFileSync(tmp, text, { mode: 0o600, flag: "wx" })
+  renameSync(tmp, path)
+}
+
+/** The resolved folder (/private/tmp, not /tmp): what process.cwd() gives the CLI there. */
+function realCwd(cwd: string): string {
+  try {
+    return realpathSync(cwd)
+  } catch {
+    return cwd
+  }
+}
+
+/** The Codebuff writer; `bin` and `version` are for tests, which must not depend on an installed CLI. */
+export function codebuffWriter(opts: { bin?: string; version?: string } = {}): Writer {
+  const cli = () => (opts.version ? { bin: opts.bin ?? "freebuff", version: opts.version } : installed())
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(w: WriteOptions): Promise<Readiness> {
+      const c = cli()
+      if (!c) return { ok: false, why: "neither Freebuff nor Codebuff is installed (no `freebuff` or `codebuff` npm package on PATH)" }
+      if (!TESTED_VERSIONS.includes(c.version)) return { ok: false, why: `${c.bin} ${c.version} is not a version this writer was checked against (${TESTED_VERSIONS.join(", ")})` }
+      if (!isDir(w.cwd)) return { ok: false, why: `${w.cwd} is not a folder; Codebuff keeps chats per project folder` }
+      return { ok: true }
+    },
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const cwd = realCwd(w.cwd)
+      const bin = cli()?.bin ?? "freebuff"
+      const now = new Date()
+      const root = chatsDir(w.home, cwd)
+      let id = chatId(now)
+      for (let ms = now.getTime() + 1; exists(join(root, id)); ms++) id = chatId(new Date(ms))
+      const dir = join(root, id)
+      // A dry run never walks the project: the snapshot does not change which files are written.
+      const plan = planChat(session, { now, cwd, given: resolve(w.cwd), fileContext: w.dryRun ? {} : fileContext(cwd, w.home) })
+      const files = [RUN_STATE, CHAT_MESSAGES, CHAT_META].map((f) => join(dir, f))
+      if (!w.dryRun) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 })
+        try {
+          writeAtomic(files[0]!, JSON.stringify(plan.runState))
+          writeAtomic(files[1]!, JSON.stringify(plan.messages))
+          writeAtomic(files[2]!, JSON.stringify(chatMeta(dir, plan.messages)))
+          const back = readChat(dir, id)
+          const n = countTurns(back)
+          const pairs = unpaired(back)
+          if (n.user !== plan.expect.users || n.tool_call !== plan.expect.calls || pairs.calls.length || pairs.results.length)
+            throw new Error(`the Codebuff chat did not read back as written (users ${n.user}/${plan.expect.users}, tool calls ${n.tool_call}/${plan.expect.calls}, unpaired ${pairs.calls.length + pairs.results.length}); nothing was kept`)
+        } catch (e) {
+          rmSync(dir, { recursive: true, force: true })
+          throw e
+        }
+      }
+      return {
+        tool: TOOL,
+        way: "native",
+        sessionId: id,
+        written: files,
+        open: `cd ${shellQuote(cwd)} && ${bin} --continue ${id}`,
+        lost: plan.lost,
+        dryRun: !!w.dryRun,
+      }
+    },
+  }
+}
+
+export const codebuffNativeWriter = codebuffWriter()

package/src/adapters/codex/index.ts

@@ -0,0 +1,8 @@
+import type { Reader, Writer } from "../types.ts"
+import { codexReader } from "./reader.ts"
+import { codexWriter } from "./writer.ts"
+
+// OpenAI Codex CLI: reads rollouts (and legacy .json sessions), and continues any session as a new
+// native Codex thread.
+export const readers: Reader[] = [codexReader]
+export const writers: Writer[] = [codexWriter]

package/src/adapters/codex/native.ts

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto"
+import { isContext, SUMMARY_PREFIX } from "./records.ts"
+
+// The shapes Codex itself writes, which a converted session must match so Codex treats it as its own:
+// how a compaction is recorded and rebuilt, how a shell call's output and an apply_patch are written, and
+// how the model's context is sized. Checked against codex-rs at rust-v0.147.0 and against rollouts Codex wrote
+// against a local stand-in server (core/src/compact.rs, rollout_reconstruction.rs, unified_exec, apply_patch).
+
+/** Codex keeps this many tokens of earlier user messages across a compaction (compact.rs COMPACT_USER_MESSAGE_MAX_TOKENS). */
+export const COMPACT_USER_BUDGET = 20_000
+
+const bytesOf = (s: string) => Buffer.byteLength(s)
+
+/** Codex's rough token count of a text: about four bytes a token, rounded up (approx_token_count). */
+export const approxTokens = (text: string) => (bytesOf(text) + 3) >> 2
+
+/** Codex's estimate of one history item: its serialized JSON over four, rounded up (history.rs estimate_item_token_count). */
+export const itemTokens = (item: unknown) => Math.ceil(bytesOf(JSON.stringify(item) ?? "") / 4)
+
+/** The text cut to about `tokens` tokens, on a character boundary, with a note of what was left out. */
+export function cutToTokens(text: string, tokens: number): string {
+  const max = Math.max(0, tokens) * 4
+  const buf = Buffer.from(text)
+  if (buf.length <= max) return text
+  let end = max
+  while (end > 0 && (buf[end]! & 0xc0) === 0x80) end--
+  return `${buf.subarray(0, end).toString("utf8")}…[${approxTokens(text) - (end >> 2)} tokens truncated]…`
+}
+
+/** A compaction's summary as Codex records and replays it: its prefix, a newline, then the summary. */
+export const compactedMessage = (summary: string) => `${SUMMARY_PREFIX}\n${summary.trim() ? summary : "(no summary available)"}`
+
+/** Whether a user message is a compaction summary Codex wrote (or this writer did): Codex never keeps those as user prompts. */
+export const isSummaryMessage = (text: string) => text.startsWith(`${SUMMARY_PREFIX}\n`)
+
+/** The summary's own text, without Codex's prefix. */
+export const summaryBody = (message: string) => (isSummaryMessage(message) ? message.slice(SUMMARY_PREFIX.length + 1) : message)
+
+const userItem = (text: string) => ({ type: "message", role: "user", content: [{ type: "input_text", text }] })
+
+/**
+ * The history Codex rebuilds at a compaction (build_compacted_history): the person's earlier messages, newest first
+ * until the budget is used, in their original order, then the summary. Context Codex injects and earlier summaries
+ * are not kept. A rollout whose compacted record lacks this makes Codex fall back to its legacy replay, which adds the
+ * developer message and environment again on every resume.
+ */
+export function replacementHistory(userTexts: string[], message: string): Array<ReturnType<typeof userItem>> {
+  const kept: string[] = []
+  let left = COMPACT_USER_BUDGET
+  for (let i = userTexts.length - 1; i >= 0; i--) {
+    const text = userTexts[i]!
+    const n = approxTokens(text)
+    if (n <= left) {
+      kept.push(text)
+      left -= n
+    } else {
+      if (left > 0) kept.push(cutToTokens(text, left))
+      break
+    }
+  }
+  kept.reverse()
+  return [...kept, message].map(userItem)
+}
+
+/** The texts of the person's messages in a history: user-role items that are neither Codex's context nor a summary. */
+export function userTextsOf(history: Array<Record<string, any>>): string[] {
+  const out: string[] = []
+  for (const h of history) {
+    if (h.type !== "message" || h.role !== "user" || !Array.isArray(h.content)) continue
+    const text = h.content.map((c: any) => (typeof c?.text === "string" ? c.text : "")).join("")
+    if (text && !isContext(text) && !isSummaryMessage(text)) out.push(text)
+  }
+  return out
+}
+
+/** A shell call's output as Codex's unified exec writes it, which is also where a failed command's exit code lives. */
+export function execOutput(text: string, ok: boolean): string {
+  const body = text.replace(/^Exit code -?\d+\n?/, "")
+  const code = ok ? 0 : Number(text.match(/^Exit code (-?\d+)/)?.[1] ?? 1) || 1
+  const chunk = createHash("sha1").update(body).digest("hex").slice(0, 6)
+  return `Chunk ID: ${chunk}\nWall time: 0.0000 seconds\nProcess exited with code ${code}\nOriginal token count: ${approxTokens(body)}\nOutput:\n${body}`
+}
+
+export interface PatchFile {
+  /** Path as the source tool gave it. */
+  path: string
+  /** A unified diff: `--- a/…`, `+++ b/…`, then hunks. */
+  patch: string
+}
+
+export interface CodexPatch {
+  /** The patch in Codex's apply_patch grammar. */
+  text: string
+  /** What Codex shows for it (patch_apply_end.changes), keyed by absolute path. */
+  changes: Record<string, { type: "add"; content: string } | { type: "update"; unified_diff: string; move_path: null }>
+  /** "M path" / "A path" lines, as apply_patch reports them. */
+  summary: string[]
+}
+
+/**
+ * Unified diffs of the files one call changed, as Codex's apply_patch text and the display record Codex keeps for it.
+ * Undefined when a diff was cut short or does not parse, so the call stays as it was written.
+ */
+export function codexPatch(files: PatchFile[], cwd: string): CodexPatch | undefined {
+  if (!files.length) return undefined
+  const sections: string[] = []
+  const changes: CodexPatch["changes"] = {}
+  const summary: string[] = []
+  for (const f of files) {
+    if (/\[\.\.\. \d+ characters cut \.\.\.\]/.test(f.patch)) return undefined
+    const lines = f.patch.split("\n")
+    const first = lines.findIndex((l) => l.startsWith("@@"))
+    if (first < 0) return undefined
+    const abs = f.path.startsWith("/") ? f.path : `${cwd}/${f.path}`
+    const rel = abs.startsWith(`${cwd}/`) ? abs.slice(cwd.length + 1) : abs
+    const hunks: Array<{ header: string; body: string[] }> = []
+    for (const l of lines.slice(first)) {
+      if (l.startsWith("@@")) hunks.push({ header: l, body: [] })
+      else if (hunks.length && (l[0] === " " || l[0] === "+" || l[0] === "-")) hunks.at(-1)!.body.push(l)
+      else if (hunks.length && l === "") hunks.at(-1)!.body.push(" ")
+    }
+    if (!hunks.length) return undefined
+    const created = hunks.length === 1 && /^@@ -0,0 /.test(hunks[0]!.header)
+    if (created) {
+      const content = `${hunks[0]!.body.map((l) => l.slice(1)).join("\n")}\n`
+      sections.push(`*** Add File: ${rel}\n${hunks[0]!.body.join("\n")}`)
+      changes[abs] = { type: "add", content }
+      summary.push(`A ${rel}`)
+    } else {
+      sections.push(`*** Update File: ${rel}\n${hunks.map((h) => `@@\n${h.body.join("\n")}`).join("\n")}`)
+      changes[abs] = { type: "update", unified_diff: `${hunks.map((h) => `${h.header}\n${h.body.join("\n")}`).join("\n")}\n`, move_path: null }
+      summary.push(`M ${rel}`)
+    }
+  }
+  return { text: `*** Begin Patch\n${sections.join("\n")}\n*** End Patch`, changes, summary }
+}
+
+/**
+ * The display record of one edit that cannot be written as an apply_patch (its diff was cut short, or the call is not
+ * one Codex could have made): a new file as its content, anything else as the hunks it has. Undefined when there is none.
+ */
+export function displayChange(patch: string, cwd: string, path: string): { path: string; change: CodexPatch["changes"][string] } | undefined {
+  const lines = patch.split("\n")
+  const first = lines.findIndex((l) => l.startsWith("@@"))
+  if (first < 0) return undefined
+  const abs = path.startsWith("/") ? path : `${cwd}/${path}`
+  if (/^@@ -0,0 /.test(lines[first]!)) {
+    const body = lines.slice(first + 1).filter((l) => l.startsWith("+")).map((l) => l.slice(1))
+    return { path: abs, change: { type: "add", content: `${body.join("\n")}\n` } }
+  }
+  return { path: abs, change: { type: "update", unified_diff: `${lines.slice(first).join("\n").replace(/\n$/, "")}\n`, move_path: null } }
+}
+
+/** The command Codex's exec_command runs for an apply_patch it intercepts. */
+export const patchCommand = (patch: string) => `apply_patch <<'EOF'\n${patch}\nEOF\n`
+
+/** The output of that command, and what apply_patch printed. */
+export const patchStdout = (summary: string[]) => `Success. Updated the following files:\n${summary.join("\n")}\n`
+export const patchOutput = (summary: string[]) => `Wall time: 0.0000 seconds\nOutput:\nExit code: 0\nWall time: 0.1 seconds\nOutput:\n${patchStdout(summary)}`
+
+/** `mcp__server__tool` as Codex's MCP event names it: the server and the tool. */
+export function mcpParts(name: string): { server: string; tool: string } | undefined {
+  const m = name.match(/^mcp__(.+?)__(.+)$/)
+  return m ? { server: m[1]!, tool: m[2]! } : undefined
+}
+
+/**
+ * A one-line title for a thread: the session's own title, or its first request, without the tags Claude Code wraps
+ * around pasted text or injects into messages, cut to about 60 characters at a word.
+ */
+export function plainTitle(text: string): string {
+  const t = text
+    .replace(/<(system-reminder|task-notification|ci-monitor-event|command-name|command-message|command-args|local-command-[a-z-]+)\b[^>]*>[\s\S]*?<\/\1>/g, " ")
+    .replace(/<\/?pasted_content\b[^>]*>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+  if (t.length <= 60) return t || "Session"
+  const cut = t.slice(0, 59)
+  const space = cut.lastIndexOf(" ")
+  return `${cut.slice(0, space > 30 ? space : 59)}…`
+}
+
+/** What registering a thread in Codex's own index came to; `named` says whether its title was set too. */
+export type Registration = { ok: true; named?: boolean } | { ok: false; why: string }
+
+/**
+ * Has Codex index a rollout it did not write, through its own read-repair: `thread/read` on its app server finds the
+ * file and adds the thread to state_5.sqlite, as it does for any rollout it meets. No model is called. Without it
+ * the thread is missing from the `codex resume` picker and `--last` resumes another thread instead.
+ */
+export async function registerThread(codexHome: string, threadId: string, cwd: string, name?: string, timeoutMs = 20_000): Promise<Registration> {
+  let proc: ReturnType<typeof Bun.spawn> | undefined
+  try {
+    proc = Bun.spawn(["codex", "app-server"], { cwd, env: { ...process.env, CODEX_HOME: codexHome }, stdin: "pipe", stdout: "pipe", stderr: "ignore" })
+    const send = (m: unknown) => (proc!.stdin as { write(s: string): void; flush(): void }).write(`${JSON.stringify(m)}\n`)
+    const reader = (proc.stdout as ReadableStream<Uint8Array>).getReader()
+    const decoder = new TextDecoder()
+    let buffer = ""
+    const response = async (id: number): Promise<any> => {
+      for (;;) {
+        const nl = buffer.indexOf("\n")
+        if (nl >= 0) {
+          const line = buffer.slice(0, nl)
+          buffer = buffer.slice(nl + 1)
+          try {
+            const msg = JSON.parse(line)
+            if (msg.id === id) return msg
+          } catch {}
+          continue
+        }
+        const { value, done } = await reader.read()
+        if (done) throw new Error("Codex's app server closed before it answered")
+        buffer += decoder.decode(value, { stream: true })
+      }
+    }
+    const run = (async () => {
+      send({ id: 1, method: "initialize", params: { clientInfo: { name: "brain", title: "brain", version: "0.1.0" }, capabilities: { experimentalApi: true } } })
+      const init = await response(1)
+      if (init.error) throw new Error(`initialize: ${init.error.message ?? "refused"}`)
+      send({ method: "initialized" })
+      send({ id: 2, method: "thread/read", params: { threadId, includeTurns: false } })
+      const read = await response(2)
+      if (read.error) throw new Error(`thread/read: ${read.error.message ?? "refused"}`)
+      if (!name) return undefined
+      // Codex's own way to title a thread (what /rename does), rather than leaving it to the first message's text.
+      send({ id: 3, method: "thread/name/set", params: { threadId, name } })
+      const named = await response(3)
+      return !named.error
+    })()
+    const named = await Promise.race([run, new Promise<never>((_, no) => setTimeout(() => no(new Error("timed out")), timeoutMs))])
+    return { ok: true, ...(named === undefined ? {} : { named }) }
+  } catch (e) {
+    return { ok: false, why: e instanceof Error ? e.message : String(e) }
+  } finally {
+    try {
+      proc?.kill()
+    } catch {}
+  }
+}