@namzu/sdk 2.0.0 → 3.0.0

package/src/compaction/__tests__/tool-result-editing.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Message } from '../../types/message/index.js'
+import { clearStaleToolResults, isClearedToolResult } from '../tool-result-editing.js'
+
+/**
+ * Compaction was all-or-nothing: once the threshold hit, every older
+ * message became a summary and the agent's own reasoning — the decisions,
+ * the false starts it learned from, the exact wording of a plan — was
+ * paraphrased away with it.
+ *
+ * That is a heavy price for a context problem usually caused by something
+ * much dumber: a handful of enormous tool outputs the agent already read,
+ * took what it needed from, and moved past.
+ */
+
+const big = (n: number) => 'x'.repeat(n)
+
+function conversation(
+	results: Array<{ tool: string; output: string; isError?: boolean }>,
+): Message[] {
+	const messages: Message[] = [{ role: 'system', content: 'you are an agent' }]
+	results.forEach((r, i) => {
+		messages.push({
+			role: 'assistant',
+			content: null,
+			toolCalls: [
+				{ id: `call_${i}`, type: 'function', function: { name: r.tool, arguments: '{}' } },
+			],
+		} as Message)
+		messages.push({
+			role: 'tool',
+			content: r.output,
+			toolCallId: `call_${i}`,
+			...(r.isError ? { isError: true } : {}),
+		} as Message)
+	})
+	return messages
+}
+
+describe('clearStaleToolResults', () => {
+	it('clears an old, large result and leaves a placeholder naming the tool', () => {
+		const messages = conversation([
+			{ tool: 'read_file', output: big(50_000) },
+			{ tool: 'ls', output: 'a.ts' },
+			{ tool: 'ls', output: 'b.ts' },
+			{ tool: 'ls', output: 'c.ts' },
+		])
+
+		const { messages: edited, clearedCount, charsReclaimed } = clearStaleToolResults(messages)
+
+		expect(clearedCount).toBe(1)
+		expect(charsReclaimed).toBeGreaterThan(49_000)
+		const cleared = edited.find((m) => m.role === 'tool' && isClearedToolResult(m.content))
+		expect(cleared?.content).toContain('read_file')
+		expect(cleared?.content).toContain('50,000 characters')
+	})
+
+	it('keeps `tool_use` ↔ `tool_result` pairing intact — nothing moves', () => {
+		// This is what makes clearing safe where trimming is not.
+		const messages = conversation([
+			{ tool: 'read_file', output: big(50_000) },
+			{ tool: 'ls', output: 'a' },
+			{ tool: 'ls', output: 'b' },
+			{ tool: 'ls', output: 'c' },
+		])
+
+		const { messages: edited } = clearStaleToolResults(messages)
+
+		expect(edited).toHaveLength(messages.length)
+		edited.forEach((msg, i) => {
+			expect(msg.role).toBe(messages[i]?.role)
+			if (msg.role === 'tool') {
+				expect(msg.toolCallId).toBe((messages[i] as { toolCallId: string }).toolCallId)
+			}
+		})
+	})
+
+	it('does not mutate the input', () => {
+		const messages = conversation([
+			{ tool: 'read_file', output: big(50_000) },
+			{ tool: 'ls', output: 'a' },
+			{ tool: 'ls', output: 'b' },
+			{ tool: 'ls', output: 'c' },
+		])
+		const before = JSON.stringify(messages)
+		clearStaleToolResults(messages)
+		expect(JSON.stringify(messages)).toBe(before)
+	})
+
+	it('leaves the most recent results alone — the agent is still using them', () => {
+		const messages = conversation([
+			{ tool: 'a', output: big(20_000) },
+			{ tool: 'b', output: big(20_000) },
+			{ tool: 'c', output: big(20_000) },
+			{ tool: 'd', output: big(20_000) },
+		])
+
+		const { clearedCount, messages: edited } = clearStaleToolResults(messages, {
+			keepRecentToolResults: 3,
+		})
+
+		expect(clearedCount).toBe(1)
+		// The last three are untouched.
+		const toolMsgs = edited.filter((m) => m.role === 'tool')
+		expect(toolMsgs.slice(1).every((m) => !isClearedToolResult(m.content))).toBe(true)
+	})
+
+	it('leaves small results alone — the placeholder would cost as much', () => {
+		const messages = conversation([
+			{ tool: 'ls', output: 'a.ts b.ts' },
+			{ tool: 'ls', output: 'c.ts' },
+			{ tool: 'ls', output: 'd.ts' },
+			{ tool: 'ls', output: 'e.ts' },
+		])
+		expect(clearStaleToolResults(messages).clearedCount).toBe(0)
+	})
+
+	it('never clears an ERROR result — the error is what steers the next turn', () => {
+		const messages = conversation([
+			{ tool: 'bash', output: big(50_000), isError: true },
+			{ tool: 'ls', output: 'a' },
+			{ tool: 'ls', output: 'b' },
+			{ tool: 'ls', output: 'c' },
+		])
+		expect(clearStaleToolResults(messages).clearedCount).toBe(0)
+	})
+
+	it('honors a preserve list, by tool name', () => {
+		const messages = conversation([
+			{ tool: 'load_spec', output: big(50_000) },
+			{ tool: 'read_file', output: big(50_000) },
+			{ tool: 'ls', output: 'a' },
+			{ tool: 'ls', output: 'b' },
+			{ tool: 'ls', output: 'c' },
+		])
+
+		const { clearedCount, messages: edited } = clearStaleToolResults(messages, {
+			preserveTools: ['load_spec'],
+		})
+
+		expect(clearedCount).toBe(1)
+		const specResult = edited.find((m) => m.role === 'tool' && m.toolCallId === 'call_0')
+		expect(isClearedToolResult(specResult?.content)).toBe(false)
+	})
+
+	it('is idempotent — a second pass finds nothing left to do', () => {
+		const messages = conversation([
+			{ tool: 'read_file', output: big(50_000) },
+			{ tool: 'ls', output: 'a' },
+			{ tool: 'ls', output: 'b' },
+			{ tool: 'ls', output: 'c' },
+		])
+
+		const first = clearStaleToolResults(messages)
+		const second = clearStaleToolResults(first.messages)
+		expect(second.clearedCount).toBe(0)
+		expect(second.charsReclaimed).toBe(0)
+	})
+
+	it('reports the NET saving, not the gross one', () => {
+		// A caller uses this number to decide "was that enough?", so
+		// overstating it would send it back to summarize when it need not.
+		const messages = conversation([
+			{ tool: 'read_file', output: big(10_000) },
+			{ tool: 'ls', output: 'a' },
+			{ tool: 'ls', output: 'b' },
+			{ tool: 'ls', output: 'c' },
+		])
+
+		const { messages: edited, charsReclaimed } = clearStaleToolResults(messages)
+		const placeholder = edited.find((m) => m.role === 'tool' && isClearedToolResult(m.content))
+		const placeholderLength = String(placeholder?.content).length
+
+		expect(charsReclaimed).toBe(10_000 - placeholderLength)
+	})
+
+	it('measures an image result by its payload, which is the biggest win available', () => {
+		// A screenshot is the single largest thing a tool result can carry,
+		// and exactly the kind of output an agent reads once.
+		const messages: Message[] = [
+			{
+				role: 'assistant',
+				content: null,
+				toolCalls: [
+					{ id: 'call_s', type: 'function', function: { name: 'screenshot', arguments: '{}' } },
+				],
+			} as Message,
+			{
+				role: 'tool',
+				content: [{ type: 'image', data: big(400_000), mediaType: 'image/png' }],
+				toolCallId: 'call_s',
+			} as Message,
+		]
+
+		const { clearedCount, charsReclaimed } = clearStaleToolResults(messages, {
+			keepRecentToolResults: 0,
+		})
+		expect(clearedCount).toBe(1)
+		expect(charsReclaimed).toBeGreaterThan(399_000)
+	})
+
+	it('does nothing to a conversation with no tool results', () => {
+		const messages: Message[] = [
+			{ role: 'system', content: 'sys' },
+			{ role: 'user', content: 'hello' },
+			{ role: 'assistant', content: 'hi' } as Message,
+		]
+		const out = clearStaleToolResults(messages)
+		expect(out.clearedCount).toBe(0)
+		expect(out.messages).toEqual(messages)
+	})
+})

