@chroxify/eunoe 1.2.2 → 1.3.0

package/src/core/forward.ts

@@ -0,0 +1,192 @@
+import { type Body, wellFormed } from "../context/content"
+import type { Reranker } from "../context/recall"
+import { CORE_DEFAULTS, type CoreConfig } from "./config"
+import { sizeOf } from "./estimate"
+import { type Rewrite, type RewriteNote, rewriteAsync, type ThreadSources } from "./rewrite"
+import type { ThreadStore } from "./state"
+import { inputTokens, recordOverflow, recordUsage, watchUsage } from "./usage"
+import { createWindowLookup, type WindowLookup } from "./window"
+
+export type ForwardNote = RewriteNote | Record<string, unknown>
+
+export type Prepared = Omit<Rewrite, "note"> & { note: ForwardNote }
+
+export interface ForwarderOptions {
+  store: ThreadStore
+  upstream?: string
+  config?: CoreConfig
+  window?: number | null | WindowLookup
+  threadIdOf?: (request: Request, body: Body) => string | null
+  sources?: (threadId: string, request: Request, body: Body) => ThreadSources | undefined
+  reranker?: Reranker
+  prepare?: (request: Request, body: Body, mayCompact: boolean) => Promise<Prepared>
+  record?: (entry: Record<string, unknown>) => void
+  countTokensTimeoutMs?: number
+}
+
+interface Outgoing {
+  note: ForwardNote
+  threadKey: string | null
+  bodyText: string | undefined
+  sentSize: number
+  givenSize: number
+  fixedSize: number
+}
+
+const COUNT_TOKENS_ATTEMPTS = 3
+
+const DROPPED_REQUEST_HEADERS = ["host", "content-length", "accept-encoding"]
+
+const clipped = (error: string) => error.slice(0, 500)
+
+export function claudeCodeSessionId(headers: Headers, body: Body): string | null {
+  const header = headers.get("x-claude-code-session-id")
+  if (header) return header
+  try {
+    return JSON.parse(body.metadata?.user_id ?? "{}").session_id ?? null
+  } catch {
+    return null
+  }
+}
+
+const defaultThreadId = (request: Request, body: Body) => request.headers.get("x-thread-id") ?? claudeCodeSessionId(request.headers, body)
+
+function forwardableHeaders(headers: Headers) {
+  const out = new Headers(headers)
+  out.delete("content-encoding")
+  out.delete("content-length")
+  return out
+}
+
+function defaultPrepare(options: ForwarderOptions, upstream: string): NonNullable<ForwarderOptions["prepare"]> {
+  const threadIdOf = options.threadIdOf ?? defaultThreadId
+  const given = options.window
+  const lookup = typeof given === "function" ? given : createWindowLookup()
+  const windowFor: (model: unknown, headers: Headers) => Promise<number | null> = typeof given === "number" || given === null ? () => Promise.resolve(given) : (model, headers) => lookup(model, headers, upstream)
+  return async (request, body, mayCompact) => {
+    const threadId = threadIdOf(request, body)
+    const window = await windowFor(body.model, request.headers)
+    const sources = threadId ? options.sources?.(threadId, request, body) : undefined
+    return rewriteAsync({ body, threadId, config: options.config ?? CORE_DEFAULTS, store: options.store, sources, window, mayCompact }, options.reranker)
+  }
+}
+
+const passthrough = (bodyText: string | undefined): Outgoing => ({ note: { action: "pass" }, threadKey: null, bodyText, sentSize: 0, givenSize: 0, fixedSize: 0 })
+
+async function outgoing(prepare: NonNullable<ForwarderOptions["prepare"]>, request: Request, givenText: string, mayCompact: boolean): Promise<Outgoing> {
+  try {
+    const given = JSON.parse(givenText) as Body
+    const result = await prepare(request, given, mayCompact)
+    const sentSize = sizeOf(result.body)
+    return {
+      note: result.note,
+      threadKey: result.threadKey,
+      bodyText: result.body !== given ? JSON.stringify(result.body, wellFormed) : givenText,
+      sentSize,
+      givenSize: result.body === given ? sentSize : sizeOf(given),
+      fixedSize: sizeOf({ ...result.body, messages: [] }),
+    }
+  } catch (error) {
+    return { ...passthrough(givenText), note: { action: "error-passthrough", error: String(error) } }
+  }
+}
+
+function createSender(request: Request, target: string, headers: Headers, timeout: number | null, stall: { count: number }) {
+  return async (body: string | undefined): Promise<Response> => {
+    if (timeout === null) return fetch(target, { method: request.method, headers, body })
+    for (;;) {
+      try {
+        return await fetch(target, { method: request.method, headers, body, signal: AbortSignal.timeout(timeout) })
+      } catch (error) {
+        const timedOut = error instanceof Error && error.name === "TimeoutError"
+        if (!timedOut || stall.count + 1 >= COUNT_TOKENS_ATTEMPTS) throw error
+        stall.count += 1
+      }
+    }
+  }
+}
+
+function delivered(answer: Response, out: Outgoing, metered: boolean, path: string, log: (entry: Record<string, unknown>) => void, store: ThreadStore): Response {
+  const { note, threadKey, sentSize, givenSize, fixedSize } = out
+  const response = new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers: forwardableHeaders(answer.headers) })
+  if (note.action === "pass" || !metered) {
+    if (note.action !== "pass" || Object.keys(note).length > 1) log({ path, status: answer.status, ...note })
+    return response
+  }
+  return watchUsage(response, (usage) => {
+    log({
+      path,
+      status: answer.status,
+      thread: threadKey,
+      ...note,
+      input: inputTokens(usage),
+      cacheRead: usage.cache_read_input_tokens ?? 0,
+      cacheWrite: usage.cache_creation_input_tokens ?? 0,
+      uncached: usage.input_tokens ?? 0,
+      charsIn: givenSize,
+      charsOut: sentSize,
+      charsFixed: fixedSize,
+    })
+    if (threadKey) recordUsage(store, threadKey, sentSize, usage)
+  })
+}
+
+export function createForwarder(options: ForwarderOptions): (request: Request) => Promise<Response> {
+  const upstream = options.upstream ?? "https://api.anthropic.com"
+  const prepare = options.prepare ?? defaultPrepare(options, upstream)
+  const timeout = options.countTokensTimeoutMs ?? 10_000
+
+  async function route(request: Request, began: number): Promise<Response> {
+    const stall = { count: 0 }
+    let prep = 0
+    let upload = 0
+    const log = (entry: Record<string, unknown>) => options.record?.({ ...entry, ms: Date.now() - began, prep, upload, ...(stall.count > 0 && { stalled: stall.count }) })
+    const url = new URL(request.url)
+    const headers = new Headers(request.headers)
+    for (const name of DROPPED_REQUEST_HEADERS) headers.delete(name)
+
+    let givenText: string | undefined
+    if (request.method !== "GET" && request.method !== "HEAD") givenText = await request.text()
+    upload = Date.now() - began
+    const isMessages = request.method === "POST" && url.pathname.startsWith("/v1/messages")
+    const isCountTokens = url.pathname.includes("count_tokens")
+
+    const build = () => (givenText && isMessages ? outgoing(prepare, request, givenText, !isCountTokens) : Promise.resolve(passthrough(givenText)))
+    const send = createSender(request, upstream + url.pathname + url.search, headers, isCountTokens ? timeout : null, stall)
+    let out = await build()
+    prep = Date.now() - began - upload
+    let answer = await send(out.bodyText)
+    const errorResponse = (text: string) => new Response(text, { status: answer.status, statusText: answer.statusText, headers: forwardableHeaders(answer.headers) })
+
+    if (answer.status >= 400 && out.note.action !== "pass") {
+      const errorText = await answer.text()
+      const logged = { path: url.pathname, status: answer.status, thread: out.threadKey, ...out.note }
+      const overflow = out.threadKey && !isCountTokens ? recordOverflow(options.store, out.threadKey, out.sentSize, errorText) : null
+      if (!overflow) {
+        log({ ...logged, error: clipped(errorText) })
+        return errorResponse(errorText)
+      }
+      log({ ...logged, overflow, error: clipped(errorText) })
+      out = await build()
+      out = { ...out, note: { ...out.note, healed: overflow } }
+      answer = await send(out.bodyText)
+      if (answer.status >= 400) {
+        const retryError = await answer.text()
+        log({ path: url.pathname, status: answer.status, thread: out.threadKey, ...out.note, error: clipped(retryError) })
+        return errorResponse(retryError)
+      }
+    }
+
+    return delivered(answer, out, isMessages && !isCountTokens, url.pathname, log, options.store)
+  }
+
+  return async (request) => {
+    const began = Date.now()
+    try {
+      return await route(request, began)
+    } catch (error) {
+      options.record?.({ path: new URL(request.url).pathname, status: 502, action: "upstream-unreachable", error: clipped(String(error)), ms: Date.now() - began })
+      return Response.json({ type: "error", error: { type: "api_error", message: `eunoe could not reach the API: ${String(error)}` } }, { status: 502 })
+    }
+  }
+}

