@namzu/sdk 30.2.0 → 31.1.0

package/src/compaction/dangling.ts

@@ -1,4 +1,5 @@
-import type { Message } from '../types/message/index.js'
+import { NamzuError } from '../types/errors/index.js'
+import type { AssistantMessage, Message, ToolCall, ToolMessage } from '../types/message/index.js'
 
 /**
  * Represents the result of scanning messages for dangling tool call/result pairs.
@@ -68,54 +69,73 @@ function isToolMessage(message: Message): boolean {
  * // result.assistantsWithUnmatchedCalls = [1] (index 1 has unmatched tool call)
  * ```
  */
-export function findDanglingMessages(messages: Message[]): DanglingResult {
+export function findDanglingMessages(messages: readonly Message[]): DanglingResult {
 	const assistantsWithUnmatchedCalls: number[] = []
 	const orphanedToolMessages: number[] = []
+	const seenToolCallIds = new Set<string>()
+
+	// Provider tool results are not joins over a conversation-wide id map.
+	// They form one contiguous batch immediately after the assistant turn that
+	// declared them. A future call cannot own an earlier result, and a result
+	// displaced past a user/assistant/system message cannot answer backwards.
+	let index = 0
+	while (index < messages.length) {
+		const message = messages[index]
+		if (!message) {
+			index++
+			continue
+		}
 
-	// Build a set of all tool call IDs that exist in assistant messages
-	// along with their coverage map (which tool messages satisfy them)
-	const toolCallIds = new Map<string, { assistantIndex: number; satisfied: boolean }>()
+		if (!hasToolCalls(message)) {
+			if (isToolMessage(message)) orphanedToolMessages.push(index)
+			index++
+			continue
+		}
 
-	for (let i = 0; i < messages.length; i++) {
-		const message = messages[i]
-		if (!message) continue
+		const calls = (message as AssistantMessage).toolCalls ?? []
+		const callIds = new Set<string>()
+		let invalidOwner = false
+		for (const call of calls) {
+			if (!call.id || callIds.has(call.id) || seenToolCallIds.has(call.id)) invalidOwner = true
+			callIds.add(call.id)
+			seenToolCallIds.add(call.id)
+		}
 
-		if (hasToolCalls(message)) {
-			// Record all tool calls from this assistant message
-			const assistantMsg = message as { toolCalls?: Array<{ id: string }> }
-			if (assistantMsg.toolCalls) {
-				for (const toolCall of assistantMsg.toolCalls) {
-					toolCallIds.set(toolCall.id, { assistantIndex: i, satisfied: false })
-				}
+		let resultEnd = index + 1
+		while (resultEnd < messages.length && messages[resultEnd]?.role === CONSTANTS.TOOL_ROLE) {
+			resultEnd++
+		}
+
+		// Keep the last immediate result for an id. A late real result can
+		// follow a synthetic cancellation result after a crash; keeping the
+		// first would preserve the stale guess and discard the observed fact.
+		const lastResultById = new Map<string, number>()
+		for (let resultIndex = index + 1; resultIndex < resultEnd; resultIndex++) {
+			const result = messages[resultIndex]
+			if (result?.role === CONSTANTS.TOOL_ROLE) {
+				lastResultById.set(result.toolCallId, resultIndex)
 			}
 		}
-	}
 
-	// Second pass: mark satisfied tool calls and find orphaned tool messages
-	for (let i = 0; i < messages.length; i++) {
-		const message = messages[i]
-		if (!message) continue
-
-		if (isToolMessage(message)) {
-			const toolMsg = message as { toolCallId: string }
-			if (toolCallIds.has(toolMsg.toolCallId)) {
-				// Tool message satisfies a preceding tool call
-				const entry = toolCallIds.get(toolMsg.toolCallId)
-				if (entry) {
-					entry.satisfied = true
-				}
-			} else {
-				// Tool message has no matching tool call
-				orphanedToolMessages.push(i)
+		const answered = new Set<string>()
+		for (let resultIndex = index + 1; resultIndex < resultEnd; resultIndex++) {
+			const result = messages[resultIndex]
+			if (result?.role !== CONSTANTS.TOOL_ROLE) continue
+			if (
+				invalidOwner ||
+				!callIds.has(result.toolCallId) ||
+				lastResultById.get(result.toolCallId) !== resultIndex
+			) {
+				orphanedToolMessages.push(resultIndex)
+				continue
 			}
+			answered.add(result.toolCallId)
 		}
-	}
 
-	// Third pass: identify unsatisfied tool calls
-	for (const entry of toolCallIds.values()) {
-		if (!entry.satisfied) {
-			assistantsWithUnmatchedCalls.push(entry.assistantIndex)
+		if (invalidOwner || calls.some((call) => !answered.has(call.id))) {
+			assistantsWithUnmatchedCalls.push(index)
 		}
+		index = resultEnd
 	}
 
 	return {
@@ -152,7 +172,7 @@ export function findDanglingMessages(messages: Message[]): DanglingResult {
  * // Result: [{ role: 'user', content: 'test' }, { role: 'user', content: 'next' }]
  * ```
  */
-export function removeDanglingMessages(messages: Message[]): Message[] {
+export function removeDanglingMessages(messages: readonly Message[]): Message[] {
 	const result = findDanglingMessages(messages)
 
 	if (result.isValid) {
@@ -203,6 +223,151 @@ export function removeDanglingMessages(messages: Message[]): Message[] {
 	return messages.filter((_, idx) => !indicesToRemove.has(idx))
 }
 
+/** Counts describing a provider-valid tool-history repair. */
+export interface ToolHistoryRepairReport {
+	/** Earlier duplicates in an immediate result batch; the last result wins. */
+	readonly duplicateToolResultsRemoved: number
+	/** Results with no immediately preceding owner call. */
+	readonly orphanedToolResultsRemoved: number
+	/** Error results inserted for calls whose durable outcome is unavailable. */
+	readonly syntheticToolResultsInserted: number
+}
+
+/** A repaired copy and the exact changes made to it. */
+export interface ToolHistoryRepairResult {
+	readonly messages: Message[]
+	readonly report: ToolHistoryRepairReport
+}
+
+/** Whether a repair changed the provider-bound history. */
+export function toolHistoryRepairChanged(report: ToolHistoryRepairReport): boolean {
+	return (
+		report.duplicateToolResultsRemoved > 0 ||
+		report.orphanedToolResultsRemoved > 0 ||
+		report.syntheticToolResultsInserted > 0
+	)
+}
+
+function validateToolCallIds(messages: readonly Message[]): void {
+	const seen = new Set<string>()
+	for (let messageIndex = 0; messageIndex < messages.length; messageIndex++) {
+		const message = messages[messageIndex]
+		if (message?.role !== CONSTANTS.ASSISTANT_ROLE) continue
+		for (let callIndex = 0; callIndex < (message.toolCalls?.length ?? 0); callIndex++) {
+			const call = message.toolCalls?.[callIndex]
+			if (!call?.id) {
+				throw new NamzuError({
+					code: 'invalid_config',
+					message: `Message history contains an empty tool-call id at messages[${messageIndex}].toolCalls[${callIndex}].`,
+					details: { messageIndex, callIndex, toolCallId: call?.id ?? '' },
+				})
+			}
+			if (seen.has(call.id)) {
+				throw new NamzuError({
+					code: 'invalid_config',
+					message: `Message history repeats tool-call id '${call.id}' at messages[${messageIndex}].toolCalls[${callIndex}]; a signed assistant turn cannot be rewritten safely.`,
+					details: { messageIndex, callIndex, toolCallId: call.id },
+				})
+			}
+			seen.add(call.id)
+		}
+	}
+}
+
+function unknownOutcomeResult(call: ToolCall, assistant: AssistantMessage): ToolMessage {
+	return {
+		role: CONSTANTS.TOOL_ROLE,
+		toolCallId: call.id,
+		isError: true,
+		content: `Tool execution was interrupted and no durable result is available for \`${call.function.name}\`. Its outcome is unknown. Retry only if the tool is read-only or idempotent; otherwise verify external state or ask the user before retrying.`,
+		...(assistant.timestamp !== undefined ? { timestamp: assistant.timestamp } : {}),
+	}
+}
+
+/**
+ * Repair provider tool-pairing violations without mutating the durable input.
+ *
+ * Results are valid only in the contiguous run immediately after their
+ * assistant call. Orphaned/displaced results are removed, earlier immediate
+ * duplicates are removed in favour of the last result, and every unanswered
+ * call receives a conservative error result in call order. Duplicate call ids
+ * fail closed: changing ids or tool calls would invalidate opaque native replay
+ * state carried by the assistant message.
+ */
+export function repairToolMessageHistory(messages: readonly Message[]): ToolHistoryRepairResult {
+	validateToolCallIds(messages)
+
+	const repaired: Message[] = []
+	let duplicateToolResultsRemoved = 0
+	let orphanedToolResultsRemoved = 0
+	let syntheticToolResultsInserted = 0
+	let index = 0
+
+	while (index < messages.length) {
+		const message = messages[index]
+		if (!message) {
+			index++
+			continue
+		}
+
+		if (!hasToolCalls(message)) {
+			if (isToolMessage(message)) orphanedToolResultsRemoved++
+			else repaired.push(message)
+			index++
+			continue
+		}
+
+		const assistant = message as AssistantMessage
+		const calls = assistant.toolCalls ?? []
+		const callIds = new Set(calls.map((call) => call.id))
+		repaired.push(assistant)
+
+		let resultEnd = index + 1
+		while (resultEnd < messages.length && messages[resultEnd]?.role === CONSTANTS.TOOL_ROLE) {
+			resultEnd++
+		}
+		const lastResultById = new Map<string, number>()
+		for (let resultIndex = index + 1; resultIndex < resultEnd; resultIndex++) {
+			const result = messages[resultIndex]
+			if (result?.role === CONSTANTS.TOOL_ROLE) {
+				lastResultById.set(result.toolCallId, resultIndex)
+			}
+		}
+
+		const answered = new Set<string>()
+		for (let resultIndex = index + 1; resultIndex < resultEnd; resultIndex++) {
+			const result = messages[resultIndex]
+			if (result?.role !== CONSTANTS.TOOL_ROLE) continue
+			if (lastResultById.get(result.toolCallId) !== resultIndex) {
+				duplicateToolResultsRemoved++
+				continue
+			}
+			if (!callIds.has(result.toolCallId)) {
+				orphanedToolResultsRemoved++
+				continue
+			}
+			repaired.push(result)
+			answered.add(result.toolCallId)
+		}
+
+		for (const call of calls) {
+			if (answered.has(call.id)) continue
+			repaired.push(unknownOutcomeResult(call, assistant))
+			syntheticToolResultsInserted++
+		}
+		index = resultEnd
+	}
+
+	return {
+		messages: repaired,
+		report: {
+			duplicateToolResultsRemoved,
+			orphanedToolResultsRemoved,
+			syntheticToolResultsInserted,
+		},
+	}
+}
+
 /**
  * Finds a safe index for trimming messages while preserving tool call/result atomicity.
  *

package/src/compaction/index.ts

@@ -7,7 +7,11 @@ export type {
 	CompactionStrategy,
 } from './types.js'
 
-export type { DanglingResult } from './dangling.js'
+export type {
+	DanglingResult,
+	ToolHistoryRepairReport,
+	ToolHistoryRepairResult,
+} from './dangling.js'
 
 export type { ConversationManager } from './interface.js'
 
@@ -31,11 +35,14 @@ export {
 } from './extractor.js'
 
 export { buildVerifiedSummary } from './verifier.js'
+export type { CompactionVerificationOptions } from './verifier.js'
 
 export {
 	findDanglingMessages,
-	removeDanglingMessages,
 	findSafeTrimIndex,
+	removeDanglingMessages,
+	repairToolMessageHistory,
+	toolHistoryRepairChanged,
 } from './dangling.js'
 
 export { findRetainedIndices } from './retention.js'

package/src/compaction/manual.ts

@@ -1,13 +1,24 @@
 import type { CompactionConfig } from '../config/runtime.js'
+import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
+import { resolveStreamIdleTimeoutMs } from '../provider/idle-timeout.js'
+import { type TokenUsage, accumulateTokenUsage } from '../types/common/index.js'
 import { NamzuError } from '../types/errors/index.js'
+import { toolResultToText } from '../types/message/content.js'
 import type { Message } from '../types/message/index.js'
 import type { LLMProvider } from '../types/provider/index.js'
 import { resolveContextWindow } from './context-window.js'
 import { findDanglingMessages, findSafeTrimIndex } from './dangling.js'
+import {
+	extractFromAssistantMessage,
+	extractFromToolCall,
+	extractFromToolResult,
+	extractFromUserMessage,
+} from './extractor.js'
 import { WorkingStateManager } from './manager.js'
 import { planCompaction } from './plan.js'
+import { findRetainedIndices } from './retention.js'
 import { buildCompactionMessage, isCompactionMessage } from './summary.js'
-import { buildVerifiedSummary } from './verifier.js'
+import { type CompactionVerificationOptions, buildVerifiedSummary } from './verifier.js'
 
 /**
  * Compaction a host can ask for, rather than one that only happens to it.
@@ -30,9 +41,17 @@ export interface CompactionResult {
 	readonly shed: number
 	/** The summary that replaced them, as it appears in `messages`. */
 	readonly summary: Message
+	/**
+	 * Tokens spent by this host-triggered pass's optional verifier call.
+	 *
+	 * A zero record means no verifier model call ran. The manual path has no
+	 * `RunManager` to account for side-channel usage, so returning it is the
+	 * only way a host can include that real provider work in its own ledger.
+	 */
+	readonly usage: TokenUsage
 }
 
-export interface CompactNowInput {
+export interface CompactNowInput extends CompactionVerificationOptions {
 	readonly messages: readonly Message[]
 	readonly config: CompactionConfig
 	readonly provider: LLMProvider
@@ -40,20 +59,72 @@ export interface CompactNowInput {
 	readonly contextWindowTokens?: number
 }
 
+function admitManualCompaction(input: CompactionVerificationOptions): void {
+	input.signal?.throwIfAborted()
+	// Validate at the public boundary even when the history is too short to
+	// call the verifier. A malformed liveness policy is not a successful no-op.
+	resolveStreamIdleTimeoutMs(input.streamIdleTimeoutMs)
+}
+
 /** Assembles the new history from a plan's partition plus its summary. */
+function preservedSystemFloor(systemMessages: readonly Message[]): Message[] {
+	// A replaceable in-run summary may be superseded. A pinned summary may not:
+	// `retain` is the public promise that compaction leaves the message alone,
+	// and a prior manual summary is opaque state rather than redundant prose.
+	return systemMessages.filter(
+		(m) =>
+			!isCompactionMessage(typeof m.content === 'string' ? m.content : null) || m.retain === true,
+	)
+}
+
 function splice(
-	systemMessages: readonly Message[],
+	preservedSystem: readonly Message[],
 	summaryBody: string,
+	retainedOlder: readonly Message[],
 	recentMessages: readonly Message[],
 ): { messages: Message[]; summary: Message } {
-	const summary = buildCompactionMessage(summaryBody)
-	// Any PRIOR summary is dropped: the state a summary is built from is
-	// cumulative, so a new one supersedes it. Without this the never-trimmed
-	// floor accumulates one redundant block per pass, unbounded.
-	const preserved = systemMessages.filter(
-		(m) => !isCompactionMessage(typeof m.content === 'string' ? m.content : null),
-	)
-	return { messages: [...preserved, summary, ...recentMessages], summary }
+	// A host-triggered pass has no run-scoped WorkingStateManager to carry the
+	// summary into a later query. Pin this summary itself: until a future run
+	// has rebuilt equivalent state, this message is the only surviving record
+	// of what the pass removed.
+	const summary = { ...buildCompactionMessage(summaryBody), retain: true }
+	return { messages: [...preservedSystem, summary, ...retainedOlder, ...recentMessages], summary }
+}
+
+/** Build the state a host-triggered pass is about to replace. */
+function populateWorkingState(
+	manager: WorkingStateManager,
+	messages: readonly Message[],
+	config: CompactionConfig,
+): void {
+	let firstUser = true
+	const toolNames = new Map<string, string>()
+
+	for (const message of messages) {
+		switch (message.role) {
+			case 'user':
+				extractFromUserMessage(manager, message.content, firstUser)
+				firstUser = false
+				break
+			case 'assistant':
+				if (message.content) extractFromAssistantMessage(manager, message.content, config)
+				for (const call of message.toolCalls ?? []) {
+					toolNames.set(call.id, call.function.name)
+					extractFromToolCall(manager, call.function.name, call.function.arguments)
+				}
+				break
+			case 'tool':
+				extractFromToolResult(
+					manager,
+					toolNames.get(message.toolCallId) ?? 'tool',
+					toolResultToText(message.content),
+					message.isError === true,
+				)
+				break
+			case 'system':
+				break
+		}
+	}
 }
 
 /**
@@ -65,6 +136,7 @@ function splice(
  * logged as a successful pass and shown to a user as work done.
  */
 export async function compactNow(input: CompactNowInput): Promise<CompactionResult | null> {
+	admitManualCompaction(input)
 	const window = resolveContextWindow(
 		input.contextWindowTokens ?? input.config.contextWindowTokens,
 		input.model,
@@ -79,22 +151,40 @@ export async function compactNow(input: CompactNowInput): Promise<CompactionResu
 		contextWindowTokens: window.tokens,
 		estimatedTokens: window.tokens,
 		force: true,
+		allowNoSystemFloor: true,
 		skipToolResultClear: true,
 	})
 	if (plan.kind !== 'plan') return null
 
+	const retained = findRetainedIndices(input.messages)
+	const retainedOlder = plan.olderMessages.filter((_, offset) =>
+		retained.has(plan.systemMessages.length + offset),
+	)
+	const preservedSystem = preservedSystemFloor(plan.systemMessages)
+	const projectedLength =
+		preservedSystem.length + 1 + retainedOlder.length + plan.recentMessages.length
+	// Decide before building a summary (and before a possible verifier call).
+	// A pinned older message remains verbatim, so replacing one removable
+	// message with one summary has shed nothing and must be reported as a no-op.
+	if (input.messages.length - projectedLength < 1) return null
+
 	const manager = new WorkingStateManager(input.config)
+	populateWorkingState(manager, plan.olderMessages, input.config)
+	let usage: TokenUsage = { ...EMPTY_TOKEN_USAGE }
 	const body = await buildVerifiedSummary(
 		manager,
 		[...plan.olderMessages],
 		input.provider,
 		input.config,
-		undefined,
+		(reported) => {
+			usage = accumulateTokenUsage(usage, reported)
+		},
 		input.model ?? '',
+		{ signal: input.signal, streamIdleTimeoutMs: input.streamIdleTimeoutMs },
 	)
 
-	const { messages, summary } = splice(plan.systemMessages, body, plan.recentMessages)
-	return { messages, shed: input.messages.length - messages.length, summary }
+	const { messages, summary } = splice(preservedSystem, body, retainedOlder, plan.recentMessages)
+	return { messages, shed: input.messages.length - messages.length, summary, usage }
 }
 
 export interface CompactRegionInput extends CompactNowInput {
@@ -115,6 +205,7 @@ export interface CompactRegionInput extends CompactNowInput {
  * the caller can move it themselves.
  */
 export async function compactRegion(input: CompactRegionInput): Promise<CompactionResult | null> {
+	admitManualCompaction(input)
 	const { messages, start, end } = input
 
 	if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end > messages.length) {
@@ -146,18 +237,34 @@ export async function compactRegion(input: CompactRegionInput): Promise<Compacti
 		}
 	}
 
+	const retained = findRetainedIndices(messages)
+	const retainedSelected = messages
+		.slice(start, end)
+		.filter((_, offset) => retained.has(start + offset))
+	// The replacement summary itself costs one slot. If the selected region
+	// contains no additional removable message, the honest result is a no-op
+	// and no verifier/provider work is authorized.
+	if (end - start - retainedSelected.length - 1 < 1) return null
+
 	const manager = new WorkingStateManager(input.config)
+	populateWorkingState(manager, messages.slice(start, end), input.config)
+	let usage: TokenUsage = { ...EMPTY_TOKEN_USAGE }
 	const body = await buildVerifiedSummary(
 		manager,
 		messages.slice(start, end),
 		input.provider,
 		input.config,
-		undefined,
+		(reported) => {
+			usage = accumulateTokenUsage(usage, reported)
+		},
 		input.model ?? '',
+		{ signal: input.signal, streamIdleTimeoutMs: input.streamIdleTimeoutMs },
 	)
 
-	const summary = buildCompactionMessage(body)
-	const out = [...messages.slice(0, start), summary, ...messages.slice(end)]
+	// Same cross-run ownership as compactNow: a selected region has been
+	// replaced outside a run, so its only surviving account is pinned.
+	const summary = { ...buildCompactionMessage(body), retain: true }
+	const out = [...messages.slice(0, start), summary, ...retainedSelected, ...messages.slice(end)]
 
 	// Checked after the splice, not only before it. The edges being
 	// individually safe does not make the RESULT valid — a span whose
@@ -173,5 +280,5 @@ export async function compactRegion(input: CompactRegionInput): Promise<Compacti
 		})
 	}
 
-	return { messages: out, shed: messages.length - out.length, summary }
+	return { messages: out, shed: messages.length - out.length, summary, usage }
 }

package/src/compaction/plan.ts

@@ -30,7 +30,7 @@ import { clearStaleToolResults } from './tool-result-editing.js'
 export type CompactionSkipReason =
 	/** Fewer messages than the recent window plus a floor — nothing to move. */
 	| 'too_few_messages'
-	/** No leading `system` message, so there is no permanent floor to keep. */
+	/** An in-run pass has no leading `system` message to use as its permanent floor. */
 	| 'no_system_floor'
 	/** Every candidate boundary would split a tool-call pair. */
 	| 'no_safe_cut'
@@ -61,14 +61,27 @@ export interface CompactionPlanInput {
 	readonly contextWindowTokens: number
 	readonly estimatedTokens: number
 	readonly force?: boolean
+	/**
+	 * Let a host-created pass establish its own retained summary floor.
+	 *
+	 * This is deliberately separate from `force`: a provider overflow can
+	 * force the threshold decision without changing the live run's prompt
+	 * invariant, while a host may own a durable user/assistant-only history
+	 * that has no system floor yet.
+	 */
+	readonly allowNoSystemFloor?: boolean
 	/**
 	 * Skip the tool-result pre-pass and go straight to the boundary search.
 	 *
-	 * The two steps are sequential in a real pass: clear first, install the
-	 * result, and if that was not enough relief, plan a cut over the history
-	 * you just edited. Returning both from one call would mean nesting a
-	 * union inside a union and computing a boundary the caller may never
-	 * use; asking twice says what is happening.
+	 * The two steps are sequential in a real pass: ask once for a cleared
+	 * candidate and, if that was not enough relief, ask again for a cut over
+	 * that candidate. The caller need not install the first answer before the
+	 * second question. In fact the live runtime deliberately stages an
+	 * insufficient clear until summary verification succeeds, then publishes
+	 * the combined edit atomically. Returning both from one call would mean
+	 * nesting a union inside a union and computing a boundary the caller may
+	 * never use; asking twice says what is happening without prescribing when
+	 * an effect becomes visible.
 	 */
 	readonly skipToolResultClear?: boolean
 }
@@ -158,16 +171,34 @@ export function planCompaction(input: CompactionPlanInput): CompactionPlan {
 	}
 
 	const messages = input.messages
-	if (messages.length < config.keepRecentMessages + 2) {
-		return { kind: 'skip', reason: 'too_few_messages' }
-	}
-
 	const systemMessages: Message[] = []
 	for (const msg of messages) {
 		if (msg.role !== 'system') break
 		systemMessages.push(msg)
 	}
-	if (systemMessages.length === 0) return { kind: 'skip', reason: 'no_system_floor' }
+
+	// Count and token retention are different boundary policies. In count
+	// mode the configured tail plus one older message must fit after the
+	// floor. Token mode does not consult keepRecentMessages at all; it only
+	// needs one older and one recent message before the token walk and safe
+	// boundary search can make the real decision.
+	//
+	// Preserve the old short-history ordering for a run with no floor: until
+	// a host explicitly allows a floorless pass, one notional system message
+	// remains part of the admission minimum and `no_system_floor` follows it.
+	const floorForAdmission =
+		systemMessages.length > 0 ? systemMessages.length : input.allowNoSystemFloor ? 0 : 1
+	const minimumMessages =
+		config.keepRecentTokens === undefined
+			? floorForAdmission + config.keepRecentMessages + 1
+			: floorForAdmission + 2
+	if (messages.length < minimumMessages) {
+		return { kind: 'skip', reason: 'too_few_messages' }
+	}
+
+	if (systemMessages.length === 0 && !input.allowNoSystemFloor) {
+		return { kind: 'skip', reason: 'no_system_floor' }
+	}
 
 	// Tool-pair atomicity. A naive cut at `length - keepRecentMessages` can
 	// land BETWEEN an assistant-with-toolCalls (dropped into `older`) and its

package/src/compaction/retention.ts

@@ -24,15 +24,18 @@ const isAssistantWithCalls = (m: Message): m is AssistantMessage =>
 
 /**
  * Indices of every message protected by a `retain` marker, expanded across
- * tool pairs.
+ * provider-valid turns.
  *
  * Transitive by necessity, not politeness. A `tool_result` whose
- * `tool_use` was dropped is rejected by the provider outright, so pinning
- * half a pair would turn a retention request into a broken next turn. So:
- * a pinned tool result pulls in the assistant turn that issued the call,
- * and a pinned assistant turn pulls in EVERY result answering it — the
- * second hop matters, because an assistant turn with three calls and one
- * surviving result is the same dangling error in the other direction.
+ * `tool_use` was dropped is rejected by the provider outright, and a
+ * compacted conversation whose first non-system message is an assistant
+ * turn is rejected before the pair is even considered. Pinning half a pair
+ * — or the pair without its user turn boundary — would therefore turn a
+ * retention request into a broken next turn. A pinned tool result pulls in
+ * the assistant turn that issued the call; a pinned assistant turn pulls in
+ * the user message that opened its turn and EVERY result answering it. The
+ * second result hop matters, because an assistant turn with three calls and
+ * one surviving result is the same dangling error in the other direction.
  */
 export function findRetainedIndices(messages: readonly Message[]): Set<number> {
 	const retained = new Set<number>()
@@ -43,10 +46,19 @@ export function findRetainedIndices(messages: readonly Message[]): Set<number> {
 
 	const assistantOfCall = new Map<string, number>()
 	const resultsOfAssistant = new Map<number, number[]>()
+	const userOfAssistant = new Map<number, number>()
 
+	let currentUser: number | undefined
 	for (let i = 0; i < messages.length; i++) {
 		const message = messages[i]
-		if (!message || !isAssistantWithCalls(message)) continue
+		if (!message) continue
+		if (message.role === 'user') {
+			currentUser = i
+			continue
+		}
+		if (message.role !== 'assistant') continue
+		if (currentUser !== undefined) userOfAssistant.set(i, currentUser)
+		if (!isAssistantWithCalls(message)) continue
 		for (const call of message.toolCalls ?? []) {
 			assistantOfCall.set(call.id, i)
 		}
@@ -80,6 +92,9 @@ export function findRetainedIndices(messages: readonly Message[]): Set<number> {
 		if (message.role === 'tool') {
 			add(assistantOfCall.get((message as ToolMessage).toolCallId))
 		}
+		if (message.role === 'assistant') {
+			add(userOfAssistant.get(index))
+		}
 		for (const sibling of resultsOfAssistant.get(index) ?? []) {
 			add(sibling)
 		}