@chroxify/eunoe 0.1.0 → 1.1.0

package/src/cli/proxy/claude-settings.ts

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+export interface Settings {
+  env?: Record<string, string>
+  autoCompactEnabled?: boolean
+  [key: string]: unknown
+}
+
+export const BLOCKING_LIMIT_ENV = "CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE"
+export const BLOCKING_LIMIT_OFF = "1000000000"
+
+export const proxyUrl = (port: number) => `http://127.0.0.1:${port}`
+
+export const pointsAtEunoe = (settings: Settings, port: number) => settings.env?.ANTHROPIC_BASE_URL === proxyUrl(port)
+
+function withoutEnv(settings: Settings, name: string): Settings {
+  if (!settings.env || !(name in settings.env)) return settings
+  const { [name]: _, ...env } = settings.env
+  const next: Settings = { ...settings, env }
+  if (Object.keys(env).length === 0) delete next.env
+  return next
+}
+
+export function withCompactionOwner(settings: Settings, mode: string): Settings {
+  if (mode !== "off") return { ...settings, autoCompactEnabled: false, env: { ...settings.env, [BLOCKING_LIMIT_ENV]: BLOCKING_LIMIT_OFF } }
+  const { autoCompactEnabled: _, ...rest } = settings
+  return rest.env?.[BLOCKING_LIMIT_ENV] === BLOCKING_LIMIT_OFF ? withoutEnv(rest, BLOCKING_LIMIT_ENV) : rest
+}
+
+export function withEunoe(settings: Settings, port: number, mode: string): Settings {
+  return withCompactionOwner({ ...settings, env: { ...settings.env, ANTHROPIC_BASE_URL: proxyUrl(port) } }, mode)
+}
+
+export function withoutEunoe(settings: Settings, port: number): Settings {
+  return withCompactionOwner(pointsAtEunoe(settings, port) ? withoutEnv(settings, "ANTHROPIC_BASE_URL") : settings, "off")
+}
+
+export function readSettings(dir: string): Settings {
+  try {
+    return JSON.parse(readFileSync(path.join(dir, "settings.json"), "utf8"))
+  } catch {
+    return {}
+  }
+}
+
+export function editSettings(dirs: string[], edit: (settings: Settings) => Settings): string[] {
+  const touched: string[] = []
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue
+    const file = path.join(dir, "settings.json")
+    const current: Settings = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {}
+    const next = edit(current)
+    if (JSON.stringify(next) === JSON.stringify(current)) continue
+    writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`)
+    touched.push(file)
+  }
+  return touched
+}

package/src/cli/proxy/inspect.ts

@@ -0,0 +1,67 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+import { type Config, claudeConfigDirs } from "../../config"
+import { paths } from "../../config/paths"
+import { HEALTH_PATH, type Health } from "../../proxy/server"
+import { parseJsonl } from "../../transcript/parse"
+import { pointsAtEunoe, proxyUrl, readSettings } from "./claude-settings"
+
+export interface RequestRecord {
+  ts: string
+  action?: string
+  thread?: string | null
+  input?: number
+  charsIn?: number
+  charsOut?: number
+  charsFixed?: number
+  cacheRead?: number
+  cacheWrite?: number
+  uncached?: number
+  compacted?: boolean
+  turns?: number
+  reranked?: string
+  rerankError?: string
+  overflow?: number
+  fit?: string
+  [key: string]: unknown
+}
+
+export const RECENT_REQUESTS = 5_000
+
+export async function probe(port: number): Promise<Health | null> {
+  try {
+    const response = await fetch(`${proxyUrl(port)}${HEALTH_PATH}`, { signal: AbortSignal.timeout(800) })
+    if (!response.ok) return null
+    return (await response.json()) as Health
+  } catch {
+    return null
+  }
+}
+
+function newestSource(dir: string): number {
+  let newest = 0
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name)
+    if (entry.isDirectory()) newest = Math.max(newest, newestSource(file))
+    else if (entry.name.endsWith(".ts")) newest = Math.max(newest, statSync(file).mtimeMs)
+  }
+  return newest
+}
+
+export function runsStaleCode(health: Health | null): boolean {
+  if (!health?.startedAt) return health !== null
+  try {
+    return newestSource(path.join(import.meta.dir, "..")) > health.startedAt
+  } catch {
+    return false
+  }
+}
+
+export function routedDirs(config: Config) {
+  return claudeConfigDirs(config).filter((dir) => pointsAtEunoe(readSettings(dir), config.port))
+}
+
+export function recentRequests(limit = RECENT_REQUESTS): RequestRecord[] {
+  if (!existsSync(paths.requests)) return []
+  return parseJsonl<RequestRecord>(readFileSync(paths.requests, "utf8")).slice(-limit)
+}

package/src/cli/proxy/launchd.ts

@@ -0,0 +1,53 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+export interface Agent {
+  label: string
+  plist: string
+  interval?: number
+}
+
+export const supported = process.platform === "darwin"
+
+export function isInstalled(agent: Agent) {
+  return existsSync(agent.plist)
+}
+
+function plistFor(agent: Agent, program: string[], logFile: string) {
+  const args = program.map((arg) => `<string>${arg}</string>`).join("")
+  const schedule = agent.interval ? `<key>StartInterval</key><integer>${agent.interval}</integer>` : `<key>KeepAlive</key><true/>\n  <key>ThrottleInterval</key><integer>1</integer>`
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${agent.label}</string>
+  <key>ProgramArguments</key><array>${args}</array>
+  <key>RunAtLoad</key><true/>
+  ${schedule}
+  <key>StandardOutPath</key><string>${logFile}</string>
+  <key>StandardErrorPath</key><string>${logFile}</string>
+</dict></plist>
+`
+}
+
+export function installAgent(agent: Agent, program: string[], logFile: string) {
+  mkdirSync(path.dirname(agent.plist), { recursive: true })
+  const plist = plistFor(agent, program, logFile)
+  if (existsSync(agent.plist) && readFileSync(agent.plist, "utf8") === plist) {
+    Bun.spawnSync(["launchctl", "load", agent.plist])
+    return
+  }
+  writeFileSync(agent.plist, plist)
+  Bun.spawnSync(["launchctl", "unload", agent.plist])
+  Bun.spawnSync(["launchctl", "load", agent.plist])
+}
+
+export function restartAgent(agent: Agent) {
+  Bun.spawnSync(["launchctl", "kickstart", "-k", `gui/${process.getuid?.() ?? ""}/${agent.label}`])
+}
+
+export function removeAgent(agent: Agent) {
+  if (!existsSync(agent.plist)) return false
+  Bun.spawnSync(["launchctl", "unload", agent.plist])
+  unlinkSync(agent.plist)
+  return true
+}