package/src/{proxy → core}/handoff.ts

@@ -1,17 +1,13 @@
-import { statSync } from "node:fs"
-import { type Config, claudeConfigDirs } from "../config"
 import { blocks, type Message } from "../context/content"
 import { FOLD_CAP_CHARS, foldedView, sourceChunks } from "../context/fold"
 import { isPrompt } from "../context/fold/turns"
 import { handoffBlock } from "../context/prompts"
 import type { RecallChunk } from "../context/recall"
-import { findSessionByPrefix } from "../transcript/locate"
-import { sessionMessages } from "../transcript/messages"
 import { isInjected, messageFingerprint } from "./fingerprint"
-import { titleOf } from "./sessions"
+import type { ThreadSources } from "./rewrite"
 import type { Handoff, ThreadState } from "./state"
 
-const sourceCache = new Map<string, { mtime: number; chunks: RecallChunk[] }>()
+const chunksOf = new WeakMap<Message[], { label: string; chunks: RecallChunk[] }>()
 
 export const continueToken = (id: string) => `{ee:continue:${id}}`
 
@@ -28,17 +24,23 @@ export function activeHandoffs(handoffs: Record<string, Handoff | null> = {}): R
   return Object.fromEntries(Object.entries(handoffs).filter((entry): entry is [string, Handoff] => Boolean(entry[1])))
 }
 
