@chroxify/eunoe 0.1.0 → 1.1.0

package/src/context/content.ts

@@ -1,13 +1,40 @@
-import type { Block, Message } from "./types"
+export type Block = { type: string; [key: string]: any }
+
+export type Message = { role: string; content: string | Block[] }
+
+export type Body = {
+  model?: string
+  system?: string | Block[]
+  messages: Message[]
+  tools?: unknown[]
+  metadata?: { user_id?: string }
+  [key: string]: any
+}
 
 export function contentBlocks(content: unknown): Block[] {
-  return typeof content === "string" ? [{ type: "text", text: content }] : Array.isArray(content) ? content : []
+  if (typeof content === "string") return [{ type: "text", text: content }]
+  return Array.isArray(content) ? content : []
 }
 
 export function blocks(message: Message): Block[] {
   return contentBlocks(message.content)
 }
 
+function joinedText(list: Block[]): string {
+  return list
+    .filter((b) => b.type === "text")
+    .map((b) => String(b.text ?? ""))
+    .join("\n")
+}
+
+export function textOf(message: Message): string {
+  return joinedText(blocks(message))
+}
+
+export function resultText(block: Block): string {
+  return typeof block.content === "string" ? block.content : joinedText(contentBlocks(block.content))
+}
+
 export function withoutCacheControl(block: Block): Block {
   if (!("cache_control" in block)) return block
   const { cache_control: _, ...rest } = block
@@ -18,7 +45,28 @@ export function clean(message: Message): Message {
   return { role: message.role, content: blocks(message).map(withoutCacheControl) }
 }
 
+export function shortHash(json: string, chars: number): string {
+  return new Bun.CryptoHasher("sha256").update(json).digest("hex").slice(0, chars)
+}
+
+export function truncate(text: string, max: number): string {
+  const cut = text.slice(0, max)
+  return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut
+}
+
 export function clip(value: unknown, max: number): string {
   const text = String(value).replace(/\s+/g, " ").trim()
-  return text.length > max ? `${text.slice(0, max)}…` : text
+  return text.length > max ? `${truncate(text, max)}…` : text
+}
+
+export function wellFormed(_key: string, value: unknown): unknown {
+  return typeof value === "string" ? value.toWellFormed() : value
+}
+
+export function describeToolCall(block: Block): string {
+  const input = block.input ?? {}
+  if (typeof input.command === "string") return `${block.name} \`${clip(input.command, 100)}\``
+  if (typeof input.file_path === "string") return `${block.name} ${input.file_path}`
+  if (typeof input.pattern === "string") return `${block.name} "${clip(input.pattern, 60)}"`
+  return `${block.name} ${clip(JSON.stringify(input), 60)}`
 }

package/src/context/fold/evidence.ts

@@ -0,0 +1,145 @@
+import { type Block, blocks, clip, describeToolCall, type Message, resultText } from "../content"
+import { toolEvidence } from "../prompts"
+
+export interface EvidenceOptions {
+  linesPerCall?: number
+  lineChars?: number
+  turnChars?: number
+  scanLines?: number
+  minScore?: number
+  allTools?: boolean
+  ranked?: boolean
+  labels?: boolean
+  callFloor?: number
+}
+
+interface Scored {
+  index: number
+  line: string
+  score: number
+}
+
+interface Entry {
+  head: string
+  lines: string[]
+}
+
+export const REREADABLE_TOOLS = new Set(["Read", "Grep", "Glob", "LS", "NotebookRead", "WebFetch", "WebSearch", "TodoWrite", "Edit", "Write", "MultiEdit", "NotebookEdit"])
+
+const ERROR_LINE = /\b(?:error|errors|fail|fails|failed|failure|fatal|exception|panic|denied|refused|timed? ?out|traceback|cannot|unable to)\b/i
+
+const ERROR_CODE =
+  /\b[A-Z][A-Z0-9]*_[A-Z0-9_]{2,}\b|\bSIG[A-Z]{2,}\d*\b|\b[A-Z]{2,}\d{2,}\b|\bE(?:NOENT|ACCES|PERM|EXIST|CONN(?:REFUSED|RESET|ABORTED)|PIPE|ADDRINUSE|TIMEDOUT|NOTFOUND|INVAL|BUSY|MFILE|AGAIN|HOSTUNREACH|NOTDIR|ISDIR|BADF|NOSPC|AI_[A-Z]+)\b/
+
+const VALUE_TOKEN =
+  /\b[a-z]{2,}[_-](?=[a-z0-9]*\d)[a-z0-9]{6,}\b|\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,}\b|https?:\/\/[^\s)"']+|\b\d{4,}\b|\b\d{6,}_[a-z0-9_]{3,}\b|\bv?\d+\.\d+\.\d+\b|\b\d+(?:\.\d+)?\s?(?:ms|s|[KMGT]i?B|kB|%)(?![a-z])|\bsha\d*:[0-9a-f]+|@[a-z][\w-]+|--[a-z][\w-]*=\S+|\b\d+ (?:pass(?:ed|ing)?|fail(?:ed|ing)?|tests?|files? changed|insertions?|deletions?|rows?|errors?|warnings?)\b|[$€£]\d+(?:[.,]\d+)?|\b(?:status|HTTP\/\d(?:\.\d)?)\s*[:=]?\s*[45]\d{2}\b|\bexit(?: code| status)?\s*[:=]?\s*(?!0\b)\d{1,3}\b/i
+
+const ID_TOKEN = /\b[a-z]{2,}[_-](?=[a-z0-9]*\d)[a-z0-9]{6,}\b|\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,}\b|https?:\/\/[^\s)"']+|\b\d{6,}_[a-z0-9_]{3,}\b|\bv?\d+\.\d+\.\d+\b|\bsha\d*:[0-9a-f]+|@[a-z][\w-]+|--[a-z][\w-]*=\S+/i
+
+const KEY_VALUE = /^[\w .\-/()]{2,48}[:=]\s*\S/
+
+const VALUE_LABEL = /\b(?:ids?|hash|sha(?:256)?|checksum|trace|deploy(?:ment)?|preview|url|version|rows|p9[59]|exit(?: code)?|signal|request[_-]?id|job|migration|applied|bundle|build|status|took|updated|created)\b/i
+
+function resolved(options: EvidenceOptions) {
+  return {
+    linesPerCall: options.linesPerCall ?? 12,
+    lineChars: options.lineChars ?? 220,
+    turnChars: options.turnChars ?? 4_000,
+    scanLines: options.scanLines ?? 1_000_000,
+    minScore: options.minScore ?? 2,
+    ranked: options.ranked ?? true,
+    labels: options.labels ?? true,
+    callFloor: options.callFloor ?? 2,
+  }
+}
+
+const isError = (line: string) => ERROR_LINE.test(line) || ERROR_CODE.test(line)
+
+export function isSalient(line: string): boolean {
+  return isError(line) || VALUE_TOKEN.test(line)
+}
+
+function scoreLines(text: string, options: EvidenceOptions): Scored[] {
+  const { scanLines, lineChars, minScore, labels } = resolved(options)
+  const scored = text
+    .split("\n")
+    .slice(0, scanLines)
+    .flatMap((raw, index) => {
+      const line = raw.trim()
+      if (line.length < 4) return []
+      const error = isError(line)
+      const value = VALUE_TOKEN.test(line)
+      if (!error && !value) return []
+      const score = (error ? 3 : 0) + (value ? (ID_TOKEN.test(line) ? 3 : 2) : 0) + (KEY_VALUE.test(line) ? 1 : 0) + (line.length < 120 ? 1 : 0) + (labels && VALUE_LABEL.test(line) ? 1 : 0)
+      return score >= minScore ? [{ index, line: clip(line, lineChars), score }] : []
+    })
+  const seen = new Set<string>()
+  return scored.sort((a, b) => b.score - a.score || a.index - b.index).filter((s) => !seen.has(s.line) && seen.add(s.line))
+}
+
+export function salientLines(text: string, options: EvidenceOptions = {}): string[] {
+  return scoreLines(text, options)
+    .slice(0, resolved(options).linesPerCall)
+    .sort((a, b) => a.index - b.index)
+    .map((s) => s.line)
+}
+
+export function toolPairs(turn: Message[]): Array<{ call: Block; result: Block }> {
+  const results = new Map<string, Block>()
+  for (const message of turn) {
+    if (message.role !== "user") continue
+    for (const block of blocks(message)) if (block.type === "tool_result") results.set(block.tool_use_id, block)
+  }
+  return turn
+    .filter((m) => m.role === "assistant")
+    .flatMap((m) => blocks(m).filter((b) => b.type === "tool_use"))
+    .flatMap((call) => {
+      const result = results.get(call.id)
+      return result ? [{ call, result }] : []
+    })
+}
+
+function render(entries: Entry[]): string | null {
+  const shown = entries.filter((e) => e.lines.length > 0).map((e) => `- ${e.head}:\n${e.lines.map((l) => `    ${l}`).join("\n")}`)
+  return shown.length > 0 ? toolEvidence(shown) : null
+}
+
+function inCallOrder(heads: string[], pairs: Array<{ result: Block }>, options: EvidenceOptions): Entry[] {
+  const { turnChars } = resolved(options)
+  const entries: Entry[] = []
+  let used = 0
+  pairs.forEach(({ result }, i) => {
+    const lines = salientLines(resultText(result), options)
+    if (lines.length === 0) return
+    const size = heads[i].length + 4 + lines.reduce((s, l) => s + l.length + 5, 0)
+    if (used + size > turnChars) return
+    entries.push({ head: heads[i], lines })
+    used += size
+  })
+  return entries
+}
+
+function byScore(heads: string[], pairs: Array<{ result: Block }>, options: EvidenceOptions): Entry[] {
+  const { turnChars, linesPerCall, callFloor } = resolved(options)
+  const perCall = pairs.map(({ result }) => scoreLines(resultText(result), options))
+  const chosen = new Map<number, Scored[]>()
+  let used = 0
+  const take = (call: number, line: Scored) => {
+    const bucket = chosen.get(call) ?? []
+    const cost = line.line.length + 5 + (bucket.length > 0 ? 0 : heads[call].length + 4)
+    if (bucket.length >= linesPerCall || used + cost > turnChars) return
+    bucket.push(line)
+    chosen.set(call, bucket)
+    used += cost
+  }
+  for (const [call, lines] of perCall.entries()) for (const line of lines.slice(0, callFloor)) take(call, line)
+  const rest = perCall.flatMap((lines, call) => lines.slice(callFloor).map((line) => ({ line, call }))).sort((a, b) => b.line.score - a.line.score || a.call - b.call || a.line.index - b.line.index)
+  for (const { line, call } of rest) take(call, line)
+  return heads.map((head, i) => ({ head, lines: (chosen.get(i) ?? []).sort((a, b) => a.index - b.index).map((s) => s.line) }))
+}
+
+export function turnEvidence(turn: Message[], options: EvidenceOptions = {}): string | null {
+  const pairs = toolPairs(turn).filter(({ call }) => options.allTools || !REREADABLE_TOOLS.has(call.name))
+  const heads = pairs.map(({ call, result }) => `${describeToolCall(call)}${result.is_error ? " (failed)" : ""}`)
+  return render(resolved(options).ranked ? byScore(heads, pairs, options) : inCallOrder(heads, pairs, options))
+}