package/src/compaction/__tests__/trim-opens-on-user.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Message } from '../../types/message/index.js'
+import { findSafeTrimIndex } from '../dangling.js'
+
+/**
+ * After compaction the kept tail IS the conversation: the summary is
+ * written as a system message and every driver hoists system messages into
+ * their own request parameter, so the first kept message becomes the first
+ * message on the wire. A conversation that opens on an assistant turn is
+ * rejected.
+ *
+ * `findSafeTrimIndex` advanced past an orphaned `tool` message and never
+ * past an `assistant` one. How often that bit depends on the shape of the
+ * history, and the shape that matters most is the worst: in a multi-step
+ * turn — the agent working through several tool calls without the user
+ * speaking in between — the tail alternates assistant/tool with no user
+ * message in it at all, so essentially every boundary landed wrong.
+ *
+ * The failure was unrecoverable, too. The resulting rejection is not
+ * classified as an overflow, so relief never fires and the run dies —
+ * compaction, whose whole job is keeping a long run alive, becoming the
+ * thing that ends it.
+ */
+
+const user = (text: string): Message => ({ role: 'user', content: text })
+const answer = (text: string): Message => ({ role: 'assistant', content: text })
+const calls = (id: string): Message => ({
+	role: 'assistant',
+	content: null,
+	toolCalls: [{ id, type: 'function', function: { name: 't', arguments: '{}' } }],
+})
+const result = (id: string): Message => ({ role: 'tool', toolCallId: id, content: 'ok' })
+
+/** user → assistant(call) → tool → assistant(answer), repeated. */
+function conversational(turns: number): Message[] {
+	const out: Message[] = []
+	for (let i = 0; i < turns; i++) {
+		out.push(user(`q${i}`), calls(`c${i}`), result(`c${i}`), answer(`a${i}`))
+	}
+	return out
+}
+
+/** One user turn, then the agent working alone — the normal agentic shape. */
+function multiStep(steps: number): Message[] {
+	const out: Message[] = [user('go')]
+	for (let i = 0; i < steps; i++) out.push(calls(`c${i}`), result(`c${i}`))
+	out.push(answer('done'))
+	return out
+}
+
+/** Two tool calls per turn, which shifts the parity of every boundary. */
+function wideTurns(turns: number): Message[] {
+	const out: Message[] = []
+	for (let i = 0; i < turns; i++) {
+		out.push(user(`q${i}`), {
+			role: 'assistant',
+			content: null,
+			toolCalls: [
+				{ id: `c${i}a`, type: 'function', function: { name: 't', arguments: '{}' } },
+				{ id: `c${i}b`, type: 'function', function: { name: 't', arguments: '{}' } },
+			],
+		})
+		out.push(result(`c${i}a`), result(`c${i}b`), answer(`a${i}`))
+	}
+	return out
+}
+
+describe('the kept tail opens the way a conversation opens', () => {
+	it.each([
+		['one tool call per turn', conversational(6)],
+		['two tool calls per turn', wideTurns(6)],
+		['a multi-step turn with no user in between', multiStep(6)],
+	])('%s', (_name, messages) => {
+		for (let keep = 1; keep <= Math.min(12, messages.length); keep++) {
+			const index = findSafeTrimIndex(messages, messages.length - keep)
+			const kept = messages.slice(index)
+			if (kept.length === 0) continue
+			expect(kept[0]?.role).toBe('user')
+		}
+	})
+
+	it('is wrong at every boundary in a multi-step turn without the guard', () => {
+		// Recorded so the regression is legible: this shape has exactly one
+		// user message, at the front, and the whole tail after it alternates
+		// assistant and tool. Any boundary inside it lands on the wrong role.
+		const messages = multiStep(6)
+		const userTurns = messages.filter((m) => m.role === 'user')
+		expect(userTurns).toHaveLength(1)
+		expect(messages.indexOf(userTurns[0] as Message)).toBe(0)
+
+		for (let keep = 1; keep < messages.length; keep++) {
+			const index = findSafeTrimIndex(messages, messages.length - keep)
+			// The only valid boundary in this shape is the very front.
+			expect(index).toBe(0)
+		}
+	})
+})
+
+describe('when no boundary can satisfy both invariants', () => {
+	it('does not re-admit an orphaned result to reach a user turn', () => {
+		// Already unsendable: the results have no call anywhere. Falling back
+		// to the user message at the front would satisfy "opens on user" by
+		// breaking "no orphaned result", which is not a fix.
+		const messages: Message[] = [user('test'), result('missing-1'), result('missing-2')]
+		const kept = messages.slice(findSafeTrimIndex(messages, 1))
+		expect(kept).toHaveLength(0)
+	})
+
+	it('declines to trim rather than invent a different broken conversation', () => {
+		const messages: Message[] = [user('a'), answer('b')]
+		const index = findSafeTrimIndex(messages, 1)
+		// Index 1 is the assistant. Forward reaches the end; back reaches the
+		// user at 0, whose tail is clean — so it keeps more than asked.
+		expect(index).toBe(0)
+		expect(messages.slice(index)[0]?.role).toBe('user')
+	})
+})

