opencode-context-tree 0.1.0

package/src/core/journal.ts

@@ -0,0 +1,343 @@
+/**
+ * Journal entry types and pure fold logic (DESIGN.md §4.1).
+ *
+ * This module must never import from `@opencode-ai/*`, `@opentui/*`, or
+ * `solid-js` — it is plain, deterministic TypeScript, unit-tested with
+ * fixtures, and run in both the server and TUI plugin halves.
+ */
+import { z } from "zod"
+
+// ---------------------------------------------------------------------------
+// Journal line payloads, one schema per `type` in DESIGN.md §4.1's table.
+// ---------------------------------------------------------------------------
+
+export const TreeCreatedData = z.object({
+  rootSessionID: z.string(),
+})
+export type TreeCreatedData = z.infer<typeof TreeCreatedData>
+
+export const BranchKind = z.enum(["explicit", "jump", "redo", "native"])
+export type BranchKind = z.infer<typeof BranchKind>
+
+export const BranchOpenedData = z.object({
+  sessionID: z.string(),
+  parentSessionID: z.string(),
+  anchorMessageID: z.string(),
+  name: z.string().optional(),
+  trunkModel: z.string().optional(),
+  branchModel: z.string().optional(),
+  kind: BranchKind,
+})
+export type BranchOpenedData = z.infer<typeof BranchOpenedData>
+
+export const BranchStatus = z.enum(["squashed", "rejected", "discarded", "abandoned"])
+export type BranchStatus = z.infer<typeof BranchStatus>
+
+export const BranchClosedData = z.object({
+  sessionID: z.string(),
+  status: BranchStatus,
+  decisionMessageID: z.string().optional(),
+  note: z.string().optional(),
+})
+export type BranchClosedData = z.infer<typeof BranchClosedData>
+
+export const SummaryRecordedData = z.object({
+  sessionID: z.string(),
+  messageID: z.string(),
+  fromSessionID: z.string(),
+  fromMessageID: z.string(),
+})
+export type SummaryRecordedData = z.infer<typeof SummaryRecordedData>
+
+export const DecisionRecordedData = z.object({
+  /** The record text as landed in the trunk (kept here so compaction re-injection and the
+   *  decisions view need no OpenCode round-trip). */
+  text: z.string().optional(),
+  sessionID: z.string(),
+  messageID: z.string(),
+  forkSessionID: z.string(),
+  branchName: z.string(),
+  siblings: z.array(z.object({ name: z.string(), reason: z.string().optional() })),
+})
+export type DecisionRecordedData = z.infer<typeof DecisionRecordedData>
+
+export const CropMode = z.enum(["result", "turn"])
+export type CropMode = z.infer<typeof CropMode>
+
+export const CropTarget = z.object({
+  messageID: z.string(),
+  partID: z.string().optional(),
+  callID: z.string().optional(),
+  tool: z.string().optional(),
+  estTokens: z.number(),
+  sha8: z.string(),
+})
+export type CropTarget = z.infer<typeof CropTarget>
+
+export const CropAppliedData = z.object({
+  sessionID: z.string(),
+  mode: CropMode,
+  targets: z.array(CropTarget),
+  anchorMessageID: z.string(),
+})
+export type CropAppliedData = z.infer<typeof CropAppliedData>
+
+export const CropRestoredData = z.object({
+  cropID: z.string(),
+})
+export type CropRestoredData = z.infer<typeof CropRestoredData>
+
+export const LabelSetData = z.object({
+  sessionID: z.string(),
+  messageID: z.string(),
+  label: z.string().nullable(),
+})
+export type LabelSetData = z.infer<typeof LabelSetData>
+
+export const SessionForgottenData = z.object({
+  sessionID: z.string(),
+})
+export type SessionForgottenData = z.infer<typeof SessionForgottenData>
+
+// ---------------------------------------------------------------------------
+// The envelope and its discriminated-union variants.
+// ---------------------------------------------------------------------------
+
+export const JournalActor = z.enum(["tui", "server", "cli"])
+export type JournalActor = z.infer<typeof JournalActor>
+
+const envelope = <Type extends string, Data extends z.ZodTypeAny>(type: Type, data: Data) =>
+  z.object({
+    v: z.literal(1),
+    id: z.string(),
+    ts: z.number(),
+    type: z.literal(type),
+    actor: JournalActor,
+    data,
+  })
+
+export const JournalEntrySchema = z.discriminatedUnion("type", [
+  envelope("tree.created", TreeCreatedData),
+  envelope("branch.opened", BranchOpenedData),
+  envelope("branch.closed", BranchClosedData),
+  envelope("summary.recorded", SummaryRecordedData),
+  envelope("decision.recorded", DecisionRecordedData),
+  envelope("crop.applied", CropAppliedData),
+  envelope("crop.restored", CropRestoredData),
+  envelope("label.set", LabelSetData),
+  envelope("session.forgotten", SessionForgottenData),
+])
+export type JournalEntry = z.infer<typeof JournalEntrySchema>
+export type JournalEntryType = JournalEntry["type"]
+
+/** Parse one JSONL line into a validated journal entry, or `undefined` if it is malformed. */
+export function parseJournalLine(line: string): JournalEntry | undefined {
+  const trimmed = line.trim()
+  if (!trimmed) return undefined
+  let json: unknown
+  try {
+    json = JSON.parse(trimmed)
+  } catch {
+    return undefined
+  }
+  const result = JournalEntrySchema.safeParse(json)
+  return result.success ? result.data : undefined
+}
+
+/** Parse a whole journal file's contents (one JSON object per line), skipping malformed lines. */
+export function parseJournal(contents: string): JournalEntry[] {
+  const entries: JournalEntry[] = []
+  for (const line of contents.split("\n")) {
+    const entry = parseJournalLine(line)
+    if (entry) entries.push(entry)
+  }
+  return entries
+}
+
+// ---------------------------------------------------------------------------
+// Folded state.
+// ---------------------------------------------------------------------------
+
+export type BranchState = {
+  sessionID: string
+  parentSessionID: string
+  anchorMessageID: string
+  name?: string
+  kind: BranchKind
+  trunkModel?: string
+  branchModel?: string
+  /** Alias of `branchModel`, the model this branch should run on (DESIGN.md §5's `/branch <name> [model]`). */
+  model?: string
+  /** "open" until a matching branch.closed; "forgotten" sessions stay in this map, greyed out. */
+  status: "open" | BranchStatus
+  decisionMessageID?: string
+  note?: string
+  forgotten: boolean
+}
+
+export type CropState = {
+  cropID: string
+  sessionID: string
+  mode: CropMode
+  targets: CropTarget[]
+  anchorMessageID: string
+  restored: boolean
+}
+
+export type DecisionState = {
+  sessionID: string
+  messageID: string
+  forkSessionID: string
+  branchName: string
+  siblings: { name: string; reason?: string }[]
+  text?: string
+  /** True once the branch it closed was re-opened by /undo: the message stays on screen
+   *  but the server hides it from the model (DESIGN.md §12 decision 4). */
+  hidden: boolean
+  recordedAt: number
+}
+
+export type TreeState = {
+  treeId: string
+  root?: string
+  /** All sessions the plugin knows about, keyed by sessionID (root included, as a degenerate branch-less entry only if it was itself forked from). */
+  sessions: Record<string, BranchState>
+  /** All crops ever applied, keyed by a synthesized cropID (index-based, stable within one fold). */
+  crops: Record<string, CropState>
+  /** Bookmarks, keyed by messageID. */
+  labels: Record<string, { sessionID: string; messageID: string; label: string }>
+  /** Decision records, keyed by messageID. */
+  decisions: Record<string, DecisionState>
+  /** Active (non-restored) crops for a session, in application order. Bound to this state. */
+  activeCrops: (sessionID: string) => CropState[]
+}
+
+function emptyTree(treeId: string): Omit<TreeState, "activeCrops"> {
+  return { treeId, root: undefined, sessions: {}, crops: {}, labels: {}, decisions: {} }
+}
+
+/** cropID is not carried on `crop.applied` itself — DESIGN.md's `crop.restored` refers to it by
+ *  the id of the applying journal entry, since a crop is uniquely identified by the event that
+ *  created it. */
+function cropIdFor(entry: Extract<JournalEntry, { type: "crop.applied" }>): string {
+  return entry.id
+}
+
+/**
+ * Fold an ordered list of journal entries into the current tree state. Pure and
+ * deterministic: folding the same entries in the same order always yields the same
+ * result, and folding is idempotent when an entry set is re-folded (e.g. after
+ * appending more lines, refold from scratch — this function does not do incremental
+ * folding itself, callers may cache on top of it).
+ */
+export function foldJournal(entries: JournalEntry[], treeId = "default"): TreeState {
+  const state = emptyTree(treeId)
+
+  for (const entry of entries) {
+    switch (entry.type) {
+      case "tree.created": {
+        state.root = entry.data.rootSessionID
+        break
+      }
+      case "branch.opened": {
+        const d = entry.data
+        const previous = state.sessions[d.sessionID]
+        // both halves adopt native forks independently, so the same branch can be opened
+        // twice; the first entry wins (re-opening a *closed* branch still folds)
+        if (previous?.status === "open") break
+        if (previous?.decisionMessageID) {
+          const decision = state.decisions[previous.decisionMessageID]
+          if (decision) decision.hidden = true
+        }
+        state.sessions[d.sessionID] = {
+          sessionID: d.sessionID,
+          parentSessionID: d.parentSessionID,
+          anchorMessageID: d.anchorMessageID,
+          name: d.name,
+          kind: d.kind,
+          trunkModel: d.trunkModel,
+          branchModel: d.branchModel,
+          model: d.branchModel,
+          status: "open",
+          forgotten: false,
+        }
+        break
+      }
+      case "branch.closed": {
+        const branch = state.sessions[entry.data.sessionID]
+        if (branch) {
+          branch.status = entry.data.status
+          branch.decisionMessageID = entry.data.decisionMessageID
+          branch.note = entry.data.note
+          if (entry.data.decisionMessageID) {
+            const decision = state.decisions[entry.data.decisionMessageID]
+            if (decision) decision.hidden = false
+          }
+        }
+        break
+      }
+      case "summary.recorded": {
+        // Summaries do not change tree shape; they are surfaced by the caller via the
+        // raw entry list if needed (e.g. to render a ◇ marker). Nothing to fold here.
+        break
+      }
+      case "decision.recorded": {
+        const d = entry.data
+        state.decisions[d.messageID] = {
+          sessionID: d.sessionID,
+          messageID: d.messageID,
+          forkSessionID: d.forkSessionID,
+          branchName: d.branchName,
+          siblings: d.siblings,
+          text: d.text,
+          hidden: false,
+          recordedAt: entry.ts,
+        }
+        break
+      }
+      case "crop.applied": {
+        const cropID = cropIdFor(entry)
+        state.crops[cropID] = {
+          cropID,
+          sessionID: entry.data.sessionID,
+          mode: entry.data.mode,
+          targets: entry.data.targets,
+          anchorMessageID: entry.data.anchorMessageID,
+          restored: false,
+        }
+        break
+      }
+      case "crop.restored": {
+        const crop = state.crops[entry.data.cropID]
+        if (crop) crop.restored = true
+        break
+      }
+      case "label.set": {
+        const d = entry.data
+        if (d.label === null) {
+          delete state.labels[d.messageID]
+        } else {
+          state.labels[d.messageID] = { sessionID: d.sessionID, messageID: d.messageID, label: d.label }
+        }
+        break
+      }
+      case "session.forgotten": {
+        const branch = state.sessions[entry.data.sessionID]
+        if (branch) branch.forgotten = true
+        break
+      }
+    }
+  }
+
+  return {
+    ...state,
+    activeCrops: (sessionID: string) => activeCrops(state as TreeState, sessionID),
+  }
+}
+
+/** Active (non-restored) crops for a given session, in application order. */
+export function activeCrops(state: TreeState, sessionID: string): CropState[] {
+  return Object.values(state.crops)
+    .filter((c) => c.sessionID === sessionID && !c.restored)
+    .sort((a, b) => (a.cropID < b.cropID ? -1 : a.cropID > b.cropID ? 1 : 0))
+}

