opencode-context-tree 0.1.0

package/src/core/cropplan.ts

@@ -0,0 +1,201 @@
+/**
+ * Crop planning (DESIGN.md §6.5): which tool results / turns *can* be cropped,
+ * which are protected, the `--auto` rules, and how a selection becomes the
+ * `crop.applied` journal payload that core/crop.ts applies.
+ *
+ * Pure, no OpenCode/opentui/solid-js imports — see test/core-purity.test.ts.
+ */
+import type { CropAppliedData, CropTarget } from "./journal.js"
+import { estimateTokens } from "./tokens.js"
+import type { StepPart, Transcript, TranscriptMessage } from "./transcript.js"
+
+/** FNV-1a 32-bit, hex — a stable 8-char handle for "this exact output". */
+export function sha8(text: string): string {
+  let h = 0x811c9dc5
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i)
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return h.toString(16).padStart(8, "0")
+}
+
+export type Protection = "latest-per-tool" | "current-turn" | "decision" | "keep-glob" | "already-cropped" | "too-small"
+
+export type ResultCandidate = {
+  kind: "result"
+  messageID: string
+  partID: string
+  callID?: string
+  tool: string
+  arg: string
+  estTokens: number
+  sha8: string
+  /** user-turn index (1-based) this result belongs to */
+  turn: number
+  turnsAgo: number
+  protections: Protection[]
+}
+
+export type TurnCandidate = {
+  kind: "turn"
+  anchorMessageID: string
+  turn: number
+  turnsAgo: number
+  steps: number
+  estTokens: number
+  sha8: string
+  targets: CropTarget[]
+  protections: Protection[]
+}
+
+export type CropRules = {
+  minTokens: number
+  olderThanTurns: number
+  keep: string[]
+}
+
+export const DEFAULT_RULES: CropRules = { minTokens: 10_000, olderThanTurns: 2, keep: [] }
+
+function primaryArg(part: StepPart): string {
+  const input = part.state?.input
+  if (!input || typeof input !== "object") return ""
+  const rec = input as Record<string, unknown>
+  const v = rec["command"] ?? rec["filePath"] ?? rec["pattern"] ?? rec["url"] ?? rec["path"]
+  return typeof v === "string" ? v : ""
+}
+
+function globToRegExp(glob: string): RegExp {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")
+  return new RegExp(`^${escaped}$`, "i")
+}
+
+function keepMatches(keep: string[], tool: string, arg: string): boolean {
+  return keep.some((g) => {
+    const re = globToRegExp(g)
+    return re.test(tool) || re.test(`${tool} ${arg}`) || re.test(arg)
+  })
+}
+
+function isCtreeKind(message: TranscriptMessage, kind: string): boolean {
+  return message.parts.some((p) => (p.metadata?.["ctree"] as { kind?: string } | undefined)?.kind === kind)
+}
+
+type Turn = { index: number; user?: TranscriptMessage; assistants: TranscriptMessage[] }
+
+function turnsOf(messages: TranscriptMessage[]): Turn[] {
+  const turns: Turn[] = []
+  let index = 0
+  for (const m of messages) {
+    if (m.role === "user") turns.push({ index: ++index, user: m, assistants: [] })
+    else {
+      // after a compaction the transcript opens with an assistant summary: it gets turn 0
+      if (turns.length === 0) turns.push({ index: 0, assistants: [] })
+      turns[turns.length - 1]!.assistants.push(m)
+    }
+  }
+  return turns
+}
+
+/** Index of the turn in progress (the last one), for the "current turn" protection. */
+function lastTurnIndex(turns: Turn[]): number {
+  return turns.at(-1)?.index ?? 0
+}
+
+/** Every completed tool result in the transcript, newest last, with its protections. */
+export function resultCandidates(transcript: Transcript, opts: { alreadyCropped?: Set<string>; keep?: string[]; minTokens?: number } = {}): ResultCandidate[] {
+  const turns = turnsOf(transcript.messages)
+  const total = lastTurnIndex(turns)
+  const out: ResultCandidate[] = []
+  for (const turn of turns) {
+    for (const m of turn.assistants) {
+      for (const p of m.parts) {
+        if (p.type !== "tool" || p.state?.status !== "completed") continue
+        const output = p.state.output ?? ""
+        const tool = p.tool ?? "tool"
+        const arg = primaryArg(p)
+        const protections: Protection[] = []
+        if (turn.index === total) protections.push("current-turn")
+        if (opts.alreadyCropped?.has(p.id)) protections.push("already-cropped")
+        if (opts.keep && keepMatches(opts.keep, tool, arg)) protections.push("keep-glob")
+        const estTokens = estimateTokens(output)
+        if (opts.minTokens !== undefined && estTokens < opts.minTokens) protections.push("too-small")
+        out.push({ kind: "result", messageID: m.id, partID: p.id, callID: p.callID, tool, arg, estTokens, sha8: sha8(output), turn: turn.index, turnsAgo: total - turn.index, protections })
+      }
+    }
+  }
+  // latest result per tool is protected (needs an explicit double-mark)
+  const seen = new Set<string>()
+  for (let i = out.length - 1; i >= 0; i--) {
+    const c = out[i]!
+    if (!seen.has(c.tool)) {
+      seen.add(c.tool)
+      c.protections.push("latest-per-tool")
+    }
+  }
+  return out
+}
+
+/** Every user turn with its answers, as a droppable unit. */
+export function turnCandidates(transcript: Transcript, opts: { alreadyDropped?: Set<string> } = {}): TurnCandidate[] {
+  const turns = turnsOf(transcript.messages)
+  const total = lastTurnIndex(turns)
+  const out: TurnCandidate[] = []
+  for (const turn of turns) {
+    if (!turn.user) continue // a compaction-opened turn has no user message to splice from
+    const protections: Protection[] = []
+    if (turn.index === total) protections.push("current-turn")
+    if (isCtreeKind(turn.user, "decision") || turn.assistants.some((m) => isCtreeKind(m, "decision"))) protections.push("decision")
+    if (opts.alreadyDropped?.has(turn.user.id)) protections.push("already-cropped")
+    const targets: CropTarget[] = []
+    let text = ""
+    const userText = turn.user.parts.map((p) => p.text ?? "").join("\n")
+    text += userText
+    targets.push({ messageID: turn.user.id, estTokens: estimateTokens(userText), sha8: "" })
+    for (const m of turn.assistants) {
+      const t = m.parts.map((p) => (p.type === "tool" ? (p.state?.output ?? "") : (p.text ?? ""))).join("\n")
+      text += `\n${t}`
+      targets.push({ messageID: m.id, estTokens: estimateTokens(t), sha8: sha8(t) })
+    }
+    // the anchor target carries the whole-turn handle: it is what crop.ts shows as `recoverable:`
+    const handle = sha8(text)
+    targets[0]!.sha8 = handle
+    const estTokens = targets.reduce((s, t) => s + t.estTokens, 0)
+    out.push({ kind: "turn", anchorMessageID: turn.user.id, turn: turn.index, turnsAgo: total - turn.index, steps: 1 + turn.assistants.length, estTokens, sha8: handle, targets, protections })
+  }
+  return out
+}
+
+/** `--auto`: pre-mark results that are big enough, old enough, and unprotected. */
+export function autoMark(candidates: ResultCandidate[], rules: CropRules = DEFAULT_RULES): ResultCandidate[] {
+  return candidates.filter((c) => c.estTokens >= rules.minTokens && c.turnsAgo >= rules.olderThanTurns && c.protections.length === 0)
+}
+
+/** The single biggest unprotected result (`/crop --top`). With `force`, the "latest per
+ *  tool" protection is waived (the current turn and decision records never are). */
+export function topCandidate(candidates: ResultCandidate[], force = false): ResultCandidate | undefined {
+  const waived: Protection[] = force ? ["too-small", "latest-per-tool"] : ["too-small"]
+  return candidates
+    .filter((c) => !c.protections.some((p) => !waived.includes(p)))
+    .sort((a, b) => b.estTokens - a.estTokens)[0]
+}
+
+/** Turn a result-mode selection into one `crop.applied` payload. */
+export function planResultCrop(sessionID: string, selected: ResultCandidate[]): CropAppliedData | undefined {
+  if (selected.length === 0) return undefined
+  const targets: CropTarget[] = selected.map((c) => ({ messageID: c.messageID, partID: c.partID, callID: c.callID, tool: c.tool, estTokens: c.estTokens, sha8: c.sha8 }))
+  // the anchor is informational for result crops: the earliest touched message
+  const anchorMessageID = selected.slice().sort((a, b) => a.turn - b.turn)[0]!.messageID
+  return { sessionID, mode: "result", targets, anchorMessageID }
+}
+
+/** One `crop.applied` payload per dropped turn (turn crops splice, so each is its own line).
+ *  The current turn is never planned — the model must keep seeing the last user message. */
+export function planTurnCrops(sessionID: string, selected: TurnCandidate[]): CropAppliedData[] {
+  return selected
+    .filter((t) => !t.protections.includes("current-turn"))
+    .map((t) => ({ sessionID, mode: "turn", targets: t.targets, anchorMessageID: t.anchorMessageID }))
+}
+
+export function reclaimed(selected: (ResultCandidate | TurnCandidate)[]): number {
+  return selected.reduce((s, c) => s + c.estTokens, 0)
+}