-export function attachHandoffs(messages: Message[], config: Config, sessionId: string | null, state: ThreadState): boolean {
+function resolveHandoff(id: string, sources: ThreadSources, state: ThreadState): Handoff | null {
+  const found = sources.findHandoff?.(id) ?? null
+  if (!found || !sources.readHandoff) return null
+  const already = Object.values(state.handoffs ?? {}).some((h) => h?.source === found.source)
+  return already ? null : { label: found.label, source: found.source, text: foldedView(sources.readHandoff(found.source), FOLD_CAP_CHARS) }
+}
+
+export function attachHandoffs(messages: Message[], sources: ThreadSources, state: ThreadState): boolean {
   let changed = false
   for (const message of messages) {
     const id = continueIdOf(message)
     if (!id) continue
     const key = messageFingerprint(message)
     if (state.handoffs && key in state.handoffs) continue
+    const handoff = resolveHandoff(id, sources, state)
     state.handoffs ??= {}
-    const file = findSessionByPrefix(id, claudeConfigDirs(config), sessionId ?? undefined)
-    const already = Object.values(state.handoffs).some((h) => h?.source === file)
-    state.handoffs[key] = file && !already ? { label: titleOf(file) ?? id, source: file, text: foldedView(sessionMessages(file), FOLD_CAP_CHARS) } : null
+    state.handoffs[key] = handoff
     changed = true
   }
   return changed
@@ -53,19 +55,17 @@ export function withHandoffs(messages: Message[], handoffs: Record<string, Hando
   })
 }
 
