headlesscode 1.0.2

package/src/engine/condense.ts

@@ -0,0 +1,512 @@
+/**
+ * Token-budget-aware context condensation — Phase 3 of the history-
+ * management plan (replaces the sliding-window placeholder's information
+ * loss; see `truncateHistory`'s doc comment in src/engine/loop.ts, which
+ * explicitly called this out as the future token-based pass).
+ *
+ * ─── What this does ──────────────────────────────────────────────────────────
+ *
+ * When the LAST request's real prompt-token count (from
+ * `LlmResponse.usage.promptTokens` — the same number that drives
+ * `BudgetTracker`/`totalInputTokens`) crosses a configurable fraction of the
+ * model's real context window, the oldest complete turns are summarized by an
+ * LLM into ONE compact synthetic `role: "user"` message, and the recent,
+ * uncompressed tail is kept verbatim after it. This is strictly better than
+ * `truncateHistory`'s drop-oldest eviction for genuinely long sessions: the
+ * stale turns are compressed instead of destroyed, so the model does not
+ * silently lose (and later re-derive at full cost) earlier file reads,
+ * command outputs, or decisions.
+ *
+ * ─── Why `role: "user"` for the synthetic message ───────────────────────────
+ *
+ * The condensed message replaces a chunk of assistant/tool/user turns, so it
+ * must be a role the API accepts after a `tool` message and before another
+ * assistant turn. `role: "user"` is the only one of the four roles that is
+ * always legal there: `system` is only legal as message[0], and `assistant`
+ * / `tool` would break the tool-call-group protocol (DeepSeek's official
+ * endpoint 400s on orphaned `tool` messages — see truncateHistory's 2026-08-01
+ * fix). A `user` message is exactly how other harnesses (including Zoo Code's
+ * own rollback/summary paths) inject synthetic context, and it lets the
+ * model's next turn respond to the summary as new instructions.
+ *
+ * ─── Stable prefix / prompt caching (constraint 5) ──────────────────────────
+ *
+ * The caller (HeadlessSession) REPLACES its working message state with the
+ * condensed array, and tracks a `condensedUpTo` marker (2 = nothing condensed
+ * yet; 3 = the summary now sits at index 2). Re-condensation is then gated on
+ * the UNCONDENSED TAIL having grown past `MIN_CONDENSE_TAIL_GROWTH` messages
+ * since the last pass — so the sent prefix ([system, firstUser, summary, ...
+ * recent tail]) stays byte-identical across many subsequent calls and only
+ * changes at a re-condensation point, exactly like `truncateHistory`'s fixed
+ * batch eviction (batch, don't reslice every call).
+ *
+ * ─── Failure contract (non-fatal, matches the repo idiom) ───────────────────
+ *
+ * The condensation LLM call is an auxiliary subsystem: if it fails (timeout,
+ * provider error, unusable summary), `maybeCondense` resolves to null and the
+ * caller falls back to `truncateHistory` for that call. It never fails or
+ * blocks the session. The ONE thing that is NOT non-fatal is cost accounting:
+ * a successful condensation call's usage is fed into the same BudgetTracker +
+ * running totals as the main session (constraint 2 of
+ * plans/context-condensation.md), and a BudgetExceededError from that
+ * accounting propagates so the session aborts exactly as if a main call had
+ * tripped the cap.
+ */
+
+import type { ChatMessage, LlmClient, LlmRequest, LlmResponse } from "./types.js"
+import type { Logger } from "./logger.js"
+
+/**
+ * Default fraction of the model's context window at which condensation
+ * triggers. 0.75 (75%) balances two failure modes:
+ *   - too LOW (e.g. 0.5): condensation fires on sessions that could have
+ *     finished comfortably inside the window, paying an LLM call + latency for
+ *     nothing (the whole point of keeping the sliding-window fallback);
+ *   - too HIGH (e.g. 0.95): the model's real usable context is smaller than
+ *     the advertised number (system prompt + tool schemas + the summary call's
+ *     own request + a long reasoning generation all compete for the same
+ *     window), so waiting that long risks a provider-side context-overflow
+ *     error on the very next request.
+ * 0.75 leaves a full quarter of the window as headroom for the next
+ * iteration's growth after condensation, which (combined with the
+ * batch-once-stable semantics above) keeps the condensed prefix stable across
+ * many subsequent calls instead of re-condensing every turn.
+ */
+export const DEFAULT_CONDENSE_THRESHOLD_FRACTION = 0.75
+
+/**
+ * Default fraction of the context window at which the ASYNC early-fire
+ * background condensation kicks off (plans/smart-condensation-async.md part
+ * 2). Must be BELOW the hard threshold fraction; at 0.6 vs a 0.75 hard
+ * threshold it leaves a 15-percentage-point runway for the 55-80s (measured)
+ * condensation call to resolve in the background while the main loop keeps
+ * making forward progress.
+ *
+ * PROVISIONAL: part 1's real per-iteration conversation-size data (the
+ * lastPromptTokens field added to the `[usage] running total` line) is what
+ * this number is supposed to be derived from — the conversation-size point
+ * where prompt-cache degradation becomes significant. That data requires a
+ * real long session, which is a later round's natural by-product; until it
+ * lands, 0.6 is a documented, TUNABLE interim value (--condense-early-fire),
+ * not a magic constant imported from anywhere. Re-derive it from fresh data
+ * before trusting it.
+ */
+export const DEFAULT_CONDENSE_EARLY_FIRE_FRACTION = 0.6
+
+/**
+ * Conservative default context window (tokens) when the real value cannot be
+ * resolved from OpenRouter's models endpoint AND no override is configured.
+ * Deliberately conservative (deepseek/deepseek-v4-flash's official endpoint
+ * is 1,048,576 per the pricing pin — see src/budget/cost.ts), because the
+ * real window is only ever used to decide WHEN to condense; a conservative
+ * number triggers condensation earlier than strictly necessary, which is the
+ * safe direction. The live value is fetched via OpenRouter's
+ * `/api/v1/models/<id>/endpoints` the same way the pricing table was
+ * verified (see `fetchModelContextWindow` in src/llm/openrouter.ts).
+ */
+export const DEFAULT_CONTEXT_WINDOW_TOKENS = 128_000
+
+/**
+ * Soft target cap on the condensed summary message, in characters. The model
+ * is asked to stay under this; the result is hard-truncated at
+ * `MAX_CONDENSED_MESSAGE_CHARS` regardless (a runaway summary must never
+ * blow the context budget this feature exists to protect).
+ */
+export const CONDENSE_TARGET_CHARS = 6_000
+
+/** Hard cap on what the condensation response is ALLOWED to become. */
+export const MAX_CONDENSED_MESSAGE_CHARS = 16_000
+
+/**
+ * Default cap on the condensation call's OUTPUT tokens. Always sent on the
+ * wire (`max_tokens`) so a runaway reasoning generation can't burn unbounded
+ * tokens and then get rejected anyway by the `MAX_CONDENSED_MESSAGE_CHARS`
+ * post-generation check. 4096 is well above the 6,000-char target summary
+ * (`CONDENSE_TARGET_CHARS`) for typical output while bounding the worst case.
+ */
+export const DEFAULT_CONDENSE_MAX_TOKENS = 4096
+
+/** Cap on the raw oldest-turn chunk fed to the condensation call. */
+export const MAX_CONDENSE_INPUT_CHARS = 200_000
+
+/**
+ * Minimum number of recent messages a condensation pass must LEAVE
+ * uncompressed. The model needs fresh context to continue; a summary alone is
+ * not enough. Also bounds how much a single pass can condense, which keeps
+ * re-condensation infrequent (the tail must re-grow past this before the next
+ * pass).
+ */
+export const MIN_KEPT_TAIL_MESSAGES = 10
+
+/**
+ * A re-condensation is only allowed once the uncompressed tail has grown by
+ * this many messages past the previous condensation point (in addition to
+ * re-crossing the token threshold). This is the "batch, don't reslice"
+ * stability guarantee: between re-condensation points the sent prefix is
+ * byte-identical across calls, so provider-side prompt caching can accrue.
+ */
+export const MIN_CONDENSE_TAIL_GROWTH = 2 * MIN_KEPT_TAIL_MESSAGES
+
+/** System prompt for the condensation LLM call. */
+export const CONDENSE_SYSTEM_PROMPT =
+	"You are a conversation-compression engine for a software engineering agent. You will be given the " +
+	"OLDEST part of an agent session transcript (the model's earlier tool calls + their results + its " +
+	"notes). Your job is to compress it into a compact summary the agent can read INSTEAD of the original " +
+	"turns. HARD RULES:\n" +
+	"1. Preserve what a coding agent needs to continue WITHOUT re-deriving: files read and what was in them " +
+	"(paths + key contents verbatim where short), commands run and their outputs/errors (error messages " +
+	"VERBATIM), decisions made and why, facts learned, and anything marked IMPORTANT. Losing this forces " +
+	"the agent to re-read/re-run at real cost.\n" +
+	"2. NEVER invent or add content. If something is a guess, say it is a guess. Do not add conclusions the " +
+	"transcript does not support.\n" +
+	"3. Omit pure mechanics (e.g. a successful trivial command whose exact output no longer matters) — " +
+	"prefer a one-line note over a long quote.\n" +
+	"4. Output ONLY the compressed summary. No preamble like 'Here is the summary', no meta-commentary, " +
+	"no advice."
+
+/** The synthetic message that stands in for the condensed chunk. */
+export function buildCondensedMessage(summary: string): ChatMessage {
+	return {
+		role: "user",
+		content: `[Condensed summary of the earlier part of this session — read this INSTEAD of the turns it replaces; it is a compression, not a quote.]\n\n${summary}`,
+	}
+}
+
+/**
+ * Build the user prompt for the condensation call: the oldest chunk, clearly
+ * delimited, with an explicit target size.
+ */
+export function buildCondenseUserPrompt(chunk: ChatMessage[], targetChars: number): string {
+	// Deliberately omit `reasoning` from the transcript: it is disposable (the
+	// model already spent its generation on it) and reading it only inflates
+	// this call's own input cost. estimateMessageChars still counts it for
+	// SIZING — the summarizer just doesn't need to read it.
+	const transcript = chunk
+		.map((m) => {
+			const head =
+				m.role === "tool"
+					? `[tool result for ${m.name ?? "tool"}]`
+					: m.role === "assistant" && m.tool_calls
+						? `[assistant tool_calls: ${m.tool_calls.map((c) => c.function?.name ?? "?").join(", ")}]`
+						: `[${m.role}]`
+			const body =
+				typeof m.content === "string" && m.content.trim() !== ""
+					? m.content
+					: m.tool_calls
+						? m.tool_calls
+								.map((c) => `${c.function?.name ?? "?"}: ${(c.function?.arguments ?? "").slice(0, 400)}`)
+								.join("\n")
+						: "(no text)"
+			return `${head}\n${body}`
+		})
+		.join("\n\n")
+
+	return (
+		`Compress the OLDEST part of this agent session transcript (${chunk.length} messages). ` +
+		`Produce a summary of roughly ${targetChars} characters or fewer — enough that the agent can continue ` +
+		`without re-reading or re-running what is summarized. Keep error messages and important file/command ` +
+		`details verbatim.\n\n` +
+		`=== TRANSCRIPT BEGIN ===\n${transcript}\n=== TRANSCRIPT END ===`
+	)
+}
+
+/**
+ * Choose how many messages to condense from the front of `messages` (from
+ * `startIndex` onward — the caller passes 2 for a fresh condensation, which
+ * folds the existing summary at index 2 back in on re-condensation).
+ *
+ * `wantTokens` is the number of tokens the condensed chunk is allowed to have
+ * occupied before compression (derived from the context budget);
+ * `conservativeCharsPerToken` is a deliberate over-estimate (a condensation
+ * that frees TOO LITTLE is harmless — the next iteration simply re-checks;
+ * one that frees TOO MUCH would drop the tool-group boundary invariants).
+ *
+ * The boundary lands on a clean turn boundary: the returned count never
+ * splits an assistant `tool_calls` message from its `tool` response messages
+ * (the 2026-08-01 DeepSeek HTTP 400 class of bug — see truncateHistory's doc
+ * comment). Sharing this helper with `truncateHistory` (via
+ * `computeEvictCount`/`skipOrphanedToolMessages`) means both the message-count
+ * fallback and the token-aware path enforce the SAME invariant from ONE
+ * implementation family.
+ */
+export function computeCondenseCount(
+	messages: ChatMessage[],
+	wantTokens: number,
+	conservativeCharsPerToken = 8,
+	startIndex = 2,
+): number {
+	if (messages.length < 4) {
+		return 0
+	}
+	const budgetChars = Math.max(1, wantTokens) * conservativeCharsPerToken
+	// Never condense the most recent `MIN_KEPT_TAIL_MESSAGES` messages (but
+	// allow a tiny history to be condensed down to zero tail — the summary is
+	// still strictly better than eviction).
+	const keepTail = Math.min(MIN_KEPT_TAIL_MESSAGES, Math.max(0, messages.length - 4))
+	const maxCount = Math.max(2, messages.length - startIndex - keepTail)
+	let count = 0
+	let chars = 0
+	for (let i = startIndex; i < messages.length && count < maxCount; i++) {
+		const m = messages[i]
+		const mChars = estimateMessageChars(m)
+		if (count > 0 && chars + mChars > budgetChars) {
+			break
+		}
+		count++
+		chars += mChars
+		if (m.role === "assistant" && m.tool_calls && m.tool_calls.length > 0) {
+			// Pull the whole tool group (the assistant call + its `tool`
+			// responses) into the chunk — never stop mid-group, even if that
+			// means the tail ends up a little smaller than keepTail.
+			let j = i + 1
+			while (j < messages.length && messages[j].role === "tool") {
+				count++
+				chars += estimateMessageChars(messages[j])
+				j++
+			}
+			i = j - 1
+		}
+	}
+	return count
+}
+
+/**
+ * Shared token-budget math for BOTH condensation paths: how many tokens the
+ * next request should target after condensation (half the hard threshold —
+ * enough that we don't re-cross it every single call) and how many oldest
+ * messages that corresponds to condensing (tool-call-group-safe, via
+ * `computeCondenseCount`). The synchronous path (`maybeCondense`) and the
+ * async early-fire path (HeadlessSession.fireBackgroundCondense) derive the
+ * SAME boundary from the SAME helper — never two independent implementations
+ * of the boundary rule.
+ */
+export function computeCondensePlan(
+	messages: ChatMessage[],
+	lastPromptTokens: number,
+	contextWindowTokens: number,
+	thresholdFraction: number,
+): { targetTokens: number; wantTokens: number; count: number } {
+	const targetTokens = Math.max(1, Math.floor(contextWindowTokens * thresholdFraction * 0.5))
+	const wantTokens = Math.max(1, lastPromptTokens - targetTokens)
+	const count = computeCondenseCount(messages, wantTokens)
+	return { targetTokens, wantTokens, count }
+}
+
+/**
+ * Shared tool-call-group-safe count computation for `truncateHistory`'s
+ * message-count eviction: how many messages to drop from index 2 onward
+ * (returned as a COUNT to drop, so the caller keeps system+firstUser).
+ *
+ * `evictCount` here means "drop this many of `rest`" — i.e. the kept tail
+ * starts at `rest.slice(evictCount)` — matching the existing
+ * `truncateHistory` contract exactly. The batch rounding (ceil to the next
+ * multiple of `batchSize`) is what keeps the sent prefix stable between
+ * eviction points.
+ */
+export function computeEvictCount(restLength: number, windowSize: number, batchSize: number): number {
+	const overflow = restLength - (windowSize - 2)
+	let evictCount = Math.ceil(overflow / batchSize) * batchSize
+	if (evictCount <= 0) {
+		evictCount = 0
+	}
+	return evictCount
+}
+
+/** Skip forward over leading `tool` messages (post-cut tail-start safety). */
+export function skipOrphanedToolMessages(messages: ChatMessage[], from: number): number {
+	let idx = from
+	while (idx < messages.length && messages[idx].role === "tool") {
+		idx++
+	}
+	return idx
+}
+
+/** Rough character-length estimate of one message (cheap, monotonic). */
+export function estimateMessageChars(m: ChatMessage): number {
+	let chars = typeof m.content === "string" ? m.content.length : 0
+	// Reasoning is echoed onto outgoing history and costs real prompt tokens —
+	// count it or sizing under-estimates reasoning-heavy sessions.
+	chars += m.reasoning?.length ?? 0
+	if (m.tool_calls) {
+		for (const c of m.tool_calls) {
+			chars += (c.function?.name?.length ?? 0) + (c.function?.arguments?.length ?? 0) + 8
+		}
+	}
+	return chars + 4
+}
+
+/**
+ * Run one condensation LLM call against `llmClient` (the session's client —
+ * same endpoint/auth, possibly a cheaper model id; see `condenseModel` in
+ * loop.ts). Returns the summary text. Throws on ANY failure — the caller
+ * (`maybeCondense`) catches and falls back to `truncateHistory`.
+ *
+ * The returned usage is surfaced via the `onUsage` callback so the session
+ * can feed it into the SAME BudgetTracker + running totals as the main
+ * session (constraint 2 — condensation must never be invisible spend).
+ */
+export async function condenseOldestTurns(
+	llmClient: LlmClient,
+	options: {
+		messages: ChatMessage[]
+		count: number
+		model: string
+		maxTokens?: number
+		signal?: AbortSignal
+		onUsage?: (usage: NonNullable<LlmResponse["usage"]>) => void
+	},
+): Promise<string> {
+	const chunk = options.messages.slice(2, 2 + options.count)
+	const request: LlmRequest = {
+		model: options.model,
+		messages: [
+			{ role: "system", content: CONDENSE_SYSTEM_PROMPT },
+			{ role: "user", content: buildCondenseUserPrompt(chunk, CONDENSE_TARGET_CHARS) },
+		],
+		maxTokens: options.maxTokens,
+		signal: options.signal,
+	}
+	const response = await llmClient.createChatCompletion(request)
+	if (response.usage) {
+		options.onUsage?.(response.usage)
+	}
+	const text = response.message.content
+	if (typeof text !== "string" || text.trim() === "") {
+		throw new Error("condensation returned an empty message content")
+	}
+	const trimmed = text.trim()
+	if (trimmed.length > MAX_CONDENSED_MESSAGE_CHARS) {
+		throw new Error(
+			`condensation produced ${trimmed.length} chars (cap ${MAX_CONDENSED_MESSAGE_CHARS}) — falling back to message-count truncation`,
+		)
+	}
+	return trimmed
+}
+
+/**
+ * Non-fatal wrapper used by HeadlessSession: decide whether to condense and
+ * do it. Returns the REPLACEMENT messages array (the oldest chunk replaced by
+ * one synthetic summary at index 2) when condensation ran; null when it did
+ * not run (below threshold, prefix still stable, or the call failed and the
+ * fallback path should apply).
+ *
+ * The caller MUST replace its working state with the returned array and keep
+ * `condensedUpTo.value` (mutated here) so the next call sees the already-
+ * condensed prefix. `condenseInFlight.value` is mutated to true while the LLM
+ * call is running and reset to false when it completes/fails — it guarantees
+ * only one condensation call is ever in flight.
+ */
+export async function maybeCondense(options: {
+	llmClient: LlmClient
+	logger: Pick<Logger, "info" | "warn">
+	messages: ChatMessage[]
+	model: string
+	lastPromptTokens: number
+	contextWindowTokens: number
+	thresholdFraction: number
+	condensedUpTo: { value: number }
+	condenseInFlight: { value: boolean }
+	condenseModel: string
+	condenseMaxTokens?: number
+	condenseAbortSignal?: AbortSignal
+	onUsage?: (usage: NonNullable<LlmResponse["usage"]>) => void
+}): Promise<ChatMessage[] | null> {
+	const {
+		llmClient,
+		logger,
+		messages,
+		lastPromptTokens,
+		contextWindowTokens,
+		thresholdFraction,
+		condensedUpTo,
+		condenseInFlight,
+		condenseModel,
+		condenseMaxTokens,
+		condenseAbortSignal,
+		onUsage,
+	} = options
+
+	// A failed/stale last request has no usable token count — never condense
+	// on guesswork.
+	if (!(lastPromptTokens > 0)) {
+		return null
+	}
+	const threshold = Math.max(1, contextWindowTokens * thresholdFraction)
+	if (lastPromptTokens < threshold) {
+		return null
+	}
+	// Prefix stability: after a condensation, the summary sits at index 2 and
+	// the tail must GROW meaningfully past it before we re-condense (otherwise
+	// the sent prefix would be rewritten on every call, defeating provider-
+	// side prompt caching — constraint 5). The FIRST condensation is exempt
+	// (there is no prefix to preserve yet).
+	const alreadyCondensed = condensedUpTo.value > 2
+	if (alreadyCondensed && messages.length - condensedUpTo.value < MIN_CONDENSE_TAIL_GROWTH) {
+		return null
+	}
+	if (condenseInFlight.value) {
+		return null
+	}
+	condenseInFlight.value = true
+	try {
+		// Condense enough that the next request lands comfortably below the
+		// threshold (target = half the threshold), so we don't re-cross it
+		// every single call. MIN_KEPT_TAIL_MESSAGES in computeCondenseCount
+		// keeps the recent tail verbatim regardless. Same shared math as the
+		// async early-fire path (computeCondensePlan).
+		const { count } = computeCondensePlan(messages, lastPromptTokens, contextWindowTokens, thresholdFraction)
+		if (count < 2) {
+			return null
+		}
+		logger.info("[condense] crossing token threshold — summarizing oldest turns", {
+			lastPromptTokens,
+			contextWindowTokens,
+			threshold: Math.round(threshold),
+			count,
+			condenseModel,
+		})
+		let summary: string
+		try {
+			summary = await condenseOldestTurns(llmClient, {
+				messages,
+				count,
+				// condenseModel (NOT model): the whole point of the `_condensation`
+				// mode-models key / --condense-model flag is that this call may use
+				// a cheaper model than the session's — and recordCondensationUsage
+				// already accounts its cost under condenseModel. Routing the call
+				// to `model` silently ignored the flag (call + accounting disagreed).
+				model: condenseModel,
+				maxTokens: condenseMaxTokens,
+				signal: condenseAbortSignal,
+				onUsage,
+			})
+		} catch (error) {
+			// Non-fatal (matches the repo's auxiliary-subsystem idiom): a
+			// failed condensation call falls back to truncateHistory for this
+			// call. The ONE exception is a BudgetExceededError thrown by
+			// onUsage's accounting (recordCondensationUsage in loop.ts) — that
+			// must propagate so the session aborts exactly as if a main call
+			// had tripped the cap, never silently under-report spend.
+			if (error instanceof Error && error.name === "BudgetExceededError") {
+				throw error
+			}
+			logger.warn("[condense] condensation call failed (non-fatal; falling back to message-count truncation)", {
+				error: error instanceof Error ? error.message : String(error),
+			})
+			return null
+		}
+		// The summary always lands at index 2 (right after system+firstUser);
+		// on re-condensation it FOLDS the previous summary back in, so there
+		// is never more than one summary message in the array.
+		condensedUpTo.value = 3
+		const condensed: ChatMessage[] = [messages[0], messages[1], buildCondensedMessage(summary), ...messages.slice(2 + count)]
+		logger.info("[condense] oldest turns condensed into one summary message", {
+			condensedCount: count,
+			historyBefore: messages.length,
+			historyAfter: condensed.length,
+		})
+		return condensed
+	} finally {
+		condenseInFlight.value = false
+	}
+}