@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/claude-code/records.ts

@@ -0,0 +1,88 @@
+import { join } from "node:path"
+import { versionOf } from "../../fsutil.ts"
+
+// What Claude Code's transcripts look like, as far as this adapter relies on it. Checked against the
+// transcripts on the author's Mac (versions 2.1.209 to 2.1.317, structure and counts only) and the
+// installed binary, 2.1.316. Catalogue: docs/sessions/2026-11-08-session-formats.md, entries 1 and 2.
+
+export const TOOL = "claude-code"
+export const LABEL = "Claude Code"
+
+/**
+ * Versions the writer's record shape was checked against: the CLI-written transcripts on the author's Mac
+ * (2.1.296 to 2.1.316) and the version Claude Desktop bundles (2.1.317). Outside this range the writer
+ * says so and the switcher falls back to the brief.
+ */
+export const TESTED = { min: "2.1.296", max: "2.1.319" }
+
+export const projectsDir = (home: string) => join(home, ".claude", "projects")
+
+/** A main transcript is `<session uuid>.jsonl`; set-aside copies (.orphaned-, .superseded-) are not sessions. */
+export const SESSION_FILE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/i
+
+/**
+ * Claude Code's project folder for a cwd, as 2.1.316 derives it: every non-alphanumeric becomes '-', and
+ * a name over 200 characters is cut to 200 and suffixed with a base-36 string hash of the full path (the
+ * `(h << 5) - h + charCode` hash Claude Code uses, so the folder matches the one it would pick itself).
+ */
+export function projectSlug(cwd: string): string {
+  const slug = cwd.replace(/[^a-zA-Z0-9]/g, "-")
+  if (slug.length <= 200) return slug
+  let h = 0
+  for (let i = 0; i < cwd.length; i++) h = ((h << 5) - h + cwd.charCodeAt(i)) | 0
+  return `${slug.slice(0, 200)}-${Math.abs(h).toString(36)}`
+}
+
+/** "2.1.316 (Claude Code)" → "2.1.316". */
+export const semver = (v: string | undefined) => v?.match(/(\d+)\.(\d+)\.(\d+)/)?.[0]
+
+function compare(a: string, b: string): number {
+  const x = a.split(".").map(Number)
+  const y = b.split(".").map(Number)
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0)
+  return 0
+}
+
+export function testedVersion(v: string | undefined): boolean {
+  const s = semver(v)
+  return !!s && compare(s, TESTED.min) >= 0 && compare(s, TESTED.max) <= 0
+}
+
+/**
+ * A release newer than the ones checked but on the same minor line (2.1.x): Claude Code ships patch releases daily
+ * and has not changed the record shapes this writer relies on between them (2.1.296 to 2.1.319). A new minor or major
+ * is still refused until it has been checked.
+ */
+export function newerPatch(v: string | undefined): boolean {
+  const s = semver(v)
+  if (!s) return false
+  const [maj, min] = s.split(".")
+  const [tmaj, tmin] = TESTED.max.split(".")
+  return maj === tmaj && min === tmin && compare(s, TESTED.max) > 0
+}
+
+/** The installed Claude Code version, or undefined when `claude` is not on the PATH. */
+export const claudeVersion = (bin = "claude") => semver(versionOf(bin))
+
+/** Records that make up the conversation tree (they carry uuid and parentUuid). `progress` is from older versions. */
+export const CHAIN_TYPES = new Set(["user", "assistant", "system", "attachment", "progress"])
+
+/**
+ * Record types Claude Code writes beside the conversation: titles, request logs, modes, latches, file
+ * checkpoints, links. Skipped without counting them as lost; anything not here or in CHAIN_TYPES is
+ * counted as an unknown record type.
+ */
+export const HOUSEKEEPING = new Set([
+  "api-request", "api-request-blob", "api-request-shape", "last-prompt", "custom-title", "ai-title", "agent-name",
+  "summary", "atis-latch", "isolation-latch", "bridge-session", "queue-operation", "mode", "permission-mode",
+  "pr-link", "history-suppression", "file-history-snapshot", "file-history-delta", "frame-link", "cost-state",
+  "artifact-autoreact-ledger", "artifact-comment-monitor", "tools-used", "relocated",
+])
+
+/** Attachments that point at a file the person mentioned; the rest (reminders, environment, listings) are context, not conversation. */
+export const FILE_ATTACHMENTS = new Set(["file", "compact_file_reference", "pdf_reference"])
+
+/** The first message of a session the writer creates; the reader recognises it and records where the session came from. */
+export const continuedNote = (label: string, id: string, when: string) =>
+  `[This session continues ${label} session ${id}, carried over by brain session on ${when}. The turns below are its history; reasoning and anything listed as lost did not carry over. Check files before relying on details, since they may have changed.]`
+export const CONTINUED_NOTE = /^\[This session continues .+? session (\S+), carried over by brain session/

package/src/adapters/claude-code/writer.ts

@@ -0,0 +1,329 @@
+import { randomBytes, 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, gitInfo, isDir } from "../../fsutil.ts"
+import type { Session, Turn, Usage } from "../../session/types.ts"
+import { countTurns, firstUserText, unpaired } from "../../session/util.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { claudeCodeReader } from "./reader.ts"
+import { LABEL, TESTED, TOOL, claudeVersion, continuedNote, newerPatch, projectSlug, projectsDir, testedVersion } from "./records.ts"
+
+// Continues a portable session in Claude Code as a new session: a transcript written where Claude Code
+// keeps its own (~/.claude/projects/<slug of cwd>/<new uuid>.jsonl), which `claude --resume <uuid>` opens.
+//
+// The records copy the shape of transcripts Claude Code 2.1.296-2.1.317 writes from the CLI: user and
+// assistant records on one uuid/parentUuid chain, with sessionId, cwd, gitBranch, version, entrypoint
+// "cli" and userType "external" (so the session shows in the resume picker like any CLI session). Each
+// assistant response is split one content block per record under a shared message.id, as Claude Code
+// does, and each tool result is its own user record pointing back at its call (sourceToolAssistantUUID).
+// The chain is kept linear (results follow the last call of their response), a shape Claude Code also
+// writes and that needs no re-attaching of parallel results when it loads.
+//
+// A compaction is written as Claude Code writes its own: a compact_boundary record that starts a new chain
+// (parentUuid null, logicalParentUuid pointing back) and the summary as the next record. Claude Code loads
+// a session from its last boundary on, so a long session continues from its summary instead of sending
+// the model every turn the summary replaced; those turns stay in the file.
+//
+// Reasoning is dropped: Claude's thinking replays only with its signature, which cannot be made for text
+// from elsewhere. Tool call ids are remapped to toolu_ ids, every call gets a result (a missing one is
+// closed as an error), and the file is read back before the session is offered.
+
+const ALNUM = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+const randomId = (prefix: string, n: number) => prefix + [...randomBytes(n)].map((b) => ALNUM[b % ALNUM.length]).join("")
+
+const shellQuote = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+/** Claude Code records the resolved folder (/private/tmp, not /tmp), and names the project folder after it. */
+function realCwd(cwd: string): string {
+  try {
+    return realpathSync(cwd)
+  } catch {
+    return cwd
+  }
+}
+
+/** Tool names the API accepts: letters, digits, _ and -, at most 128. */
+const toolName = (name: string) => name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128) || "tool"
+
+/**
+ * What Codex's unified exec wrote for a command, as Claude Code's Bash result reads: the output itself, and for a
+ * failure its "Exit code N" first line. Anything that is not that format is left as it is.
+ */
+function fromUnifiedExec(text: string): string {
+  const m = text.match(/^(?:Chunk ID: [^\n]*\n)?(?:Wall time: [^\n]*\n)?Process exited with code (-?\d+)\n(?:Original token count: [^\n]*\n)?Output:\n([\s\S]*)$/)
+  if (!m) return text
+  return m[1] === "0" ? m[2]! : `Exit code ${m[1]}\n${m[2]}`
+}
+
+/** tool_use input must be an object; other tools sometimes pass a raw string (apply_patch) or an array. */
+const toolInput = (input: unknown): Record<string, unknown> =>
+  input && typeof input === "object" && !Array.isArray(input) ? (input as Record<string, unknown>) : { input: input ?? null }
+
+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
+
+type Block = Record<string, unknown>
+type Call = Extract<Turn, { kind: "tool_call" }>
+type Result = Extract<Turn, { kind: "tool_result" }>
+
+/** The conversation as API-shaped messages, before ids, chain and timestamps are assigned. */
+type Msg =
+  /** `meta`: written as Claude Code's isMeta record, which the model reads but which is not the person's words. */
+  | { role: "user"; at?: string; content: string | Block[]; meta?: boolean }
+  | { role: "assistant"; at?: string; model: string; usage?: Usage; blocks: Block[]; calls: Call[] }
+  | { role: "compaction"; at?: string; summary: string }
+
+export interface TranscriptPlan {
+  /** Every record of the new transcript, in order. */
+  lines: Array<Record<string, unknown>>
+  /** What the new session cannot keep. */
+  lost: string[]
+  /** What a read-back must find. */
+  expect: { calls: number }
+}
+
+/** The records of a new Claude Code session `sessionId` continuing `session`. Pure apart from reading attached images. */
+export function planTranscript(
+  session: Session,
+  opts: { sessionId: string; cwd: string; version: string; gitBranch: string; now: Date },
+): TranscriptPlan {
+  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 note saying where the session came from is meta: readers (and so the brief) must not take it for the first request.
+  // Shell calls from tools that run them under another name (Codex's exec_command takes `cmd`) come back as Bash.
+  const shellMapped = new Set<string>()
+  const msgs: Msg[] = [{ role: "user", content: continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10)), meta: true }]
+  let cur: Extract<Msg, { role: "assistant" }> | undefined
+  let model = session.header.models[session.header.models.length - 1] ?? "unknown"
+  const flush = () => {
+    if (cur?.blocks.length) msgs.push(cur)
+    cur = undefined
+  }
+  const assistant = (at?: string) => (cur ??= { role: "assistant", ...(at ? { at } : {}), model, blocks: [], calls: [] })
+  const seen = new Set<string>()
+
+  for (const t of session.turns) {
+    switch (t.kind) {
+      case "user": {
+        flush()
+        const blocks: Block[] = []
+        let text = t.text
+        for (const a of t.attachments ?? []) {
+          if (!a.path) continue // bytes the reader could not keep; it already counted them
+          if (a.kind === "file") {
+            text += `\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) {
+            blocks.push({ type: "image", source: { type: "base64", media_type: mime, data: readFileSync(a.path).toString("base64") } })
+          } else drop("images that could not be attached")
+        }
+        if (!text.trim() && !blocks.length) break
+        msgs.push({ role: "user", ...(t.at ? { at: t.at } : {}), content: blocks.length ? [{ type: "text", text: text.trim() ? text : "(image)" }, ...blocks] : text })
+        break
+      }
+      case "compaction":
+        flush()
+        msgs.push({ role: "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 "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.model) model = t.model
+        assistant(t.at)
+        if (t.model && !cur!.blocks.length) cur!.model = t.model
+        if (t.text.trim()) cur!.blocks.push({ type: "text", text: t.text })
+        if (t.usage && !cur!.usage) cur!.usage = t.usage
+        break
+      case "tool_call":
+        if (seen.has(t.id)) break
+        seen.add(t.id)
+        {
+          const raw = t.input && typeof t.input === "object" && !Array.isArray(t.input) ? (t.input as Record<string, unknown>) : undefined
+          const asBash = t.toolKind === "shell" && t.name !== "Bash" && typeof raw?.cmd === "string"
+          if (asBash) shellMapped.add(t.id)
+          assistant(t.at).blocks.push({
+            type: "tool_use",
+            id: "",
+            name: asBash ? "Bash" : toolName(t.name),
+            input: asBash ? { command: raw!.cmd } : toolInput(t.input),
+            caller: { type: "direct" },
+          })
+        }
+        cur!.calls.push(t)
+        break
+      case "tool_result":
+        // Written right after its call's response; a result whose call never came is dropped. A result
+        // closes the response it answers, so a call made 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":
+        drop("reasoning (Claude Code replays thinking only with its signature)")
+        break
+      case "file_edit":
+        if (!t.callId || !callIds.has(t.callId)) drop("file edits outside a tool call")
+        break
+      case "subagent":
+        drop("subagent transcripts (their results stay in the parent's tool results)")
+        break
+    }
+  }
+  flush()
+
+  // Records, on one chain, with timestamps that never go backwards.
+  const lines: Array<Record<string, unknown>> = []
+  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 + 1
+    return new Date(clock).toISOString()
+  }
+  let parent: string | null = null
+  let promptId = randomUUID()
+  // Characters of conversation since the last compaction, for the boundary's token estimate.
+  let chars = 0
+  const common = (at?: string) => ({ timestamp: stamp(at), userType: "external", entrypoint: "cli", cwd: opts.cwd, sessionId: opts.sessionId, version: opts.version, gitBranch: opts.gitBranch })
+  const push = (fields: Record<string, unknown>, at?: string) => {
+    const uuid = randomUUID()
+    lines.push({ parentUuid: parent, isSidechain: false, ...fields, uuid, ...common(at) })
+    parent = uuid
+    const message = fields.message as { content?: unknown } | undefined
+    if (message) chars += JSON.stringify(message.content ?? "").length
+    return uuid
+  }
+  let calls = 0
+  let lastPrompt = ""
+  for (const m of msgs) {
+    if (m.role === "compaction") {
+      const before = parent
+      const preTokens = Math.round(chars / 4)
+      parent = null
+      push({ logicalParentUuid: before, type: "system", subtype: "compact_boundary", content: "Conversation compacted", isMeta: false, level: "info", compactMetadata: { trigger: "auto", preTokens, postTokens: Math.round(m.summary.length / 4) } }, m.at)
+      chars = 0
+      promptId = randomUUID()
+      push({ promptId, type: "user", message: { role: "user", content: m.summary }, isVisibleInTranscriptOnly: true, isCompactSummary: true }, m.at)
+      continue
+    }
+    if (m.role === "user") {
+      if (m.meta) {
+        push({ type: "user", message: { role: "user", content: m.content }, isMeta: true }, m.at)
+        continue
+      }
+      promptId = randomUUID()
+      if (typeof m.content === "string") lastPrompt = m.content
+      push({ promptId, type: "user", message: { role: "user", content: m.content } }, m.at)
+      continue
+    }
+    const id = randomId("msg_01", 22)
+    const requestId = randomId("req_011C", 20)
+    const usage = { input_tokens: m.usage?.input ?? 0, cache_creation_input_tokens: m.usage?.cacheWrite ?? 0, cache_read_input_tokens: m.usage?.cacheRead ?? 0, output_tokens: m.usage?.output ?? 0, service_tier: "standard" }
+    const stop = m.calls.length ? "tool_use" : "end_turn"
+    const byCall = new Map<Call, { toolu: string; record: string }>()
+    let k = 0
+    m.blocks.forEach((b, i) => {
+      if (b.type === "tool_use") {
+        const call = m.calls[k++]!
+        b.id = randomId("toolu_01", 22)
+        const record = push({ message: { model: m.model, id, type: "message", role: "assistant", content: [b], stop_reason: stop, stop_sequence: null, usage }, requestId, type: "assistant", apiBlockIndex: i }, m.at)
+        byCall.set(call, { toolu: b.id as string, record })
+        calls++
+      } else push({ message: { model: m.model, id, type: "message", role: "assistant", content: [b], stop_reason: stop, stop_sequence: null, usage }, requestId, type: "assistant", apiBlockIndex: i }, m.at)
+    })
+    for (const call of m.calls) {
+      const { toolu, record } = byCall.get(call)!
+      const r = results.get(call.id)
+      if (!r) drop("tool calls without a result (closed as errors)")
+      const ok = r?.ok ?? false
+      let output = r?.output ?? "No result was recorded for this call; the session moved before it finished."
+      if (r && shellMapped.has(call.id)) output = fromUnifiedExec(output)
+      if (r?.fullPath) output += `\n\n[Full output: ${r.fullPath}]`
+      if (!output.trim()) output = "(no output)"
+      // toolUseResult is what Claude Code's UI renders from; it checks the shape first, so a plain string is
+      // safe for any tool. Bash's own shape is simple enough to rebuild.
+      const toolUseResult = !ok ? `Error: ${output}` : call.name === "Bash" || shellMapped.has(call.id) ? { stdout: output, stderr: "", interrupted: false, isImage: false, noOutputExpected: false } : output
+      push(
+        {
+          promptId,
+          type: "user",
+          message: { role: "user", content: [{ tool_use_id: toolu, type: "tool_result", content: output, ...(ok ? {} : { is_error: true }) }] },
+          toolUseResult,
+          sourceToolAssistantUUID: record,
+        },
+        r?.at ?? m.at,
+      )
+    }
+  }
+
+  const title = session.header.title ?? firstUserText(session)?.replace(/\s+/g, " ").trim().slice(0, 60) ?? "Session"
+  lines.push({ type: "custom-title", customTitle: `${title} (from ${label})`, sessionId: opts.sessionId })
+  lines.push({ type: "last-prompt", lastPrompt: lastPrompt.slice(0, 500), leafUuid: parent, sessionId: opts.sessionId })
+  return { lines, lost: [...drops].map(([what, n]) => `${what} (${n})`), expect: { calls } }
+}
+
+/** The Claude Code writer; `version` and `bin` are for tests, which must not depend on the installed binary. */
+export function claudeCodeWriter(opts: { bin?: string; version?: string } = {}): Writer {
+  const installed = () => opts.version ?? claudeVersion(opts.bin)
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(w: WriteOptions): Promise<Readiness> {
+      const v = installed()
+      if (!v) return { ok: false, why: "Claude Code is not installed (`claude --version` did not run)" }
+      if (!testedVersion(v) && !newerPatch(v)) return { ok: false, why: `Claude Code ${v} is not a version this writer was checked against (${TESTED.min} to ${TESTED.max})` }
+      if (!isDir(w.cwd)) return { ok: false, why: `${w.cwd} is not a folder; Claude Code resumes a session in the folder it belongs to` }
+      return { ok: true }
+    },
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const cwd = realCwd(w.cwd)
+      const git = gitInfo(cwd)
+      const version = installed() ?? TESTED.max
+      let sessionId = randomUUID()
+      const dir = join(projectsDir(w.home), projectSlug(cwd))
+      while (exists(join(dir, `${sessionId}.jsonl`))) sessionId = randomUUID()
+      const path = join(dir, `${sessionId}.jsonl`)
+      const plan = planTranscript(session, { sessionId, cwd, version, gitBranch: git.gitBranch ?? (git.gitCommit ? "HEAD" : ""), now: new Date() })
+      if (!w.dryRun) {
+        mkdirSync(dir, { recursive: true })
+        // "wx": a new file only; an existing session is never touched.
+        writeFileSync(path, `${plan.lines.map((l) => JSON.stringify(l)).join("\n")}\n`, { flag: "wx" })
+        const back = await claudeCodeReader.read({ tool: TOOL, sourceId: sessionId, path }, w.home)
+        const pairs = unpaired(back)
+        const got = countTurns(back).tool_call
+        if (got !== plan.expect.calls || pairs.calls.length || pairs.results.length) {
+          rmSync(path, { force: true })
+          throw new Error(`the new Claude Code transcript did not read back intact (${got} of ${plan.expect.calls} tool calls, ${pairs.calls.length + pairs.results.length} unpaired); nothing was kept`)
+        }
+      }
+      return {
+        tool: TOOL,
+        way: "native",
+        sessionId,
+        written: [path],
+        open: `cd ${shellQuote(cwd)} && claude --resume ${sessionId}`,
+        lost: newerPatch(version) ? [...plan.lost, `Claude Code ${version} is newer than the versions this writer was checked against (${TESTED.min} to ${TESTED.max}); the record shapes it relies on have not changed between patch releases`] : plan.lost,
+        dryRun: !!w.dryRun,
+      }
+    },
+  }
+}
+
+export const claudeCodeNativeWriter = claudeCodeWriter()

package/src/adapters/cline/index.ts

@@ -0,0 +1,12 @@
+import type { Reader, Writer } from "../types.ts"
+import { taskReader } from "./reader.ts"
+import { taskWriters } from "./writer.ts"
+
+// Cline's classic task folders, and Roo Code's, which share the layout (catalogue entries 37 and 39). Both
+// are read from every VS Code-family editor, and continued as a new native task in the editor named by the
+// writer: `cline` and `roo` write to VS Code, `cline-cursor`, `roo-cursor` (and -windsurf) to the others.
+export const readers: Reader[] = [
+  taskReader({ tool: "cline", label: "Cline", extension: "saoudrizwan.claude-dev" }),
+  taskReader({ tool: "roo", label: "Roo Code", extension: "rooveterinaryinc.roo-cline" }),
+]
+export const writers: Writer[] = taskWriters