-export function handoffChunks(handoffs: Record<string, Handoff>): RecallChunk[] {
-  const sources = new Map<string, string>()
-  for (const handoff of Object.values(handoffs)) if (!sources.has(handoff.source)) sources.set(handoff.source, handoff.label)
-  return [...sources].flatMap(([source, label]) => {
-    let mtime: number
-    try {
-      mtime = statSync(source).mtimeMs
-    } catch {
-      return []
-    }
-    const cached = sourceCache.get(source)
-    const chunks = cached?.mtime === mtime ? cached.chunks : sourceChunks(sessionMessages(source), label, true)
-    sourceCache.set(source, { mtime, chunks })
+export function handoffChunks(handoffs: Record<string, Handoff>, sources: ThreadSources): RecallChunk[] {
+  const read = sources.readHandoff
+  if (!read) return []
+  const labels = new Map<string, string>()
+  for (const handoff of Object.values(handoffs)) if (!labels.has(handoff.source)) labels.set(handoff.source, handoff.label)
+  return [...labels].flatMap(([source, label]) => {
+    const messages = read(source)
+    const known = chunksOf.get(messages)
+    if (known?.label === label) return known.chunks
+    const chunks = sourceChunks(messages, label, true)
+    chunksOf.set(messages, { label, chunks })
     return chunks
   })
 }

package/src/core/index.ts

@@ -0,0 +1,14 @@
+export type { Block, Body, Message } from "../context/content"
+export type { RecallChunk, Reranker } from "../context/recall"
+export { jevReranker } from "../context/recall/rerank"
+export type { StuckSizes } from "./compaction"
+export { CORE_DEFAULTS, type CoreConfig, type Mode } from "./config"
+export { type Folded, type FoldOptions, type FoldTarget, foldThread, pinTurns } from "./fold"
+export { claudeCodeSessionId, createForwarder, type ForwarderOptions, type ForwardNote, type Prepared } from "./forward"
+export { continueToken } from "./handoff"
+export { type Rewrite, type RewriteInput, type RewriteNote, rewrite, rewriteAsync, type ThreadSources, threadKeyOf } from "./rewrite"
+export { memoryStore, type ThreadState, type ThreadStore } from "./state"
+export { listSubagentRecall, type Subagent } from "./subagents"
+export { renderTranscriptFiles, type TranscriptOptions, transcriptGuide } from "./transcript"
+export { inputTokens, recordOverflow, recordUsage, type Usage, watchUsage } from "./usage"
+export { createWindowLookup, type WindowLookup } from "./window"

package/src/{proxy → core}/recall.ts

@@ -1,11 +1,10 @@
-import { type Body, blocks, resultText } from "../context/content"
+import { type Body, blocks, type Message, resultText } from "../context/content"
 import { livePrompt, type RecallChunk, type Reranker, recallChunks, recallFor, recallForWith, withRecall } from "../context/recall"
-import { sessionMessages } from "../transcript/messages"
-import { subagentChunks } from "../transcript/subagents"
 import { messageFingerprint } from "./fingerprint"
 import { activeHandoffs, handoffChunks } from "./handoff"
 import type { Rewrite, RewriteInput } from "./rewrite"
-import { readState, saveState } from "./state"
+
+const closingTurn: Message = { role: "user", content: "" }
 
 export const wantsRecall = (input: RewriteInput) => (input.config.eval?.recall ?? true) && input.config.mode !== "off"
 
@@ -13,31 +12,30 @@ export const activeRecalls = (recalls: Record<string, string> = {}) => Object.fr
 
 const touched = (input: RewriteInput, result: Rewrite) => result.threadKey !== null && !(result.body === input.body && result.note.action === "pass")
 
-function droppedChunks(input: RewriteInput, result: Rewrite): RecallChunk[] {
-  const transcript = input.transcript?.jsonl ?? null
+function droppedChunks(input: RewriteInput, result: Rewrite, threadKey: string): RecallChunk[] {
+  const sources = input.sources ?? {}
   const kept = new Map<string, string>()
   for (const message of result.body.messages) for (const b of blocks(message)) if (b.type === "tool_result") kept.set(b.tool_use_id, resultText(b))
   const own = recallChunks(input.body.messages, kept)
-  const session = own.length > 0 || !transcript ? own : recallChunks([...sessionMessages(transcript), { role: "user", content: "" }], kept)
-  const withSubagents = transcript ? [...session, ...subagentChunks(transcript)] : session
-  const handoffs = result.threadKey ? activeHandoffs(readState(result.threadKey).handoffs) : {}
-  return [...handoffChunks(handoffs), ...withSubagents]
+  const session = own.length > 0 || !sources.readHistory ? own : recallChunks([...sources.readHistory(), closingTurn], kept)
+  const withSubagents = sources.listSubagentChunks ? [...session, ...sources.listSubagentChunks()] : session
+  return [...handoffChunks(activeHandoffs(input.store.read(threadKey).handoffs), sources), ...withSubagents]
 }
 
-function recallTarget(original: Body, result: Rewrite): { key: string; text: string } | null {
+function recallTarget(original: Body): { key: string; text: string } | null {
   const live = livePrompt(original.messages)
-  return live && result.threadKey ? { key: messageFingerprint(original.messages[live.index]), text: live.text } : null
+  return live ? { key: messageFingerprint(original.messages[live.index]), text: live.text } : null
 }
 
 export function applyRecall(input: RewriteInput, result: Rewrite): Rewrite {
   if (!touched(input, result) || !result.threadKey) return result
-  const state = readState(result.threadKey)
+  const state = input.store.read(result.threadKey)
   state.recalls ??= {}
-  const target = recallTarget(input.body, result)
+  const target = recallTarget(input.body)
   let note = result.note
   if (target && !(target.key in state.recalls)) {
-    state.recalls[target.key] = recallFor(target.text, droppedChunks(input, result), input.config.eval?.recallOptions) ?? ""
-    saveState(result.threadKey, state)
+    state.recalls[target.key] = recallFor(target.text, droppedChunks(input, result, result.threadKey), input.config.eval?.recallOptions) ?? ""
+    input.store.save(result.threadKey, state)
     note = { ...note, recalled: state.recalls[target.key].length }
   }
   const messages = withRecall(result.body.messages, messageFingerprint, activeRecalls(state.recalls))
@@ -46,13 +44,13 @@ export function applyRecall(input: RewriteInput, result: Rewrite): Rewrite {
 
 export async function prefetchFor(input: RewriteInput, result: Rewrite, rerank: Reranker): Promise<number | null> {
   if (!touched(input, result) || !result.threadKey) return null
-  const target = recallTarget(input.body, result)
+  const target = recallTarget(input.body)
   if (!target) return null
-  const state = readState(result.threadKey)
+  const state = input.store.read(result.threadKey)
   state.recalls ??= {}
   if (target.key in state.recalls) return null
   const options = { candidates: input.config.eval?.rerank?.candidates, ...input.config.eval?.recallOptions }
-  state.recalls[target.key] = (await recallForWith(target.text, droppedChunks(input, result), rerank, options)) ?? ""
-  saveState(result.threadKey, state)
+  state.recalls[target.key] = (await recallForWith(target.text, droppedChunks(input, result, result.threadKey), rerank, options)) ?? ""
+  input.store.save(result.threadKey, state)
   return state.recalls[target.key].length
 }

package/src/core/rewrite.ts

@@ -0,0 +1,189 @@
+import type { Body, Message } from "../context/content"
+import { appendSystem, tailMessages, trimMessages } from "../context/fold/strategies"
+import { splitTurns, turnFingerprint } from "../context/fold/turns"
+import { SYSTEM_PROMPT, searchOnlyInstructions, trimInstructions } from "../context/prompts"
+import { identityReranker, type RecallChunk, type Reranker, withRecall } from "../context/recall"
+import { compact, type StuckSizes } from "./compaction"
+import type { CoreConfig } from "./config"
+import { DEFAULT_RATIO, estimator, sizeOf, targetSize } from "./estimate"
+import { messageFingerprint } from "./fingerprint"
+import { activeHandoffs, attachHandoffs, withHandoffs } from "./handoff"
+import { activeRecalls, applyRecall, prefetchFor, wantsRecall } from "./recall"
+import type { ThreadStore } from "./state"
+
+export interface ThreadSources {
+  guide?: string | null
+  transcriptDir?: string | null
+  readHistory?: () => Message[]
+  listSubagentChunks?: () => RecallChunk[]
+  findHandoff?: (id: string) => { label: string; source: string } | null
+  readHandoff?: (source: string) => Message[]
+}
+
+export interface RewriteInput {
+  body: Body
+  threadId: string | null
+  config: CoreConfig
+  store: ThreadStore
+  sources?: ThreadSources
+  window: number | null
+  mayCompact: boolean
+  omittedBefore?: number
+}
+
+export type RewriteNote = {
+  action: "pass" | "full" | "compact" | "guide" | "trim" | "tail"
+  compacted?: boolean
+  actions?: string[]
+  cutTurn?: number | null
+  omitted?: number
+  folded?: number
+  pinned?: number
+  host?: boolean
+  keep?: number
+  cleared?: number
+  stuck?: StuckSizes
+  turns?: number
+  keptTurns?: number
+  messagesIn?: number
+  messagesOut?: number
+  estimate?: number
+  window?: number | null
+  fit?: "recut" | "bare" | "over"
+  fitEstimate?: number
+  recalled?: number
+  handoff?: number
+  handoffFrom?: string
+}
+
+export interface Rewrite {
+  body: Body
+  threadKey: string | null
+  note: RewriteNote
+}
+
+const pass = (body: Body): Rewrite => ({ body, threadKey: null, note: { action: "pass" } })
+
+const isAgentThread = (body: Body) => Array.isArray(body.tools) && body.tools.length > 0
+
+const withSystemPrompt = (system: Body["system"], extra?: string | null) => appendSystem(extra ? appendSystem(system, extra) : system, SYSTEM_PROMPT)
+
+const ratioOf = (input: RewriteInput, threadKey: string) => input.store.read(threadKey).ratio ?? DEFAULT_RATIO
+
+export function threadKeyOf(threadId: string, messages: Message[]): string | null {
+  const first = splitTurns(messages).turns[0]
+  return first ? `${threadId}-${turnFingerprint(first)}` : null
+}
+
+function evalStrategy(input: RewriteInput, turns: Message[][], threadKey: string, guide: string | null): Rewrite | null {
+  const { body, config } = input
+  const strategy = config.eval?.strategy
+  if (strategy !== "guide" && strategy !== "trim" && strategy !== "tail") return null
+  if (!isAgentThread(body)) return pass(body)
+  const counts = { turns: turns.length, messagesIn: body.messages.length }
+  if (strategy === "guide") {
+    return { body: { ...body, system: withSystemPrompt(body.system, guide ? searchOnlyInstructions(guide) : null) }, threadKey, note: { action: "guide", ...counts } }
+  }
+  if (strategy === "trim") {
+    const messages = trimMessages(body.messages, { evidence: config.eval?.evidence ?? true })
+    return { body: { ...body, system: withSystemPrompt(body.system, trimInstructions(guide)), messages }, threadKey, note: { action: "trim", ...counts, messagesOut: messages.length } }
+  }
+  const based = { ...body, system: withSystemPrompt(body.system) }
+  const size = estimator(based, ratioOf(input, threadKey))
+  let from = 1
+  if (input.window) {
+    const target = targetSize(size, input.window)
+    from = turns.length - 1
+    while (from > 1 && size.of(tailMessages(body.messages, from - 1, guide)) <= target) from -= 1
+  }
+  const messages = tailMessages(body.messages, from, guide)
+  return { body: { ...based, messages }, threadKey, note: { action: "tail", keptTurns: turns.length - from, ...counts, messagesOut: messages.length, estimate: size.of(messages) } }
+}
+
+function strategize(input: RewriteInput): Rewrite {
+  const { body, threadId, config, store } = input
+  const sources = input.sources ?? {}
+  if (!threadId || !Array.isArray(body.messages) || body.messages.length === 0) return pass(body)
+  const threadKey = threadKeyOf(threadId, body.messages)
+  if (!threadKey) return pass(body)
+  const off = config.mode === "off"
+  const state = store.read(threadKey)
+  if (off && !state.host) return pass(body)
+  const { turns } = splitTurns(body.messages)
+  const guide = sources.guide ?? null
+  if (!off && attachHandoffs(body.messages, sources, state)) store.save(threadKey, state)
+
+  const forced = off ? null : evalStrategy(input, turns, threadKey, guide)
+  if (forced) return forced
+
+  const based = isAgentThread(body) ? { ...body, system: withSystemPrompt(body.system) } : body
+  if (body.messages.length < 2) return { body: based, threadKey, note: { action: "full", turns: turns.length } }
+  const handoffs = activeHandoffs(state.handoffs)
+  const recalls = wantsRecall(input) ? activeRecalls(state.recalls) : {}
+  const result = compact({
+    body: based,
+    config,
+    state,
+    window: input.window,
+    guide,
+    transcriptDir: sources.transcriptDir ?? null,
+    mayCompact: input.mayCompact && !off,
+    omittedBefore: input.omittedBefore,
+    decorate: (messages) => withRecall(withHandoffs(messages, handoffs), messageFingerprint, recalls),
+  })
+  if (result.stateChanged) store.save(threadKey, state)
+  return { body: result.messages === body.messages ? based : { ...based, messages: result.messages }, threadKey, note: result.note }
+}
+
+function withAttachedHandoffs(input: RewriteInput, result: Rewrite): Rewrite {
+  if (!result.threadKey) return result
+  const handoffs = activeHandoffs(input.store.read(result.threadKey).handoffs)
+  const messages = withHandoffs(result.body.messages, handoffs)
+  if (messages === result.body.messages) return result
+  const attached = Object.values(handoffs)
+  const note = { ...result.note, handoff: attached.reduce((sum, h) => sum + h.text.length, 0), handoffFrom: attached.map((h) => h.label).join(", ") }
+  return { ...result, body: { ...result.body, messages }, note }
+}
+
+function once(input: RewriteInput): Rewrite {
+  const result = withAttachedHandoffs(input, strategize(input))
+  return wantsRecall(input) ? applyRecall(input, result) : result
+}
+
+function sentEstimate(input: RewriteInput, result: Rewrite): number {
+  return Math.round(sizeOf(result.body) * (result.threadKey ? ratioOf(input, result.threadKey) : DEFAULT_RATIO))
+}
+
+function overLimit(input: RewriteInput, result: Rewrite): boolean {
+  if (!input.window || !result.threadKey || input.mayCompact === false || result.note.action === "pass") return false
+  return sentEstimate(input, result) > input.config.compactAt * input.window
+}
+
+function carried(from: Rewrite, to: Rewrite): Rewrite {
+  const actions = [...(from.note.actions ?? []), ...(to.note.actions ?? [])]
+  if (!from.note.compacted && actions.length === 0) return to
+  return { ...to, note: { ...to.note, compacted: Boolean(to.note.compacted || from.note.compacted), actions } }
+}
+
+export function rewrite(input: RewriteInput, before?: Rewrite): Rewrite {
+  const result = before ? carried(before, once(input)) : once(input)
+  if (!overLimit(input, result)) return result
+  const recut = carried(result, once(input))
+  if (!overLimit(input, recut)) return { ...recut, note: { ...recut.note, fit: "recut" } }
+  const bare = carried(recut, once({ ...input, config: { ...input.config, eval: { ...input.config.eval, recall: false } } }))
+  return { ...bare, note: { ...bare.note, fit: overLimit(input, bare) ? "over" : "bare", fitEstimate: sentEstimate(input, bare) } }
+}
+
+export async function prefetchRecall(input: RewriteInput, rerank: Reranker): Promise<{ reranked: boolean; rerankError: null; recalled: number } | null> {
+  if (!wantsRecall(input)) return null
+  const recalled = await prefetchFor(input, strategize(input), rerank)
+  return recalled === null ? null : { reranked: rerank !== identityReranker, rerankError: null, recalled }
+}
+
+export async function rewriteAsync(input: RewriteInput, rerank: Reranker = identityReranker): Promise<Rewrite> {
+  if (!wantsRecall(input) || rerank === identityReranker) return rewrite(input)
+  const first = strategize(input)
+  const recalled = await prefetchFor(input, first, rerank)
+  const final = rewrite(input, first)
+  return recalled === null ? final : { ...final, note: { ...final.note, recalled } }
+}

package/src/core/state.ts

@@ -0,0 +1,40 @@
+export interface Handoff {
+  label: string
+  source: string
+  text: string
+}
+
+export interface ThreadState {
+  handoffs?: Record<string, Handoff | null>
+  cut?: string
+  keep?: number
+  cleared?: number
+  stuck?: number
+  host?: boolean
+  pins?: string[]
+  ratio?: number
+  recalls?: Record<string, string>
+}
+
+export interface ThreadStore {
+  read: (key: string) => ThreadState
+  save: (key: string, state: ThreadState) => void
+}
+
+export function memoryStore(initial: Record<string, ThreadState> = {}): ThreadStore {
+  const threads = new Map(Object.entries(initial).map(([key, state]) => [key, structuredClone(state)]))
+  return {
+    read: (key) => structuredClone(threads.get(key) ?? {}),
+    save: (key, state) => {
+      threads.set(key, structuredClone(state))
+    },
+  }
+}
+
+export function resetCut(state: ThreadState) {
+  delete state.cut
+  delete state.keep
+  delete state.cleared
+  delete state.stuck
+  delete state.host
+}

package/src/core/subagents.ts

@@ -0,0 +1,28 @@
+import { blocks, type Message } from "../context/content"
+import { splitTurns } from "../context/fold/turns"
+import { type RecallChunk, recallChunks } from "../context/recall"
+
+export interface Subagent {
+  description: string
+  messages: Message[]
+  toolUseId?: string
+}
+
+const closingTurn: Message = { role: "user", content: "" }
+
+export function launchTurnOf(parentMessages: Message[], toolUseId: string | undefined): number {
+  if (!toolUseId) return 0
+  const index = splitTurns(parentMessages).turns.findIndex((turn) => turn.some((message) => message.role === "assistant" && blocks(message).some((b) => b.type === "tool_use" && b.id === toolUseId)))
+  return index + 1
+}
+
+const subagentLabel = (description: string) => `subagent "${description}"`
+
+export function subagentRecall(messages: Message[], description: string, parentTurn: number): RecallChunk[] {
+  const from = subagentLabel(description)
+  return recallChunks([...messages, closingTurn], new Map()).map((chunk) => ({ ...chunk, from, turn: parentTurn }))
+}
+
+export function listSubagentRecall(parentMessages: Message[], subagents: Subagent[]): RecallChunk[] {
+  return subagents.flatMap((subagent) => subagentRecall(subagent.messages, subagent.description, launchTurnOf(parentMessages, subagent.toolUseId)))
+}

package/src/core/transcript.ts

@@ -0,0 +1,44 @@
+import { blocks, type Message } from "../context/content"
+import { isPrompt } from "../context/fold/turns"
+import { searchGuide } from "../context/prompts"
+import { renderIndex, renderMarkdown, renderSubagentMarkdown, renderSubagentXml, renderXml, type SubagentRecord, subagentFile, turnFile } from "../transcript/format"
+import { parseTurns, type SessionEntry, type TranscriptFormat, type Turn } from "../transcript/parse"
+import { launchTurnOf, type Subagent } from "./subagents"
+
+export interface TranscriptOptions {
+  format?: TranscriptFormat
+  subagents?: Subagent[]
+}
+
+const isNote = (message: Message) => message.role === "user" && !isPrompt(message) && !blocks(message).some((b) => b.type === "tool_result")
+
+const turnsOf = (messages: Message[], sidechain: boolean | "any" = false): Turn[] =>
+  parseTurns(
+    messages.map((message): SessionEntry => ({ type: message.role, isMeta: isNote(message), message })),
+    sidechain,
+  )
+
+function subagentRecords(messages: Message[], turns: Turn[], subagents: Subagent[], format: TranscriptFormat): SubagentRecord[] {
+  const perTurn = new Map<number, number>()
+  return subagents.map((subagent) => {
+    const parentTurn = launchTurnOf(messages, subagent.toolUseId)
+    const k = (perTurn.get(parentTurn) ?? 0) + 1
+    perTurn.set(parentTurn, k)
+    const file = subagentFile(parentTurn, k, format)
+    const launcher = turns[parentTurn - 1]?.parts.find((part) => part.kind === "tool" && part.id === subagent.toolUseId)
+    if (launcher?.kind === "tool") launcher.record = file
+    return { run: { description: subagent.description }, turns: turnsOf(subagent.messages, "any"), parentTurn, file }
+  })
+}
+
+export function renderTranscriptFiles(messages: Message[], { format = "markdown", subagents = [] }: TranscriptOptions = {}): Record<string, string> {
+  const turns = turnsOf(messages)
+  const records = subagentRecords(messages, turns, subagents, format)
+  const files: Record<string, string> = {}
+  for (const turn of turns) files[turnFile(turn, format)] = format === "xml" ? renderXml(turn) : renderMarkdown(turn)
+  for (const record of records) files[record.file] = format === "xml" ? renderSubagentXml(record) : renderSubagentMarkdown(record)
+  files["index.md"] = renderIndex(turns, format, records)
+  return files
+}
+
+export const transcriptGuide = (dir: string, format: TranscriptFormat = "markdown") => searchGuide({ mode: format, dir, jsonl: "" })