@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/memory/mcp-server.ts

@@ -0,0 +1,296 @@
+// `brain mcp serve`: one small stdio MCP server the brain owns, so every tool gets the same memory.
+// Hand-written JSON-RPC 2.0 over newline-delimited JSON (no SDK). Read-only: it never writes to Chitta, the blob store
+// or the project. Everything it returns goes through redact().
+//
+// Tools (kept tiny on purpose: their definitions are sent in every request, so they are a token cost; a test holds
+// the three under 700 tokens):
+//   brain_recall  the best memories for a question in the current project, at most 1500 tokens
+//   brain_expand  a stored tool output by blob id or by its stub text: grep for matching lines, or page with offset/limit (8,000 characters by default)
+//   brain_status  whether memory is available, the store, item counts, the project
+//   brain_map     compact map of the folder's code (layout, ranked exports), cached until the code changes
+
+import { gitInfo } from "../fsutil.ts"
+import { expandStub } from "./externalize.ts"
+import { openBlobStore } from "./blobs.ts"
+import { projectKey } from "./project.ts"
+import { redact } from "./redact.ts"
+import { repoMap } from "./repomap.ts"
+import { windowOf } from "./relevance.ts"
+import { logLookup } from "./lookups.ts"
+import { openMemory } from "./store.ts"
+import { approxTokens, type BlobStore, type Memory, type ProjectKey } from "./types.ts"
+
+export interface McpServerOptions {
+  home: string
+  /** Overrides the project (default: the one of the folder the process was started in). */
+  project?: ProjectKey
+  input?: ReadableStream<Uint8Array>
+  output?: WritableStream<Uint8Array>
+  /** Folder to take the project from (default process.cwd()). */
+  cwd?: string
+  /** Test seams: use these instead of opening the real stores. */
+  memory?: Memory
+  blobs?: BlobStore
+}
+
+/** Protocol versions this server can speak; it answers with the client's when it is one of them. */
+const VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"]
+const RECALL_TOKENS = 1500
+/** What one brain_expand call returns by default and at most. Tools truncate long MCP results on their own (Codex drops the middle of one), so the default is small and the model pages or greps for the rest. */
+const EXPAND_DEFAULT = 8_000
+const EXPAND_MAX = 60_000
+const SERVER_INFO = { name: "brain", version: "0.1.0" }
+
+type Json = Record<string, any>
+
+export const TOOLS = [
+  {
+    name: "brain_recall",
+    description: "Look up what earlier sessions of this project established (decisions, constraints, failed attempts, commands). Use at the start of a task or before repeating work. Returns up to 1500 tokens.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "What you need to know" },
+        project: { type: "string", description: "Project label or id, when it is not the folder you are in" },
+        limit: { type: "number", description: "Max items (default 8)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "brain_expand",
+    description: "Get the text of a tool output that was replaced by a '[brain: output stored ... id=...]' stub. Pass the id (or the stub). Best: grep to get only the matching lines with context; else offset/limit to page. Use only when the digest is not enough.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Blob id or the stub text" },
+        grep: { type: "string", description: "Regex: return only matching lines (and context lines around them)" },
+        context: { type: "number", description: "Lines around each match (default 2)" },
+        offset: { type: "number", description: "First character to return (default 0)" },
+        limit: { type: "number", description: "Characters to return (default 8000, max 60000)" },
+        query: { type: "string", description: "Words to look for: with no grep/offset/limit, adds the best-matching parts of a long output to its head and tail" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "brain_status",
+    description: "Whether brain memory is available, its store, item counts and the current project.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "brain_map",
+    description: "Compact map of this folder's code: layout and exported symbols, ranked. Orientation only: read files narrowly after it.",
+    inputSchema: { type: "object", properties: {} },
+  },
+]
+
+const ok = (text: string) => ({ content: [{ type: "text", text }] })
+const fail = (text: string) => ({ content: [{ type: "text", text }], isError: true })
+
+const clip = (s: string, n: number) => (s.length > n ? `${s.slice(0, n - 1)}…` : s)
+
+export async function runMcpServer(opts: McpServerOptions): Promise<void> {
+  const cwd = opts.cwd ?? process.cwd()
+  const project: ProjectKey = opts.project ?? projectKey({ cwd, ...gitInfo(cwd, opts.home) })
+  let memory = opts.memory
+  let blobs = opts.blobs
+  // Opened on first use: a tool that only lists its tools should not touch the disk.
+  const mem = () => (memory ??= openMemory(opts.home))
+  const blob = () => (blobs ??= openBlobStore(opts.home))
+
+  async function recall(args: Json) {
+    const query = typeof args.query === "string" ? args.query.trim() : ""
+    if (!query) return fail("query is required")
+    const st = await mem().status()
+    if (!st.available) return ok(`memory is not available: ${st.why ?? "unknown reason"}`)
+    const limit = Math.max(1, Math.min(50, Math.floor(Number(args.limit)) || 8))
+    // Tools start the server in different folders (a desktop app may start it in the home folder), so the project can be named.
+    const known = (await (mem() as { projects?: () => Promise<Array<{ id: string; label: string; items: number }>> }).projects?.().catch(() => undefined)) ?? []
+    let target = project
+    if (typeof args.project === "string" && args.project.trim()) {
+      const want = args.project.trim().toLowerCase()
+      const hit = known.filter((p) => p.id.toLowerCase() === want || p.label.toLowerCase() === want)
+      const near = hit.length ? hit : known.filter((p) => p.label.toLowerCase().startsWith(want) || p.id.toLowerCase().endsWith(want))
+      if (near.length !== 1) return ok(near.length ? `"${clip(redact(args.project), 60)}" matches several projects: ${near.map((p) => p.label).join(", ")}` : `no project "${clip(redact(args.project), 60)}" has memory${known.length ? `; projects with memory: ${known.map((p) => `${p.label} (${p.items})`).join(", ")}` : ""}`)
+      target = { id: near[0]!.id, label: near[0]!.label }
+    }
+    const found = await mem().recall(target, query, { limit, maxTokens: RECALL_TOKENS })
+    if (!found.length) {
+      const others = known.filter((p) => p.id !== target.id && p.items > 0).slice(0, 8)
+      const hint = others.length ? ` Projects with memory: ${others.map((p) => `${p.label} (${p.items})`).join(", ")}; pass project=<label> to search one.` : ""
+      return ok(`no memories for ${target.label} match "${clip(redact(query), 80)}".${hint}`)
+    }
+    const lines: string[] = []
+    let used = 0
+    for (const r of found) {
+      const line = redact(`[${r.kind ?? "note"}] ${clip(r.text.replace(/\s+/g, " ").trim(), 1500)}${r.source ? ` (from ${clip(r.source, 60)})` : ""}`)
+      const cost = approxTokens(line) + 1
+      // The total is hard-capped here whatever the store returned; the first line always fits (it is clipped to 1500 chars).
+      if (used + cost > RECALL_TOKENS && lines.length) break
+      lines.push(line)
+      used += cost
+    }
+    return ok(lines.join("\n"))
+  }
+
+  function expand(args: Json) {
+    const raw = typeof args.id === "string" ? args.id.trim() : ""
+    if (!raw) return fail("id is required")
+    // A bare blob id, or a whole stub (or text containing one).
+    const id = /^[0-9a-f]{8,64}$/i.test(raw) ? raw.toLowerCase() : expandStub(raw)
+    if (!id) return fail("that is not a blob id or a brain stub")
+    const text = blob().get(id)
+    if (text === undefined) return fail(`no stored output with id ${id} (never stored, or pruned)`)
+    const how = typeof args.grep === "string" && args.grep ? "grep" : args.offset === undefined && args.limit === undefined ? "window" : "page"
+    logLookup(opts.home, { event: "expand", at: new Date().toISOString(), id, kind: blob().kindOf?.(id) ?? "unknown", how })
+    const safe = redact(text)
+    const limit = Math.min(EXPAND_MAX, Math.max(1, Math.floor(Number(args.limit) || EXPAND_DEFAULT)))
+    if (typeof args.grep === "string" && args.grep) {
+      let re: RegExp
+      try {
+        re = new RegExp(args.grep, "i")
+      } catch {
+        re = new RegExp(args.grep.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i") // not a valid regex: match it as plain text
+      }
+      const lines = safe.split("\n")
+      const hit = lines.map((l, i) => (re.test(l) ? i : -1)).filter((i) => i >= 0)
+      if (!hit.length) return ok(`[brain: no line of the ${lines.length}-line output matches "${clip(args.grep, 60)}"]`)
+      const ctx = Math.min(10, Math.max(0, Math.floor(Number(args.context ?? 2)) || 0))
+      const keep = new Set<number>()
+      for (const i of hit) for (let j = Math.max(0, i - ctx); j <= Math.min(lines.length - 1, i + ctx); j++) keep.add(j)
+      const out: string[] = []
+      let used = 0
+      let prev = -2
+      let shown = 0
+      for (const i of [...keep].sort((a, b) => a - b)) {
+        const line = `${i + 1}: ${clip(lines[i]!, 400)}`
+        if (used + line.length + 1 > limit) break
+        if (i !== prev + 1 && out.length) out.push("--")
+        out.push(line)
+        used += line.length + 1
+        prev = i
+        shown++
+      }
+      const more = keep.size > shown ? ` (showing ${shown} of ${keep.size} lines; narrow the grep or raise limit)` : ""
+      return ok(`[brain: ${hit.length} matching line${hit.length === 1 ? "" : "s"} of ${lines.length}${more}]\n${out.join("\n")}`)
+    }
+    // Neither grep, offset nor limit: head + tail (+ the parts matching `query`), not the first page only: agents rarely page.
+    if (args.offset === undefined && args.limit === undefined) return ok(windowOf(safe, EXPAND_DEFAULT, { query: typeof args.query === "string" ? args.query : undefined }))
+    const offset = Math.max(0, Math.floor(Number(args.offset) || 0))
+    const end = Math.min(safe.length, offset + limit)
+    const body = safe.slice(offset, end)
+    return ok(end < safe.length || offset > 0 ? `${body}\n[brain: characters ${offset}-${end} of ${safe.length}${end < safe.length ? `; more: call again with offset=${end}, or pass grep to find a line` : ""}]` : body)
+  }
+
+  async function status() {
+    const st = await mem().status()
+    const lines = [`project: ${project.label} (${project.id})`, `memory: ${st.available ? "available" : `not available: ${st.why ?? "unknown reason"}`}`]
+    if (st.store) lines.push(`store: ${st.store}`)
+    if (st.items !== undefined) lines.push(`items: ${st.items}`)
+    lines.push(`blobs: ${blob().dir}`)
+    return ok(redact(lines.join("\n")))
+  }
+
+  async function callTool(params: Json) {
+    const args = params?.arguments && typeof params.arguments === "object" ? params.arguments : {}
+    try {
+      switch (params?.name) {
+        case "brain_recall":
+          return await recall(args)
+        case "brain_expand":
+          return expand(args)
+        case "brain_status":
+          return await status()
+        case "brain_map": {
+          const m = repoMap(cwd, opts.home)
+          return ok(redact(m.text || "no files found in this folder"))
+        }
+        default:
+          return undefined
+      }
+    } catch (e) {
+      return fail(`${params.name} failed: ${redact(e instanceof Error ? e.message : String(e))}`)
+    }
+  }
+
+  /** One request: a response object, or undefined for a notification. */
+  async function handle(msg: Json): Promise<Json | undefined> {
+    if (!msg || typeof msg !== "object" || Array.isArray(msg) || typeof msg.method !== "string") {
+      return { jsonrpc: "2.0", id: msg?.id ?? null, error: { code: -32600, message: "invalid request" } }
+    }
+    const hasId = msg.id !== undefined && msg.id !== null
+    const reply = (result: unknown) => (hasId ? { jsonrpc: "2.0", id: msg.id, result } : undefined)
+    const error = (code: number, message: string) => (hasId ? { jsonrpc: "2.0", id: msg.id, error: { code, message } } : undefined)
+    switch (msg.method) {
+      case "initialize": {
+        const want = msg.params?.protocolVersion
+        return reply({
+          protocolVersion: VERSIONS.includes(want) ? want : VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: SERVER_INFO,
+        })
+      }
+      case "ping":
+        return reply({})
+      case "tools/list":
+        return reply({ tools: TOOLS })
+      case "tools/call": {
+        const result = await callTool(msg.params)
+        return result ? reply(result) : error(-32602, `unknown tool: ${String(msg.params?.name)}`)
+      }
+      default:
+        // Notifications (notifications/initialized, cancelled, ...) get no answer; unknown requests get an error.
+        return msg.method.startsWith("notifications/") ? undefined : error(-32601, `method not found: ${msg.method}`)
+    }
+  }
+
+  const input = opts.input ?? (Bun.stdin.stream() as ReadableStream<Uint8Array>)
+  const output = opts.output ?? new WritableStream<Uint8Array>({ write: (chunk) => void process.stdout.write(chunk) })
+  const writer = output.getWriter()
+  const enc = new TextEncoder()
+  const send = (v: unknown) => writer.write(enc.encode(`${JSON.stringify(v)}\n`))
+
+  async function line(text: string) {
+    if (!text.trim()) return
+    let msg: unknown
+    try {
+      msg = JSON.parse(text)
+    } catch {
+      await send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } })
+      return
+    }
+    if (Array.isArray(msg)) {
+      const out = (await Promise.all(msg.map((m) => handle(m)))).filter((r) => r !== undefined)
+      if (out.length) await send(out)
+      return
+    }
+    const res = await handle(msg as Json)
+    if (res) await send(res)
+  }
+
+  const reader = input.getReader()
+  const dec = new TextDecoder()
+  let buf = ""
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buf += dec.decode(value, { stream: true })
+      let nl: number
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const l = buf.slice(0, nl)
+        buf = buf.slice(nl + 1)
+        await line(l)
+      }
+    }
+    buf += dec.decode()
+    await line(buf)
+  } finally {
+    try {
+      await writer.close()
+    } catch {
+      // The output may already be closed by the other side.
+    }
+  }
+}