package/src/core/ctree-args.ts

@@ -0,0 +1,89 @@
+/** Argument parsing for the headless `/ctree …` server command (DESIGN.md §5). Pure. */
+export type CtreeCommand =
+  | { kind: "status" }
+  | { kind: "branch"; name: string; model?: string }
+  | { kind: "merge-discard"; note?: string }
+  | { kind: "crop-top"; apply: boolean; force: boolean }
+  | { kind: "crop-auto"; apply: boolean; minTokens?: number; olderThan?: number; keep: string[] }
+  | { kind: "undo" }
+  | { kind: "decisions"; export?: string }
+  | { kind: "help"; error?: string }
+
+/** Relative to the project directory, as promised by `CTREE_HELP` and docs/USAGE.md. */
+export const DEFAULT_DECISIONS_EXPORT = "ctree-decisions.md"
+
+export function parseCtreeArgs(raw: string): CtreeCommand {
+  const args = raw.trim().split(/\s+/).filter(Boolean)
+  const [sub, ...rest] = args
+  switch (sub) {
+    case undefined:
+    case "help":
+      return { kind: "help" }
+    case "status":
+      return { kind: "status" }
+    case "branch": {
+      // only a `provider/model`-shaped last token is a model, so `branch fix flaky test` keeps its name
+      const model = rest.length > 1 && rest[rest.length - 1]!.includes("/") ? rest.pop() : undefined
+      const name = rest.join(" ")
+      if (!name) return { kind: "help", error: "branch needs a name: /ctree branch <name> [provider/model]" }
+      return { kind: "branch", name, model }
+    }
+    case "merge": {
+      if (rest[0] !== "--discard") return { kind: "help", error: "headless merge supports --discard only (squash needs the TUI's editor gate): /ctree merge --discard [note]" }
+      const note = rest.slice(1).join(" ").trim() || undefined
+      return { kind: "merge-discard", note }
+    }
+    case "crop": {
+      const apply = rest.includes("--apply")
+      if (rest.includes("--top")) return { kind: "crop-top", apply, force: rest.includes("--force") }
+      if (rest.includes("--auto")) {
+        // a `--`-prefixed token is the next flag, never this flag's value
+        const value = (flag: string): string | undefined => {
+          const i = rest.indexOf(flag)
+          if (i < 0) return undefined
+          const v = rest[i + 1]
+          return v && !v.startsWith("--") ? v : ""
+        }
+        const num = (flag: string): number | undefined | null => {
+          const raw = value(flag)
+          if (raw === undefined) return undefined
+          const n = Number(raw)
+          return raw !== "" && Number.isFinite(n) && n >= 0 ? n : null
+        }
+        const minTokens = num("--min-tokens")
+        if (minTokens === null) return { kind: "help", error: "--min-tokens needs a number, e.g. --min-tokens 10000" }
+        const olderThan = num("--older-than")
+        if (olderThan === null) return { kind: "help", error: "--older-than needs a number of turns, e.g. --older-than 2" }
+        const keep: string[] = []
+        for (let i = 0; i < rest.length; i++) {
+          if (rest[i] !== "--keep") continue
+          const glob = rest[i + 1]
+          if (!glob || glob.startsWith("--")) return { kind: "help", error: "--keep needs a glob, e.g. --keep chrome.*" }
+          keep.push(glob)
+        }
+        return { kind: "crop-auto", apply, minTokens, olderThan, keep }
+      }
+      return { kind: "help", error: "crop needs --top or --auto (add --apply to write; without it, dry run)" }
+    }
+    case "undo":
+      return { kind: "undo" }
+    case "decisions": {
+      const i = rest.indexOf("--export")
+      if (i < 0) return { kind: "decisions" }
+      const target = rest[i + 1] && !rest[i + 1]!.startsWith("--") ? rest[i + 1]! : DEFAULT_DECISIONS_EXPORT
+      return { kind: "decisions", export: target }
+    }
+    default:
+      return { kind: "help", error: `unknown subcommand "${sub}"` }
+  }
+}
+
+export const CTREE_HELP = `context tree — headless commands
+  /ctree status                       tree, branch, crops of this session
+  /ctree branch <name> [provider/model]  fork here into a named branch
+  /ctree merge --discard [note]       close this branch as rejected, back to the parent
+  /ctree crop --top [--apply] [--force]  biggest unprotected tool result (dry run unless --apply; --force ignores "latest per tool")
+  /ctree crop --auto [--apply] [--min-tokens N] [--older-than N] [--keep glob]
+  /ctree undo                         revert the last crop / branch / merge on this path
+  /ctree decisions [--export [path]]  list ◆ decision records (default export: ./ctree-decisions.md)
+The TUI has the full experience: /tree (ctrl+q), /branch, /merge, /decisions.`

