@chroxify/eunoe 0.0.0-stage → 1.0.0

package/src/context/evidence.ts

@@ -0,0 +1,92 @@
+import { ERROR_CODE, ERROR_LINE, EVIDENCE_CALL_FLOOR, EVIDENCE_LABELS, EVIDENCE_LINE_CHARS, EVIDENCE_LINES_PER_CALL, EVIDENCE_MIN_SCORE, EVIDENCE_RANKED, EVIDENCE_SCAN_LINES, EVIDENCE_TURN_CHARS, ID_TOKEN, KEY_VALUE, REREADABLE_TOOLS, VALUE_LABEL, VALUE_TOKEN } from "./constants"
+import { blocks, clip, describeToolCall, resultText } from "./content"
+import type { Block, EvidenceOptions, Message } from "./types"
+
+interface Scored {
+  index: number
+  line: string
+  score: number
+}
+
+export function isSalient(line: string): boolean {
+  return ERROR_LINE.test(line) || ERROR_CODE.test(line) || VALUE_TOKEN.test(line)
+}
+
+function scoreLines(text: string, options: EvidenceOptions): Scored[] {
+  const scan = options.scanLines ?? EVIDENCE_SCAN_LINES
+  const lineChars = options.lineChars ?? EVIDENCE_LINE_CHARS
+  const minScore = options.minScore ?? EVIDENCE_MIN_SCORE
+  const scored = text.split("\n").slice(0, scan).flatMap((raw, index) => {
+    const line = raw.trim()
+    if (line.length < 4) return []
+    const error = ERROR_LINE.test(line) || ERROR_CODE.test(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) + ((options.labels ?? EVIDENCE_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, options.linesPerCall ?? EVIDENCE_LINES_PER_CALL)
+    .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) => (results.has(call.id) ? [{ call, result: results.get(call.id)! }] : []))
+}
+
+function render(entries: Array<{ head: string; lines: string[] }>): string | null {
+  const body = entries.filter((e) => e.lines.length).map((e) => `- ${e.head}:\n${e.lines.map((l) => `    ${l}`).join("\n")}`)
+  return body.length ? `<tool-evidence>\nKey lines of command output from this turn, kept verbatim (the full output is in the transcript):\n${body.join("\n")}\n</tool-evidence>` : null
+}
+
+export function turnEvidence(turn: Message[], options: EvidenceOptions = {}): string | null {
+  const turnChars = options.turnChars ?? EVIDENCE_TURN_CHARS
+  const perCall = options.linesPerCall ?? EVIDENCE_LINES_PER_CALL
+  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)" : ""}`)
+  if (!(options.ranked ?? EVIDENCE_RANKED)) {
+    const entries: Array<{ head: string; lines: string[] }> = []
+    let used = 0
+    pairs.forEach(({ result }, i) => {
+      const lines = salientLines(resultText(result), options)
+      if (!lines.length) 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 render(entries)
+  }
+  const floor = options.callFloor ?? EVIDENCE_CALL_FLOOR
+  const perCallLines = 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 : heads[call].length + 4)
+    if (bucket.length >= perCall || used + cost > turnChars) return
+    bucket.push(line)
+    chosen.set(call, bucket)
+    used += cost
+  }
+  perCallLines.forEach((lines, call) => lines.slice(0, floor).forEach((line) => take(call, line)))
+  perCallLines
+    .flatMap((lines, call) => lines.slice(floor).map((line) => ({ line, call })))
+    .sort((a, b) => b.line.score - a.line.score || a.call - b.call || a.line.index - b.line.index)
+    .forEach(({ line, call }) => take(call, line))
+  return render(heads.map((head, i) => ({ head, lines: (chosen.get(i) ?? []).sort((a, b) => a.index - b.index).map((s) => s.line) })))
+}

package/src/context/prompts.ts

