opencode-context-tree 0.1.0

package/docs/USAGE.md

@@ -0,0 +1,155 @@
+# opencode-context-tree — usage
+
+## Install
+
+```jsonc
+// opencode.json (server half: crops, branch model, headless /ctree commands)
+{ "plugin": [["opencode-context-tree", { "storage": "local" }]] }
+// tui.json (TUI half: /tree, /branch, /merge, /decisions, gauge, sidebar card)
+{ "plugin": [["opencode-context-tree", { "storage": "local", "jumpSummary": "ask" }]] }
+```
+
+Each half only sees the options of its own file, and both halves read `storage` — so if you
+change it, **set the same `storage` in both files**, or the TUI and the server end up with
+two different journals (crops written by one would never reach the other). The remaining
+options only matter to the half that implements them (`storage` both; `jumpSummary`,
+`hardCrop`, `keybinds` TUI-only). Plain `{ "plugin": ["opencode-context-tree"] }` in both
+files is fine and uses the defaults.
+
+From a checkout: `bun install && bun run build`, then list `/abs/path/dist/server.js` and
+`/abs/path/dist/tui.js` instead of the package name.
+
+Options: `storage` `"local"` (default, `.opencode/context-tree/` in the worktree, gitignored)
+or `"global"` (OpenCode's state dir); `jumpSummary` `"ask"` (default, Pi behaviour) or `"never"`;
+`hardCrop` `true` also sets OpenCode's own "compacted" flag on cropped tool parts so the
+transcript shows `[Old tool result content cleared]` (reversible by undo, but it touches
+OpenCode storage — off by default); `keybinds` overrides any route key by command name,
+e.g. `{ "keybinds": { "open": "ctrl+t", "up": "k,up", "copy": "none" } }` — names are
+`open up down jump_up jump_down first last prev_branch next_branch fold unfold toggle go
+branch label filter search back crop crop_toggle_mode mark auto undo merge inspector
+consumers copy mode_duration mode_turns mode_calls decisions export help`.
+
+## The loop
+
+```
+/branch            name it → you are on ⎇ name, a real OpenCode session (b in the tree
+                   also asks "Model for this branch", Enter keeps the current one)
+…side quest…
+/merge             Squash → the branch model drafts a ◆ decision record → your $EDITOR →
+                   save to confirm → the record lands in the trunk as one message; the
+                   noisy turns stay on the branch
+/tree              see where you are, what it costs, and jump anywhere
+c … space … ⏎      crop a fat tool result (double space for protected ones) → the model
+                   sees "[cropped: bash …]" from the next turn; the transcript keeps the text
+x                  undo the last crop / branch / merge on this path
+```
+
+`/merge` asks how to close the branch:
+
+| option | what it does |
+|---|---|
+| **Squash** | drafts a ◆ decision record you confirm — one model call, then your `$EDITOR` (or an in-app confirm when none is set); it lands in the trunk as one message |
+| **Squash without LLM** | you write the record yourself, from the empty template |
+| **Discard** | rejected; nothing lands in the trunk |
+| **Tournament** | compare sibling branches and keep one — only offered when the branch has open siblings |
+
+Every confirmation repeats the promise: *your transcript is never rewritten; the record is
+appended to the trunk as a normal message.*
+
+## `/tree` keys
+
+| key | action |
+|---|---|
+| `↑↓` `j k` · `J K` (20) · `g G` | move |
+| `[` `]` | previous / next branch row |
+| `← →` `h l` `e` | fold / unfold a branch inline |
+| `⏎` | go here: switch to a branch tip, or fork (a user turn = redo with the text pre-filled; a step = continue from there). Asks "Summarize the branch you are leaving?" (Pi) |
+| `b` | branch here: name it, then "Model for this branch" (Enter keeps the current one) |
+| `m` | merge: Squash / Squash without LLM / Discard / Tournament (siblings only) |
+| `c` `space` `a` `t` `⏎` | crop mode: mark, auto-mark (≥10k tokens, older than 2 turns), result⇄turn, apply |
+| `x` | undo |
+| `D` `E` | decisions panel, export `ctree-decisions.md` |
+| `u` | consumers: what is filling the context |
+| `i` | inspector pane on/off (auto-hidden under 110 columns) |
+| `1 2 3` | minimap lanes by duration / turns / tool calls |
+| `L` | label the selected message |
+| `f` `/` | filter cycle (default → no-tools → user-only → labeled → all), search |
+| `y` | save the selected text to `.opencode/context-tree/last-copy.txt` |
+| `?` | help overlay: how to read the screen + every key (`?` or `esc` closes) |
+| `q` `esc` | back (esc leaves crop mode / panels first) |
+
+The footer only lists the six you need — `⏎ go  b branch  m merge  c crop  x undo  ? help
+q back`; the rest live behind `?`.
+
+Palette: **Context tree**, **Branch here**, **Merge branch**, **Decisions**, **Label this point**.
+`ctrl+q` opens the tree.
+
+## Reading the screen
+
+```
+┌ Context tree · Fix flaky test · trunk                        ctx ~46k/200k · filling
+│ filter: default 24 rows
+│ ● user: build yourself a tool that reads the context window…              ~1.2k
+│ ○ assistant: I'll start by inspecting my environment…                      0.3k
+│ ⚙ [bash $ ls -la ~/Documents/] → total 744 …                              ~2.1k
+│ ● user: decompress the session and show the structure                     ~0.2k
+│ ╰⎇ try-redis  ▸ squashed · 9 turns                                         ~22k
+│ ╰⎇ fix-flaky  ▾ open · 6 turns  ← here                                     ~14k
+│ │ ● user: the bun test is flaky, find the race                            ~0.4k
+│ │ ⚙ [bash $ bun test src/foo.test.ts] ⚠                                    ~4.7k
+│ ◆ Decision: try-redis · Outcome: switched to a write-through cache…        ~0.9k
+└ ⏎ go  b branch  m merge  c crop  i inspector  1·2·3 lanes  x undo  ? help  q back
+```
+
+- `/tree` is an outline of the *whole* tree: one content-forward row per message (`● user:` /
+  `○ assistant:`) and tool step (`⚙ [bash $ …]` / `[tool: arg] → out`). From anywhere you see the
+  whole tree — your branch open with `← here`, the rest folded to their `⎇` header (`→` opens one).
+- The Input/Model/Tools lanes and the right-hand inspector (DeepSeek-Harness trajectory) are OFF by
+  default so the first screen is the clean outline; `1/2/3` bring in the lanes, `i` the inspector.
+- The header's context string is the same one the prompt gauge shows, character for
+  character. The lanes only appear once there are three turns to plot; a session with no
+  messages says so instead of drawing an empty frame.
+- `⎇` rows hang off the message they were forked from. Colours: open green, squashed blue,
+  rejected red, abandoned/deleted grey.
+- From inside a branch, its own `⎇` row is drawn at the fork point with `← here`; the rows
+  below it are the branch's own turns.
+- `┆⎇` rows at the bottom are branches you cannot reach on the active path (siblings, or the
+  trunk continuing past your fork point); `⏎` switches to them, `→` expands them.
+- Sessions made with OpenCode's own `/fork` are adopted into the tree automatically (matched
+  to their parent by the copied message prefix; they show under the session's title).
+- Tokens: a leading `~` means estimated (chars/4); assistant steps use the model's own counts.
+  Step durations and lane heights are read from the same data — estimated wherever the `~` is.
+- `⚠` ≥10k tokens, `✂` cropped, `✗` tool error, `◆` decision record, `◇` branch summary.
+- A branch you just made says `just branched, nothing here yet` — there is nothing to unfold.
+- The gauge on the prompt line: `⎇ fix-flaky · ctx ~46k/200k · filling ▲+24% (bash)` —
+  absolute bands (<8k low · 8–32k healthy · 32–64k filling · ≥64k red), the jump since the
+  last look and what caused it. One toast when you enter red; one when OpenCode's
+  auto-compaction is near.
+- The sidebar card, under a **Context tree** heading: `⎇ <branch>` and, on its own line,
+  `open · from "<the session you forked>"` — or `trunk · 2 branches` when you are on the
+  trunk. Active crops add `✂ 2 crops · ~31k hidden`; last line is the `/tree · ctrl+q` hint.
+
+## Headless (desktop / web / scripts)
+
+`/ctree status` · `/ctree branch <name> [provider/model]` · `/ctree merge --discard [note]` ·
+`/ctree crop --top [--apply]` ·
+`/ctree crop --auto [--apply] [--min-tokens N] [--older-than N] [--keep glob]` · `/ctree undo` ·
+`/ctree decisions [--export [path]]` (no path → `./ctree-decisions.md`, relative to the
+project directory). These run as OpenCode commands, so the model answers with a one-line
+acknowledgement. (Squash merges need the TUI's `$EDITOR` gate.)
+
+`/ctree branch` takes the whole rest of the line as the name unless the last word looks like
+a model (`provider/model`): `/ctree branch fix flaky test` names the branch "fix flaky test",
+`/ctree branch fix anthropic/claude-haiku-4-5` names it "fix" and runs it on that model.
+
+## What is (and is not) touched
+
+- Branch = OpenCode session (`session.fork`). The plugin remembers `(parent, anchor)` in
+  `.opencode/context-tree/<tree>.jsonl` (append-only) and mirrors it into `session.metadata`.
+- Sessions you fork with OpenCode's own `/fork` are adopted into the tree automatically (the
+  copied message prefix identifies the parent); they show up under it with their session
+  title. Adoption only appends a journal line — the sessions themselves are untouched.
+- Crops and hidden records are applied per request in the server plugin; OpenCode's own
+  storage is never rewritten. `/undo` appends, never deletes.
+- Decision records are ordinary user messages (`noReply`) tagged in part metadata; they are
+  re-injected verbatim when OpenCode compacts.

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "opencode-context-tree",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Pi-style context tree for OpenCode: branch, merge (human-confirmed decision records), crop, undo, plus a DeepSeek-Harness-style trajectory view",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./src/server/index.ts",
+      "import": "./dist/server.js"
+    },
+    "./server": {
+      "types": "./src/server/index.ts",
+      "import": "./dist/server.js"
+    },
+    "./tui": {
+      "types": "./src/tui/index.tsx",
+      "import": "./dist/tui.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "docs/USAGE.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "prepack": "bun run build",
+    "typecheck": "bunx tsc --noEmit -p tsconfig.json",
+    "test": "bun test",
+    "test:e2e": "CTREE_E2E=1 bun test --timeout 120000 test/e2e"
+  },
+  "engines": {
+    "opencode": ">=1.18.0"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.18.26",
+    "@opencode-ai/sdk": "1.18.26",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@opentui/core": "^0.5.10",
+    "@opentui/keymap": "^0.5.10",
+    "@opentui/solid": "^0.5.10",
+    "@types/bun": "latest",
+    "solid-js": "^1.9.12",
+    "typescript": "^5.8.2"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.10",
+    "@opentui/keymap": ">=0.5.10",
+    "@opentui/solid": ">=0.5.10",
+    "solid-js": ">=1.9.12"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/keymap": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  },
+  "author": "Naveen (navbytes)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/navbytes/opencode-tree.git"
+  },
+  "homepage": "https://github.com/navbytes/opencode-tree#readme",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "context-tree",
+    "context-engineering",
+    "branch",
+    "merge",
+    "crop",
+    "trajectory",
+    "tui"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/core/actions.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure planning of the "go here" jump action (DESIGN.md §6.2), given a selected
+ * `Row` and the `TreeView` it came from. Planning never performs the jump itself —
+ * callers (the server/TUI halves) execute the plan against OpenCode and the journal.
+ *
+ * Pure, no OpenCode/opentui/solid-js imports — see test/core-purity.test.ts.
+ */
+import type { Row } from "./tree.js"
+import type { Transcript } from "./transcript.js"
+
+export type JumpPlan =
+  | { kind: "noop"; reason: string }
+  | { kind: "switch"; sessionID: string }
+  | {
+      kind: "fork"
+      sessionID: string
+      /** The message to fork AT (exclusive — `session.fork` copies everything before it). */
+      messageID: string
+      prefill?: string
+      mode: "redo" | "continue"
+    }
+
+/**
+ * Plan the jump for a selected row (DESIGN.md §6.2), against the *unfiltered*
+ * transcripts so search/filters never change what a jump does:
+ * - a **branch row** → switch to that branch's session (same as its tip), or a noop on the
+ *   marker row of the session you are already in;
+ * - a **turn/step row on the last message of a non-current session** → switch to it
+ *   (no fork) — Pi's "move the leaf to an existing leaf";
+ * - a **turn row** elsewhere → fork at that user message, prefilled with its text;
+ * - a **step row** elsewhere → fork at the *next* message after its assistant message;
+ * - the **last message of the current session** → noop, "already here".
+ */
+export function planJump(row: Row, ctx: { transcripts: Record<string, Transcript>; currentSessionID: string }): JumpPlan {
+  if (row.kind === "branch") return row.sessionID === ctx.currentSessionID ? { kind: "noop", reason: "you are here" } : { kind: "switch", sessionID: row.sessionID }
+  const tr = ctx.transcripts[row.sessionID]
+  if (!tr) return { kind: "noop", reason: "that session is not loaded" }
+  const idx = tr.messages.findIndex((m) => m.id === row.messageID)
+  if (idx === -1) return { kind: "noop", reason: "message not found" }
+  const last = idx === tr.messages.length - 1
+  if (row.sessionID === ctx.currentSessionID) {
+    if (last) return { kind: "noop", reason: "already here" }
+  } else if (last) {
+    return { kind: "switch", sessionID: row.sessionID }
+  }
+  if (row.kind === "turn") {
+    const text = tr.messages[idx]!.parts.filter((p) => p.type === "text").map((p) => p.text ?? "").join("\n")
+    return { kind: "fork", sessionID: row.sessionID, messageID: row.messageID, prefill: text || row.preview, mode: "redo" }
+  }
+  const next = tr.messages[idx + 1]
+  if (!next) return { kind: "switch", sessionID: row.sessionID }
+  return { kind: "fork", sessionID: row.sessionID, messageID: next.id, mode: "continue" }
+}