package/src/memory/prepare.ts

@@ -0,0 +1,179 @@
+// What `brain session continue` does with a session before a writer sees it, to spend fewer tokens:
+//   - lean: on a long session (or when asked) big tool output is replaced by digests, the full text kept on disk;
+//   - memory: what the session established is distilled into the project's memory (the brain's own store), and what the
+//     project already knows about the new request is recalled for the brief.
+// Both are optional and degrade quietly: no Chitta means no memory; a short session stays as it is.
+import { gitInfo, isDir } from "../fsutil.ts"
+import type { WriteOptions } from "../adapters/types.ts"
+import type { Session } from "../session/types.ts"
+import { withoutInjected } from "../session/util.ts"
+import { openBlobStore } from "./blobs.ts"
+import { distill } from "./distill.ts"
+import { externalize, externalizeToBudget } from "./externalize.ts"
+import { tidySession } from "./tidy.ts"
+import { projectKey } from "./project.ts"
+import { repoMap } from "./repomap.ts"
+import { logLookup } from "./lookups.ts"
+import { openMemory } from "./store.ts"
+import { approxTokens, type BlobRef, type BlobStore, type Memory, type ProjectKey } from "./types.ts"
+
+/** Sessions with at least this many tokens are made lean when nothing says otherwise: below it, full fidelity costs little. */
+export const LEAN_AUTO_TOKENS = 50_000
+/** Above this many tokens a native continuation cannot fit the context of most models. */
+export const WINDOW_WARN_TOKENS = 400_000
+/** What a lean brief costs, roughly (its budget in characters / 4, plus recalled memory). */
+const BRIEF_TOKENS_HINT = 2_500
+/** What the brief may take from memory. */
+const RECALL_LIMIT = 8
+const RECALL_TOKENS = 1_200
+/** The project map's size in the brief: the brief takes at most 1,200 characters of it (MAP_CHARS). */
+const MAP_TOKENS = 300
+
+export interface PrepareOptions {
+  home: string
+  /** The folder the session continues in. */
+  cwd: string
+  dryRun: boolean
+  /** true: lean; false: full; undefined: lean when the session is long. */
+  lean?: boolean
+  /** Neither ingest into nor recall from memory. */
+  noMemory?: boolean
+  /** Aim for a session of at most this many tokens: big outputs are replaced in graduated levels until it fits (implies lean when the session is bigger). */
+  budget?: number
+  /** Tidy tool results that stay (lossless in meaning: ANSI, progress lines, repeated lines, JSON whitespace). Default true. */
+  tidy?: boolean
+}
+
+export interface Prepared {
+  session: Session
+  brief: NonNullable<WriteOptions["brief"]>
+  lean: boolean
+  /** One line per thing done, for the person ("memory: recalled 3 items", ...). */
+  notes: string[]
+}
+
+/** The tokens in a session's text-bearing parts (chars / 4). */
+export function sessionTokens(s: Session): number {
+  let chars = 0
+  for (const t of s.turns) {
+    switch (t.kind) {
+      case "user":
+      case "assistant":
+      case "reasoning":
+        chars += t.text.length
+        break
+      case "tool_call":
+        chars += JSON.stringify(t.input ?? "").length
+        break
+      case "tool_result":
+        chars += t.output.length
+        break
+      case "file_edit":
+        chars += t.patch?.length ?? 0
+        break
+      case "compaction":
+        chars += t.summary.length
+        break
+    }
+  }
+  return approxTokens("x".repeat(chars))
+}
+
+/** What to ask memory: the latest real request, else the first. */
+export function queryOf(s: Session): string {
+  const users = s.turns.filter((t) => t.kind === "user") as Array<Extract<Session["turns"][number], { kind: "user" }>>
+  const real = users.map((u) => withoutInjected(u.text).trim()).filter(Boolean)
+  return (real[real.length - 1] ?? real[0] ?? "").slice(0, 500)
+}
+
+/** Blobs held in memory only: a dry run counts what would be replaced without writing anything. */
+function scratchBlobs(): BlobStore {
+  const m = new Map<string, string>()
+  return {
+    dir: "(dry run)",
+    put(text: string): BlobRef {
+      const id = Bun.hash(text).toString(16).padStart(16, "0").slice(0, 16)
+      m.set(id, text)
+      return { id, chars: text.length }
+    },
+    get: (id) => m.get(id),
+    prune: () => 0,
+  }
+}
+
+export async function prepare(session: Session, o: PrepareOptions, deps: { memory?: Memory; blobs?: BlobStore } = {}): Promise<Prepared> {
+  const notes: string[] = []
+  const tokens = sessionTokens(session)
+  const budget = o.budget !== undefined && Number.isFinite(o.budget) && o.budget > 0 ? Math.floor(o.budget) : undefined
+  const lean = o.lean ?? (tokens >= LEAN_AUTO_TOKENS || (budget !== undefined && tokens > budget))
+  const brief: Prepared["brief"] = { lean }
+  let out = session
+  const tidy = o.tidy !== false
+
+  if (lean) {
+    const blobs = deps.blobs ?? (o.dryRun ? scratchBlobs() : openBlobStore(o.home))
+    const r = budget !== undefined ? externalizeToBudget(session, blobs, { targetTokens: budget, tidy }) : externalize(session, blobs, { tidy })
+    out = r.session
+    if (!o.dryRun && r.replaced) logLookup(o.home, { event: "stubs", at: new Date().toISOString(), session: session.header.id, byKind: r.byKind as Record<string, number> })
+    const digested = Math.round((r.before - r.after - r.tidied) / 4)
+    if (r.replaced) notes.push(`lean: ${r.replaced} big tool outputs replaced by digests, about ${digested.toLocaleString()} of ${Math.round(r.before / 4).toLocaleString()} tokens saved${o.dryRun ? " (dry run: nothing stored)" : "; the full text is kept; install the brain tools (`brain mcp install`) so the model can ask for it"}`)
+    else notes.push(`lean: nothing to replace (the session is ${tokens.toLocaleString()} tokens, and its big outputs are all recent)`)
+    if (budget !== undefined && "level" in r) {
+      const b = r as ReturnType<typeof externalizeToBudget>
+      notes.push(`budget: target ${budget.toLocaleString()} tokens, ${b.reached ? `reached at level ${b.level} (${b.tokens.toLocaleString()} tokens)` : `not reached: level ${b.level} of 4 leaves ${b.tokens.toLocaleString()} tokens`}`)
+    }
+    if (r.tidied) notes.push(`tidy: ${Math.round(r.tidied / 4).toLocaleString()} tokens saved`)
+  } else {
+    if (budget !== undefined) notes.push("budget: ignored (the session is kept full)")
+    if (tidy) {
+      const t = tidySession(session)
+      out = t.session
+      if (t.tidied) notes.push(`tidy: ${Math.round(t.tidied / 4).toLocaleString()} tokens saved`)
+    }
+  }
+
+  // A session still bigger than a model's window cannot be carried over whole, lean or not: say so, and say what does fit.
+  const left = sessionTokens(out)
+  if (left > WINDOW_WARN_TOKENS) notes.push(`size: still about ${left.toLocaleString()} tokens, more than most models take at once; \`--way brief\` carries the essentials and what the project remembers in about ${(BRIEF_TOKENS_HINT).toLocaleString()} tokens`)
+
+  if (!o.noMemory) {
+    const memory = deps.memory ?? openMemory(o.home)
+    const status = await memory.status().catch((e: Error) => ({ available: false as const, why: e.message }))
+    if (!status.available) notes.push(`memory: not used (${status.why ?? "unavailable"})`)
+    else {
+      const own = projectKey({ ...session.header.project, ...(session.header.project.cwd ? gitInfo(session.header.project.cwd) : {}) })
+      const here: ProjectKey = projectKey({ cwd: o.cwd, ...gitInfo(o.cwd) })
+      if (!o.dryRun) {
+        const items = distill(session)
+        if (items.length) {
+          const r = await memory.ingest(own, items).catch(() => undefined)
+          notes.push(r ? `memory: ${r.stored} item${r.stored === 1 ? "" : "s"} from this session kept for ${own.label}` : "memory: could not store this session's items")
+        }
+      }
+      const q = queryOf(session)
+      if (q) {
+        const recalled = await memory.recall(here, q, { limit: RECALL_LIMIT, maxTokens: RECALL_TOKENS }).catch(() => [])
+        // Items from this very session add nothing the brief does not already say.
+        const fresh = recalled.filter((r) => r.source !== session.header.id)
+        if (fresh.length) {
+          brief.memory = fresh.map((r) => ({ ...(r.kind ? { kind: r.kind } : {}), text: r.text, ...(r.source ? { source: r.source } : {}) }))
+          notes.push(`memory: ${fresh.length} earlier item${fresh.length === 1 ? "" : "s"} about this project added to the brief`)
+        }
+      }
+    }
+  }
+  // A lean continuation starts with a map of the code (cached while the code is unchanged), so the model does not rediscover the files.
+  if (lean && isDir(o.cwd)) {
+    try {
+      const m = repoMap(o.cwd, o.home, { maxTokens: MAP_TOKENS, write: !o.dryRun })
+      if (m.text) {
+        ;(brief as { map?: string }).map = m.text
+        notes.push(`map: about ${m.tokens.toLocaleString()} tokens of project map added to the brief (${m.cached ? "cached, code unchanged" : "regenerated from the code"})`)
+      }
+    } catch {
+      // The map is an extra; the brief is complete without it.
+    }
+  }
+  return { session: out, brief, lean, notes }
+}
+

