@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/adapters/openhands/records.ts

@@ -0,0 +1,136 @@
+import { closeSync, openSync, readSync, realpathSync } from "node:fs"
+import { join } from "node:path"
+import { versionOf } from "../../fsutil.ts"
+import type { ToolKind } from "../../session/types.ts"
+import { toolKindOf } from "../../session/util.ts"
+
+// What OpenHands CLI conversations look like, as far as this adapter relies on it. Checked against the
+// released CLI, openhands 1.16.0 on PyPI with openhands-sdk 1.21.0 (installed from PyPI; source read in
+// site-packages: openhands_cli/conversations/store/local.py, openhands/sdk/conversation/{state,event_store,
+// persistence_const}.py, openhands/sdk/event/**, openhands/sdk/agent/agent.py), and against events the SDK
+// itself serialised (EventLog.append, model_dump_json(exclude_none=True)). Catalogue entry 15.
+//
+// A conversation is a folder ~/.openhands/conversations/<uuid hex>/ holding base_state.json (the
+// ConversationState) and events/event-<5-digit index>-<event uuid>.json, one pydantic event per file with a
+// "kind" discriminator. The CLI lists every folder whose events/ holds at least one event, dated by the first
+// event's timestamp and titled by the first user MessageEvent; `openhands --resume <id>` builds the
+// conversation from those files (ConversationState.create), and the model is sent the events in order:
+// the SystemPromptEvent first, then messages, actions and observations, with Condensation events applied.
+
+export const TOOL = "openhands"
+export const LABEL = "OpenHands CLI"
+
+/** OpenHands CLI versions whose conversation format the writer was checked against (and their SDK). */
+export const TESTED_VERSIONS = ["1.16.0"]
+
+export const openhandsDir = (home: string) => join(home, ".openhands")
+export const conversationsDir = (home: string) => join(openhandsDir(home), "conversations")
+export const agentSettingsPath = (home: string) => join(openhandsDir(home), "agent_settings.json")
+
+/** persistence_const.EVENT_NAME_RE: exactly five digits of index, then the event id. */
+export const EVENT_FILE = /^event-(\d{5})-([0-9a-fA-F-]{8,})\.json$/
+export const eventFile = (index: number, id: string) => `event-${String(index).padStart(5, "0")}-${id}.json`
+
+/** The note a continued conversation carries in its system prompt's dynamic context; the reader looks for it. */
+export const continuedNote = (label: string, id: string, when: string) =>
+  `[This conversation continues ${label} session ${id}, carried over by brain session on ${when}. The events after this system prompt are its history; anything listed as lost did not carry over. Check files before relying on details, since they may have changed.]`
+export const CONTINUED_NOTE = /\[This conversation continues .+? session (\S+), carried over by brain session/
+
+/** "OpenHands CLI 1.16.0" → "1.16.0". */
+export const openhandsVersion = (bin = "openhands") => versionOf(bin)?.match(/(\d+\.\d+\.\d+)/)?.[1]
+
+const pad = (n: number, w = 2) => String(n).padStart(w, "0")
+/**
+ * A timestamp as OpenHands writes it: datetime.now().isoformat(), local time without a zone. The CLI sorts
+ * conversations by it, and a zoned value next to its own naive ones would fail that comparison.
+ */
+export function naiveLocal(ms: number): string {
+  const d = new Date(Math.floor(ms))
+  const micros = pad(d.getMilliseconds(), 3) + pad(Math.floor((ms % 1) * 1000), 3)
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${micros}`
+}
+
+/** A naive local or zoned OpenHands timestamp → ISO. */
+export function eventTime(v: unknown): string | undefined {
+  if (typeof v !== "string" || !v) return undefined
+  const t = new Date(/[zZ]|[+-]\d\d:?\d\d$/.test(v) ? v : v.slice(0, 23))
+  return Number.isFinite(t.getTime()) ? t.toISOString() : undefined
+}
+
+/** OpenHands' own tools, with what each does in portable terms. file_editor's kind depends on its command. */
+export function openhandsKind(name: string, input: unknown): ToolKind {
+  if (name === "terminal" || name === "execute_bash") return "shell"
+  if (name === "task_tracker") return "todo"
+  if (name === "task_tool_set" || name === "task" || name === "delegate") return "task"
+  if (name === "think" || name === "finish") return "other"
+  if (name === "file_editor" || name === "str_replace_editor") {
+    const command = (input as { command?: unknown } | undefined)?.command
+    return command === "view" ? "read" : command === "create" ? "write" : "edit"
+  }
+  return toolKindOf(name)
+}
+
+/**
+ * The Python of a pip or uv install of the CLI: the interpreter named by the `openhands` script's shebang,
+ * either directly (#!/…/bin/python) or through pip's long-path form (#!/bin/sh then '''exec' '/…/python').
+ * A standalone binary has none.
+ */
+export function openhandsPython(bin: string): string | undefined {
+  const path = bin.includes("/") ? bin : Bun.which(bin, { PATH: process.env.PATH ?? "" })
+  if (!path) return undefined
+  let head = ""
+  try {
+    const fd = openSync(realpathSync(path), "r")
+    const buf = Buffer.alloc(600)
+    const n = readSync(fd, buf, 0, buf.length, 0)
+    closeSync(fd)
+    head = buf.subarray(0, n).toString("utf8")
+  } catch {
+    return undefined
+  }
+  if (!head.startsWith("#!")) return undefined
+  const direct = head.match(/^#!\s*(\S*python[\d.]*)\s*\n/)?.[1]
+  if (direct) return direct
+  return head.match(/^'''exec' ['"]([^'"]*python[\d.]*)['"]/m)?.[1]
+}
+
+/**
+ * Run with the CLI's own Python: the system prompt a new conversation in `cwd` would start with, made the way
+ * the CLI makes it (AgentStore.load_from_disk for the person's agent settings, the CLI's agent context of
+ * project skills plus "Your current working directory is ..." / "User operating system ..."), without
+ * starting tools, MCP servers or a model. Public skills are left out: loading them fetches from the network.
+ */
+export const RENDER_PROMPT_PY = `
+import json, sys
+from openhands.sdk import AgentContext
+from openhands.sdk.context import load_project_skills
+from openhands_cli.stores import AgentStore
+from openhands_cli.utils import get_os_description
+cwd = sys.argv[1]
+agent = AgentStore().load_from_disk()
+if agent is None:
+    print("BRAIN-RENDER " + json.dumps({"error": "no agent settings"}))
+    sys.exit(0)
+suffix = "\\n".join([f"Your current working directory is: {cwd}", f"User operating system: {get_os_description()}"])
+ctx = AgentContext(skills=load_project_skills(cwd), system_message_suffix=suffix, load_user_skills=True, load_public_skills=False)
+agent = agent.model_copy(update={"agent_context": ctx})
+dynamic = ctx.get_system_message_suffix(llm_model=agent.llm.model, llm_model_canonical=agent.llm.model_canonical_name)
+print("BRAIN-RENDER " + json.dumps({"system_prompt": agent.static_system_message, "dynamic_context": dynamic, "model": agent.llm.model}))
+`
+
+export interface RenderedPrompt {
+  system_prompt: string
+  dynamic_context?: string | null
+  model?: string
+}
+
+/** The system prompt from the installed CLI, run against `home` (its agent settings) and `cwd` (its skills). */
+export function renderPrompt(python: string, home: string, cwd: string): RenderedPrompt {
+  const env: Record<string, string> = { HOME: home, PATH: process.env.PATH ?? "/usr/bin:/bin", OPENHANDS_SUPPRESS_BANNER: "1", OPENHANDS_WORK_DIR: cwd, LANG: process.env.LANG ?? "en_US.UTF-8" }
+  const p = Bun.spawnSync([python, "-I", "-c", RENDER_PROMPT_PY, cwd], { cwd, env, stdout: "pipe", stderr: "pipe", timeout: 120_000 })
+  const line = p.stdout.toString().split("\n").find((l) => l.startsWith("BRAIN-RENDER "))
+  if (!line) throw new Error(`OpenHands could not build its system prompt (exit ${p.exitCode}): ${p.stderr.toString().trim().split("\n").slice(-3).join(" ")}`)
+  const out = JSON.parse(line.slice("BRAIN-RENDER ".length)) as RenderedPrompt & { error?: string }
+  if (out.error || !out.system_prompt) throw new Error(`OpenHands could not build its system prompt: ${out.error ?? "empty prompt"}`)
+  return out
+}

package/src/adapters/openhands/writer.ts

@@ -0,0 +1,404 @@
+import { randomUUID } from "node:crypto"
+import { mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { extname, join } 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 { readConversation } from "./reader.ts"
+import {
+  LABEL,
+  type RenderedPrompt,
+  TESTED_VERSIONS,
+  TOOL,
+  agentSettingsPath,
+  continuedNote,
+  conversationsDir,
+  eventFile,
+  naiveLocal,
+  openhandsPython,
+  openhandsVersion,
+  renderPrompt,
+} from "./records.ts"
+
+// Continues a portable session in the OpenHands CLI as a new conversation: a folder under
+// ~/.openhands/conversations/<uuid hex>/events/ holding the events the SDK itself would have stored, in its
+// serialisation (kind discriminators, naive local timestamps, five-digit indexes). `openhands --resume <id>`
+// lists and opens it: with no base_state.json yet, ConversationState.create takes its fresh path, loads the
+// events through EventLog and writes base_state.json from the CLI's current agent, as for any new
+// conversation; nothing has to agree with an agent snapshot written here.
+//
+// The first event is the SystemPromptEvent, because the agent refuses a log whose first events hold a user
+// message without one (Agent.init_state), and the model is sent the events in order. Its text is made by the
+// installed CLI from the person's own agent settings (records.ts RENDER_PROMPT_PY), so the model gets the
+// OpenHands prompt it would get in any conversation. The note saying where the session came from goes in
+// that event's dynamic context, OpenHands' per-conversation part of the system prompt, not in a user message.
+//
+// Tool calls stay structural: ActionEvent + ObservationEvent paired by tool_call_id, parallel calls sharing
+// an llm_response_id. Shell, read, write and edit calls become OpenHands' own terminal and file_editor calls
+// (TerminalAction/TerminalObservation, FileEditorAction/FileEditorObservation); others keep their name with
+// no executable action and a generic MCPToolObservation, the SDK's record for a named tool's text result.
+// A failed call is an AgentErrorEvent. Readable reasoning rides on the next agent event's reasoning_content,
+// a plain-text field OpenHands keeps and sends back only to models that take it. A compaction is a native
+// Condensation: the turns before it stay on screen, the model gets the system prompt, the summary and what
+// follows.
+
+type Ev = 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 text = (t: string) => ({ cache_prompt: false, type: "text", text: t })
+
+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
+
+const pick = (o: Record<string, unknown>, keys: string[]) => {
+  for (const k of keys) if (typeof o[k] === "string") return o[k] as string
+  return undefined
+}
+
+/** The exit code a failed command's output states ("Exit code 2", "exited with code 2"), if it states one. */
+export 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
+}
+
+/**
+ * The call as OpenHands' own tool where one fits: its name, arguments and executable action, and the
+ * observation kind its result is stored as. Anything else keeps its own name with no action.
+ */
+export function mapCall(call: Call, cwd?: string): { name: string; args: Record<string, unknown> | string; action?: Ev; observe: (ok: boolean, out: string) => Ev; native: boolean } {
+  const input = call.input && typeof call.input === "object" && !Array.isArray(call.input) ? (call.input as Record<string, unknown>) : undefined
+  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) {
+      return {
+        name: "terminal",
+        args: { command },
+        action: { command, is_input: false, reset: false, kind: "TerminalAction" },
+        // A success is exit code 0. A failure takes the code its output states, else 1: OpenHands reads -1 as a
+        // command still running, which would misstate a failed one (the writer lists how many it guessed).
+        observe: (ok, out) => {
+          const code = ok ? 0 : (exitCodeOf(out) ?? 1)
+          return { content: [text(out)], is_error: !ok, command, exit_code: code, timeout: false, metadata: { exit_code: code, pid: -1, ...(cwd ? { working_dir: cwd } : {}), prefix: "", suffix: `\n[The command completed with exit code ${code}.]` }, kind: "TerminalObservation" }
+        },
+        native: true,
+      }
+    }
+    const path = pick(input, ["file_path", "path", "filePath", "absolute_path", "target_file", "file"])
+    const editor = (command: string, extra: Record<string, unknown>) => ({
+      name: "file_editor",
+      args: { command, path, ...extra },
+      action: { command, path, ...extra, kind: "FileEditorAction" },
+      observe: (ok: boolean, out: string) => ({ content: [text(out)], is_error: !ok, command, path, prev_exist: true, kind: "FileEditorObservation" }),
+      native: true,
+    })
+    if (path && call.toolKind === "read") return editor("view", {})
+    const content = pick(input, ["content", "file_text", "contents"])
+    if (path && call.toolKind === "write" && content !== undefined) return editor("create", { file_text: content })
+    const oldStr = pick(input, ["old_string", "old_str", "oldText", "old_text"])
+    const newStr = pick(input, ["new_string", "new_str", "newText", "new_text"])
+    if (path && call.toolKind === "edit" && oldStr !== undefined && newStr !== undefined) return editor("str_replace", { old_str: oldStr, new_str: newStr })
+  }
+  // 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,
+    args: typeof call.input === "string" ? call.input : (input ?? { input: call.input ?? null }),
+    observe: (ok, out) => ({ content: [text(out)], is_error: !ok, tool_name: name, kind: "MCPToolObservation" }),
+    native: false,
+  }
+}
+
+/** The conversation regrouped: messages, agent responses (thought plus the calls made together), compactions. */
+type Step =
+  | { kind: "user"; at?: string; content: Ev[] }
+  | { kind: "agent"; at?: string; texts: string[]; reasoning?: string; calls: Call[] }
+  | { kind: "compaction"; at?: string; summary: string }
+
+export interface EventPlan {
+  /** Every event of the new conversation, in index order. */
+  events: Ev[]
+  lost: string[]
+  /** What a read-back must find. */
+  expect: { users: number; calls: number }
+}
+
+/** The events of a new OpenHands conversation continuing `session`. Pure apart from reading attached images. */
+export function planEvents(session: Session, opts: { now: Date; prompt: RenderedPrompt; cwd?: string }): EventPlan {
+  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)
+  }
+
+  const steps: Step[] = []
+  let cur: Extract<Step, { kind: "agent" }> | undefined
+  let reasoning: string[] = []
+  const flush = () => {
+    if (cur && (cur.texts.length || cur.calls.length)) steps.push(cur)
+    cur = undefined
+  }
+  const agent = (at?: string) => {
+    if (!cur) {
+      cur = { kind: "agent", ...(at ? { at } : {}), texts: [], calls: [] }
+      if (reasoning.length) cur.reasoning = reasoning.join("\n\n")
+      reasoning = []
+    }
+    return cur
+  }
+  const dropReasoning = () => {
+    if (reasoning.length) drop("reasoning with no reply after it", reasoning.length)
+    reasoning = []
+  }
+  const seen = new Set<string>()
+  for (const t of session.turns) {
+    switch (t.kind) {
+      case "user": {
+        flush()
+        dropReasoning()
+        const content: Ev[] = []
+        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 mime = a.mime ?? IMAGE_TYPES[extname(a.path).toLowerCase()]
+          let size = Number.POSITIVE_INFINITY
+          try {
+            size = statSync(a.path).size
+          } catch {}
+          if (mime && Object.values(IMAGE_TYPES).includes(mime) && size <= IMAGE_LIMIT)
+            content.push({ cache_prompt: false, type: "image", image_urls: [`data:${mime};base64,${readFileSync(a.path).toString("base64")}`] })
+          else drop("images that could not be attached")
+        }
+        if (!body.trim() && !content.length) break
+        steps.push({ kind: "user", ...(t.at ? { at: t.at } : {}), content: [text(body.trim() ? body : "(image)"), ...content] })
+        break
+      }
+      case "assistant":
+        // Text after a tool call is a new response: it was written after the call's result came back.
+        if (cur?.calls.length) flush()
+        if (t.text.trim()) agent(t.at).texts.push(t.text)
+        break
+      case "tool_call":
+        if (seen.has(t.id)) break
+        seen.add(t.id)
+        agent(t.at).calls.push(t)
+        break
+      case "tool_result":
+        // A result closes the response it answers; a call after it is a new response, not a parallel one.
+        if (!callIds.has(t.callId)) drop("tool results without a call")
+        else if (cur?.calls.some((c) => c.id === t.callId)) flush()
+        break
+      case "reasoning":
+        if (cur?.calls.length || cur?.texts.length) flush()
+        if (t.text.trim()) reasoning.push(t.text)
+        break
+      case "compaction":
+        flush()
+        dropReasoning()
+        steps.push({ kind: "compaction", ...(t.at ? { at: t.at } : {}), summary: `[Summary of the earlier conversation in ${label}, which replaced the turns before it]\n\n${t.summary}` })
+        break
+      case "file_edit":
+        if (!t.callId || !callIds.has(t.callId)) drop("file edits outside a tool call")
+        break
+      case "subagent":
+        drop("subagent sessions (their results stay in the parent's tool results)")
+        break
+    }
+  }
+  flush()
+  dropReasoning()
+
+  // Events, with timestamps that never go backwards and call ids every model API accepts.
+  const known = session.turns.map((t) => (t.at ? Date.parse(t.at) : Number.NaN)).find(Number.isFinite)
+  let clock = (known ?? opts.now.getTime()) - 1
+  const stamp = (at?: string) => {
+    const t = at ? Date.parse(at) : Number.NaN
+    clock = Number.isFinite(t) && t > clock ? t : clock + 0.001
+    return naiveLocal(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 events: Ev[] = []
+  const push = (fields: Ev, at?: string) => {
+    const e = { id: randomUUID(), timestamp: stamp(at), ...fields }
+    events.push(e)
+    return e
+  }
+  const dynamic = [opts.prompt.dynamic_context, continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10))].filter(Boolean).join("\n\n")
+  push({ source: "agent", system_prompt: text(opts.prompt.system_prompt), tools: [], dynamic_context: text(dynamic), kind: "SystemPromptEvent" }, undefined)
+  // Ids of what the model has been shown since the system prompt, for a Condensation to forget.
+  let shown: string[] = []
+  const expect = { users: 0, calls: 0 }
+  let renamed = 0
+  for (const s of steps) {
+    if (s.kind === "user") {
+      shown.push(push({ source: "user", llm_message: { role: "user", content: s.content, thinking_blocks: [] }, activated_skills: [], extended_content: [], kind: "MessageEvent" }, s.at).id as string)
+      expect.users++
+      continue
+    }
+    if (s.kind === "compaction") {
+      const e = push({ source: "environment", forgotten_event_ids: shown, summary: s.summary, summary_offset: 1, llm_response_id: randomUUID(), kind: "Condensation" }, s.at)
+      shown = [`${e.id}-summary`]
+      continue
+    }
+    const response = randomUUID()
+    const thought = s.texts.map(text)
+    if (!s.calls.length) {
+      shown.push(
+        push(
+          { source: "agent", llm_message: { role: "assistant", content: thought, ...(s.reasoning ? { reasoning_content: s.reasoning } : {}), thinking_blocks: [] }, llm_response_id: response, activated_skills: [], extended_content: [], kind: "MessageEvent" },
+          s.at,
+        ).id as string,
+      )
+      continue
+    }
+    const actions: Array<{ call: Call; event: Ev; mapped: ReturnType<typeof mapCall>; id: string }> = []
+    s.calls.forEach((call, k) => {
+      const mapped = mapCall(call, opts.cwd)
+      if (!mapped.native && mapped.name !== call.name) renamed++
+      const id = toolCallId(call.id)
+      const args = typeof mapped.args === "string" ? mapped.args : JSON.stringify(mapped.args)
+      // Only the first action of a response carries its thought and reasoning (_combine_action_events).
+      const event = push(
+        {
+          source: "agent",
+          thought: k === 0 ? thought : [],
+          ...(k === 0 && s.reasoning ? { reasoning_content: s.reasoning } : {}),
+          thinking_blocks: [],
+          ...(mapped.action ? { action: mapped.action } : {}),
+          tool_name: mapped.name,
+          tool_call_id: id,
+          tool_call: { id, name: mapped.name, arguments: args, origin: "completion" },
+          llm_response_id: response,
+          security_risk: "UNKNOWN",
+          kind: "ActionEvent",
+        },
+        call.at ?? s.at,
+      )
+      shown.push(event.id as string)
+      actions.push({ call, event, mapped, id })
+      expect.calls++
+    })
+    for (const a of actions) {
+      const r = results.get(a.call.id)
+      let out = r?.output ?? ""
+      if (r?.fullPath) out += `\n\n[Full output: ${r.fullPath}]`
+      if (r && !out.trim()) out = "(no output)"
+      const fields: Ev = !r
+        ? { source: "agent", tool_name: a.mapped.name, tool_call_id: a.id, error: "No result was recorded for this call; the session moved on before it finished.", kind: "AgentErrorEvent" }
+        : !r.ok && !a.mapped.native
+          ? { source: "agent", tool_name: a.mapped.name, tool_call_id: a.id, error: out, kind: "AgentErrorEvent" }
+          : { source: "environment", tool_name: a.mapped.name, tool_call_id: a.id, observation: a.mapped.observe(r.ok, out), action_id: a.event.id, kind: "ObservationEvent" }
+      if (!r) drop("tool calls without a result (closed as errors)")
+      else if (!r.ok && a.mapped.name === "terminal" && exitCodeOf(out) === undefined) drop("exit codes of failed shell commands, recorded as 1")
+      shown.push(push(fields, r?.at ?? s.at).id as string)
+    }
+  }
+  if (!expect.users && !expect.calls && !steps.some((s) => s.kind === "agent")) throw new Error("nothing OpenHands can replay: the session has no messages or tool calls")
+
+  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("OpenHands public skills (not listed in this conversation's system prompt)")
+  return { events, lost, expect }
+}
+
+/** The resolved folder (/private/tmp, not /tmp): the path OpenHands itself would record for the workspace. */
+function realCwd(cwd: string): string {
+  try {
+    return realpathSync(cwd)
+  } catch {
+    return cwd
+  }
+}
+
+/**
+ * The OpenHands writer. `bin`, `version` and `render` are for tests and harnesses: the CLI to run, its
+ * version, and what builds the system prompt (the installed CLI's own code by default).
+ */
+export function openhandsWriter(opts: { bin?: string; version?: string; render?: (home: string, cwd: string) => RenderedPrompt } = {}): Writer {
+  const bin = opts.bin ?? "openhands"
+  const installed = () => opts.version ?? openhandsVersion(bin)
+  const render =
+    opts.render ??
+    ((home: string, cwd: string) => {
+      const python = openhandsPython(bin)
+      if (!python) throw new Error("the OpenHands CLI's Python was not found")
+      return renderPrompt(python, home, cwd)
+    })
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(w: WriteOptions): Promise<Readiness> {
+      const v = installed()
+      if (!v) return { ok: false, why: "the OpenHands CLI is not installed (`openhands --version` did not run)" }
+      if (!TESTED_VERSIONS.includes(v)) return { ok: false, why: `OpenHands CLI ${v} is not a version this writer was checked against (${TESTED_VERSIONS.join(", ")})` }
+      if (!opts.render && !openhandsPython(bin))
+        return { ok: false, why: "the OpenHands CLI is a standalone binary here; the writer needs the Python install (`uv tool install openhands`) to build OpenHands' system prompt" }
+      if (!exists(agentSettingsPath(w.home))) return { ok: false, why: "OpenHands has no agent settings yet (~/.openhands/agent_settings.json); run `openhands` once to choose a model" }
+      if (!isDir(w.cwd)) return { ok: false, why: `${w.cwd} is not a folder; OpenHands works in the folder a conversation belongs to` }
+      return { ok: true }
+    },
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const cwd = realCwd(w.cwd)
+      let id = randomUUID().replace(/-/g, "")
+      while (exists(join(conversationsDir(w.home), id))) id = randomUUID().replace(/-/g, "")
+      const dir = join(conversationsDir(w.home), id)
+      // A dry run never runs OpenHands: the prompt does not change which files are written.
+      const prompt = w.dryRun ? { system_prompt: "(made by OpenHands when written)" } : render(w.home, cwd)
+      const plan = planEvents(session, { now: new Date(), prompt, cwd })
+      const files = plan.events.map((e, i) => join(dir, "events", eventFile(i, e.id as string)))
+      if (!w.dryRun) {
+        mkdirSync(join(dir, "events"), { recursive: true })
+        plan.events.forEach((e, i) => writeFileSync(files[i]!, JSON.stringify(e), { flag: "wx" }))
+        const back = readConversation(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) {
+          rmSync(dir, { recursive: true, force: true })
+          throw new Error(
+            `the OpenHands conversation 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`,
+          )
+        }
+      }
+      return {
+        tool: TOOL,
+        way: "native",
+        sessionId: id,
+        written: files,
+        open: `cd ${shellQuote(cwd)} && openhands --resume ${id}`,
+        lost: plan.lost,
+        dryRun: !!w.dryRun,
+      }
+    },
+  }
+}
+
+export const openhandsNativeWriter = openhandsWriter()

package/src/adapters/pearai/index.ts

@@ -0,0 +1,10 @@
+import { continueReader } from "../continue/reader.ts"
+import { PEARAI } from "../continue/records.ts"
+import { continueWriter } from "../continue/writer.ts"
+import type { Reader, Writer } from "../types.ts"
+
+// PearAI's chat, a fork of an older Continue: the same session store under ~/.pearai/sessions, with text-only
+// messages, so the Continue adapter does the work with PearAI's settings (records.ts, PEARAI).
+export const reader = continueReader(PEARAI)
+export const readers: Reader[] = [reader]
+export const writers: Writer[] = [continueWriter(PEARAI)]

package/src/adapters/pi/index.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path"
+import type { Reader, Writer } from "../types.ts"
+import { piFamilyReader } from "./reader.ts"
+import type { PiFlavor } from "./records.ts"
+import { piFamilyWriter } from "./writer.ts"
+
+// Pi coding agent (earendil-works/pi, formerly badlogic/pi-mono): reads its sessions and continues any
+// session as a new native Pi session, `pi --session <id>`.
+
+/** Pi versions whose session format this writer was checked against (format version 3). */
+export const PI_TESTED_VERSIONS = ["1.5.0"]
+
+export const piFlavor: PiFlavor = {
+  tool: "pi",
+  label: "Pi",
+  bin: "pi",
+  // ~/.pi/agent/sessions; PI_CODING_AGENT_DIR and --session-dir move it, which brain does not follow.
+  sessionsRoot: (home) => join(home, ".pi", "agent", "sessions"),
+  // <start time with : and . as ->_<id>.jsonl, as SessionManager.newSession names it.
+  fileName: (id, startedAt) => `${startedAt.replace(/[:.]/g, "-")}_${id}.jsonl`,
+  newId: () => Bun.randomUUIDv7(),
+}
+
+export const piReader = piFamilyReader(piFlavor)
+export const piWriter = (version?: string) => piFamilyWriter(piFlavor, { tested: PI_TESTED_VERSIONS, ...(version ? { version } : {}) })
+
+export const readers: Reader[] = [piReader]
+export const writers: Writer[] = [piWriter()]