package/src/core/lanes.ts

@@ -0,0 +1,149 @@
+/**
+ * DSH-style timeline lanes (DESIGN.md §7.1, §7.3): one column per unit of the
+ * chosen mode, three series — Input (context size at each assistant turn), Model
+ * (output tokens per assistant step), Tools (result size per tool call, errors
+ * flagged). Pure.
+ */
+import { estimateTokens } from "./tokens.js"
+import type { Transcript, TranscriptMessage } from "./transcript.js"
+
+export type LaneMode = "turns" | "calls" | "duration"
+
+export type LaneColumn = {
+  /** identifies what the column represents, for cursor mirroring */
+  messageID: string
+  /** the column's user message, so the cursor also mirrors ● rows (turns/duration mode) */
+  userMessageID?: string
+  partID?: string
+  turn: number
+  input: number
+  output: number
+  tool: number
+  toolError: boolean
+  /** wall-clock span of the column, ms (duration mode) */
+  ms: number
+}
+
+export type Lanes = { mode: LaneMode; columns: LaneColumn[] }
+
+type Turn = { user?: TranscriptMessage; assistants: TranscriptMessage[]; index: number }
+
+function turnsOf(messages: TranscriptMessage[]): Turn[] {
+  const out: Turn[] = []
+  let index = 0
+  for (const m of messages) {
+    if (m.role === "user") out.push({ user: m, assistants: [], index: ++index })
+    else {
+      // after a compaction the transcript opens with an assistant summary: it gets turn 0
+      if (out.length === 0) out.push({ assistants: [], index: 0 })
+      out[out.length - 1]!.assistants.push(m)
+    }
+  }
+  return out
+}
+
+function spanOf(m: TranscriptMessage): number {
+  const end = m.time.completed ?? m.parts.reduce((e, p) => Math.max(e, p.state?.time?.end ?? p.time?.end ?? 0), 0)
+  return end > m.time.created ? end - m.time.created : 0
+}
+
+export function buildLanes(transcript: Transcript, mode: LaneMode): Lanes {
+  const columns: LaneColumn[] = []
+  for (const turn of turnsOf(transcript.messages)) {
+    if (mode === "calls") {
+      let any = false
+      for (const m of turn.assistants) {
+        for (const p of m.parts) {
+          if (p.type !== "tool") continue
+          any = true
+          const out = p.state?.output ?? ""
+          const t = p.state?.time
+          columns.push({ messageID: m.id, userMessageID: turn.user?.id, partID: p.id, turn: turn.index, input: m.tokens?.input ?? 0, output: 0, tool: estimateTokens(out), toolError: p.state?.status === "error", ms: t?.start !== undefined && t?.end !== undefined ? t.end - t.start : 0 })
+        }
+      }
+      if (!any) {
+        const last = turn.assistants.at(-1)
+        columns.push({ messageID: last?.id ?? turn.user?.id ?? "", userMessageID: turn.user?.id, turn: turn.index, input: last?.tokens?.input ?? 0, output: last?.tokens?.output ?? 0, tool: 0, toolError: false, ms: last ? spanOf(last) : 0 })
+      }
+      continue
+    }
+    // turns / duration: one column per user turn
+    const last = turn.assistants.at(-1)
+    let tool = 0
+    let toolError = false
+    let ms = 0
+    let output = 0
+    for (const m of turn.assistants) {
+      output += m.tokens?.output ?? 0
+      ms += spanOf(m)
+      for (const p of m.parts) {
+        if (p.type !== "tool") continue
+        tool += estimateTokens(p.state?.output ?? "")
+        if (p.state?.status === "error") toolError = true
+      }
+    }
+    columns.push({ messageID: last?.id ?? turn.user?.id ?? "", userMessageID: turn.user?.id, turn: turn.index, input: last?.tokens?.input ?? 0, output, tool, toolError, ms })
+  }
+  return { mode, columns }
+}
+
+const BLOCKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+
+/** `scale` (the model's context limit for the Input lane) fixes the reference height, so a
+ *  two-message session no longer draws a full bar next to `ctx 100 · low`. */
+export function sparkline(values: number[], width: number, scale?: number): string {
+  if (values.length === 0 || width <= 0) return ""
+  const cells = fitColumns(values, width)
+  const max = Math.max(1, scale ?? 0, ...cells)
+  return cells.map((v) => (v <= 0 ? " " : BLOCKS[Math.min(7, Math.floor((v / max) * 7.999))]!)).join("")
+}
+
+/** Resample `values` to exactly `width` cells (max-pooling when shrinking, repeating when growing). */
+export function fitColumns(values: number[], width: number): number[] {
+  if (values.length === 0) return []
+  if (values.length === width) return values.slice()
+  const out: number[] = []
+  if (values.length > width) {
+    const per = values.length / width
+    for (let i = 0; i < width; i++) {
+      const a = Math.floor(i * per)
+      const b = Math.max(a + 1, Math.floor((i + 1) * per))
+      out.push(Math.max(...values.slice(a, b)))
+    }
+    return out
+  }
+  const rep = width / values.length
+  for (let i = 0; i < width; i++) out.push(values[Math.min(values.length - 1, Math.floor(i / rep))]!)
+  return out
+}
+
+/** Duration mode: repeat each column proportionally to its wall-clock share. */
+export function durationWeighted(lanes: Lanes, width: number): { input: number[]; output: number[]; tool: number[]; toolError: boolean[]; columnAt: (cell: number) => number } {
+  const total = lanes.columns.reduce((s, c) => s + Math.max(1, c.ms), 0) || 1
+  const input: number[] = []
+  const output: number[] = []
+  const tool: number[] = []
+  const toolError: boolean[] = []
+  const owner: number[] = []
+  lanes.columns.forEach((c, i) => {
+    const cells = Math.max(1, Math.round((Math.max(1, c.ms) / total) * width))
+    for (let k = 0; k < cells; k++) {
+      input.push(c.input)
+      output.push(c.output)
+      tool.push(c.tool)
+      toolError.push(c.toolError)
+      owner.push(i)
+    }
+  })
+  return { input, output, tool, toolError, columnAt: (cell) => owner[Math.min(owner.length - 1, Math.max(0, cell))] ?? 0 }
+}
+
+/** Index of the column that contains a given message/part (for the cursor marker). */
+export function columnFor(lanes: Lanes, messageID: string, partID?: string): number {
+  if (partID) {
+    const i = lanes.columns.findIndex((c) => c.partID === partID)
+    if (i >= 0) return i
+  }
+  const i = lanes.columns.findIndex((c) => c.messageID === messageID || c.userMessageID === messageID)
+  return i >= 0 ? i : -1
+}