package/src/cli/proxy/service.ts

@@ -0,0 +1,53 @@
+import { homedir } from "node:os"
+import path from "node:path"
+import type { Config } from "../../config"
+import { paths } from "../../config/paths"
+import type { Health } from "../../proxy/server"
+import { c, line, ok, warn } from "../terminal/ui"
+import { proxyUrl } from "./claude-settings"
+import { probe, runsStaleCode } from "./inspect"
+import * as launchd from "./launchd"
+
+const agentFor = (label: string, interval?: number): launchd.Agent => ({ label, plist: path.join(homedir(), "Library", "LaunchAgents", `${label}.plist`), interval })
+
+export const PROXY_AGENT = agentFor("com.chroxify.eunoe")
+const WATCH_AGENT = agentFor("com.chroxify.eunoe.watch", 10)
+
+const cli = () => path.resolve(process.argv[1] ?? "")
+
+async function waitFor(port: number, ready: (health: Health | null) => boolean) {
+  const deadline = Date.now() + 3_000
+  while (Date.now() < deadline) {
+    if (ready(await probe(port))) return true
+    await Bun.sleep(150)
+  }
+  return false
+}
+
+export async function startService(config: Config) {
+  if (!launchd.supported) {
+    if (await probe(config.port)) return true
+    warn("No launchd here, so keep the proxy running yourself:")
+    line(`    ${c.cyan("eunoe serve")}`)
+    return false
+  }
+  launchd.installAgent(PROXY_AGENT, [process.execPath, cli(), "serve"], paths.proxyLog)
+  launchd.installAgent(WATCH_AGENT, [process.execPath, cli(), "watch"], paths.proxyLog)
+  const running = await probe(config.port)
+  if (running && runsStaleCode(running)) {
+    launchd.restartAgent(PROXY_AGENT)
+    await waitFor(config.port, (health) => health !== null && health.pid !== running.pid)
+  }
+  if (await waitFor(config.port, (health) => health !== null)) {
+    ok(`Proxy running in the background on ${c.cyan(proxyUrl(config.port))}`)
+    return true
+  }
+  warn(`The proxy didn't answer on ${proxyUrl(config.port)}. Check ${paths.proxyLog}.`)
+  return false
+}
+
+export function removeService() {
+  const removed = launchd.removeAgent(PROXY_AGENT)
+  launchd.removeAgent(WATCH_AGENT)
+  return removed
+}