@@ -0,0 +1,66 @@
+import type { NoticeCounts } from "./types"
+
+export function compactionNotice(args: NoticeCounts) {
+  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
+        ? "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 ?? "",
+    "</context-compacted>",
+  ].filter(Boolean).join("\n\n")
+}
+
+export function truncationNotice(args: NoticeCounts) {
+  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.`,
+    "Instructions and preferences the user gave in earlier turns still apply.",
+    args.guide ?? "",
+    "</context-truncated>",
+  ].filter(Boolean).join("\n\n")
+}
+
+export function trimInstructions(guide: string): string {
+  return [
+    "# Context between turns",
+    "",
+    "This session trims its context between turns: of every earlier turn you keep only the user's message (with anything that arrived with it) and your final message. Everything in between is gone when the next turn starts: tool calls and their results, files you read, command output, your thinking, and anything you wrote along the way. Within a turn, nothing is trimmed.",
+    "",
+    "So your final message is the only memory you carry forward. End each turn with a final message that lets you pick the work back up cold:",
+    "- What changed: files with their paths, branches, commits, PRs, anything created, moved or deleted.",
+    "- What you found: facts you would otherwise have to dig up again. Where code lives, how something works, the cause of a bug, exact error text, IDs, URLs, the numbers that matter.",
+    "- 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.",
+    "",
+    "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.",
+  ].join("\n")
+}
+
+export function searchOnlyInstructions(guide: string): string {
+  return [
+    "# The full transcript",
+    "",
+    "Earlier parts of this session may be summarised or missing from your context. The complete record is on disk, and for any exact detail from earlier (an ID, a path, a command you ran, what it printed, an error, a value) you should look it up there rather than answer 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.",
+    "",
+    guide,
+  ].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."

package/src/context/recall.ts

@@ -0,0 +1,155 @@
+import { BM25_B, BM25_K1, RECALL_LINE_CHARS, RECALL_MAX_CHARS, RECALL_MAX_CHARS_MULTI, RECALL_MIN_TERMS, RECALL_NARRATIVE, RECALL_PER_QUERY, RECALL_RERANK_CANDIDATES, RECALL_SALIENT_EXCERPT, RECALL_SHOWN_LINES, RECALL_WINDOW_LINES, STOPWORDS } from "./constants"
+import { blocks, clip, describeToolCall, resultText } from "./content"
+import { isSalient, toolPairs } from "./evidence"
+import { isPrompt, splitTurns } from "./turns"
+import type { Message, RecallChunk, RecallOptions, RecallPick, Reranker } from "./types"
+
+const REMINDERS = /<(system-reminder|system-message|recalled-context|tool-evidence)>[\s\S]*?<\/\1>/g
+
+export function terms(text: string): string[] {
+  return (text.toLowerCase().match(/[a-z0-9_@$][a-z0-9_.:/@$-]*[a-z0-9_]|[a-z0-9]/g) ?? [])
+    .flatMap((term) => (/[._:/-]/.test(term) ? [term, ...term.split(/[._:/-]+/)] : [term]))
+    .filter((term) => term.length >= 3 && !STOPWORDS.has(term))
+}
+
+function promptText(message: Message): string {
+  return blocks(message).filter((b) => b.type === "text").map((b) => String(b.text ?? "")).join("\n").replace(REMINDERS, "").trim()
+}
+
+function windows(lines: string[], size: number): string[][] {
+  const out: string[][] = []
+  for (let start = 0; start < lines.length; start += size) out.push(lines.slice(start, start + size))
+  return out
+}
+
+export function recallChunks(messages: Message[], keptIds: Map<string, string>, options: RecallOptions = {}): RecallChunk[] {
+  const { turns } = splitTurns(messages)
+  const size = options.windowLines ?? RECALL_WINDOW_LINES
+  const weight = Math.max(1, options.callWeight ?? 1)
+  const chunks: RecallChunk[] = []
+  turns.slice(0, -1).forEach((turn, turnIndex) => {
+    for (const { call, result } of toolPairs(turn)) {
+      const text = resultText(result)
+      if (keptIds.get(call.id) === text || !text.trim()) continue
+      const head = describeToolCall(call)
+      const headTerms = Array.from({ length: weight }, () => terms(head)).flat()
+      for (const window of windows(text.split("\n"), size)) {
+        chunks.push({ turn: turnIndex + 1, call: head, lines: window, terms: [...headTerms, ...terms(window.join("\n"))] })
+      }
+    }
+    if (!(options.narrative ?? RECALL_NARRATIVE)) return
+    const said = turn.slice(1, -1).filter((m) => m.role === "assistant").flatMap((m) => blocks(m).filter((b) => b.type === "text").map((b) => String(b.text ?? "").trim())).filter(Boolean)
+    for (const window of windows(said.join("\n").split("\n"), size)) {
+      chunks.push({ turn: turnIndex + 1, call: "agent", lines: window, terms: terms(window.join("\n")) })
+    }
+  })
+  return chunks
+}
+
+export function rank(query: string[], chunks: RecallChunk[], minTerms = RECALL_MIN_TERMS) {
+  const df = new Map<string, number>()
+  for (const chunk of chunks) for (const term of new Set(chunk.terms)) df.set(term, (df.get(term) ?? 0) + 1)
+  const average = chunks.reduce((s, c) => s + c.terms.length, 0) / Math.max(1, chunks.length)
+  const wanted = [...new Set(query)].filter((t) => df.has(t))
+  return chunks.map((chunk, index) => {
+    const tf = new Map<string, number>()
+    for (const term of chunk.terms) tf.set(term, (tf.get(term) ?? 0) + 1)
+    let score = 0
+    let matched = 0
+    for (const term of wanted) {
+      const f = tf.get(term) ?? 0
+      if (!f) continue
+      matched += 1
+      const idf = Math.log(1 + (chunks.length - df.get(term)! + 0.5) / (df.get(term)! + 0.5))
+      score += idf * (f * (BM25_K1 + 1)) / (f + BM25_K1 * (1 - BM25_B + BM25_B * chunk.terms.length / average))
+    }
+    return { index, score, matched }
+  }).filter((r) => r.matched >= Math.min(minTerms, wanted.length) && r.score > 0).sort((a, b) => b.score - a.score)
+}
+
+function excerpt(chunk: RecallChunk, query: Set<string>, salient: boolean): string[] {
+  const hits = chunk.lines.map((line, i) => (terms(line).some((t) => query.has(t)) ? i : -1)).filter((i) => i >= 0)
+  const shown = new Set<number>()
+  for (const i of hits) for (const j of [i - 1, i, i + 1]) if (j >= 0 && j < chunk.lines.length) shown.add(j)
+  if (salient) for (let i = 0; i < chunk.lines.length && shown.size < RECALL_SHOWN_LINES + 2; i += 1) if (isSalient(chunk.lines[i])) shown.add(i)
+  const ordered = [...shown].sort((a, b) => a - b).slice(0, salient ? RECALL_SHOWN_LINES + 2 : RECALL_SHOWN_LINES)
+  return (ordered.length ? ordered : [0]).map((i) => clip(chunk.lines[i], RECALL_LINE_CHARS)).filter(Boolean)
+}
+
+export function queriesOf(prompt: string): string[] {
+  const lines = prompt.split("\n").map((l) => l.trim()).filter((l) => terms(l).length >= 2)
+  return lines.length > 1 ? lines : [prompt]
+}
+
+export function pickRecall(prompt: string, chunks: RecallChunk[], options: RecallOptions = {}): RecallPick[] {
+  const perQuery = options.perQuery ?? RECALL_PER_QUERY
+  const picked = new Map<number, Set<string>>()
+  for (const query of queriesOf(prompt)) {
+    const q = terms(query)
+    for (const hit of rank(q, chunks, options.minTerms).slice(0, perQuery)) {
+      if (!picked.has(hit.index)) picked.set(hit.index, new Set())
+      for (const t of q) picked.get(hit.index)!.add(t)
+    }
+  }
+  return [...picked.entries()].map(([index, query]) => ({ index, query }))
+}
+
+export async function pickRecallWith(prompt: string, chunks: RecallChunk[], rerank: Reranker, options: RecallOptions = {}): Promise<RecallPick[]> {
+  const perQuery = options.perQuery ?? RECALL_PER_QUERY
+  const width = options.candidates ?? RECALL_RERANK_CANDIDATES
+  const picked = new Map<number, Set<string>>()
+  for (const query of queriesOf(prompt)) {
+    const q = terms(query)
+    const candidates = rank(q, chunks, options.minTerms).slice(0, width).map((hit) => hit.index)
+    for (const index of (await rerank(query, chunks, candidates)).slice(0, perQuery)) {
+      if (!picked.has(index)) picked.set(index, new Set())
+      for (const t of q) picked.get(index)!.add(t)
+    }
+  }
+  return [...picked.entries()].map(([index, query]) => ({ index, query }))
+}
+
+export function renderRecall(prompt: string, chunks: RecallChunk[], picks: RecallPick[], options: RecallOptions = {}): string | null {
+  if (!picks.length) return null
+  const budget = queriesOf(prompt).length > 1 ? options.maxCharsMulti ?? RECALL_MAX_CHARS_MULTI : options.maxChars ?? RECALL_MAX_CHARS
+  const entries: string[] = []
+  let used = 0
+  for (const pick of [...picks].sort((a, b) => chunks[a.index].turn - chunks[b.index].turn || a.index - b.index)) {
+    const chunk = chunks[pick.index]
+    const entry = `[turn ${chunk.turn}] ${chunk.call}:\n${excerpt(chunk, pick.query, options.salientExcerpt ?? RECALL_SALIENT_EXCERPT).map((l) => `    ${l}`).join("\n")}`
+    if (used + entry.length > budget) continue
+    entries.push(entry)
+    used += entry.length
+  }
+  return entries.length
+    ? `<recalled-context>\nExcerpts from earlier in this session 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>`
+    : null
+}
+
+export function recallFor(prompt: string, chunks: RecallChunk[], options: RecallOptions = {}): string | null {
+  if (!chunks.length) return null
+  return renderRecall(prompt, chunks, pickRecall(prompt, chunks, options), options)
+}
+
+export async function recallForWith(prompt: string, chunks: RecallChunk[], rerank: Reranker, options: RecallOptions = {}): Promise<string | null> {
+  if (!chunks.length) return null
+  return renderRecall(prompt, chunks, await pickRecallWith(prompt, chunks, rerank, options), options)
+}
+
+export function livePrompt(messages: Message[]): { index: number; text: string } | null {
+  const { preamble, turns } = splitTurns(messages)
+  if (turns.length < 2) return null
+  const first = turns.at(-1)![0]
+  if (!isPrompt(first)) return null
+  const index = preamble.length + turns.slice(0, -1).reduce((s, t) => s + t.length, 0)
+  return { index, text: promptText(first) }
+}
+
+export function withRecall(messages: Message[], fingerprint: (message: Message) => string, recalls: Record<string, string>): Message[] {
+  if (!Object.keys(recalls).length) return messages
+  return messages.map((message) => {
+    if (!isPrompt(message)) return message
+    const text = recalls[fingerprint(message)]
+    return text ? { ...message, content: [...blocks(message), { type: "text", text }] } : message
+  })
+}

package/src/context/rerank.ts

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs"
+import { paths } from "../config/constants"
+import { RERANK_ENDPOINT, RERANK_LINE_CHARS, RERANK_TIMEOUT_MS } from "./constants"
+import type { RecallChunk, Reranker } from "./types"
+
+export function rerankKey(): string | null {
+  const env = process.env.TYPESAFE_API_KEY?.trim()
+  if (env) return env
+  return existsSync(paths.typesafeKey) ? readFileSync(paths.typesafeKey, "utf8").trim() : null
+}
+
+export function rerankState(chunks: RecallChunk[], candidates: number[]): string {
+  return candidates.map((index, n) => `### ${n}\n[turn ${chunks[index].turn}] ${chunks[index].call}\n${chunks[index].lines.map((l) => l.slice(0, RERANK_LINE_CHARS)).join("\n")}`).join("\n\n")
+}
+
+export function orderByProbability(candidates: number[], probabilities: Record<string, number>): number[] {
+  return candidates.map((_, n) => n).sort((a, b) => (probabilities[String(b)] ?? 0) - (probabilities[String(a)] ?? 0) || a - b).map((n) => candidates[n])
+}
+
+export function jevReranker(model: string, key: string, endpoint = RERANK_ENDPOINT): Reranker {
+  return async (query, chunks, candidates) => {
+    if (candidates.length < 2) return candidates
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+        signal: AbortSignal.timeout(RERANK_TIMEOUT_MS),
+        body: JSON.stringify({
+          model,
+          state: rerankState(chunks, candidates),
+          questions: {
+            where: { type: "choice", instructions: `Which excerpt contains the exact answer to the developer's question about this coding session: "${query}"?`, criteria: Object.fromEntries(candidates.map((_, n) => [String(n), null])) },
+          },
+        }),
+      })
+      if (!response.ok) return candidates
+      const json: any = await response.json()
+      const probabilities = json?.answers?.where?.probabilities
+      return probabilities && typeof probabilities === "object" ? orderByProbability(candidates, probabilities) : candidates
+    } catch {
+      return candidates
+    }
+  }
+}

