@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/kiro-cli/records.ts

@@ -0,0 +1,260 @@
+import { createHash } from "node:crypto"
+import { join, posix, resolve } from "node:path"
+import { versionOf } from "../../fsutil.ts"
+import type { Session, ToolKind, Turn } from "../../session/types.ts"
+import { asText, clip, iso, lossCounter, toolKindOf } from "../../session/util.ts"
+import { CONTINUED_NOTE } from "../claude-code/records.ts"
+
+// What Kiro's V3 sessions look like, shared by the Kiro CLI and Kiro IDE adapters: the V3 engine (Kiro's
+// agent server, @kiro/agent) keeps both products' sessions in one store. Checked against @kiro/agent 0.66.91
+// as Kiro CLI 3.1.0 ships it: SessionPersistence (saveSession, loadSession, listSessions, the bucket list
+// index), the record schemas (session.json and the messages.jsonl line union), messagesToContextMessages
+// (what the model is sent) and convertMessage (what the chat shows). Catalogue:
+// docs/sessions/2026-11-08-session-formats.md, "Kiro CLI" and "Kiro IDE".
+//
+// A session is ~/.kiro/sessions/<bucket>/<id>/: session.json (metadata, rewritten whole) and messages.jsonl
+// (one {id, timestamp, payload} record per line, appended). The bucket is the first 16 hex of the SHA-256 of
+// the session's sorted, normalized workspace folders; the id is sess_<uuid>. Kiro lists a workspace's
+// sessions from its bucket, through an index (<bucket>/.index/index.json) that re-walks the bucket when the
+// folder's mtime changes, so a session folder added from outside is listed like one of Kiro's own.
+
+export const TESTED_VERSIONS = ["3.1.0"]
+/** The agent engine those versions ship; the record shapes below are its own. */
+export const ENGINE = "@kiro/agent 0.66.91"
+
+export const sessionsDir = (home: string) => join(home, ".kiro", "sessions")
+
+/** "3.1.0" from `kiro-cli --version` ("kiro-cli 3.1.0"); undefined when kiro-cli is missing. */
+export const kiroCliVersion = (bin = "kiro-cli") => versionOf(bin)?.match(/\d+\.\d+\.\d+/)?.[0]
+
+/** Kiro's normalizePath: absolute, forward slashes, POSIX-normalized, no trailing slash. */
+function normalizePath(p: string): string {
+  let n = posix.normalize(resolve(p).replace(/\\/g, "/"))
+  if (n.length > 1) n = n.replace(/\/+$/, "") || n
+  return n
+}
+
+/** Kiro's computeWorkspaceHash: the bucket a session with these workspace folders lives in. */
+export function workspaceHash(paths: string[]): string {
+  if (!paths.length) return "_global"
+  const key = paths.map(normalizePath).sort().join("\0")
+  return createHash("sha256").update(key).digest("hex").slice(0, 16)
+}
+
+/** Kiro's session id rule (isValidSessionId): it refuses to load anything else. */
+export const validSessionId = (id: string) => id.length > 0 && id.length <= 128 && /^[A-Za-z0-9_-]+$/.test(id)
+
+/** session.json: the fields Kiro requires, and the optional ones this adapter reads or writes. */
+export interface KiroMetadata {
+  schemaVersion: string
+  dataModelVersion?: number
+  id: string
+  title: string
+  agentMode: string
+  workspacePaths: string[]
+  createdAt: string
+  lastModifiedAt: string
+  modelId?: string
+  parentSessionId?: string
+  status?: string
+  titleSetByUser?: boolean
+  [k: string]: unknown
+}
+
+/** One messages.jsonl line. */
+export interface KiroRow {
+  id: string
+  timestamp: string
+  payload: Record<string, any> & { type: string }
+}
+
+/** Kiro's placeholder for reasoning it did not keep. */
+const ELIDED_REASONING = "..."
+
+/**
+ * What a Kiro tool does. The V3 built-ins are read_file, fs_write, fs_append, str_replace, delete_file,
+ * list_directory, execute_bash (execute_pwsh on Windows), grep_search, file_search, web_fetch and
+ * invoke_sub_agent; MCP tools are named after their server.
+ */
+export function kiroToolKind(name: string): ToolKind {
+  switch (name) {
+    case "read_file":
+      return "read"
+    case "fs_write":
+    case "fs_append":
+      return "write"
+    case "str_replace":
+    case "delete_file":
+      return "edit"
+    case "list_directory":
+      return "list"
+    case "execute_bash":
+    case "execute_pwsh":
+      return "shell"
+    case "grep_search":
+    case "file_search":
+      return "search"
+    case "web_fetch":
+      return "web"
+    case "invoke_sub_agent":
+      return "task"
+  }
+  return toolKindOf(name)
+}
+
+const str = (v: unknown) => (typeof v === "string" ? v : undefined)
+
+/** A call as Kiro's own built-in tool would have been called, when its arguments say what that tool needs. */
+export function kiroCall(c: Extract<Turn, { kind: "tool_call" }>): { name: string; args: Record<string, unknown> } | undefined {
+  const i = (c.input && typeof c.input === "object" && !Array.isArray(c.input) ? c.input : {}) as Record<string, unknown>
+  const path = str(i.file_path) ?? str(i.path) ?? str(i.filePath) ?? str(i.target_file) ?? str(i.absolute_path)
+  switch (c.toolKind) {
+    case "shell": {
+      const command = str(i.command) ?? str(i.cmd) ?? (Array.isArray(i.command) ? (i.command as unknown[]).map(String).join(" ") : undefined)
+      return command ? { name: "execute_bash", args: { command } } : undefined
+    }
+    case "write": {
+      const text = str(i.content) ?? str(i.file_text) ?? str(i.contents) ?? str(i.text)
+      return path && text !== undefined ? { name: "fs_write", args: { path, text } } : undefined
+    }
+    case "edit": {
+      const oldStr = str(i.old_string) ?? str(i.old_str) ?? str(i.oldText) ?? str(i.oldStr)
+      const newStr = str(i.new_string) ?? str(i.new_str) ?? str(i.newText) ?? str(i.newStr)
+      return path && oldStr !== undefined && newStr !== undefined ? { name: "str_replace", args: { path, oldStr, newStr } } : undefined
+    }
+    case "read":
+      return path ? { name: "read_file", args: { path } } : undefined
+  }
+  return undefined
+}
+
+/** The chat's icon for a call (the tool_call record's `kind`). */
+export function uiKind(k: ToolKind): string {
+  switch (k) {
+    case "read":
+    case "list":
+      return "read"
+    case "edit":
+    case "write":
+      return "edit"
+    case "shell":
+      return "execute"
+    case "search":
+      return "search"
+    case "web":
+      return "fetch"
+  }
+  return "other"
+}
+
+/**
+ * Applies checkpoint reverts the way Kiro resolves tombstones: a tombstone removes the rows from the one it
+ * names up to itself. Rows before a summarization tombstone are kept, since they stay on screen.
+ */
+function revertCheckpoints(rows: KiroRow[]): KiroRow[] {
+  const out: KiroRow[] = []
+  for (const r of rows) {
+    if (r.payload.type !== "tombstone" || r.payload.kind !== "checkpoint_revert") {
+      out.push(r)
+      continue
+    }
+    // A tombstone whose target is gone is skipped, as Kiro skips it.
+    for (let at = out.length - 1; at >= 0; at--)
+      if (out[at]!.id === r.payload.effectiveFromMessageId) {
+        out.length = at
+        break
+      }
+  }
+  return out
+}
+
+/**
+ * The portable turns of a Kiro session. Everything the chat shows is history, including turns a compaction
+ * hid from the model; the compaction itself is its summary row. Returns the id of the session a brain-written
+ * session continues, when its note is there.
+ */
+export function turnsOf(rows: KiroRow[], h: Session["header"]): { turns: Turn[]; continued?: string } {
+  const turns: Turn[] = []
+  const lost = lossCounter()
+  let continued: string | undefined
+  const calls = new Map<string, Extract<Turn, { kind: "tool_call" }>>()
+  const answered = new Set<string>()
+  for (const r of revertCheckpoints(rows)) {
+    const p = r.payload
+    const at = iso(r.timestamp)
+    const stamp = at ? { at } : {}
+    switch (p.type) {
+      case "user": {
+        // Prompts Kiro makes up itself (continuations, wake-ups) are not the person's words.
+        if (p._meta?.kiro && Object.hasOwn(p._meta.kiro, "syntheticUserMessageReason")) {
+          lost.add("Kiro's own follow-up prompts (not carried)")
+          break
+        }
+        if (Array.isArray(p.images) && p.images.length) lost.add("images", p.images.length)
+        if (Array.isArray(p.documents) && p.documents.length) lost.add("documents", p.documents.length)
+        const text = String(p.content ?? "")
+        if (text.trim()) turns.push({ kind: "user", ...stamp, text })
+        break
+      }
+      case "assistant": {
+        const text = String(p.content ?? "")
+        if (p.operationType === "Summary") {
+          if (text.trim()) turns.push({ kind: "compaction", ...stamp, summary: text })
+        } else if (p.operationType === "Reasoning") {
+          if (p.reasoningRedactedContent) lost.add("redacted reasoning")
+          else if (text.trim() && text !== ELIDED_REASONING) turns.push({ kind: "reasoning", ...stamp, text })
+        } else if (text.trim()) turns.push({ kind: "assistant", ...stamp, text, ...(h.models[0] ? { model: h.models[0] } : {}) })
+        break
+      }
+      case "tool_call": {
+        const id = String(p.toolCallId)
+        const args = p.args ?? {}
+        const seen = calls.get(id)
+        // Kiro writes a call again as its approval and status change; the last arguments are the ones that ran.
+        if (seen) seen.input = args
+        else {
+          const call = { kind: "tool_call" as const, ...stamp, id, name: String(p.toolName), toolKind: kiroToolKind(String(p.toolName)), input: args }
+          calls.set(id, call)
+          turns.push(call)
+        }
+        break
+      }
+      case "tool_result": {
+        const id = String(p.toolCallId)
+        if (answered.has(id) || p.metadata?.reverted === true) break
+        answered.add(id)
+        if (Array.isArray(p.images) && p.images.length) lost.add("images in tool results", p.images.length)
+        const c = clip(asText(p.content))
+        turns.push({ kind: "tool_result", ...stamp, callId: id, ok: p.success !== false, output: c.text, ...(c.truncated ? { truncated: true } : {}) })
+        break
+      }
+      case "sub_agent_start": {
+        // The model sees a subagent as an invoke_sub_agent call answered by its final response.
+        const id = String(p.subSessionId)
+        if (calls.has(id)) break
+        const call = { kind: "tool_call" as const, ...stamp, id, name: "invoke_sub_agent", toolKind: "task" as const, input: { name: p.subAgentName, prompt: p.prompt } }
+        calls.set(id, call)
+        turns.push(call)
+        lost.add("subagent transcripts (their results stay in the parent's tool results)")
+        break
+      }
+      case "sub_agent_complete": {
+        const id = String(p.subSessionId)
+        if (answered.has(id) || !calls.has(id)) break
+        answered.add(id)
+        const c = clip(asText(p.response ?? p.errorMessage ?? ""))
+        turns.push({ kind: "tool_result", ...stamp, callId: id, ok: p.status === "success", output: c.text, ...(c.truncated ? { truncated: true } : {}) })
+        break
+      }
+      case "agent_note": {
+        const note = String(p.content ?? "").match(CONTINUED_NOTE)
+        if (note) continued = note[1]
+        else lost.add("Kiro agent notes (not carried)")
+        break
+      }
+      // Turn boundaries, usage, hooks, steering, approvals and session events are not conversation.
+    }
+  }
+  lost.flush(h)
+  return { turns, ...(continued ? { continued } : {}) }
+}