package/src/context/fold/index.ts

@@ -0,0 +1,65 @@
+import { type Message, textOf } from "../content"
+import { type RecallChunk, recallChunks, terms } from "../recall"
+import { isPrompt, reduceTurn, splitTurns } from "./turns"
+
+export interface FoldedTurn {
+  user: string
+  evidence: string
+  reply: string
+}
+
+export const FOLD_CAP_CHARS = 400_000
+
+const spoken = (message: Message) =>
+  textOf(message)
+    .replace(/<(system-reminder|system-message|recalled-context|handoff)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g, "")
+    .trim()
+
+const isEvidence = (text: string) => text.startsWith("<tool-evidence>")
+
+export function foldedTurns(messages: Message[]): FoldedTurn[] {
+  return splitTurns(messages)
+    .turns.filter((turn) => isPrompt(turn[0]))
+    .map((turn) => {
+      const reduced = reduceTurn(turn, { evidence: true })
+      const users = reduced.filter((m) => m.role === "user").map(spoken)
+      return {
+        user: users.filter((t) => t && !isEvidence(t)).join("\n\n"),
+        evidence: users.filter(isEvidence).join("\n"),
+        reply: reduced
+          .filter((m) => m.role === "assistant")
+          .map(spoken)
+          .join("\n"),
+      }
+    })
+}
+
+function renderTurn(turn: FoldedTurn, index: number, full: boolean): string {
+  const parts = [`### Turn ${index + 1}`, `**You:** ${turn.user}`]
+  if (full && turn.evidence) parts.push(turn.evidence)
+  if (full && turn.reply) parts.push(`**Agent:** ${turn.reply}`)
+  return parts.join("\n\n")
+}
+
+export function foldedView(messages: Message[], cap = Number.POSITIVE_INFINITY): string {
+  const turns = foldedTurns(messages)
+  const full = new Set<number>()
+  let used = 0
+  for (let i = turns.length - 1; i >= 0; i -= 1) {
+    const size = renderTurn(turns[i], i, true).length
+    if (used + size > cap) break
+    full.add(i)
+    used += size
+  }
+  return turns.map((turn, i) => renderTurn(turn, i, full.has(i))).join("\n\n")
+}
+
+export function sourceChunks(messages: Message[], from: string, users = false): RecallChunk[] {
+  const chunks = recallChunks([...messages, { role: "user", content: "" }], new Map()).map((chunk) => ({ ...chunk, from }))
+  if (!users) return chunks
+  const said = splitTurns(messages)
+    .turns.filter((turn) => isPrompt(turn[0]))
+    .map((turn, i) => ({ turn: i + 1, text: spoken(turn[0]) }))
+    .filter((t) => t.text)
+  return [...said.map((t) => ({ turn: t.turn, from, call: "you", lines: t.text.split("\n"), terms: terms(t.text) })), ...chunks]
+}