package/src/core/decision.ts

@@ -0,0 +1,97 @@
+/**
+ * Decision records (DESIGN.md §6.4, template from pi-context-tree spec §6).
+ * Pure: prompt/template builders and transcript serialisation for the merge draft.
+ */
+import type { TreeState } from "./journal.js"
+import type { Transcript, TranscriptMessage } from "./transcript.js"
+
+export const DECISION_SYSTEM =
+  "You write concise engineering decision records. You are given the transcript of a side branch of a coding session. Do NOT continue the conversation. Output ONLY the record in the exact markdown template requested, nothing else."
+
+export function decisionTemplate(branchName: string, model?: string, date = new Date()): string {
+  return `## Decision: ${branchName}
+**Date:** ${date.toISOString().slice(0, 10)} · **Model:** ${model ?? "unknown"} · **Branch:** ${branchName}
+**Outcome:** <1–3 sentences: what was concluded / built>
+**Why:** 
+- <≤5 bullets>
+**Assumptions:** <taken as true but not verified — the trunk must know these>
+**Changes:** <files touched, or "none">
+**Gotchas:** <traps found on the way>
+**Open questions:** <what is still unknown>
+**Confidence / revisit-if:** <high|medium|low; what would change the decision>
+
+### Rejected alternatives
+- **<name>:** <one-line reason>
+`
+}
+
+/**
+ * Serialise the branch's own messages (after its anchor) for the drafting model.
+ * The anchor id lives in the *parent* (fork copies the shared prefix with fresh ids), so
+ * it is resolved against `parentMessageIDs` and applied positionally. Omitting
+ * `messageID` asks for the whole transcript; an id the parent no longer has is an error,
+ * never a silent "include the shared prefix too".
+ */
+export function branchTranscriptText(transcript: Transcript, anchor: { messageID?: string; parentMessageIDs: string[] }, toolChars = 2000): string {
+  let anchorIndex = -1
+  if (anchor.messageID) {
+    anchorIndex = anchor.parentMessageIDs.indexOf(anchor.messageID)
+    if (anchorIndex === -1) throw new Error(`anchor message ${anchor.messageID} is no longer in the parent session — cannot tell this branch's own turns from the shared prefix`)
+  }
+  const msgs = transcript.messages.slice(anchorIndex + 1)
+  return msgs
+    .map((m) => messageText(m, toolChars))
+    .filter(Boolean)
+    .join("\n\n")
+}
+
+function messageText(m: TranscriptMessage, toolChars: number): string {
+  const role = m.role === "user" ? "[User]" : "[Assistant]"
+  const body = m.parts
+    .map((p) => {
+      if (p.type === "text") return p.text ?? ""
+      if (p.type === "tool") {
+        const input = JSON.stringify(p.state?.input ?? {}).slice(0, 300)
+        const output = String(p.state?.output ?? "")
+        return `(tool ${p.tool ?? "?"} ${input} → ${output.length > toolChars ? `${output.slice(0, toolChars)}… [${output.length - toolChars} more chars]` : output})`
+      }
+      return ""
+    })
+    .filter(Boolean)
+    .join("\n")
+  return body ? `${role}: ${body}` : ""
+}
+
+export function buildDecisionDraftPrompt(input: { branchName: string; model?: string; transcript: string; siblings?: { name: string; transcript: string }[] }): string {
+  const siblings = input.siblings?.length
+    ? `\n\nThe following sibling branches explored alternatives that LOST to this one. Add one line each under "Rejected alternatives" — an epitaph that stops the trunk model from proposing them again:\n${input.siblings.map((s) => `\n<sibling name="${s.name}">\n${s.transcript}\n</sibling>`).join("\n")}`
+    : ""
+  return `<branch name="${input.branchName}">\n${input.transcript}\n</branch>${siblings}\n\nFill in this template exactly (keep the headings, replace every <placeholder>, drop bullets you cannot fill, target 300–800 words, preserve exact file paths, function names and error messages):\n\n${decisionTemplate(input.branchName, input.model)}`
+}
+
+/** The text that lands in the trunk: a ◆ header the user can scan plus the record body. */
+export function decisionMessageText(record: string, branchName: string): string {
+  const body = record.trim()
+  return body.startsWith("## Decision:") ? `◆ ${body}` : `◆ ## Decision: ${branchName}\n${body}`
+}
+
+/** Open sibling branches forked from the same point (tournament, DESIGN.md §6.4). */
+export function openSiblings(state: TreeState, sessionID: string): string[] {
+  const me = state.sessions[sessionID]
+  if (!me) return []
+  return Object.values(state.sessions)
+    .filter((b) => b.sessionID !== sessionID && b.status === "open" && b.parentSessionID === me.parentSessionID && b.anchorMessageID === me.anchorMessageID)
+    .map((b) => b.sessionID)
+}
+
+/** Markdown export of every decision on a session's path (`/decisions --export`). */
+export function exportDecisions(records: { branchName: string; text: string; sessionID: string; at?: number }[]): string {
+  if (records.length === 0) return "# Decisions\n\n_(none yet)_\n"
+  const one = (r: { branchName: string; text: string; sessionID: string; at?: number }) => {
+    const when = r.at ? new Date(r.at).toISOString() : "date unknown"
+    // the heading already names the branch, so the record's own "## Decision: <name>" goes
+    const body = r.text.replace(/^◆ /, "").replace(/^## Decision:[^\n]*\n?/, "").trim()
+    return `## ⎇ ${r.branchName} · ${when}\n_session ${r.sessionID}_\n\n${body}`
+  }
+  return `# Decisions\n\n${records.map(one).join("\n\n---\n\n")}\n`
+}