package/src/cli/proxy/stats.ts

@@ -0,0 +1,81 @@
+import type { RequestRecord } from "./inspect"
+
+export interface SessionStats {
+  context: number
+  fixed: number | null
+  plain: number | null
+  turns: number | null
+  requests: number
+  folds: number
+  lastSeen: string
+}
+
+export interface Totals {
+  requests: number
+  cacheRead: number
+  cacheWrite: number
+  uncached: number
+  folds: number
+  lastFold: string | null
+  sent: number
+  saved: number
+}
+
+const sessionOf = (record: RequestRecord): string | null => (typeof record.thread === "string" ? record.thread.replace(/-[0-9a-f]{24}$/, "") : null)
+
+const inputOf = (record: RequestRecord) => record.input ?? 0
+
+function scaled(record: RequestRecord, chars: number | undefined): number | null {
+  const input = inputOf(record)
+  const charsOut = record.charsOut ?? 0
+  return input > 0 && charsOut > 0 && chars && chars > 0 ? Math.round((input * chars) / charsOut) : null
+}
+
+export function withinWindow(records: RequestRecord[], now = Date.now(), window = 24 * 3_600_000): RequestRecord[] {
+  return records.filter((record) => now - Date.parse(record.ts) <= window)
+}
+
+export function perSession(records: RequestRecord[]): Map<string, SessionStats> {
+  const stats = new Map<string, SessionStats>()
+  for (const record of records) {
+    const id = sessionOf(record)
+    if (!id || inputOf(record) <= 0) continue
+    const previous = stats.get(id)
+    stats.set(id, {
+      context: inputOf(record),
+      fixed: scaled(record, record.charsFixed),
+      plain: scaled(record, record.charsIn),
+      turns: record.turns ?? previous?.turns ?? null,
+      requests: (previous?.requests ?? 0) + 1,
+      folds: (previous?.folds ?? 0) + (record.compacted ? 1 : 0),
+      lastSeen: record.ts,
+    })
+  }
+  return stats
+}
+
+export function totals(records: RequestRecord[]): Totals {
+  const out: Totals = { requests: 0, cacheRead: 0, cacheWrite: 0, uncached: 0, folds: 0, lastFold: null, sent: 0, saved: 0 }
+  for (const record of records) {
+    if (inputOf(record) <= 0) continue
+    out.requests += 1
+    out.cacheRead += record.cacheRead ?? 0
+    out.cacheWrite += record.cacheWrite ?? 0
+    out.uncached += record.uncached ?? 0
+    if (record.compacted) {
+      out.folds += 1
+      out.lastFold = record.ts
+    }
+    const plain = scaled(record, record.charsIn)
+    if (plain !== null) {
+      out.sent += inputOf(record)
+      out.saved += plain - inputOf(record)
+    }
+  }
+  return out
+}
+
+export function savedShare(context: number, plain: number | null): number | null {
+  if (!plain) return null
+  return plain > context ? 1 - context / plain : 0
+}