package/src/compaction/__tests__/verifier-model.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { CompactionConfig } from '../../config/runtime.js'
+import { MockLLMProvider } from '../../provider/mock.js'
+import type { Message } from '../../types/message/index.js'
+import { WorkingStateManager } from '../manager.js'
+import { buildVerifiedSummary } from '../verifier.js'
+
+/**
+ * The compaction verifier called `provider.chatStream({ model: '' })`.
+ *
+ * Some drivers quietly substitute a default and others reject outright —
+ * on Bedrock the model id IS the endpoint, and OpenRouter requires it. So
+ * the verifier failed exactly on the providers where a long run most needs
+ * compaction, and the failure surfaced as compaction killing the run it
+ * exists to save.
+ */
+
+function config(overrides: Partial<CompactionConfig> = {}): CompactionConfig {
+	return {
+		strategy: 'structured',
+		triggerThreshold: 0.7,
+		resetThreshold: 0.4,
+		keepRecentMessages: 4,
+		clearToolResults: true,
+		keepRecentToolResults: 3,
+		minToolResultCharsToClear: 1_000,
+		maxToolResults: 30,
+		maxListSize: 25,
+		keepFirstEntries: 3,
+		llmVerification: true,
+		llmVerificationMaxTokens: 2048,
+		richStateThreshold: 15,
+		convoTextBudget: 12_000,
+		maxSentencesPerTurn: 5,
+		maxCharsPerNote: 500,
+		maxCharsPerRequirement: 300,
+		maxCharsPerTask: 400,
+		...overrides,
+	} as CompactionConfig
+}
+
+const older: Message[] = [
+	{ role: 'user', content: 'build the thing' },
+	{ role: 'assistant', content: 'I built it' } as Message,
+]
+
+describe('buildVerifiedSummary', () => {
+	it('sends the run`s model, not an empty string', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'COMPLETE' }] })
+		const manager = new WorkingStateManager(config())
+
+		await buildVerifiedSummary(
+			manager,
+			older,
+			provider,
+			config(),
+			undefined,
+			'anthropic.claude-opus-4-v1',
+		)
+
+		expect(provider.requests).toHaveLength(1)
+		expect(provider.requests[0]?.model).toBe('anthropic.claude-opus-4-v1')
+	})
+
+	it('bills the side-channel call to the run', async () => {
+		// A compaction pass is not free, and a run that cannot see the cost
+		// cannot enforce its own budget.
+		const provider = new MockLLMProvider({ turns: [{ text: 'COMPLETE' }] })
+		const onUsage = vi.fn()
+
+		await buildVerifiedSummary(
+			new WorkingStateManager(config()),
+			older,
+			provider,
+			config(),
+			onUsage,
+			'some-model',
+		)
+
+		expect(onUsage).toHaveBeenCalledOnce()
+	})
+})