package/src/adapters/kiro-cli/writer.ts

@@ -0,0 +1,305 @@
+import { randomUUID } from "node:crypto"
+import { mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { extname, join, 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, firstUserText, unpaired } from "../../session/util.ts"
+import { continuedNote } from "../claude-code/records.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { readKiroDir } from "./reader.ts"
+import { type KiroMetadata, type KiroRow, TESTED_VERSIONS, kiroCall, kiroCliVersion, kiroToolKind, sessionsDir, uiKind, workspaceHash } from "./records.ts"
+
+// Continues a portable session as a new Kiro V3 session: a folder in ~/.kiro/sessions/<bucket>/ holding the
+// messages.jsonl and session.json that SessionPersistence.saveSession writes, with the records Kiro's own
+// turns produce. Each user turn is a turn_start, the user record, the replies (assistant "Say" text, plain
+// "Reasoning", tool_call and tool_result records paired by toolCallId) and a turn_end. Calls are mapped onto
+// Kiro's built-ins (execute_bash, fs_write, str_replace, read_file) when their arguments carry what those
+// need; others keep their names. A compaction is written as Kiro compacts: a summarization tombstone, which
+// hides the turns before it from the model while the chat still shows them, then the summary row. The note
+// saying where the session came from is an agent_note, which Kiro sends the model and never shows.
+//
+// Kiro writes nothing about a session into a shared database: it lists a workspace from its bucket folder,
+// and its list index re-walks a bucket whose folder changed. So adding a folder needs Kiro neither closed nor
+// told; only the new session's own folder is written. Readable reasoning is kept as Kiro keeps it, shown in
+// the chat; Kiro sends the model only signed reasoning, so it never reaches the model.
+
+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 NO_RESULT = "No result was recorded for this call; the session moved before it finished."
+
+type Call = Extract<Turn, { kind: "tool_call" }>
+
+export interface KiroPlan {
+  id: string
+  bucket: string
+  metadata: KiroMetadata
+  rows: KiroRow[]
+  lost: string[]
+  /** What a read-back must find. */
+  expect: { users: number; assistants: number; calls: number; compactions: number }
+}
+
+/** The session folder's contents for `session` continued in `cwd`. Pure apart from reading attached images. */
+export function planKiro(session: Session, opts: { cwd: string; now: Date; id?: string }): KiroPlan {
+  const id = opts.id ?? `sess_${randomUUID()}`
+  const label = toolLabel(session.header.tool)
+  const drops = new Map<string, number>()
+  const drop = (what: string, n = 1) => drops.set(what, (drops.get(what) ?? 0) + n)
+  const turns = session.turns
+  const lastCompaction = turns.map((t) => t.kind).lastIndexOf("compaction")
+  const expect = { users: 0, assistants: 0, calls: 0, compactions: 0 }
+  const results = new Map<string, boolean>()
+  for (const t of turns) if (t.kind === "tool_result" && !results.has(t.callId)) results.set(t.callId, t.ok)
+
+  // Tool call ids: Kiro's request builder takes [A-Za-z0-9_-], up to 64; others are mapped once.
+  const ids = new Map<string, string>()
+  const used = new Set<string>()
+  let remapped = 0
+  const callId = (raw: string) => {
+    let v = ids.get(raw)
+    if (v) return v
+    const base = /^[A-Za-z0-9_-]{1,64}$/.test(raw) ? raw : `call_${raw.replace(/[^A-Za-z0-9]/g, "").slice(-40) || "x"}`
+    v = base
+    for (let n = 2; used.has(v); n++) v = `${base}_${n}`
+    ids.set(raw, v)
+    used.add(v)
+    if (v !== raw) remapped++
+    return v
+  }
+
+  // Record times never go backwards; turns without one take the last one seen.
+  const known = turns.map((t) => (t.at ? Date.parse(t.at) : Number.NaN)).find(Number.isFinite)
+  let clock = known ?? opts.now.getTime()
+  const time = (at?: string) => {
+    const t = at ? Date.parse(at) : Number.NaN
+    if (Number.isFinite(t) && t > clock) clock = t
+    return new Date(clock).toISOString()
+  }
+
+  const rows: KiroRow[] = []
+  const push = (payload: KiroRow["payload"], at?: string, rowId: string = randomUUID()) => {
+    rows.push({ id: rowId, timestamp: time(at), payload })
+    return rowId
+  }
+  let turn: { id: string; replied: boolean } | undefined
+  const close = (at?: string) => {
+    if (!turn) return
+    push({ type: "turn_end", stopReason: turn.replied ? "end_turn" : "cancelled", executionId: turn.id, turnId: turn.id, boundarySource: "observed" }, at, `${turn.id}-turn-end`)
+    turn = undefined
+  }
+  const open = (at?: string) => {
+    turn = { id: randomUUID(), replied: false }
+    push({ type: "turn_start", executionId: turn.id, turnId: turn.id, boundarySource: "observed" }, at, `${turn.id}-turn-start`)
+  }
+  /** The current turn's identity, opening one for replies that come before any user turn. */
+  const inTurn = (at?: string) => {
+    if (!turn) open(at)
+    turn!.replied = true
+    return { executionId: turn!.id, turnId: turn!.id }
+  }
+
+  push({ type: "agent_note", content: continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10)) }, turns[0]?.at, `note_${randomUUID()}`)
+  /** The first record after the note: where a compaction's tombstone starts hiding turns from the model. */
+  const firstAfterNote = () => rows[1]?.id
+  const written = new Set<string>()
+  const done = new Set<string>()
+  const result = (raw: string, ok: boolean, output: string, at?: string) =>
+    push({ type: "tool_result", toolCallId: callId(raw), content: output || "(no output)", success: ok, ...inTurn(at) }, at)
+
+  for (const [i, t] of turns.entries()) {
+    switch (t.kind) {
+      case "user": {
+        let text = t.text
+        const images: Array<{ data: string; mimeType: string }> = []
+        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) images.push({ data: readFileSync(a.path).toString("base64"), mimeType: mime })
+          else drop("images that could not be attached")
+        }
+        if (!text.trim() && !images.length) break
+        close(t.at)
+        open(t.at)
+        push({ type: "user", content: text.trim() ? text : "(image)", source: "chat", ...(images.length ? { images } : {}) }, t.at)
+        expect.users++
+        break
+      }
+      case "assistant":
+        if (!t.text.trim()) break
+        push({ type: "assistant", content: t.text, operationType: "Say", ...inTurn(t.at) }, t.at)
+        expect.assistants++
+        break
+      case "reasoning":
+        if (!t.text.trim() || t.text === "...") break
+        push({ type: "assistant", content: t.text, operationType: "Reasoning", ...inTurn(t.at) }, t.at)
+        break
+      case "tool_call": {
+        if (written.has(t.id)) {
+          drop("repeated tool call ids")
+          break
+        }
+        written.add(t.id)
+        const mapped = kiroCall(t as Call)
+        const name = mapped?.name ?? t.name
+        const args = mapped?.args ?? (t.input && typeof t.input === "object" && !Array.isArray(t.input) ? (t.input as Record<string, unknown>) : { input: t.input ?? null })
+        const ok = results.get(t.id)
+        push(
+          { type: "tool_call", toolCallId: callId(t.id), toolName: name, args, status: ok === false || ok === undefined ? "failed" : "completed", kind: uiKind(mapped ? kiroToolKind(name) : t.toolKind), ...inTurn(t.at) },
+          t.at,
+        )
+        expect.calls++
+        if (ok === undefined) {
+          result(t.id, false, NO_RESULT, t.at)
+          done.add(t.id)
+          drop("tool calls without a result (closed as errors)")
+        }
+        break
+      }
+      case "tool_result": {
+        if (!written.has(t.callId)) {
+          drop("tool results without a call")
+          break
+        }
+        if (done.has(t.callId)) {
+          drop("repeated tool results")
+          break
+        }
+        done.add(t.callId)
+        result(t.callId, t.ok, t.fullPath ? `${t.output}\n\n[Full output: ${t.fullPath}]` : t.output, t.at)
+        break
+      }
+      case "compaction": {
+        close(t.at)
+        const summary = `[Summary of the earlier conversation in ${label}, which replaced the turns before it]\n\n${t.summary}`
+        const from = firstAfterNote()
+        // Only the last compaction hides turns: Kiro resolves a tombstone against the rows still in effect.
+        if (i === lastCompaction && from)
+          push({ type: "tombstone", kind: "summarization", effectiveFromMessageId: from, metadata: { truncatedMessageCount: rows.length - 1, truncatedAt: time(t.at) } }, t.at, `tombstone_summarize_${randomUUID()}`)
+        push({ type: "assistant", content: summary, operationType: "Summary" }, t.at, `summary_${randomUUID()}`)
+        expect.compactions++
+        break
+      }
+      case "file_edit":
+        if (!t.callId || !written.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
+    }
+  }
+  close()
+
+  const first = rows[0]?.timestamp ?? opts.now.toISOString()
+  const title = session.header.title ?? firstUserText(session)?.replace(/\s+/g, " ").trim().slice(0, 60) ?? "Session"
+  const metadata: KiroMetadata = {
+    schemaVersion: "1.0.0",
+    dataModelVersion: 1,
+    id,
+    title: `${title} (from ${label})`,
+    agentMode: "vibe",
+    workspacePaths: [opts.cwd],
+    createdAt: first,
+    lastModifiedAt: opts.now.toISOString(),
+    status: "idle",
+    titleSetByUser: true,
+  }
+  const lost = [...drops].map(([what, n]) => `${what} (${n})`)
+  if (remapped) lost.push(`tool call ids, remapped to ids Kiro accepts (${remapped})`)
+  return { id, bucket: workspaceHash([opts.cwd]), metadata, rows, lost, expect }
+}
+
+/** The kiro-cli binary: the installer's ~/.local/bin/kiro-cli first, else whatever is on PATH. */
+function resolveBin(home: string): { path: string; command: string } {
+  const own = join(home, ".local", "bin", "kiro-cli")
+  if (exists(own)) return { path: own, command: Bun.which("kiro-cli") === own ? "kiro-cli" : own }
+  return { path: "kiro-cli", command: "kiro-cli" }
+}
+
+/**
+ * The folder as Kiro CLI reports it to its engine (the process's current directory, so with symlinks
+ * resolved: /tmp is /private/tmp on macOS); the session's bucket is keyed by it.
+ */
+export function realCwd(cwd: string): string {
+  try {
+    return realpathSync(cwd)
+  } catch {
+    return resolve(cwd)
+  }
+}
+
+export const sh = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+export interface KiroTarget {
+  tool: string
+  label: string
+  ready(w: WriteOptions): Promise<Readiness>
+  /** How the person opens the new session: a command, and what to do after it. */
+  open(w: { home: string; cwd: string; id: string; title: string }): { open: string; note?: string }
+}
+
+/** A writer into the shared store for one Kiro product. */
+export function kiroWriter(target: KiroTarget): Writer {
+  return {
+    tool: target.tool,
+    label: target.label,
+    way: "native",
+    ready: (w) => target.ready(w),
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const cwd = realCwd(w.cwd)
+      const plan = planKiro(session, { cwd, now: new Date() })
+      const dir = join(sessionsDir(w.home), plan.bucket, plan.id)
+      const files = [join(dir, "messages.jsonl"), join(dir, "session.json")]
+      const how = target.open({ home: w.home, cwd, id: plan.id, title: plan.metadata.title })
+      const result = { tool: target.tool, way: "native" as const, sessionId: plan.id, written: files, ...how, lost: plan.lost }
+      if (w.dryRun) return { ...result, dryRun: true }
+
+      // Kiro's own modes: the folders private to the person, the files too. The transcript goes first, as
+      // Kiro saves it, so a folder with a session.json is always complete.
+      mkdirSync(dir, { recursive: true, mode: 0o700 })
+      writeFileSync(files[0]!, `${plan.rows.map((r) => JSON.stringify(r)).join("\n")}\n`, { flag: "wx", mode: 0o600 })
+      writeFileSync(files[1]!, JSON.stringify(plan.metadata, null, 2), { flag: "wx", mode: 0o600 })
+
+      // Read it back as the reader reads Kiro; a session that does not round-trip is removed again.
+      const back = readKiroDir(dir, w.home, target.tool)
+      const n = countTurns(back)
+      const pairs = unpaired(back)
+      const e = plan.expect
+      if (n.user !== e.users || n.assistant !== e.assistants || n.tool_call !== e.calls || n.compaction !== e.compactions || pairs.calls.length || pairs.results.length) {
+        rmSync(dir, { recursive: true, force: true })
+        throw new Error(
+          `the new Kiro session did not read back as written (users ${n.user}/${e.users}, replies ${n.assistant}/${e.assistants}, tool calls ${n.tool_call}/${e.calls}, summaries ${n.compaction}/${e.compactions}, unpaired ${pairs.calls.length + pairs.results.length}); it was removed`,
+        )
+      }
+      return { ...result, dryRun: false }
+    },
+  }
+}
+
+/** Kiro CLI: its V3 engine (the default since 3.0) resumes the session by id from the folder it ran in. */
+export function kiroCliWriter(opts: { bin?: string; version?: string } = {}): Writer {
+  const binFor = (home: string) => (opts.bin ? { path: opts.bin, command: opts.bin } : resolveBin(home))
+  return kiroWriter({
+    tool: "kiro-cli",
+    label: "Kiro CLI",
+    async ready(w) {
+      const v = opts.version ?? kiroCliVersion(binFor(w.home).path)
+      if (!v) return { ok: false, why: "Kiro CLI is not installed (`kiro-cli --version` did not run)" }
+      if (!TESTED_VERSIONS.includes(v)) return { ok: false, why: `Kiro CLI ${v} is not a version this writer was checked against (${TESTED_VERSIONS.join(", ")})` }
+      if (!isDir(w.cwd)) return { ok: false, why: `the folder to continue in does not exist: ${w.cwd}` }
+      return { ok: true }
+    },
+    open: ({ home, cwd, id }) => ({ open: `cd ${sh(cwd)} && ${sh(binFor(home).command)} chat --resume-id ${id}` }),
+  })
+}
+
+export const kiroCliNativeWriter = kiroCliWriter()