package/src/cli/proxy/watch.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
+import { type Config, claudeConfigDirs, compactionOwner } from "../../config"
+import { paths } from "../../config/paths"
+import { editSettings, withEunoe, withoutEunoe } from "./claude-settings"
+import { probe, routedDirs } from "./inspect"
+
+interface Watch {
+  misses: number
+  paused: string[]
+  pausedAt?: string
+}
+
+interface WatchStep {
+  watch: Watch
+  pause: string[]
+  resume: string[]
+}
+
+export const WATCH_MISSES = 2
+
+const idle = (): Watch => ({ misses: 0, paused: [] })
+
+export function readWatch(): Watch {
+  try {
+    return { ...idle(), ...JSON.parse(readFileSync(paths.watch, "utf8")) }
+  } catch {
+    return idle()
+  }
+}
+
+function saveWatch(watch: Watch) {
+  if (watch.misses === 0 && watch.paused.length === 0) {
+    if (existsSync(paths.watch)) unlinkSync(paths.watch)
+    return
+  }
+  writeFileSync(paths.watch, `${JSON.stringify(watch, null, 2)}\n`)
+}
+
+export function clearWatch() {
+  saveWatch(idle())
+}
+
+export function nextWatch(watch: Watch, alive: boolean, routed: string[], now: string): WatchStep {
+  if (alive) return { watch: idle(), pause: [], resume: watch.paused }
+  if (routed.length === 0) return { watch: { ...watch, misses: 0 }, pause: [], resume: [] }
+  const misses = watch.misses + 1
+  if (misses < WATCH_MISSES) return { watch: { ...watch, misses }, pause: [], resume: [] }
+  return { watch: { misses: 0, paused: [...new Set([...watch.paused, ...routed])], pausedAt: now }, pause: routed, resume: [] }
+}
+
+export async function runWatch(config: Config): Promise<WatchStep> {
+  const alive = (await probe(config.port)) !== null
+  const step = nextWatch(readWatch(), alive, routedDirs(config), new Date().toISOString())
+  if (step.pause.length > 0) editSettings(step.pause, (settings) => withoutEunoe(settings, config.port))
+  const managed = claudeConfigDirs(config)
+  const resumed = step.resume.filter((dir) => managed.includes(dir))
+  if (resumed.length > 0) editSettings(resumed, (settings) => withEunoe(settings, config.port, compactionOwner(config)))
+  saveWatch(step.watch)
+  return step
+}

package/src/cli/replay/index.ts