package/src/compaction/context-window.ts

@@ -0,0 +1,107 @@
+/**
+ * Model context-window resolution for the compaction trigger.
+ *
+ * Compaction asks "how full is the window?". That question needs a WINDOW,
+ * and the runtime previously answered it with `runConfig.tokenBudget` — the
+ * run's cumulative spend cap. The two are different quantities, and using
+ * the second as the divisor for the first is self-defeating: cumulative
+ * spend always exceeds the live window, and the guard force-finalizes at
+ * 0.9 x tokenBudget while compaction needs 0.7 x the same number, so the
+ * mechanism raced its own budget. With the shipped CLI's
+ * `tokenBudget: 1_000_000` the trigger sat at ~700k — far past any window
+ * it targets.
+ *
+ * The table is a floor, not an oracle: a host that knows better passes
+ * `contextWindowTokens` explicitly and this file is never consulted.
+ */
+
+/**
+ * Conservative default for a model we do not recognise.
+ *
+ * Under-estimating is the safe direction: it compacts earlier than needed,
+ * costing a summarization pass. Over-estimating means the run dies on a
+ * provider `context_length_exceeded` with nothing recoverable.
+ */
+export const DEFAULT_ASSUMED_CONTEXT_WINDOW = 128_000
+
+/**
+ * Longest-prefix match table. Keys are matched against a lowercased model
+ * id, so `claude-opus-5-20260514` resolves through `claude-opus-5`.
+ * Ordered longest-first at lookup time, so a more specific key always wins
+ * over a shorter one that also prefixes it.
+ */
+const WINDOWS: ReadonlyArray<readonly [prefix: string, tokens: number]> = [
+	['claude-fable-5', 200_000],
+	['claude-opus-5', 200_000],
+	['claude-sonnet-5', 200_000],
+	['claude-haiku-4-5', 200_000],
+	['claude-opus-4', 200_000],
+	['claude-sonnet-4', 200_000],
+	['claude-3-7-sonnet', 200_000],
+	['claude-3-5-sonnet', 200_000],
+	['claude-3-5-haiku', 200_000],
+	['claude-3-opus', 200_000],
+	['claude-', 200_000],
+	['gpt-5', 400_000],
+	['gpt-4.1', 1_047_576],
+	['gpt-4o', 128_000],
+	['gpt-4-turbo', 128_000],
+	['gpt-4', 8_192],
+	['gpt-3.5-turbo', 16_385],
+	['o3', 200_000],
+	['o4-mini', 200_000],
+	['gemini-2.5-pro', 1_048_576],
+	['gemini-2.5-flash', 1_048_576],
+	['gemini-1.5-pro', 2_097_152],
+	['gemini-', 1_048_576],
+	// Open weights, common local sizes
+	['llama-3.3', 128_000],
+	['llama-3.1', 128_000],
+	['qwen', 32_768],
+	['mistral-large', 128_000],
+	['mixtral', 32_768],
+	['deepseek', 64_000],
+]
+
+const SORTED = [...WINDOWS].sort((a, b) => b[0].length - a[0].length)
+
+/**
+ * Best-effort context window for a model id, or `undefined` when the id is
+ * unrecognised. Gateway-qualified ids that prefix or namespace the
+ * model name are handled by substring matching rather than a strict
+ * prefix, since the same model ships under several namespaced ids.
+ */
+export function lookupContextWindow(model: string | undefined): number | undefined {
+	if (!model) return undefined
+	const id = model.toLowerCase()
+	for (const [prefix, tokens] of SORTED) {
+		if (id.includes(prefix)) return tokens
+	}
+	return undefined
+}
+
+export interface ResolvedContextWindow {
+	readonly tokens: number
+	readonly source: 'config' | 'model-table' | 'default'
+}
+
+/**
+ * Resolve the window the compaction trigger measures against.
+ *
+ * Note what is NOT in the precedence list: `tokenBudget`. It is the wrong
+ * quantity and having it as a fallback is what made the whole compaction
+ * subsystem inert in every shipped consumer.
+ */
+export function resolveContextWindow(
+	configured: number | undefined,
+	model: string | undefined,
+): ResolvedContextWindow {
+	if (configured !== undefined && configured > 0) {
+		return { tokens: configured, source: 'config' }
+	}
+	const known = lookupContextWindow(model)
+	if (known !== undefined) {
+		return { tokens: known, source: 'model-table' }
+	}
+	return { tokens: DEFAULT_ASSUMED_CONTEXT_WINDOW, source: 'default' }
+}