package/src/adapters/kiro-ide/index.ts

@@ -0,0 +1,8 @@
+import type { Reader, Writer } from "../types.ts"
+import { kiroIdeNativeWriter } from "./writer.ts"
+
+// Kiro IDE: continues any session as a new chat in Kiro's V3 session store. The IDE shares that store with
+// Kiro CLI, whose reader (kiro-cli) lists and reads both products' sessions; a second reader here would list
+// every session twice, since a session does not record which product made it.
+export const readers: Reader[] = []
+export const writers: Writer[] = [kiroIdeNativeWriter]

package/src/adapters/kiro-ide/writer.ts

@@ -0,0 +1,52 @@
+import { join } from "node:path"
+import { exists, isDir } from "../../fsutil.ts"
+import type { Writer } from "../types.ts"
+import { kiroWriter, sh } from "../kiro-cli/writer.ts"
+import { ENGINE } from "../kiro-cli/records.ts"
+
+// Continues a portable session in Kiro IDE. Since 1.0 the IDE keeps its chats in the same V3 store as Kiro
+// CLI (~/.kiro/sessions/<bucket>/<id>/, the bucket keyed by the workspace's folders), so the session is
+// written exactly as for the CLI and appears in the IDE's chat history for that folder.
+//
+// The shape was checked against the agent engine Kiro CLI 3.1.0 ships (see ENGINE), not against an IDE: no
+// Kiro IDE was available to check which engine it bundles. So no IDE version is listed as tested yet, and
+// ready() says so; add a version here once a session written by this writer has been opened in it.
+
+export const TESTED_IDE_VERSIONS: string[] = []
+
+/** Where Kiro IDE is installed, if it is: the system Applications folder or the person's own. */
+export function kiroApp(home: string): string | undefined {
+  return ["/Applications/Kiro.app", join(home, "Applications", "Kiro.app")].find((p) => isDir(p))
+}
+
+/** The app's CFBundleShortVersionString, e.g. "1.4.121". */
+export function appVersion(app: string): string | undefined {
+  const plist = join(app, "Contents", "Info.plist")
+  if (!exists(plist)) return undefined
+  const p = Bun.spawnSync(["plutil", "-extract", "CFBundleShortVersionString", "raw", plist], { stdout: "pipe", stderr: "pipe" })
+  return p.exitCode === 0 ? p.stdout.toString().trim() || undefined : undefined
+}
+
+/** The Kiro IDE writer; `app` and `version` are for tests, which must not depend on an installed Kiro. */
+export function kiroIdeWriter(opts: { app?: string; version?: string; tested?: string[] } = {}): Writer {
+  const tested = opts.tested ?? TESTED_IDE_VERSIONS
+  return kiroWriter({
+    tool: "kiro-ide",
+    label: "Kiro IDE",
+    async ready(w) {
+      const app = opts.app ?? kiroApp(w.home)
+      if (!app || !isDir(app)) return { ok: false, why: "Kiro IDE is not installed (no Kiro.app in /Applications or ~/Applications)" }
+      const v = opts.version ?? appVersion(app)
+      if (!v || !tested.includes(v))
+        return {
+          ok: false,
+          why: `Kiro IDE ${v ?? "(unknown version)"} is not a version this writer was checked against (${tested.join(", ") || `none yet; the format was checked against ${ENGINE} in Kiro CLI 3.1.0`})`,
+        }
+      if (!isDir(w.cwd)) return { ok: false, why: `the folder to continue in does not exist: ${w.cwd}` }
+      return { ok: true }
+    },
+    open: ({ cwd, title }) => ({ open: `open -a Kiro ${sh(cwd)}`, note: `In Kiro's chat, open the session history and pick "${title}".` }),
+  })
+}
+
+export const kiroIdeNativeWriter = kiroIdeWriter()

package/src/adapters/letta/index.ts

@@ -0,0 +1,8 @@
+import type { Reader, Writer } from "../types.ts"
+import { lettaReader } from "./reader.ts"
+import { lettaNativeWriter } from "./writer.ts"
+
+// Letta Code: reads and writes conversations of the local backend's agents (~/.letta/lc-local-backend).
+// Server ("cloud") agents keep their history on the Letta server and are not on disk.
+export const readers: Reader[] = [lettaReader]
+export const writers: Writer[] = [lettaNativeWriter]