@@ -0,0 +1,141 @@
+import type { Config } from "../../config"
+import type { Body, Message } from "../../context/content"
+import { isPrompt, type ReduceOptions, reduceTurn, splitTurns, turnFingerprint } from "../../context/fold/turns"
+import { compact } from "../../proxy/compaction"
+import { DEFAULT_RATIO, sizeOf } from "../../proxy/estimate"
+import type { ThreadState } from "../../proxy/state"
+
+export interface ReplayOptions {
+  config: Config
+  window: number
+  fixedTokens: number
+  recallChars?: number
+}
+
+export interface Replay {
+  requests: number
+  turns: number
+  folds: number
+  dropped: number
+  nativeCompactions: number
+  discarded: number
+  plainTokens: number
+  eunoeTokens: number
+  plainCost: number
+  eunoeCost: number
+  peakPlain: number
+  peakEunoe: number
+}
+
+export interface ReplayedSession extends Replay {
+  id: string
+  file: string
+  bytes: number
+  cwd: string | null
+  title: string | null
+  ms: number
+}
+
+export const REPLAY_NATIVE_COMPACT_AT = 0.92
+
+const NATIVE_SUMMARY_CHARS = 30_000
+const CACHE_READ_WEIGHT = 0.1
+const CACHE_WRITE_WEIGHT = 1.25
+
+const emptyChars = sizeOf({ system: "", tools: [], messages: [] })
+const charsOf = (message: Message) => sizeOf({ system: "", tools: [], messages: [message] }) - emptyChars
+const listChars = (sum: number, count: number) => sum + Math.max(0, count - 1)
+const tokens = (chars: number) => Math.round(chars * DEFAULT_RATIO)
+
+function commonPrefix(a: Message[], b: Message[]): number {
+  let chars = 0
+  for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+    if (a[i] !== b[i] && JSON.stringify(a[i]) !== JSON.stringify(b[i])) break
+    chars += charsOf(a[i]) + 1
+  }
+  return chars
+}
+
+export function replaySession(messages: Message[], { config, window, fixedTokens, recallChars: recallPerPrompt = 3_500 }: ReplayOptions): Replay {
+  const out: Replay = { requests: 0, turns: 0, folds: 0, dropped: 0, nativeCompactions: 0, discarded: 0, plainTokens: 0, eunoeTokens: 0, plainCost: 0, eunoeCost: 0, peakPlain: 0, peakEunoe: 0 }
+  const fixedChars = Math.round(fixedTokens / DEFAULT_RATIO)
+  const system = "x".repeat(fixedChars)
+  const sizes = messages.map(charsOf)
+  const { preamble, turns } = splitTurns(messages)
+  const turnAt = [...preamble.map(() => -1), ...turns.flatMap((turn, k) => turn.map(() => k))]
+  const limit = (config.compactAt * window) / DEFAULT_RATIO
+  const cost = (chars: number, cacheable: number) => {
+    const cached = Math.max(0, cacheable - fixedChars)
+    return CACHE_READ_WEIGHT * tokens(cached) + CACHE_WRITE_WEIGHT * tokens(chars - fixedChars - cached)
+  }
+  out.turns = turns.length
+
+  const reduced = new Map<string, Message[]>()
+  const reduce = (turn: Message[], options: ReduceOptions) => {
+    const key = `${turnFingerprint(turn)}:${turn.length}`
+    const hit = reduced.get(key) ?? reduceTurn(turn, options)
+    reduced.set(key, hit)
+    return hit
+  }
+
+  const state: ThreadState = {}
+  const eunoe = { sent: [] as Message[], sum: 0, count: 0, upTo: 0, recall: 0, compactedTurn: -2, previous: 0 }
+  const plain = { sum: 0, count: 0, since: 0, previous: 0 }
+
+  const sendEunoe = (i: number) => {
+    const turn = turnAt[i - 1]
+    const newTurn = turn !== eunoe.compactedTurn
+    if (newTurn && state.cut && isPrompt(messages[i - 1])) eunoe.recall += recallPerPrompt
+    for (; eunoe.upTo < i; eunoe.upTo += 1) {
+      eunoe.sum += sizes[eunoe.upTo]
+      eunoe.count += 1
+    }
+    let cacheable = eunoe.previous
+    if (newTurn || fixedChars + listChars(eunoe.sum, eunoe.count) + eunoe.recall > limit) {
+      const recall = eunoe.recall
+      const decorate = (ms: Message[]) => (recall ? [...ms, { role: "user", content: "r".repeat(recall) }] : ms)
+      const result = compact({ body: { system, tools: [], messages: messages.slice(0, i) } as Body, config, state, window, guide: null, mayCompact: true, reduce, decorate })
+      if (result.note.compacted) out.folds += 1
+      out.dropped = Math.max(out.dropped, Number(result.note.omitted ?? 0))
+      if (result.note.compacted || result.note.actions) cacheable = Math.min(eunoe.previous, fixedChars + commonPrefix(eunoe.sent, result.messages))
+      eunoe.sent = result.messages
+      eunoe.sum = eunoe.sent.reduce((sum, m) => sum + charsOf(m), 0)
+      eunoe.count = eunoe.sent.length
+      eunoe.compactedTurn = turn
+    }
+    const chars = fixedChars + listChars(eunoe.sum, eunoe.count) + eunoe.recall
+    out.eunoeTokens += tokens(chars - fixedChars)
+    out.peakEunoe = Math.max(out.peakEunoe, tokens(chars))
+    out.eunoeCost += cost(chars, cacheable)
+    eunoe.previous = chars
+  }
+
+  const sendPlain = (i: number) => {
+    for (; plain.since < i; plain.since += 1) {
+      plain.sum += sizes[plain.since]
+      plain.count += 1
+    }
+    let chars = fixedChars + listChars(plain.sum, plain.count)
+    let cacheable = plain.previous
+    out.peakPlain = Math.max(out.peakPlain, tokens(chars))
+    if (tokens(chars) > REPLAY_NATIVE_COMPACT_AT * window) {
+      out.nativeCompactions += 1
+      out.discarded += tokens(chars - fixedChars)
+      plain.sum = NATIVE_SUMMARY_CHARS
+      plain.count = 1
+      chars = fixedChars + listChars(plain.sum, plain.count)
+      cacheable = fixedChars
+    }
+    out.plainTokens += tokens(chars - fixedChars)
+    out.plainCost += cost(chars, cacheable)
+    plain.previous = chars
+  }
+
+  for (let i = 1; i < messages.length; i += 1) {
+    if (messages[i].role !== "assistant") continue
+    out.requests += 1
+    sendEunoe(i)
+    sendPlain(i)
+  }
+  return out
+}

package/src/cli/replay/worker.ts

@@ -0,0 +1,15 @@
+import { statSync } from "node:fs"
+import { basename } from "node:path"
+import { cwdOf, titleOf } from "../../proxy/sessions"
+import { sessionMessages } from "../../transcript/messages"
+import { type ReplayedSession, type ReplayOptions, replaySession } from "."
+
+declare var self: Worker
+
+self.onmessage = (event: MessageEvent<{ file: string; options: ReplayOptions }>) => {
+  const { file, options } = event.data
+  const started = performance.now()
+  const replay = replaySession(sessionMessages(file), options)
+  const done: ReplayedSession = { ...replay, id: basename(file, ".jsonl"), file, bytes: statSync(file).size, cwd: cwdOf(file) ?? null, title: titleOf(file) ?? null, ms: Math.round(performance.now() - started) }
+  postMessage(done)
+}