package/src/memory/preview.ts

@@ -0,0 +1,154 @@
+// What a lean stub shows of the output it replaced, so the model can often answer without calling brain_expand.
+// Every expansion costs a whole extra request (measured live, docs/live-savings/), and the industry's stubs carry previews
+// for the same reason (Gemini CLI head/tail, OpenCode 2,000 chars, Codex counts). Deterministic and model-free, so the
+// stub is byte-identical every time (the prompt cache depends on it), and capped so a stub stays small next to the output.
+//
+//   code read   an outline of top-level declarations, with short constant values ("EXPAND_MAX = 60_000; runMcpServer()")
+//   shell       first lines, last lines (where results and failures are), and error lines in between
+//   search      the first matches
+//   list        the first entries
+//   other       first and last lines
+import type { ToolKind } from "../session/types.ts"
+import { hasSecret, redact } from "./redact.ts"
+
+/** The whole preview, at most this many characters. */
+export const PREVIEW_MAX = 900
+const LINE = 160
+
+const CODE_EXT = /\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|kts|rb|php|c|h|cc|cpp|hpp|cs|swift|scala|sh|bash|zsh|lua|dart|ex|exs)$/i
+/** Line-number prefixes that read tools add: "  12→" (Claude Code), "12\t", "12: " (OpenCode), "12| " and "00012| " (100xprompt, older OpenCode), "  12|" (Devin). */
+const NUMBERED = /^\s*\d{1,6}(?:→|\t|: |\s?\|\s?)/
+const TRIPLE = ['"""', "'''"]
+
+const clip = (s: string, n = LINE): string => {
+  const t = s.replace(/\s+/g, " ").trim()
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t
+}
+const safe = (l: string): string => {
+  const r = clip(redact(l))
+  return hasSecret(r) ? "[line withheld: secret]" : r
+}
+
+/** Joins items with `sep` while the result stays within `max` characters; ends with "…" when some were left out. */
+export function joinWithin(items: string[], sep: string, max: number): string {
+  let out = ""
+  for (let i = 0; i < items.length; i++) {
+    const next = out ? `${out}${sep}${items[i]}` : items[i]!
+    const room = i < items.length - 1 ? max - sep.length - 1 : max
+    if (next.length > room) return out ? `${out}${sep}…` : `${items[i]!.slice(0, Math.max(0, max - 1))}…`
+    out = next
+  }
+  return out
+}
+
+const count = (s: string, needle: string) => s.split(needle).length - 1
+
+/** Top-level declarations of a source file, in order: names, with the value of short constants. */
+export function outline(code: string, max = 40): string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  const add = (s: string, key: string) => {
+    if (seen.has(key) || out.length >= max) return
+    seen.add(key)
+    out.push(s)
+  }
+  const value = (v: string | undefined) => {
+    const t = (v ?? "").trim().replace(/[;,]\s*$/, "")
+    const open = (t.match(/[{([]/g) ?? []).length
+    const close = (t.match(/[})\]]/g) ?? []).length
+    // An object or call cut at the line end, or a string that only opens on this line, is not a value.
+    const opensString = count(t, "`") % 2 === 1 || TRIPLE.some((q) => count(t, q) % 2 === 1)
+    return t && t.length <= 40 && open === close && !opensString ? ` = ${t}` : ""
+  }
+  // Lines inside a multi-line string (a JS/TS template literal, a Python triple-quoted string) are prose, not declarations.
+  let inTemplate = false
+  let inTriple: string | undefined
+  for (const raw of code.split("\n")) {
+    const l = raw.replace(/\r$/, "").replace(NUMBERED, "")
+    const inside = inTemplate || inTriple !== undefined
+    if (count(l.replace(/\\`/g, ""), "`") % 2 === 1) inTemplate = !inTemplate
+    for (const q of TRIPLE) if (count(l, q) % 2 === 1 && (inTriple === undefined || inTriple === q)) inTriple = inTriple === undefined ? q : undefined
+    if (inside) continue
+    if (/^\s/.test(l) && !/^\s*export\s/.test(l)) continue // nested: only top level
+    let m: RegExpExecArray | null
+    if ((m = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\*?\s+([A-Za-z_$][\w$]*)/.exec(l))) add(`${m[1]}()`, m[1]!)
+    else if ((m = /^(?:export\s+)?(?:declare\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::\s*[^=]+?)?=\s*(.*)$/.exec(l))) {
+      const isFn = /^(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::[^=]+)?=>/.test(m[2]!.trim())
+      add(isFn ? `${m[1]}()` : `${m[1]}${value(m[2])}`, m[1]!)
+    } else if ((m = /^(?:export\s+)?(?:default\s+)?(?:abstract\s+)?(class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/.exec(l))) add(`${m[1]} ${m[2]}`, m[2]!)
+    else if ((m = /^(?:async\s+)?def\s+(\w+)\s*\(/.exec(l))) add(`${m[1]}()`, m[1]!)
+    else if ((m = /^class\s+(\w+)/.exec(l))) add(`class ${m[1]}`, m[1]!)
+    else if ((m = /^([A-Z][A-Z0-9_]+)\s*(?::\s*[^=]+)?=\s*(.*)$/.exec(l))) add(`${m[1]}${value(m[2])}`, m[1]!)
+    else if ((m = /^func\s+(?:\([^)]*\)\s*)?(\w+)/.exec(l))) add(`${m[1]}()`, m[1]!)
+    else if ((m = /^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?(fn|struct|enum|trait|mod)\s+(\w+)/.exec(l))) add(m[1] === "fn" ? `${m[2]}()` : `${m[1]} ${m[2]}`, m[2]!)
+    else if ((m = /^(?:pub(?:\([^)]*\))?\s+)?(?:const|static)\s+(\w+)\s*:[^=]*=\s*(.*)$/.exec(l))) add(`${m[1]}${value(m[2])}`, m[1]!)
+  }
+  return out
+}
+
+const ERROR_LINE = /\b(?:error|errors|fail(?:ed|ure|ing)?|exception|traceback|panic(?:ked)?|fatal|denied|not found|cannot|undefined is not)\b/i
+
+/** Joins preview lines under the cap; never cuts a line in the middle except the last that fits. */
+function fit(parts: Array<[string, string[]]>): string {
+  const out: string[] = []
+  let used = 0
+  for (const [label, lines] of parts) {
+    if (!lines.length) continue
+    const head = `${label}:`
+    if (used + head.length + 1 > PREVIEW_MAX) break
+    out.push(head)
+    used += head.length + 1
+    for (const l of lines) {
+      const s = `  ${l}`
+      if (used + s.length + 1 > PREVIEW_MAX) {
+        out.push("  …")
+        return out.join("\n")
+      }
+      out.push(s)
+      used += s.length + 1
+    }
+  }
+  return out.join("\n")
+}
+
+/**
+ * The preview block for a replaced tool result ("" when there is nothing useful to add). `path` is the file a read
+ * call named, when there is one.
+ */
+export function previewOf(raw: string, kind: ToolKind, opts: { ok: boolean; path?: string } = { ok: true }): string {
+  // Secrets are found in the whole text first: a private key spans many lines, and one line of it looks like plain base64.
+  const output = redact(raw)
+  const lines = output
+    .split("\n")
+    .map((l) => l.replace(/\r$/, "").replace(/\x1b\[[0-9;]*[A-Za-z]/g, ""))
+    .filter((l) => l.trim())
+  if (!lines.length) return ""
+  const headTail = (h: number, t: number): Array<[string, string[]]> =>
+    lines.length <= h + t ? [["lines", lines.map(safe)]] : [["first lines", lines.slice(0, h).map(safe)], ["last lines", lines.slice(-t).map(safe)]]
+  const errors = (skip: Set<number>) =>
+    lines
+      .map((l, i) => [l, i] as const)
+      .filter(([l, i]) => !skip.has(i) && ERROR_LINE.test(l))
+      .slice(0, 4)
+      .map(([l]) => safe(l))
+
+  if (kind === "read") {
+    const code = (opts.path && CODE_EXT.test(opts.path)) || /^\s*(?:\d+(?:→|\t|: |\s?\|)\s*)?(?:import|export|package|use|from|#include|def|func|fn)\b/m.test(output)
+    if (code) {
+      const o = outline(output).map((d) => clip(d, 80)).filter((d) => !hasSecret(d))
+      if (o.length) return `outline: ${joinWithin(o, "; ", PREVIEW_MAX - 9)}`
+    }
+    return fit(headTail(3, 2))
+  }
+  if (kind === "shell") {
+    const h = 2
+    const t = 4
+    const skip = new Set<number>([...Array(Math.min(h, lines.length)).keys(), ...Array.from({ length: Math.min(t, lines.length) }, (_, i) => lines.length - 1 - i)])
+    const parts = headTail(h, t)
+    const e = lines.length > h + t ? errors(skip) : []
+    return fit(opts.ok ? [...parts, ["error lines", e]] : [["error lines", e], ...parts])
+  }
+  if (kind === "search") return fit([["first matches", lines.slice(0, 6).map(safe)]])
+  if (kind === "list") return `first entries:\n  ${joinWithin(lines.slice(0, 15).map((l) => safe(l).slice(0, 60)), ", ", PREVIEW_MAX - 18)}`
+  return fit(headTail(2, 2))
+}

package/src/memory/project.ts

@@ -0,0 +1,35 @@
+// The key a project's memory is filed under: its git remote when it has one (so two clones, or the same repo opened from
+// two tools or two machines, share memory), else the real path of its folder.
+import { realpathSync } from "node:fs"
+import { basename, resolve } from "node:path"
+import type { Project } from "../session/types.ts"
+import type { ProjectKey } from "./types.ts"
+
+/** `git@github.com:Owner/Repo.git`, `https://user:tok@GitHub.com/owner/repo/`, `ssh://git@host:22/o/r` -> `github.com/owner/repo`. */
+export function normalizeRemote(remote: string): string | undefined {
+  let r = remote.trim()
+  if (!r) return undefined
+  r = r.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "") // protocol
+  r = r.replace(/^[^@/]*@/, "") // user[:password]@
+  r = r.replace(/^([^/:]+):(\d+)(?=\/)/, "$1") // host:port/path
+  r = r.replace(/^([^/:]+):(?!\/)/, "$1/") // scp-style host:owner/repo
+  r = r.replace(/[?#].*$/, "").replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "")
+  r = r.toLowerCase()
+  return r.includes("/") ? r : undefined
+}
+
+export function projectKey(project: Project): ProjectKey {
+  const remote = project.gitRemote ? normalizeRemote(project.gitRemote) : undefined
+  if (remote) return { id: remote, label: remote.split("/").pop() || remote }
+  if (project.cwd) {
+    let path = project.cwd
+    try {
+      path = realpathSync(project.cwd)
+    } catch {
+      path = resolve(project.cwd) // a folder from another machine: keep it as written
+    }
+    path = path.replace(/\/+$/, "") || "/"
+    return { id: path, label: basename(path) || path }
+  }
+  return { id: "unknown", label: "unknown" }
+}