package/src/context/fold/strategies.ts

@@ -0,0 +1,94 @@
+import { type Block, type Body, blocks, type Message, truncate, withoutCacheControl } from "../content"
+import { clearedInput, compactionNotice, truncationNotice } from "../prompts"
+import { hasContent, isHarness, type ReduceOptions, reduceTurn, splitTurns } from "./turns"
+
+export interface CompactOptions extends ReduceOptions {
+  keepTurns: number
+  capChars?: number
+  guide: string | null
+  omittedBefore?: number
+  reduce?: (turn: Message[], options: ReduceOptions) => Message[]
+}
+
+export function trimMessages(messages: Message[], options: ReduceOptions = {}): Message[] {
+  const { preamble, turns } = splitTurns(messages)
+  if (turns.length < 2) return messages
+  return [...preamble, ...turns.slice(0, -1).flatMap((turn) => reduceTurn(turn, options)), ...(turns.at(-1) ?? [])]
+}
+
+export function compactMessages(messages: Message[], cutIndex: number, options: CompactOptions): Message[] {
+  const { preamble, turns } = splitTurns(messages)
+  if (cutIndex <= 0 || cutIndex >= turns.length) return messages
+  const reduce = options.reduce ?? reduceTurn
+  const keptFrom = Math.max(1, cutIndex - options.keepTurns)
+  const notice = compactionNotice({ omitted: keptFrom - 1 + (options.omittedBefore ?? 0), kept: cutIndex - keptFrom, guide: options.guide })
+  const removed = [...turns[0].slice(1), ...turns.slice(1, keptFrom).flat()]
+  const carried = removed
+    .filter((m) => isHarness(m) && hasContent(m))
+    .flatMap((m) => blocks(m).filter((b) => b.type === "text"))
+    .map((b) => ({ type: "text", text: `<system-reminder>\n${b.text}\n</system-reminder>` }))
+  return [...preamble, turns[0][0], { role: "user", content: [{ type: "text", text: notice }, ...carried] }, ...turns.slice(keptFrom, cutIndex).flatMap((turn) => reduce(turn, options)), ...turns.slice(cutIndex).flat()]
+}
+
+export function capTurns(messages: Message[], options: CompactOptions): Message[] {
+  const { capChars } = options
+  if (!capChars) return messages
+  const { preamble, turns } = splitTurns(messages)
+  if (turns.length < 3) return messages
+  const live = turns.length - 1
+  const over = (turn: Message[], i: number) => i > 0 && i < live && JSON.stringify(turn).length > capChars
+  if (!turns.some(over)) return messages
+  const reduce = options.reduce ?? reduceTurn
+  return [...preamble, ...turns.flatMap((turn, i) => (over(turn, i) ? reduce(turn, options) : turn))]
+}
+
+export function tailMessages(messages: Message[], from: number, guide: string | null): Message[] {
+  const { preamble, turns } = splitTurns(messages)
+  if (turns.length === 0 || from <= 1) return messages
+  const notice = truncationNotice({ omitted: from - 1, kept: turns.length - from, guide })
+  return [...preamble, turns[0][0], { role: "user", content: [{ type: "text", text: notice }] }, ...turns.slice(from).flat()]
+}
+
+export function countToolResults(messages: Message[], from: number): number {
+  return messages
+    .slice(from)
+    .filter((m) => m.role === "user")
+    .reduce((total, m) => total + blocks(m).filter((b) => b.type === "tool_result").length, 0)
+}
+
+function shortenInput(input: unknown): unknown {
+  if (typeof input === "string") return input.length > 2_000 ? clearedInput(truncate(input, 500), input.length - 500) : input
+  if (Array.isArray(input)) return input.map(shortenInput)
+  if (input && typeof input === "object") return Object.fromEntries(Object.entries(input).map(([k, v]) => [k, shortenInput(v)]))
+  return input
+}
+
+export function clearToolResults(messages: Message[], from: number, count: number, placeholder: string): Message[] {
+  let left = count
+  const cleared = new Set<string>()
+  const clearResult = (b: Block): Block => {
+    if (b.type !== "tool_result" || left <= 0) return b
+    left -= 1
+    cleared.add(b.tool_use_id)
+    return { type: "tool_result", tool_use_id: b.tool_use_id, ...(b.is_error ? { is_error: true } : {}), content: placeholder }
+  }
+  const withResultsCleared = messages.map((message, index) => {
+    if (left <= 0 || index < from || message.role !== "user" || typeof message.content === "string") return message
+    if (!message.content.some((b) => b.type === "tool_result")) return message
+    return { ...message, content: message.content.map(clearResult) }
+  })
+  const isClearedCall = (b: Block) => b.type === "tool_use" && cleared.has(b.id)
+  return withResultsCleared.map((message) => {
+    if (message.role !== "assistant" || typeof message.content === "string" || !message.content.some(isClearedCall)) return message
+    return { ...message, content: message.content.map((b) => (isClearedCall(b) ? { ...b, input: shortenInput(b.input) } : b)) }
+  })
+}
+
+export function appendSystem(system: Body["system"], text: string): Block[] {
+  const list: Block[] = typeof system === "string" ? [{ type: "text", text: system }] : [...(system ?? [])]
+  const lastCached = list.findLastIndex((b) => b.cache_control)
+  const cacheControl = lastCached >= 0 ? list[lastCached].cache_control : undefined
+  if (lastCached >= 0) list[lastCached] = withoutCacheControl(list[lastCached])
+  list.push({ type: "text", text, ...(cacheControl ? { cache_control: cacheControl } : {}) })
+  return list
+}

