@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/kimi/writer.ts

@@ -0,0 +1,367 @@
+import { randomUUID } from "node:crypto"
+import { appendFileSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { toolLabel } from "../../brief.ts"
+import { exists, isDir, versionOf } from "../../fsutil.ts"
+import type { Session, Turn } from "../../session/types.ts"
+import { imageDataUrl } from "../../session/attachments.ts"
+import { countTurns, firstUserText, unpaired } from "../../session/util.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { reader } from "./reader.ts"
+import { LABEL, META_VERSION, TOOL, WIRE_PROTOCOL, workDirKey } from "./records.ts"
+
+// Continues a portable session in Kimi Code as a new session of its own: sessions/<wd_slug_hash>/<id>/
+// with agents/main/wire.jsonl and state.json, plus its line in session_index.jsonl. `kimi session list`
+// lists it and `kimi --session <id>` resumes it.
+//
+// The records are the ones Kimi Code writes for a session converted from another tool (migration-legacy's
+// writeMainAgentWire and writeImportedSession): per turn a turn.prompt, the turn's messages as
+// context.append_message, and turn.ended, so the turn clock resumes past them. Unlike Kimi's own importer,
+// which packs a foreign conversation into one message, every message stays its own: assistant messages
+// carry their tool calls (Kimi's own tools where the arguments fit: Read, Write, Edit, Bash, Glob, Grep),
+// each answered by a tool message, failures marked isError. Readable reasoning stays as think parts.
+// The wire header is protocol 1.5, as Kimi Code 2.5.2 writes a new session; state.json is written last.
+//
+// The note saying where the session came from is a system reminder (origin kind "injection"), the way Kimi
+// injects context it does not show as the person's words. A compaction is written as Kimi writes one:
+// full_compaction.begin, context.apply_compaction and full_compaction.complete. The earlier turns stay on
+// screen and the model starts from the summary.
+
+/** Kimi Code versions whose session store this writer was checked against. */
+export const TESTED_VERSIONS = ["2.5.2"]
+
+/** The installed version (`kimi --version` prints "2.5.2"), or undefined when it is missing. */
+export function kimiVersion(bin = "kimi"): string | undefined {
+  return versionOf(bin)?.match(/(\d+\.\d+\.\d+(?:-[\w.]+)?)/)?.[1]
+}
+
+/** The note's injection variant; readers skip injections. */
+export const NOTE_VARIANT = "brain_continuation"
+
+const reminder = (text: string) => `<system-reminder>\n${text.trim()}\n</system-reminder>`
+const continuedNote = (label: string, id: string, when: string) =>
+  reminder(
+    `This session continues ${label} session ${id}, carried over by brain session on ${when}. The turns below are its history; anything listed as lost did not carry over. Check files before relying on details, since they may have changed.`,
+  )
+
+const shellQuote = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+/** Kimi records the folder its process runs in, which is the resolved path (/private/tmp, not /tmp). */
+function realCwd(cwd: string): string {
+  try {
+    return realpathSync(cwd)
+  } catch {
+    return cwd
+  }
+}
+
+type Call = Extract<Turn, { kind: "tool_call" }>
+type Json = Record<string, unknown>
+type Part = { type: "text"; text: string } | { type: "think"; think: string } | { type: "image_url"; imageUrl: { url: string } }
+type Message =
+  | { role: "user"; content: Part[]; toolCalls: []; origin: Json }
+  | { role: "assistant"; content: Part[]; toolCalls: Array<{ type: "function"; id: string; name: string; arguments: string }> }
+  | { role: "tool"; content: Part[]; toolCalls: []; toolCallId: string; isError?: true }
+
+// Argument names other tools use for the same thing.
+const FILE = ["file_path", "path", "filePath", "absolute_path", "target_file", "file", "filename"]
+const OLD = ["old_string", "oldString", "old_str", "old_text"]
+const NEW = ["new_string", "newString", "new_str", "new_text"]
+const CONTENT = ["content", "contents", "file_text", "text"]
+const COMMAND = ["command", "cmd", "commandLine"]
+const PATTERN = ["pattern", "regex", "query", "glob_pattern"]
+const DIR = ["path", "dir_path", "directory", "target_directory"]
+
+/** The call as Kimi Code's own tool when its arguments fit one; otherwise undefined and it keeps its own. */
+export function kimiTool(c: Call): { name: string; args: Json } | undefined {
+  const input = c.input && typeof c.input === "object" && !Array.isArray(c.input) ? (c.input as Json) : {}
+  const str = (keys: string[]) => {
+    const v = keys.map((k) => input[k]).find((x) => typeof x === "string" || (Array.isArray(x) && x.every((y) => typeof y === "string")))
+    return Array.isArray(v) ? v.join(" ") : (v as string | undefined)
+  }
+  const path = str(FILE)
+  switch (c.toolKind) {
+    case "read":
+      return path ? { name: "Read", args: { path } } : undefined
+    case "edit": {
+      const [o, n] = [str(OLD), str(NEW)]
+      return path && o && n !== undefined ? { name: "Edit", args: { path, old_string: o, new_string: n } } : undefined
+    }
+    case "write": {
+      const content = str(CONTENT)
+      return path && content !== undefined ? { name: "Write", args: { path, content } } : undefined
+    }
+    case "shell": {
+      const command = str(COMMAND)
+      return command ? { name: "Bash", args: { command } } : undefined
+    }
+    case "search": {
+      const pattern = str(PATTERN)
+      const dir = str(DIR)
+      return pattern ? { name: /glob/i.test(c.name) ? "Glob" : "Grep", args: { pattern, ...(dir ? { path: dir } : {}) } } : undefined
+    }
+    default:
+      return undefined
+  }
+}
+
+export interface WirePlan {
+  records: Json[]
+  lost: string[]
+  /** What a read-back must find. */
+  expect: { users: number; assistants: number; calls: number; compactions: number }
+  title: string
+  lastPrompt: string
+}
+
+/** The wire.jsonl records of a new Kimi Code session continuing `session`. Pure. */
+export function planWire(session: Session, opts: { now: Date }): WirePlan {
+  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)
+  let clock = opts.now.getTime()
+  const time = () => clock++
+  const records: Json[] = [{ type: "metadata", protocol_version: WIRE_PROTOCOL, created_at: opts.now.getTime() }]
+  const expect = { users: 0, assistants: 0, calls: 0, compactions: 0 }
+
+  // The turns as Kimi groups them: each user message opens a turn (turn.prompt … turn.ended).
+  let turnId = 0
+  let inTurn = false
+  let replied = false
+  // Messages in the model's context since the last compaction, which a compaction record counts.
+  let context = 0
+  const append = (message: Message) => {
+    records.push({ type: "context.append_message", agentId: "main", message, time: time() })
+    context++
+  }
+  const endTurn = () => {
+    if (inTurn && replied) records.push({ type: "turn.ended", agentId: "main", turnId, reason: "completed", time: time() })
+    if (inTurn) turnId++
+    inTurn = false
+    replied = false
+  }
+  const openTurn = (input: Part[], origin: Json) => {
+    endTurn()
+    records.push({ type: "turn.prompt", agentId: "main", input, origin, time: time() })
+    inTurn = true
+  }
+
+  // Call ids stay as they were when Kimi can carry them, else get a call_ id; each is used once.
+  const ids = new Map<string, string>()
+  const used = new Set<string>()
+  const idFor = (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; used.has(v); n++) v = `${base}_${n}`
+    ids.set(id, v)
+    used.add(v)
+    return v
+  }
+  const results = new Map<string, Extract<Turn, { kind: "tool_result" }>>()
+  for (const t of session.turns) if (t.kind === "tool_result" && !results.has(t.callId)) results.set(t.callId, t)
+
+  // The assistant message being built: its reasoning, text and calls.
+  let cur: { think: string[]; text: string; calls: Call[] } | undefined
+  let pendingThink: string[] = []
+  const answered = new Set<string>()
+  const flush = () => {
+    if (!cur) return
+    const content: Part[] = [...cur.think.map((think) => ({ type: "think" as const, think })), ...(cur.text ? [{ type: "text" as const, text: cur.text }] : [])]
+    const toolCalls = cur.calls.map((c) => {
+      const own = kimiTool(c)
+      return { type: "function" as const, id: idFor(c.id), name: own?.name ?? (c.name.replace(/[^A-Za-z0-9_.:-]/g, "_").slice(0, 64) || "tool"), arguments: JSON.stringify(own?.args ?? c.input ?? {}) }
+    })
+    if (!inTurn) openTurn([], { kind: "system_trigger", name: "imported_orphan" })
+    append({ role: "assistant", content, toolCalls })
+    replied = true
+    if (cur.text.trim()) expect.assistants++
+    // A call the session never answered is closed as Kimi closes an interrupted one.
+    for (const c of cur.calls) {
+      if (results.has(c.id)) continue
+      append({ role: "tool", content: [{ type: "text", text: "Tool execution was interrupted before its result was recorded. Do not assume the tool completed successfully." }], toolCalls: [], toolCallId: idFor(c.id), isError: true })
+      answered.add(c.id)
+      drop("tool calls without a result (closed as interrupted)")
+    }
+    cur = undefined
+  }
+
+  const firstUser = session.turns.findIndex((t) => t.kind === "user" && t.text.trim())
+  const note: Message = { role: "user", content: [{ type: "text", text: continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10)) }], toolCalls: [], origin: { kind: "injection", variant: NOTE_VARIANT } }
+  if (firstUser < 0) {
+    openTurn([], { kind: "system_trigger", name: "imported_orphan" })
+    append(note)
+  }
+
+  for (const [i, t] of session.turns.entries()) {
+    switch (t.kind) {
+      case "user": {
+        flush()
+        if (pendingThink.length) drop("reasoning without a reply", pendingThink.length)
+        pendingThink = []
+        // Kimi keeps a pasted image in the message as an image_url part holding a data URL.
+        const images: Part[] = []
+        for (const a of t.attachments ?? []) {
+          const url = imageDataUrl(a)
+          if (url) images.push({ type: "image_url", imageUrl: { url } })
+          else drop("attachments")
+        }
+        if (!t.text.trim()) {
+          if (images.length) drop("attachments without text", images.length)
+          break
+        }
+        const content: Part[] = [{ type: "text", text: t.text }, ...images]
+        openTurn(content, { kind: "user" })
+        // Kimi puts the context it injects for a prompt just before the prompt's message.
+        if (i === firstUser) append(note)
+        append({ role: "user", content, toolCalls: [], origin: { kind: "user" } })
+        expect.users++
+        break
+      }
+      case "assistant":
+        if (cur?.calls.length || (cur?.text.trim() && t.text.trim())) flush()
+        cur ??= { think: pendingThink, text: "", calls: [] }
+        pendingThink = []
+        cur.text = t.text
+        break
+      case "reasoning":
+        if (cur?.calls.length || cur?.text.trim()) flush()
+        pendingThink.push(t.text)
+        break
+      case "tool_call":
+        if (ids.has(t.id)) {
+          drop("repeated tool call ids")
+          break
+        }
+        idFor(t.id)
+        cur ??= { think: pendingThink, text: "", calls: [] }
+        pendingThink = []
+        cur.calls.push(t)
+        expect.calls++
+        break
+      case "tool_result": {
+        if (!ids.has(t.callId)) {
+          drop("tool results without a call")
+          break
+        }
+        if (answered.has(t.callId) || results.get(t.callId) !== t) {
+          drop("repeated tool results")
+          break
+        }
+        if (cur?.calls.some((c) => c.id === t.callId)) flush()
+        let text = t.output
+        if (t.fullPath) text += `\n\n[Full output: ${t.fullPath}]`
+        // Kimi renders an empty output as "Tool output is empty."; an empty text part would be dropped.
+        append({ role: "tool", content: [{ type: "text", text: text || (t.ok ? "Tool output is empty." : "The tool failed.") }], toolCalls: [], toolCallId: idFor(t.callId), ...(t.ok ? {} : { isError: true as const }) })
+        answered.add(t.callId)
+        break
+      }
+      case "compaction": {
+        flush()
+        endTurn()
+        const summary = `[Summary of the earlier conversation in ${label}, which replaced the turns before it]\n\n${t.summary}`
+        // compactedCount is the whole context so far, so the model starts from the summary alone.
+        records.push({ type: "full_compaction.begin", agentId: "main", source: "auto", time: time() })
+        records.push({ type: "context.apply_compaction", agentId: "main", summary, contextSummary: summary, compactedCount: context, tokensBefore: 0, time: time() })
+        records.push({ type: "full_compaction.complete", agentId: "main", time: time() })
+        context = 1
+        expect.compactions++
+        break
+      }
+      case "file_edit":
+        if (!t.callId || !ids.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()
+  if (pendingThink.length) drop("reasoning without a reply", pendingThink.length)
+  endTurn()
+
+  const title = `${session.header.title ?? firstUserText(session)?.replace(/\s+/g, " ").trim().slice(0, 60) ?? "Session"} (from ${label})`
+  const lastUser = [...session.turns].reverse().find((t) => t.kind === "user" && t.text.trim())
+  return { records, lost: [...drops].map(([what, n]) => `${what} (${n})`), expect, title, lastPrompt: lastUser?.kind === "user" ? lastUser.text.slice(0, 200) : "" }
+}
+
+/** The Kimi Code writer; `version` is for tests, which must not depend on an installed binary. */
+export function kimiCodeWriter(opts: { version?: string } = {}): Writer {
+  const installed = () => opts.version ?? kimiVersion()
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(w: WriteOptions): Promise<Readiness> {
+      const v = installed()
+      if (!v) return { ok: false, why: "Kimi Code is not installed (`kimi --version` did not run)" }
+      if (!TESTED_VERSIONS.includes(v)) return { ok: false, why: `Kimi Code ${v} 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; Kimi Code finds a session by its working directory` }
+      return { ok: true }
+    },
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const cwd = realCwd(w.cwd)
+      const home = join(w.home, ".kimi-code")
+      const bucket = join(home, "sessions", workDirKey(cwd))
+      let sessionId = `session_${randomUUID()}`
+      while (exists(join(bucket, sessionId))) sessionId = `session_${randomUUID()}`
+      const dir = join(bucket, sessionId)
+      const now = new Date()
+      const plan = planWire(session, { now })
+      const paths = { wire: join(dir, "agents", "main", "wire.jsonl"), state: join(dir, "state.json"), index: join(home, "session_index.jsonl") }
+      if (!w.dryRun) {
+        mkdirSync(bucket, { recursive: true, mode: 0o700 })
+        // mkdir without recursive on the session folder itself: an existing session is never touched.
+        mkdirSync(dir, { mode: 0o700 })
+        try {
+          mkdirSync(join(dir, "agents", "main"), { recursive: true, mode: 0o700 })
+          writeFileSync(paths.wire, `${plan.records.map((r) => JSON.stringify(r)).join("\n")}\n`, { flag: "wx", mode: 0o600 })
+          const at = now.getTime()
+          const state = {
+            id: sessionId,
+            version: META_VERSION,
+            cwd,
+            createdAt: at,
+            updatedAt: at,
+            archived: false,
+            title: plan.title,
+            // "generated" keeps the title when the session goes on, as Kimi does for imported sessions.
+            titleKind: "generated",
+            isCustomTitle: false,
+            lastPrompt: plan.lastPrompt,
+            lastTurnReason: "completed",
+            agents: { main: { homedir: join(dir, "agents", "main"), type: "main", parentAgentId: null } },
+            custom: { continued_from: { tool: session.header.tool, id: session.header.sourceId, by: "brain session" } },
+          }
+          writeFileSync(paths.state, JSON.stringify(state, null, 2), { flag: "wx", mode: 0o600 })
+          const back = await reader.read({ tool: TOOL, sourceId: sessionId, path: paths.wire, extra: { dir } }, w.home)
+          const n = countTurns(back)
+          const pairs = unpaired(back)
+          if (n.user !== plan.expect.users || n.assistant !== plan.expect.assistants || n.tool_call !== plan.expect.calls || n.compaction !== plan.expect.compactions || pairs.calls.length || pairs.results.length)
+            throw new Error(
+              `the new Kimi Code session did not read back as written (users ${n.user}/${plan.expect.users}, replies ${n.assistant}/${plan.expect.assistants}, tool calls ${n.tool_call}/${plan.expect.calls}, compactions ${n.compaction}/${plan.expect.compactions}, unpaired ${pairs.calls.length + pairs.results.length}); nothing was kept`,
+            )
+        } catch (e) {
+          rmSync(dir, { recursive: true, force: true })
+          throw e
+        }
+        // The index Kimi uses to find a session by id alone; one appended line, as Kimi's own writers add.
+        appendFileSync(paths.index, `${JSON.stringify({ sessionId, sessionDir: dir, workDir: cwd })}\n`, { mode: 0o600 })
+      }
+      return {
+        tool: TOOL,
+        way: "native",
+        sessionId,
+        written: [paths.wire, paths.state, paths.index],
+        open: `cd ${shellQuote(cwd)} && kimi --session ${sessionId}`,
+        lost: plan.lost,
+        dryRun: !!w.dryRun,
+      }
+    },
+  }
+}
+
+export const kimiCodeNativeWriter = kimiCodeWriter()

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