package/src/context/strategies.ts

@@ -0,0 +1,89 @@
+import { CLEARED_INPUT_KEPT, CLEARED_INPUT_THRESHOLD } from "./constants"
+import { blocks, truncate, withoutCacheControl } from "./content"
+import { compactionNotice, truncationNotice } from "./prompts"
+import { hasContent, isHarness, reduceTurn, splitTurns } from "./turns"
+import type { Block, Body, CompactOptions, Message, ReduceOptions } from "./types"
+
+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 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) => reduceTurn(turn, options)),
+    ...turns.slice(cutIndex).flat(),
+  ]
+}
+
+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).reduce((total, m) => total + (m.role === "user" ? blocks(m).filter((b) => b.type === "tool_result").length : 0), 0)
+}
+
+export function clearToolResults(messages: Message[], from: number, count: number, placeholder: string): Message[] {
+  let left = count
+  const cleared = new Set<string>()
+  const results = 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((b) => {
+        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 }
+      }),
+    }
+  })
+  return results.map((message) => {
+    if (message.role !== "assistant" || typeof message.content === "string") return message
+    if (!message.content.some((b) => b.type === "tool_use" && cleared.has(b.id))) return message
+    return { ...message, content: message.content.map((b) => (b.type === "tool_use" && cleared.has(b.id) ? { ...b, input: shortenInput(b.input) } : b)) }
+  })
+}
+
+function shortenInput(input: unknown): unknown {
+  if (typeof input === "string") return input.length > CLEARED_INPUT_THRESHOLD ? `${truncate(input, CLEARED_INPUT_KEPT)}… [${input.length - CLEARED_INPUT_KEPT} chars cleared; in the transcript]` : 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 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/turns.ts

@@ -0,0 +1,87 @@
+import { REMINDER_ONLY, SUMMARY_CALLS_SHOWN, SUMMARY_LAST_WORDS_CHARS } from "./constants"
+import { blocks, clean, describeToolCall, truncate, withoutCacheControl } from "./content"
+import { turnEvidence } from "./evidence"
+import type { Block, Message, ReduceOptions } from "./types"
+
+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) {
+    if (isPrompt(message) && !(turns.length > 0 && turns.at(-1)!.every((m) => m.role === "user"))) {
+      turns.push([message])
+    } else if (turns.length > 0) {
+      turns.at(-1)!.push(message)
+    } else {
+      preamble.push(message)
+    }
+  }
+  return { preamble, turns }
+}
+
+export function turnFingerprint(turn: Message[]): string {
+  const hasher = new Bun.CryptoHasher("sha256")
+  hasher.update(JSON.stringify(blocks(turn[0]).map(withoutCacheControl)))
+  return hasher.digest("hex").slice(0, 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())
+}
+
+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 interruptedSummary(turn: Message[]): string {
+  const assistant = turn.filter((m) => m.role === "assistant")
+  const lastWords = [...assistant].reverse()
+    .map((m) => blocks(m).filter((b) => b.type === "text").map((b) => String(b.text ?? "")).join("\n").trim())
+    .find(Boolean)
+  const calls = assistant.flatMap((m) => blocks(m).filter((b) => b.type === "tool_use")).map(describeToolCall)
+  const shown = calls.slice(-SUMMARY_CALLS_SHOWN)
+  return [
+    "[This turn was interrupted before a final reply.]",
+    lastWords ? `Last thing you said: ${lastWords.length > SUMMARY_LAST_WORDS_CHARS ? `${truncate(lastWords, SUMMARY_LAST_WORDS_CHARS)}…` : 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")
+}
+
+function carriedText(messages: Message[]): Block[] {
+  return messages
+    .filter((m) => m.role === "user")
+    .flatMap((m) => blocks(m).filter((b) => b.type === "text" && String(b.text ?? "").trim() && !REMINDER_ONLY.test(String(b.text))))
+    .map((b) => ({ type: "text", text: b.text }))
+}
+
+export function reduceTurn(turn: Message[], options: ReduceOptions = {}): Message[] {
+  const opening: Message[] = []
+  let i = 0
+  for (; i < turn.length && turn[i].role !== "assistant"; i += 1) {
+    if (turn[i].role === "user") opening.push(clean(turn[i]))
+  }
+  const carried = carriedText(turn.slice(i))
+  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].reverse().find((m) => m.role !== "system")!
+  const content = last.role === "assistant" ? blocks(last) : []
+  const text = content.filter((b) => b.type === "text" && String(b.text ?? "").trim())
+  const final = text.length > 0 && !content.some((b) => b.type === "tool_use")
+    ? text.map((b) => ({ type: "text", text: b.text }))
+    : [{ type: "text", text: interruptedSummary(turn) }]
+  return [...opening, { role: "assistant", content: final }]
+}

package/src/context/types.ts

@@ -0,0 +1,66 @@
+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 interface ReduceOptions {
+  evidence?: boolean
+}
+
+export interface CompactOptions extends ReduceOptions {
+  keepTurns: number
+  guide: string | null
+  omittedBefore?: number
+}
+
+export interface NoticeCounts {
+  omitted: number
+  kept: number
+  guide: string | null
+}
+
+export interface RecallChunk {
+  turn: number
+  call: string
+  lines: string[]
+  terms: string[]
+}
+
+export interface EvidenceOptions {
+  linesPerCall?: number
+  lineChars?: number
+  turnChars?: number
+  scanLines?: number
+  minScore?: number
+  allTools?: boolean
+  ranked?: boolean
+  labels?: boolean
+  callFloor?: number
+}
+
+export interface RecallOptions {
+  windowLines?: number
+  perQuery?: number
+  minTerms?: number
+  maxChars?: number
+  maxCharsMulti?: number
+  narrative?: boolean
+  callWeight?: number
+  salientExcerpt?: boolean
+  candidates?: number
+}
+
+export type Reranker = (query: string, chunks: RecallChunk[], candidates: number[]) => Promise<number[]>
+
+export interface RecallPick {
+  index: number
+  query: Set<string>
+}

package/src/proxy/canonical.ts

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import type { Body } from "../context/types"
+import { BILLING_LINE } from "./constants"
+import type { Canonical, CanonicalResult } from "./types"
+
+const billingLine = (system: Body["system"]) => {
+  const first = Array.isArray(system) ? String(system[0]?.text ?? "") : String(system ?? "")
+  return first.match(BILLING_LINE)?.[0] ?? null
+}
+
+function withBilling(system: Body["system"], line: string | null): Body["system"] {
+  if (!line) return system
+  if (Array.isArray(system)) {
+    const [first, ...rest] = system
+    return [{ ...first, text: String(first?.text ?? "").replace(BILLING_LINE, line) }, ...rest]
+  }
+  return String(system ?? "").replace(BILLING_LINE, line)
+}
+
+export function applyCanonical(body: Body, file: string): CanonicalResult {
+  if (!Array.isArray(body.tools) || body.tools.length === 0) return { body, status: "skipped" }
+  if (existsSync(file)) {
+    const canonical = JSON.parse(readFileSync(file, "utf8")) as Canonical
+    return { body: { ...body, system: withBilling(canonical.system, billingLine(body.system)), tools: canonical.tools }, status: "applied" }
+  }
+  mkdirSync(path.dirname(file), { recursive: true })
+  const partial = `${file}.${process.pid}.${Date.now()}`
+  writeFileSync(partial, JSON.stringify({ system: body.system, tools: body.tools } satisfies Canonical))
+  renameSync(partial, file)
+  return { body, status: "captured" }
+}