package/src/core/navigation.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure row-selection and expand/filter helpers for the tree + trajectory route
+ * (DESIGN.md §7). Operates on a `Row[]`/`TreeView` built by `core/tree.ts`.
+ *
+ * Pure, no OpenCode/opentui/solid-js imports — see test/core-purity.test.ts.
+ */
+import type { Filter, Row, TreeView } from "./tree.js"
+
+/** Move the selection by `delta` rows, clamped to the row list's bounds.
+ *  Returns -1 for an empty row list. */
+export function moveSelection(rows: Row[], index: number, delta: number): number {
+  if (rows.length === 0) return -1
+  const next = index + delta
+  if (next < 0) return 0
+  if (next > rows.length - 1) return rows.length - 1
+  return next
+}
+
+/** The next/previous `branch` row from `index` in direction `dir` (DESIGN.md §7.2's
+ *  gutter jump). Stays put if there is no branch row in that direction. */
+export function nextBranchIndex(rows: Row[], index: number, dir: 1 | -1): number {
+  if (rows.length === 0) return index
+  let i = index
+  for (let step = 0; step < rows.length; step++) {
+    i += dir
+    if (i < 0 || i >= rows.length) return index
+    if (rows[i]!.kind === "branch") return i
+  }
+  return index
+}
+
+/** Toggle one sessionID's membership in the `expanded` set, returning a new Set
+ *  (DESIGN.md §7's `e`/`→` expand, `←` fold). */
+export function toggleExpanded(expanded: Set<string>, sessionID: string): Set<string> {
+  const next = new Set(expanded)
+  if (next.has(sessionID)) next.delete(sessionID)
+  else next.add(sessionID)
+  return next
+}
+
+const FILTER_ORDER: Filter[] = ["default", "no-tools", "user-only", "labeled", "all"]
+
+/** `f` cycles `default → no-tools → user-only → labeled → all → default …`
+ *  (DESIGN.md §7.5). */
+export function cycleFilter(filter: Filter): Filter {
+  const idx = FILTER_ORDER.indexOf(filter)
+  return FILTER_ORDER[(idx + 1) % FILTER_ORDER.length]!
+}
+
+/**
+ * Resolve which row index should carry the selection after the view was rebuilt
+ * (a filter/search/expand change, a journal refold, …):
+ * 1. `preferredId` (the previously-selected row's id) if it is still present.
+ * 2. Failing that, the nearest surviving row for the same message — a step row's
+ *    id is `sessionID:messageID:partID`, so its owning turn (`sessionID:messageID`)
+ *    is a reasonable "nearest" landing spot when the step itself was filtered out.
+ * 2b. `previousIndex`, clamped, when given — keeps the cursor where it was.
+ * 3. `currentRowId` (or, failing that, `view.currentRowId`) — the "you are here" row.
+ * 4. The first row, or -1 if the view is empty.
+ */
+export function resolveSelection(
+  view: TreeView,
+  preferredId: string | undefined,
+  currentRowId: string | undefined,
+  previousIndex?: number,
+): number {
+  if (view.rows.length === 0) return -1
+
+  if (preferredId !== undefined) {
+    const exact = view.indexById[preferredId]
+    if (exact !== undefined) return exact
+
+    const owner = preferredId.split(":").slice(0, 2).join(":")
+    for (let i = 0; i < view.rows.length; i++) {
+      const row = view.rows[i]!
+      const rowOwner = row.kind === "branch" ? row.id : `${row.sessionID}:${row.messageID}`
+      if (rowOwner === owner) return i
+    }
+  }
+
+  // 2b. the row that now sits where the old selection was (filter/fold changed the list)
+  if (previousIndex !== undefined && previousIndex >= 0) return Math.min(previousIndex, view.rows.length - 1)
+
+  if (currentRowId !== undefined) {
+    const idx = view.indexById[currentRowId]
+    if (idx !== undefined) return idx
+  }
+
+  if (view.currentRowId !== undefined) {
+    const idx = view.indexById[view.currentRowId]
+    if (idx !== undefined) return idx
+  }
+
+  return 0
+}