package/src/context/fold/turns.ts

@@ -0,0 +1,76 @@
+import { type Block, blocks, clean, describeToolCall, type Message, shortHash, textOf, withoutCacheControl } from "../content"
+import { interruptedReply } from "../prompts"
+import { turnEvidence } from "./evidence"
+
+export interface ReduceOptions {
+  evidence?: boolean
+}
+
+export function isPrompt(message: Message) {
+  if (message.role !== "user") return false
+  const content = blocks(message)
+  return !content.some((block) => block.type === "tool_result") && content.some((block) => block.type === "text" || block.type === "image" || block.type === "document")
+}
+
+export function splitTurns(messages: Message[]): { preamble: Message[]; turns: Message[][] } {
+  const preamble: Message[] = []
+  const turns: Message[][] = []
+  for (const message of messages) {
+    const current = turns.at(-1)
+    if (isPrompt(message) && !current?.every((m) => m.role === "user")) turns.push([message])
+    else if (current) current.push(message)
+    else preamble.push(message)
+  }
+  return { preamble, turns }
+}
+
+export function turnFingerprint(turn: Message[]): string {
+  return shortHash(JSON.stringify(blocks(turn[0]).map(withoutCacheControl)), 24)
+}
+
+export function isHarness(message: Message) {
+  return message.role === "system"
+}
+
+export function hasContent(message: Message) {
+  return blocks(message).some((block) => block.type !== "text" || String(block.text ?? "").trim())
+}
+
+const hasText = (block: Block) => block.type === "text" && String(block.text ?? "").trim() !== ""
+
+function mergedHarness(turn: Message[]): Message[] {
+  const content = turn.filter((m) => isHarness(m) && hasContent(m)).flatMap((m) => blocks(m).map(withoutCacheControl))
+  return content.length > 0 ? [{ role: "system", content }] : []
+}
+
+function interrupted(turn: Message[]): string {
+  const assistant = turn.filter((m) => m.role === "assistant")
+  const lastWords = assistant
+    .map((m) => textOf(m).trim())
+    .filter(Boolean)
+    .at(-1)
+  const calls = assistant.flatMap((m) => blocks(m).filter((b) => b.type === "tool_use")).map(describeToolCall)
+  return interruptedReply(lastWords, calls)
+}
+
+function carriedText(messages: Message[]): Block[] {
+  return messages
+    .filter((m) => m.role === "user")
+    .flatMap((m) => blocks(m).filter((b) => hasText(b) && !/^\s*(?:<system-reminder>[\s\S]*?<\/system-reminder>\s*)+$/.test(String(b.text))))
+    .map((b) => ({ type: "text", text: b.text }))
+}
+
+export function reduceTurn(turn: Message[], options: ReduceOptions = {}): Message[] {
+  const firstReply = turn.findIndex((m) => m.role === "assistant")
+  const opening = (firstReply === -1 ? turn : turn.slice(0, firstReply)).filter((m) => m.role === "user").map(clean)
+  const carried = carriedText(firstReply === -1 ? [] : turn.slice(firstReply))
+  if (carried.length > 0) opening.push({ role: "user", content: carried })
+  const evidence = options.evidence ? turnEvidence(turn) : null
+  if (evidence) opening.push({ role: "user", content: [{ type: "text", text: evidence }] })
+  opening.push(...mergedHarness(turn))
+  const last = turn.findLast((m) => m.role !== "system")
+  const content = last?.role === "assistant" ? blocks(last) : []
+  const text = content.filter(hasText)
+  const final = text.length > 0 && !content.some((b) => b.type === "tool_use") ? text.map((b) => ({ type: "text", text: b.text })) : [{ type: "text", text: interrupted(turn) }]
+  return [...opening, { role: "assistant", content: final }]
+}