package/src/cli/sessions/browse.ts

@@ -0,0 +1,88 @@
+import { clip } from "../../context/content"
+import { interact, keys, printable } from "../terminal/prompt"
+import { c, wrap } from "../terminal/ui"
+import { askOf, metaOf, shortId } from "."
+import { rankCandidates, type SessionCandidate } from "./source"
+
+export const UNTITLED = "untitled"
+
+const ROWS = 7
+
+const metas = new Map<string, string>()
+
+const columns = () => Math.max(60, process.stdout.columns ?? 100)
+
+function cachedMeta(cand: SessionCandidate) {
+  const meta = metas.get(cand.id) ?? metaOf(cand)
+  metas.set(cand.id, meta)
+  return meta
+}
+
+export function filterCandidates(query: string, candidates: SessionCandidate[]): SessionCandidate[] {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean)
+  if (words.length === 0) return candidates
+  const ranked = rankCandidates(query, candidates)
+  const haystack = (cand: SessionCandidate) => `${cand.label} ${cand.asks.join(" ")} ${cand.id}`.toLowerCase()
+  const loose = candidates.filter((cand) => !ranked.includes(cand) && words.every((word) => haystack(cand).includes(word)))
+  return [...ranked, ...loose]
+}
+
+function row(cand: SessionCandidate, chosen: boolean, width: number): string[] {
+  const marker = chosen ? c.green("●") : c.dim("○")
+  const info = cachedMeta(cand)
+  const title = cand.label ? clip(cand.label, width - info.length - 16) : UNTITLED
+  const head = `  ${marker} ${c.cyan(shortId(cand.id))}  ${chosen ? c.bold(title) : cand.label ? title : c.dim(title)}  ${c.dim(info)}`
+  if (!chosen) return [head]
+  const lines = [head]
+  for (const [label, text] of [
+    ["first", cand.asks[0]],
+    ["last ", cand.asks.at(-1)],
+  ] as const) {
+    const [first = "", ...rest] = wrap(askOf(text), width - 14)
+    lines.push(`      ${c.dim(label)}  ${first}`, ...rest.map((more) => `             ${more}`))
+  }
+  return lines
+}
+
+function render(title: string, query: string, shown: SessionCandidate[], total: number, index: number, help: string): string[] {
+  const width = columns()
+  const lines = [`  ${c.bold(title)}  ${c.dim(`${shown.length} of ${total}`)}`, `  ${c.cyan("›")} ${query || c.dim("type to filter")}`, ""]
+  if (shown.length === 0) lines.push(`  ${c.dim("nothing matches")}`)
+  const start = Math.max(0, Math.min(index - Math.floor(ROWS / 2), shown.length - ROWS))
+  if (start > 0) lines.push(`  ${c.dim(`↑ ${start} more`)}`)
+  for (const [i, cand] of shown.slice(start, start + ROWS).entries()) lines.push(...row(cand, start + i === index, width))
+  if (start + ROWS < shown.length) lines.push(`  ${c.dim(`↓ ${shown.length - start - ROWS} more`)}`)
+  lines.push("", `  ${c.dim(help)}`)
+  return lines
+}
+
+export async function browse(title: string, candidates: SessionCandidate[], initial = "", help = "↑↓ move · type to filter · enter choose · esc quit"): Promise<SessionCandidate | null> {
+  let query = initial
+  let shown = filterCandidates(query, candidates)
+  let index = 0
+  let chosen: SessionCandidate | null = null
+  const step = (by: number) => {
+    index = shown.length > 0 ? (index + shown.length + by) % shown.length : 0
+  }
+  await interact(
+    () => render(title, query, shown, candidates.length, index, help),
+    (key) => {
+      if (key === keys.up || key === keys.down) {
+        step(key === keys.up ? -1 : 1)
+        return
+      }
+      if (keys.enter.includes(key)) {
+        chosen = shown[index] ?? null
+        return true
+      }
+      if (keys.escape.includes(key)) return true
+      if (keys.backspace.includes(key)) query = query.slice(0, -1)
+      else if (key === keys.clear) query = ""
+      else if (printable(key)) query += key
+      else return
+      shown = filterCandidates(query, candidates)
+      index = 0
+    },
+  )
+  return chosen
+}