package/src/compaction/dangling.ts

@@ -317,5 +317,52 @@ export function findSafeTrimIndex(messages: Message[], targetIndex: number): num
 		}
 	}
 
-	return Math.min(currentIndex, messages.length)
+	return alignToUserTurn(messages, Math.min(currentIndex, messages.length))
+}
+
+/**
+ * Move the boundary onto a `user` message.
+ *
+ * The loop above advances past an orphaned `tool` message but never past
+ * an `assistant` one, and after compaction the kept tail IS the start of
+ * the conversation: the summary is written as a system message and the
+ * drivers hoist every system message into its own request parameter, so
+ * the first kept message becomes the first message on the wire. A
+ * conversation that opens with an assistant turn is rejected outright.
+ *
+ * How often depends on the shape of the history, and the shape that
+ * matters most is the worst: in a multi-step turn — the agent working
+ * through several tool calls without the user speaking in between — the
+ * tail alternates assistant/tool with no user message anywhere in it, so
+ * essentially every boundary lands wrong. The failure is unrecoverable
+ * too, because the resulting rejection is not classified as an overflow
+ * and so never reaches relief. Compaction, whose whole job is keeping a
+ * long run alive, becomes the thing that ends it.
+ *
+ * Landing on a `user` message also settles the orphan question for free:
+ * a user message is never a tool result, and everything skipped past is
+ * dropped along with the assistant turn that owned it.
+ */
+function alignToUserTurn(messages: Message[], index: number): number {
+	let forward = index
+	while (forward < messages.length && messages[forward]?.role !== 'user') {
+		forward++
+	}
+	if (forward < messages.length) return forward
+
+	// Nothing ahead. Falling back keeps MORE than asked, which costs context
+	// but stays valid — except that reaching further back can re-admit the
+	// dangling pairs the loop above just walked past, so a candidate only
+	// counts if its own suffix is clean. Two wire invariants are in play and
+	// satisfying one by breaking the other is not a fix.
+	for (let back = Math.min(index, messages.length) - 1; back >= 0; back--) {
+		if (messages[back]?.role !== 'user') continue
+		if (findDanglingMessages(messages.slice(back)).isValid) return back
+	}
+
+	// No boundary satisfies both. The input was already unsendable, and
+	// there is no cut that makes it otherwise — so keep the prior
+	// behaviour of trimming past the end rather than inventing a different
+	// invalid conversation to replace it with.
+	return forward
 }