package/src/context/prompts.ts

@@ -1,33 +1,105 @@
-import type { NoticeCounts } from "./types"
+import type { TranscriptRef } from "../transcript/search"
+import { truncate } from "./content"
 
-export function compactionNotice(args: NoticeCounts) {
+interface NoticeCounts {
+  omitted: number
+  kept: number
+  guide: string | null
+}
+
+const plural = (count: number, word: string) => `${count} ${word}${count === 1 ? "" : "s"}`
+
+export const SYSTEM_PROMPT = [
+  "# Earlier sessions in this project",
+  "",
+  "eunoe keeps the full record of this project's earlier Claude Code sessions, and the user expects you to use it the way a colleague who was there would. When they point you at one, skipping it is the failure to avoid: you will redo finished work, break rules the user already set, and ask for things they already told you.",
+  "",
+  "## When",
+  "",
+  'A message carrying `{ee:continue:<id>}` already has that session attached to it as a `<handoff>` block: read it as part of the message, nothing to run. Use the commands below when the user names a session without the marker (`eunoe load <id>`), or when they refer to earlier work you have no context for: a plan, a todo, "the thing we talked about", "where we left off". `eunoe sessions <key words>` lists the closest earlier sessions, newest first, each with its first and last request; if one clearly continues into this message, load it, otherwise ask which they mean. Do not go looking for work that is clearly new and unrelated.',
+  "",
+  "## How",
+  "",
+  "1. `eunoe load <id>` writes that whole session to a file and prints its path. Read the file with the Read tool from the first line to the last, in as many Read calls as its length needs, before you act. Do not grep, head, tail or sed it, and do not stop partway: the rules, values and open todos you need are spread across all of it.",
+  "2. Only then start the work. Follow what the record establishes: the user's rules and preferences, decisions made, what was finished and what was left for later. Its values (ids, versions, names, commands) are exact.",
+  "",
+  "`eunoe peek <id> <words>` returns just the excerpts of a session that match, for a single fact such as an error message or a value. It is not a substitute for loading when the message continues that session's work.",
+  "",
+  "Loading or peeking needs no permission and no announcement: run it and carry on with the request.",
+].join("\n")
+
+const HANDOFF_PREAMBLE =
+  "What follows is carried over from an earlier session on this project so you can pick the work up without being told again: the user's messages, the key output lines and the agent's replies, in order. Treat the rules and preferences in it as still in force, and the values in it (ids, versions, names, commands) as exact. Its full tool output is not here but stays reachable two ways: when a later message touches it, the matching excerpts are attached to that message as recalled context, labelled with this session's title; and for a specific value you can run `eunoe peek <id> <words>` yourself."
+
+export function handoffBlock(label: string, text: string): string {
+  return `<handoff from="${label}">\n${HANDOFF_PREAMBLE}\n\n${text}\n</handoff>`
+}
+
+export function recalledContext(entries: string[], fromEarlierSessions: boolean): string {
+  const where = fromEarlierSessions ? "earlier in this session or in an earlier session on this project" : "earlier in this session"
+  return `<recalled-context>\nExcerpts from ${where} that match this message: tool output that is no longer in your context, quoted exactly, oldest first. Where the same thing appears twice, the later turn is current. Use them if they answer what was asked; ignore them otherwise.\n\n${entries.join("\n")}\n</recalled-context>`
+}
+
+export function rerankQuestion(query: string): string {
+  return `Which excerpt contains the exact answer to the developer's question about this coding session: "${query}"?`
+}
+
+export function toolEvidence(entries: string[]): string {
+  return `<tool-evidence>\nKey lines of command output from this turn, kept verbatim (the full output is in the transcript):\n${entries.join("\n")}\n</tool-evidence>`
+}
+
+export function interruptedReply(lastWords: string | undefined, calls: string[]): string {
+  const shown = calls.slice(-20)
+  return [
+    "[This turn was interrupted before a final reply.]",
+    lastWords ? `Last thing you said: ${lastWords.length > 600 ? `${truncate(lastWords, 600)}…` : lastWords}` : "",
+    calls.length > 0 ? `Tool calls (${calls.length}${calls.length > shown.length ? `, last ${shown.length} shown` : ""}): ${shown.join("; ")}` : "",
+    "Their output is in the full transcript.",
+  ]
+    .filter(Boolean)
+    .join("\n")
+}
+
+export function clearedOutput(dir: string | null): string {
+  return `[Output cleared to keep the context within its limit. It is in the full transcript${dir ? ` at ${dir}` : ""}: search there for this call.]`
+}
+
+export function clearedInput(kept: string, cleared: number): string {
+  return `${kept}… [${cleared} chars cleared; in the transcript]`
+}
+
+export function compactionNotice({ omitted, kept, guide }: NoticeCounts): string {
   return [
     "<context-compacted>",
     "Your context was compacted here, so tool calls and their output from before this point were removed.",
-    args.omitted > 0
-      ? `${args.omitted} of the oldest turns didn't fit and were removed entirely. The ${args.kept} turn${args.kept === 1 ? "" : "s"} after them are shown as the user's message and your final reply.`
-      : args.kept > 0
+    omitted > 0
+      ? `${omitted} of the oldest turns didn't fit and were removed entirely. The ${plural(kept, "turn")} after them are shown as the user's message and your final reply.`
+      : kept > 0
         ? "Every earlier turn is shown below as the user's message and your final reply."
         : "",
     "The turn that was in progress when the context filled up follows in full. Continue from it.",
     "Instructions and preferences the user gave in earlier turns still apply: how they want things done, and what to do or not do on your own. Look back over their messages before you act.",
     "For an exact detail from before this point (an ID, a path, a command, an error, a value, what a tool printed), look it up instead of going from memory. A lookup is cheap; a wrong detail is not. Never say you don't know about something earlier in this session without searching for it first, and if what you remember contradicts what the user says, search before telling them they are wrong.",
-    args.guide ?? "",
+    guide ?? "",
     "</context-compacted>",
-  ].filter(Boolean).join("\n\n")
+  ]
+    .filter(Boolean)
+    .join("\n\n")
 }
 