@@ -0,0 +1,8 @@
+import type { Reader, Writer } from "../types.ts"
+import { kiroCliReader } from "./reader.ts"
+import { kiroCliNativeWriter } from "./writer.ts"
+
+// Kiro CLI (successor to the Amazon Q Developer CLI): reads Kiro's V3 session store, which Kiro IDE shares,
+// and continues any session there as a new Kiro session that `kiro-cli chat --resume-id` opens.
+export const readers: Reader[] = [kiroCliReader]
+export const writers: Writer[] = [kiroCliNativeWriter]

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

@@ -0,0 +1,87 @@
+import { join } from "node:path"
+import { gitInfo, isDir, ls, readJson, readJsonl } from "../../fsutil.ts"
+import type { Session } from "../../session/types.ts"
+import { header, iso, noteModel } from "../../session/util.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { type KiroMetadata, type KiroRow, sessionsDir, turnsOf } from "./records.ts"
+
+// Kiro's V3 session store, ~/.kiro/sessions/<bucket>/<id>/, which Kiro CLI (3.0 and later, by default) and
+// Kiro IDE (1.0 and later) share. A session's folder counts when it has a session.json, as Kiro's own lister
+// requires; the bucket's ".index" folder is Kiro's cache of the list, not a session.
+
+export const TOOL = "kiro-cli"
+export const LABEL = "Kiro"
+
+/** A session folder's metadata, or undefined when it is not one Kiro would list. */
+function metadataOf(dir: string): KiroMetadata | undefined {
+  const m = readJson<KiroMetadata>(join(dir, "session.json"))
+  if (!m || typeof m.id !== "string" || typeof m.title !== "string" || !Array.isArray(m.workspacePaths)) return undefined
+  return m
+}
+
+/** Every session folder in the store, with its metadata. */
+export function sessionFolders(home: string): Array<{ dir: string; meta: KiroMetadata }> {
+  const out: Array<{ dir: string; meta: KiroMetadata }> = []
+  const base = sessionsDir(home)
+  for (const bucket of ls(base)) {
+    if (bucket.startsWith(".") || !isDir(join(base, bucket))) continue
+    for (const name of ls(join(base, bucket))) {
+      if (name.startsWith(".")) continue
+      const dir = join(base, bucket, name)
+      const meta = isDir(dir) ? metadataOf(dir) : undefined
+      if (meta) out.push({ dir, meta })
+    }
+  }
+  return out
+}
+
+/** One session folder as a portable session. */
+export function readKiroDir(dir: string, home: string, tool = TOOL): Session {
+  const meta = metadataOf(dir)
+  if (!meta) throw new Error(`${dir} is not a Kiro session (no readable session.json)`)
+  const { rows, bad } = readJsonl(join(dir, "messages.jsonl"))
+  // Kiro skips a line its record schema rejects; these are the lines it would not even parse.
+  const records = rows.filter((r): r is KiroRow => typeof r.id === "string" && typeof r.timestamp === "string" && typeof r.payload?.type === "string")
+  const cwd = meta.workspacePaths[0]
+  const h = header(tool, meta.id, {
+    sourcePath: dir,
+    title: meta.title,
+    project: cwd ? { cwd, ...gitInfo(cwd, home) } : {},
+    ...(iso(meta.createdAt) ? { startedAt: iso(meta.createdAt)! } : {}),
+    ...(iso(meta.lastModifiedAt) ? { updatedAt: iso(meta.lastModifiedAt)! } : {}),
+  })
+  noteModel(h, meta.modelId)
+  if (meta.parentSessionId) h.parent = { id: `${tool}:${meta.parentSessionId}`, kind: "fork" }
+  const { turns, continued } = turnsOf(records, h)
+  if (bad + rows.length - records.length) h.lost.push(`unreadable records (${bad + rows.length - records.length})`)
+  if (continued) h.parent = { id: continued, kind: "continued" }
+  return { header: h, turns }
+}
+
+/** A reader of the shared store under one tool id. */
+export function kiroReader(tool: string, label: string): Reader {
+  return {
+    tool,
+    label,
+    async list(home) {
+      const refs: SessionRef[] = sessionFolders(home).map(({ dir, meta }) => {
+        const updatedAt = iso(meta.lastModifiedAt)
+        return {
+          tool,
+          sourceId: meta.id,
+          path: dir,
+          title: meta.title,
+          ...(meta.workspacePaths[0] ? { cwd: meta.workspacePaths[0] } : {}),
+          ...(updatedAt ? { updatedAt } : {}),
+        }
+      })
+      return refs.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+    },
+    async read(ref, home) {
+      if (!isDir(ref.path)) throw new Error(`Kiro session folder not found: ${ref.path}`)
+      return readKiroDir(ref.path, home, tool)
+    },
+  }
+}
+
+export const kiroCliReader = kiroReader(TOOL, LABEL)