package/src/compaction/extractor.ts

@@ -110,14 +110,69 @@ export function extractFromToolResult(
 			timestamp: Date.now(),
 		})
 	} else {
+		// Everything the builtin name-sets do not recognise — every MCP tool,
+		// every custom tool, every connector-bridged tool — used to collapse
+		// into a flat 120-character head slice. On an MCP-heavy run that made
+		// the summary near information-free: `Ran: {"results":[{"id":"a1b2` and
+		// nothing else. Unknown tools are the ones the summary can say least
+		// about from the name, so they need MORE room, not less, and a
+		// structure-aware slice rather than a blind prefix.
 		manager.addToolResult({
 			tool: toolName,
-			summary: truncateResult(result, 120),
+			summary: summarizeUnknownResult(result),
 			timestamp: Date.now(),
 		})
 	}
 }
 
+/** Room for an unrecognised tool's result. */
+const UNKNOWN_RESULT_BUDGET = 400
+
+/**
+ * Summarize a result from a tool we know nothing about.
+ *
+ * A blind prefix of JSON is the worst possible slice: it spends the whole
+ * budget on syntax and array scaffolding before reaching a single value.
+ * Where the payload parses as JSON, describe its SHAPE — that is what a
+ * later turn actually needs in order to decide whether to re-run the tool.
+ */
+function summarizeUnknownResult(result: string): string {
+	const trimmed = result.trim()
+	if (trimmed.length <= UNKNOWN_RESULT_BUDGET) return trimmed
+
+	if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+		try {
+			const parsed: unknown = JSON.parse(trimmed)
+			if (Array.isArray(parsed)) {
+				const shape = parsed.length > 0 ? describeShape(parsed[0]) : 'empty'
+				return `array of ${parsed.length} × ${shape} — ${truncateResult(trimmed, 200)}`
+			}
+			if (parsed && typeof parsed === 'object') {
+				const keys = Object.keys(parsed)
+				return `object{${keys.slice(0, 12).join(', ')}${keys.length > 12 ? ', …' : ''}} — ${truncateResult(trimmed, 200)}`
+			}
+		} catch {
+			// Not JSON after all; fall through to the text slice.
+		}
+	}
+
+	// Plain text: keep the head AND the tail. The tail is where a command's
+	// error or a document's conclusion lives.
+	const head = trimmed.slice(0, UNKNOWN_RESULT_BUDGET - 120)
+	const tail = trimmed.slice(-100)
+	return `${head} … [${trimmed.length - head.length - tail.length} chars omitted] … ${tail}`
+}
+
+function describeShape(value: unknown): string {
+	if (value === null) return 'null'
+	if (Array.isArray(value)) return 'array'
+	if (typeof value === 'object') {
+		const keys = Object.keys(value as object)
+		return `object{${keys.slice(0, 6).join(', ')}${keys.length > 6 ? ', …' : ''}}`
+	}
+	return typeof value
+}
+
 export function extractFromUserMessage(
 	manager: WorkingStateManager,
 	content: string,

package/src/compaction/index.ts

@@ -30,6 +30,22 @@ export {
 	findSafeTrimIndex,
 } from './dangling.js'
 
+export { findRetainedIndices } from './retention.js'
+
 export { NullManager, SlidingWindowManager, StructuredCompactionManager } from './managers/index.js'
 
 export { createConversationManager } from './factory.js'
+export {
+	DEFAULT_ASSUMED_CONTEXT_WINDOW,
+	lookupContextWindow,
+	resolveContextWindow,
+} from './context-window.js'
+export type { ResolvedContextWindow } from './context-window.js'
+
+export {
+	clearStaleToolResults,
+	isClearedToolResult,
+	DEFAULT_KEEP_RECENT_TOOL_RESULTS,
+	DEFAULT_MIN_CHARS_TO_CLEAR,
+} from './tool-result-editing.js'
+export type { ToolResultEditConfig, ToolResultEditOutcome } from './tool-result-editing.js'