-export function truncationNotice(args: NoticeCounts) {
+export function truncationNotice({ omitted, kept, guide }: NoticeCounts): string {
   return [
     "<context-truncated>",
-    `${args.omitted} earlier turn${args.omitted === 1 ? " was" : "s were"} dropped to fit the context window. What follows is the most recent ${args.kept} turn${args.kept === 1 ? "" : "s"}, unchanged.`,
+    `${omitted} earlier turn${omitted === 1 ? " was" : "s were"} dropped to fit the context window. What follows is the most recent ${plural(kept, "turn")}, unchanged.`,
     "Instructions and preferences the user gave in earlier turns still apply.",
-    args.guide ?? "",
+    guide ?? "",
     "</context-truncated>",
-  ].filter(Boolean).join("\n\n")
+  ]
+    .filter(Boolean)
+    .join("\n\n")
 }
 
-export function trimInstructions(guide: string): string {
+export function trimInstructions(guide: string | null): string {
   return [
     "# Context between turns",
     "",
@@ -39,15 +111,19 @@ export function trimInstructions(guide: string): string {
     "- Decisions and their reasons, including approaches you tried and ruled out.",
     "- Where things stand: what is done, what is not, what you verified and how, and what is waiting on the user.",
     "",
-    "It is still your reply to the user, so write it for them, but leave out nothing you will need. State things outright instead of pointing back at tool output: \"as shown above\" means nothing next turn. One exact line (a path, a command, a value) beats a paragraph describing it. A turn that ends on a question still needs the state written down. A trivial turn (a quick answer, small talk) needs no state.",
+    'It is still your reply to the user, so write it for them, but leave out nothing you will need. State things outright instead of pointing back at tool output: "as shown above" means nothing next turn. One exact line (a path, a command, a value) beats a paragraph describing it. A turn that ends on a question still needs the state written down. A trivial turn (a quick answer, small talk) needs no state.',
     "",
     "Instructions and preferences the user gave in earlier turns still apply: how they want things done, and what to do or not do on your own.",
-    "",
-    "Nothing is lost. What you see of earlier turns is only their outcome. For an exact detail from an earlier turn (an ID, a path, a command you ran, what it printed, a file's earlier content, an error), look it up in the full transcript instead of going from memory or redoing the work. A lookup is cheap; a wrong detail is not.",
-    "",
-    guide,
-    "",
-    "What you read from it stays in context for this turn only. If you will need it again later, put it in your final message.",
+    ...(guide
+      ? [
+          "",
+          "Nothing is lost. What you see of earlier turns is only their outcome. For an exact detail from an earlier turn (an ID, a path, a command you ran, what it printed, a file's earlier content, an error), look it up in the full transcript instead of going from memory or redoing the work. A lookup is cheap; a wrong detail is not.",
+          "",
+          guide,
+          "",
+          "What you read from it stays in context for this turn only. If you will need it again later, put it in your final message.",
+        ]
+      : []),
   ].join("\n")
 }
 
@@ -61,6 +137,49 @@ export function searchOnlyInstructions(guide: string): string {
   ].join("\n")
 }
 
-export const CLEARED_OUTPUT = "[Output cleared to keep the context within its limit. It is in the full transcript: search there for this call.]"
-
-export const TRANSCRIPT_FALLBACK = "The full transcript is your Claude Code session file under ~/.claude/projects."
+export function searchGuide(ref: TranscriptRef): string {
+  if (ref.mode === "jsonl") {
+    return [
+      `The full transcript is Claude Code's session file: ${ref.jsonl}`,
+      "It is JSONL, one entry per line. Your tool calls are `tool_use` blocks in `assistant` entries; their output is in the `tool_result` blocks of the `user` entries that follow. It is large: search it narrowly and never read it whole. For example:",
+      `  grep -n 'distinctive text' ${ref.jsonl} | cut -c1-400`,
+      `  jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use") | "\\(.name) \\(.input | tostring | .[0:200])"' ${ref.jsonl}`,
+    ].join("\n")
+  }
+  const layout =
+    ref.mode === "xml"
+      ? [
+          `The full transcript is a folder with one XML file per turn: ${ref.dir}`,
+          "- `index.md`: one line per turn, what the user asked and how the turn ended. Skim it to find the turn you need.",
+          "- `turn-0001.xml`, …: one turn each, `<turn n>` with `<user>` (the message), `<said>` (what you wrote while working), `<tool n name>` holding `<call>`, `<input>` and `<output>`, and `<final_reply>`.",
+          "- `turn-0001-subagent-1.xml`, …: the whole run of a subagent launched in that turn, same layout. The turn itself only has the subagent's report; what the subagent saw and ran is here.",
+        ]
+      : [
+          `The full transcript is a folder of markdown files: ${ref.dir}`,
+          "- `index.md`: one line per turn, what the user asked and how the turn ended. Skim it to find the turn you need.",
+          "- `turn-0001.md`, …: one turn each. `## User` (the message), `### [tool 3/12] Bash: …` for every tool call with `[output of tool 3]` below it, and `## Final reply`.",
+          "- `turn-0001-subagent-1.md`, …: the whole run of a subagent launched in that turn, same layout. The turn itself only has the subagent's report; what the subagent saw and ran is here.",
+        ]
+  const habits =
+    "Search for more than one phrasing (the exact term, a synonym, a file or function name, an error string) before you conclude something isn't there. Read the whole turn file around a hit: the answer is often a few calls before or after it."
+  if (ref.mode === "qmd") {
+    return [
+      ...layout,
+      "It is indexed with qmd. Run qmd from inside that folder:",
+      `  cd ${ref.dir} && qmd query "a natural-language question"   # semantic + keyword, best when you don't know the exact words (5–20s)`,
+      `  cd ${ref.dir} && qmd search "exact words"                 # keyword only, instant`,
+      `  then Read ${ref.dir}/turn-NNNN.md (or qmd get turn-NNNN.md)`,
+      "If qmd isn't ready yet (the index builds in the background), grep the folder instead.",
+      habits,
+    ].join("\n")
+  }
+  const ext = ref.mode === "xml" ? "xml" : "md"
+  return [
+    ...layout,
+    "To find something:",
+    `  grep -ril 'distinctive words' ${ref.dir}        # which turns mention it`,
+    `  grep -n -i 'distinctive words' ${ref.dir}/*.${ext} | cut -c1-300`,
+    `  then Read ${ref.dir}/turn-NNNN.${ext}`,
+    habits,
+  ].join("\n")
+}