package/src/core/tokens.ts

@@ -0,0 +1,105 @@
+/**
+ * Token estimation and context-size bands (DESIGN.md §3.3, §6.7).
+ *
+ * Pure, no OpenCode/opentui imports — see test/core-purity.test.ts.
+ */
+
+/** chars/4 heuristic used throughout the design for anything not yet costed by the model. */
+export function estimateTokens(text: string): number {
+  if (!text) return 0
+  return Math.ceil(text.length / 4)
+}
+
+export type MinimalPart = {
+  type: string
+  text?: string
+  tool?: string
+  state?: {
+    status?: string
+    input?: unknown
+    output?: string
+    title?: string
+  }
+}
+
+export type MinimalAssistantInfo = {
+  role: "assistant"
+  tokens?: { input?: number; output?: number; reasoning?: number; cache?: { read?: number; write?: number } }
+}
+
+export type MinimalMessageInfo = MinimalAssistantInfo | { role: "user" | "system" }
+
+export type MinimalMessage = {
+  info: MinimalMessageInfo
+  parts: MinimalPart[]
+}
+
+/** Rough text content of a part, for chars/4 estimation of anything newer than the last assistant turn. */
+function partText(part: MinimalPart): string {
+  if (part.type === "text" || part.type === "reasoning") return part.text ?? ""
+  if (part.type === "tool") {
+    const input = part.state?.input !== undefined ? JSON.stringify(part.state.input) : ""
+    const output = typeof part.state?.output === "string" ? part.state.output : ""
+    return `${part.tool ?? ""} ${input} ${output}`
+  }
+  return ""
+}
+
+/**
+ * Context size of a session's message list: the last assistant turn's real
+ * `tokens.input`, plus a chars/4 estimate of everything the next request will add on
+ * top of it — that turn's own output and tool results included (DESIGN.md §3.3 /
+ * §6.7). Returns `{ tokens, estimated }`; `estimated` is true whenever any part of
+ * the figure is a chars/4 guess.
+ */
+export function contextSizeOf(messages: MinimalMessage[]): { tokens: number; estimated: boolean } {
+  let lastAssistantIndex = -1
+  let lastAssistantInput = 0
+  for (let i = 0; i < messages.length; i++) {
+    const info = messages[i]!.info
+    if (info.role === "assistant" && typeof info.tokens?.input === "number") {
+      lastAssistantIndex = i
+      lastAssistantInput = info.tokens.input
+    }
+  }
+
+  if (lastAssistantIndex === -1) {
+    // No costed assistant turn yet: everything is an estimate.
+    let estimated = 0
+    for (const message of messages) {
+      for (const part of message.parts) estimated += estimateTokens(partText(part))
+    }
+    return { tokens: estimated, estimated: true }
+  }
+
+  // starts AT the last assistant: its `tokens.input` is the context it was *given*, so its
+  // own output and tool results are only in the context from the next request on.
+  let newer = 0
+  for (let i = lastAssistantIndex; i < messages.length; i++) {
+    for (const part of messages[i]!.parts) newer += estimateTokens(partText(part))
+  }
+
+  return { tokens: lastAssistantInput + newer, estimated: newer > 0 }
+}
+
+export type ContextBand = "low" | "healthy" | "filling" | "red"
+
+/** Absolute bands from DESIGN.md §6.7: <8k low · 8-32k healthy · 32-64k filling · >=64k red. */
+export function bandFor(tokens: number): ContextBand {
+  if (tokens < 8_000) return "low"
+  if (tokens < 32_000) return "healthy"
+  if (tokens < 64_000) return "filling"
+  return "red"
+}
+
+/** `12345` → `12.3k`, `800` → `800`. */
+export function formatK(tokens: number): string {
+  if (tokens < 1000) return String(tokens)
+  const k = (tokens / 1000).toFixed(1)
+  return `${k.endsWith(".0") ? k.slice(0, -2) : k}k`
+}
+
+/** The one context string every surface shows: `ctx ~2.3k/32.8k · low` (`~` when estimated). */
+export function formatContext(size: { tokens: number; estimated: boolean }, limit?: number): string {
+  return `ctx ${size.estimated ? "~" : ""}${formatK(size.tokens)}${limit ? `/${formatK(limit)}` : ""} · ${bandFor(size.tokens)}`
+}