package/src/core/adopt.ts

@@ -0,0 +1,93 @@
+/**
+ * Matching OpenCode's *native* forks (`/fork`, `session.fork`) back to the session
+ * they came from, so the tree can adopt them as `branch.opened { kind: "native" }`.
+ *
+ * `session.fork` sets no `parentID` and copies the prefix with fresh message ids but
+ * identical `time.created`, so the only proof of a fork is that prefix; the
+ * `"… (fork #n)"` title is a hint used for ranking, never for matching.
+ *
+ * Pure, no OpenCode/opentui/solid-js imports — see test/core-purity.test.ts. The IO
+ * half lives in ../shared/adopt.ts.
+ */
+
+export type ForkMessage = { id: string; role: string; created: number }
+
+/** OpenCode's `Session`, reduced to the fields adoption needs. */
+export type SessionInfo = {
+  id: string
+  title: string
+  created: number
+  /** Set only on subagent children — never on a fork, and never adoptable. */
+  parentID?: string
+  directory?: string
+}
+
+export type ForkCandidate = SessionInfo & { messages: ForkMessage[] }
+
+export type ForkParent = { parentID: string; anchorMessageID: string }
+
+const FORK_TITLE = /^(.+) \(fork #(\d+)\)$/
+
+/** `"Fix the bug (fork #2)"` → `{ base: "Fix the bug", n: 2 }`. */
+export function parseForkTitle(title: string): { base: string; n: number } | undefined {
+  const match = FORK_TITLE.exec(title)
+  if (!match) return undefined
+  const n = Number(match[2])
+  if (!Number.isInteger(n) || n < 1) return undefined
+  return { base: match[1]!, n }
+}
+
+/** The title `getForkedTitle` must have read to produce `title`, if it still follows the pattern. */
+export function expectedParentTitle(title: string): string | undefined {
+  const parsed = parseForkTitle(title)
+  if (!parsed) return undefined
+  return parsed.n === 1 ? parsed.base : `${parsed.base} (fork #${parsed.n - 1})`
+}
+
+/** How much of `fork` is a copy of `candidate`, by (role, created) from index 0. */
+function sharedPrefixLength(fork: ForkMessage[], candidate: ForkMessage[]): number {
+  const max = Math.min(fork.length, candidate.length)
+  let n = 0
+  while (n < max && fork[n]!.role === candidate[n]!.role && fork[n]!.created === candidate[n]!.created) n++
+  return n
+}
+
+/**
+ * The session `fork` was forked from, with the journal's anchor (the last *shared*
+ * message in the parent, inclusive). `candidates` should be scoped to the same directory;
+ * the fork's own age and `parentID` are re-checked here.
+ *
+ * Only the *copied* head of the fork can match: everything it said after the fork has a
+ * `created` of its own, so a fork is adoptable long after it has moved on. Matching on the
+ * longest common prefix (≥1 message, starting at index 0) is what makes that work.
+ */
+export function findForkParent(fork: ForkCandidate, candidates: ForkCandidate[]): ForkParent | undefined {
+  if (fork.messages.length === 0) return undefined
+  const expected = expectedParentTitle(fork.title)
+  const matches: { candidate: ForkCandidate; shared: number }[] = []
+  for (const candidate of candidates) {
+    if (candidate.id === fork.id || candidate.parentID || candidate.created > fork.created) continue
+    const shared = sharedPrefixLength(fork.messages, candidate.messages)
+    if (shared > 0) matches.push({ candidate, shared })
+  }
+  if (matches.length === 0) return undefined
+  const titled = (m: { candidate: ForkCandidate }) => (expected !== undefined && m.candidate.title === expected ? 1 : 0)
+  // a fork of a fork copies its grandparent's messages too, but only through its parent —
+  // so the longest shared prefix is the closest ancestor; two forks of one session share a
+  // title, so the title expectation and then creation time break the ties
+  matches.sort((a, b) => b.shared - a.shared || titled(b) - titled(a) || b.candidate.created - a.candidate.created)
+  const best = matches[0]!
+  return { parentID: best.candidate.id, anchorMessageID: best.candidate.messages[best.shared - 1]!.id }
+}
+
+/**
+ * Sessions worth testing for adoption, oldest first so a parent that is itself an
+ * un-adopted fork joins the tree before its children. Only `"… (fork #n)"` titles
+ * qualify: matching every untitled session costs one round-trip each and mis-adopts
+ * strangers, so a fork the user renamed is simply not adopted automatically.
+ */
+export function pickAdoptables(sessions: SessionInfo[], registered: Set<string>): SessionInfo[] {
+  return sessions
+    .filter((s) => !s.parentID && !registered.has(s.id) && parseForkTitle(s.title) !== undefined)
+    .sort((a, b) => a.created - b.created)
+}

package/src/core/consumers.ts

@@ -0,0 +1,39 @@
+/**
+ * "What is filling the window" (DESIGN.md §7.4): tokens by source over the
+ * current session's context. Pure.
+ */
+import { estimateTokens } from "./tokens.js"
+import type { Transcript } from "./transcript.js"
+
+export type Consumer = { source: string; kind: "tool" | "assistant" | "user" | "decision" | "summary" | "reasoning"; tokens: number; count: number; share: number }
+
+export function consumers(transcript: Transcript, opts: { cropped?: Set<string> } = {}): Consumer[] {
+  const acc = new Map<string, Consumer>()
+  const add = (source: string, kind: Consumer["kind"], tokens: number) => {
+    const c = acc.get(source) ?? { source, kind, tokens: 0, count: 0, share: 0 }
+    c.tokens += tokens
+    c.count += 1
+    acc.set(source, c)
+  }
+  for (const m of transcript.messages) {
+    for (const p of m.parts) {
+      if (opts.cropped?.has(p.id)) continue
+      if (p.type === "tool") add(p.tool ?? "tool", "tool", estimateTokens(p.state?.output ?? "") + estimateTokens(JSON.stringify(p.state?.input ?? "")))
+      else if (p.type === "text") {
+        const kind = (p.metadata?.["ctree"] as { kind?: string } | undefined)?.kind
+        if (kind === "decision") add("◆ decisions", "decision", estimateTokens(p.text ?? ""))
+        else if (kind === "summary") add("◇ branch summaries", "summary", estimateTokens(p.text ?? ""))
+        else if (m.role === "user") add("● user prompts", "user", estimateTokens(p.text ?? ""))
+        else if (m.summary) add("◇ compaction summaries", "summary", estimateTokens(p.text ?? ""))
+        else add("○ assistant text", "assistant", estimateTokens(p.text ?? ""))
+      } else if (p.type === "reasoning") add("(thinking)", "reasoning", estimateTokens(p.text ?? ""))
+    }
+  }
+  const total = [...acc.values()].reduce((s, c) => s + c.tokens, 0) || 1
+  return [...acc.values()].map((c) => ({ ...c, share: c.tokens / total })).sort((a, b) => b.tokens - a.tokens)
+}
+
+export function bar(share: number, width: number): string {
+  const n = Math.round(share * width)
+  return "▰".repeat(n) + "▱".repeat(Math.max(0, width - n))
+}

package/src/core/crop.ts

@@ -0,0 +1,176 @@
+/**
+ * Crop application (DESIGN.md §6.5, invariants in §8.1).
+ *
+ * Operates on a minimal structural type that mirrors OpenCode's
+ * `{ info: Message, parts: Part[] }` shape closely enough to be driven by
+ * `experimental.chat.messages.transform`, without importing anything from
+ * `@opencode-ai/*`. Pure, no OpenCode/opentui imports — see
+ * test/core-purity.test.ts.
+ */
+
+export type MinimalToolState = {
+  status?: string
+  input?: unknown
+  output?: string
+  title?: string
+  time?: { start?: number; end?: number; compacted?: number }
+}
+
+export type MinimalPart = {
+  id: string
+  type: string
+  tool?: string
+  callID?: string
+  state?: MinimalToolState
+  text?: string
+  metadata?: Record<string, unknown>
+}
+
+export type MinimalMessageInfo = {
+  id: string
+  role: "user" | "assistant" | "system"
+  sessionID: string
+}
+
+export type MinimalMessage = {
+  info: MinimalMessageInfo
+  parts: MinimalPart[]
+}
+
+/** One crop target, as recorded on a `crop.applied` journal line (see core/journal.ts). */
+export type CropTargetRef = {
+  messageID: string
+  partID?: string
+  callID?: string
+  tool?: string
+  estTokens: number
+  sha8: string
+}
+
+export type CropSpec = {
+  mode: "result" | "turn"
+  targets: CropTargetRef[]
+  anchorMessageID: string
+}
+
+const CROPPED_PREFIX = "[cropped:"
+const DROPPED_PREFIX = "[dropped turn"
+
+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`
+}
+
+function isDecisionMessage(message: MinimalMessage): boolean {
+  return message.parts.some((p) => {
+    const ctree = p.metadata?.["ctree"] as { kind?: string } | undefined
+    return ctree?.kind === "decision"
+  })
+}
+
+function findLastUserIndex(messages: MinimalMessage[]): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]!.info.role === "user") return i
+  }
+  return -1
+}
+
+function matchesTarget(part: MinimalPart, target: CropTargetRef): boolean {
+  if (target.partID) return part.id === target.partID
+  if (target.callID) return part.callID === target.callID
+  if (target.tool) return part.type === "tool" && part.tool === target.tool
+  return part.type === "tool"
+}
+
+function shortArg(state: MinimalToolState | undefined): string {
+  if (!state?.input || typeof state.input !== "object") return ""
+  const input = state.input as Record<string, unknown>
+  const candidate = input["command"] ?? input["filePath"] ?? input["pattern"] ?? input["url"]
+  if (typeof candidate !== "string") return ""
+  const trimmed = candidate.length > 40 ? `${candidate.slice(0, 40)}…` : candidate
+  return ` "${trimmed}"`
+}
+
+/** result mode: rewrite `state.output` to a stub; input/callID/status are left untouched. */
+function applyResultCrop(messages: MinimalMessage[], crop: CropSpec, lastUserIndex: number): void {
+  for (const target of crop.targets) {
+    const index = messages.findIndex((m) => m.info.id === target.messageID)
+    if (index === -1) continue
+    if (index === lastUserIndex) continue // never touch the last user message
+    const message = messages[index]!
+    if (isDecisionMessage(message)) continue // decision records are never cropped
+
+    for (const part of message.parts) {
+      if (part.type !== "tool") continue
+      if (!matchesTarget(part, target)) continue
+      if (!part.state || part.state.status !== "completed") continue
+      if (typeof part.state.output === "string" && part.state.output.startsWith(CROPPED_PREFIX)) continue // idempotent
+
+      const arg = shortArg(part.state)
+      part.state.output = `${CROPPED_PREFIX} ${target.tool ?? part.tool ?? "tool"}${arg}, ~${formatK(target.estTokens)} tokens, sha8 ${target.sha8}]`
+    }
+  }
+}
+
+/**
+ * turn mode: splice out the user message at `anchorMessageID` and every
+ * assistant/tool message up to (excluding) the next user message, replacing them
+ * with exactly one synthetic user message so role alternation is preserved.
+ */
+function applyTurnCrop(messages: MinimalMessage[], crop: CropSpec, lastUserIndex: number): void {
+  const startIndex = messages.findIndex((m) => m.info.id === crop.anchorMessageID)
+  if (startIndex === -1) return // already dropped (idempotent) or not in this array
+  if (startIndex >= lastUserIndex) return // nothing at or after the last user message is ever dropped
+  const anchor = messages[startIndex]!
+  if (anchor.info.role !== "user") return
+  if (isDecisionMessage(anchor)) return
+  if (anchor.parts.some((p) => p.type === "text" && typeof p.text === "string" && p.text.startsWith(DROPPED_PREFIX))) return // idempotent
+
+  let endIndex = startIndex + 1
+  while (endIndex < messages.length && messages[endIndex]!.info.role !== "user") endIndex++
+
+  const removed = endIndex - startIndex
+  const target = crop.targets[0]
+  const estTokens = crop.targets.reduce((sum, t) => sum + t.estTokens, 0)
+  const sha8 = target?.sha8 ?? "00000000"
+
+  const synthetic: MinimalMessage = {
+    info: { id: anchor.info.id, role: "user", sessionID: anchor.info.sessionID },
+    parts: [
+      {
+        id: `${anchor.info.id}-dropped`,
+        type: "text",
+        text: `${DROPPED_PREFIX} — ${removed} steps, ~${formatK(estTokens)} tokens, recoverable: ${sha8}]`,
+      },
+    ],
+  }
+
+  messages.splice(startIndex, removed, synthetic)
+}
+
+/**
+ * Apply a set of crops to `messages` in place, mirroring how the server plugin
+ * mutates OpenCode's `output.messages` by reference in
+ * `experimental.chat.messages.transform`. Returns the same array for convenience.
+ *
+ * Invariants (DESIGN.md §8.1), all enforced here:
+ * 1. Never remove or alter the last user message.
+ * 2. A tool part is stubbed by rewriting `state.output` only.
+ * 3. A dropped turn removes user + assistant/tool up to the next user message and
+ *    inserts exactly one synthetic user message, so roles still alternate.
+ * 5. Decision records are never cropped.
+ * 6. Idempotent: running this twice on the same array yields the same result.
+ */
+export function applyCrops(messages: MinimalMessage[], crops: CropSpec[]): MinimalMessage[] {
+  if (messages.length === 0 || crops.length === 0) return messages
+
+  for (const crop of crops) {
+    // Recomputed per crop: turn crops splice the array, so indices shift.
+    const lastUserIndex = findLastUserIndex(messages)
+    if (crop.mode === "result") applyResultCrop(messages, crop, lastUserIndex)
+    else applyTurnCrop(messages, crop, lastUserIndex)
+  }
+
+  return messages
+}