@namzu/sdk 53.1.0 → 53.2.1

package/dist/types/tool/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"AAizCA,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/tool/index.ts"],"names":[],"mappings":"AAyzCA,cAAc,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "53.1.0",
+  "version": "53.2.1",
   "description": "Open-source AI kernel for TypeScript: runs an agent the way an operating system runs a process, with an identity and a budget, scheduled tool calls and checkpointed turns.",
   "license": "FSL-1.1-MIT",
   "engines": {

package/src/compaction/index.ts

@@ -71,7 +71,12 @@ export type { ToolResultEditConfig, ToolResultEditOutcome } from './tool-result-
 // can offer, rather than something that only happens when a threshold trips.
 export { compactNow, compactRegion } from './manual.js'
 export type { CompactionResult, CompactNowInput, CompactRegionInput } from './manual.js'
-export { COMPACTION_HEADER, buildCompactionMessage, isCompactionMessage } from './summary.js'
+export {
+	COMPACTION_HEADER,
+	COMPACTION_RECOVERY_NOTE,
+	buildCompactionMessage,
+	isCompactionMessage,
+} from './summary.js'
 
 // The salience-scored working set: every message scored, the least salient
 // evicted first. See `docs/sdk/salience-working-set.md`.

package/src/compaction/manual.ts

@@ -63,6 +63,11 @@ export interface CompactNowInput extends CompactionVerificationOptions {
 	 * a no-op. The callback owns persistence and must not mutate the messages.
 	 */
 	readonly onShed?: (messages: readonly Message[]) => void | Promise<void>
+	/**
+	 * A paragraph added to the end of the summary, for a host that can point the
+	 * model at the originals ({@link COMPACTION_RECOVERY_NOTE}). Absent adds none.
+	 */
+	readonly recoveryNote?: string
 }
 
 async function publishManualCompaction(
@@ -100,12 +105,13 @@ function splice(
 	summaryBody: string,
 	retainedOlder: readonly Message[],
 	recentMessages: readonly Message[],
+	recoveryNote?: string,
 ): { messages: Message[]; summary: Message } {
 	// A host-triggered pass has no turn-scoped WorkingStateManager to carry the
 	// summary into a later query. Pin this summary itself: until a future turn
 	// has rebuilt equivalent state, this message is the only surviving record
 	// of what the pass removed.
-	const summary = { ...buildCompactionMessage(summaryBody), retain: true }
+	const summary = { ...buildCompactionMessage(summaryBody, recoveryNote), retain: true }
 	return { messages: [...preservedSystem, summary, ...retainedOlder, ...recentMessages], summary }
 }
 
@@ -205,7 +211,13 @@ export async function compactNow(input: CompactNowInput): Promise<CompactionResu
 		},
 	)
 
-	const { messages, summary } = splice(preservedSystem, body, retainedOlder, plan.recentMessages)
+	const { messages, summary } = splice(
+		preservedSystem,
+		body,
+		retainedOlder,
+		plan.recentMessages,
+		input.recoveryNote,
+	)
 	return publishManualCompaction(input, {
 		messages,
 		shed: input.messages.length - messages.length,
@@ -294,7 +306,7 @@ export async function compactRegion(input: CompactRegionInput): Promise<Compacti
 
 	// Same cross-run ownership as compactNow: a selected region has been
 	// replaced outside a turn, so its only surviving account is pinned.
-	const summary = { ...buildCompactionMessage(body), retain: true }
+	const summary = { ...buildCompactionMessage(body, input.recoveryNote), retain: true }
 	const out = [...messages.slice(0, start), summary, ...retainedSelected, ...messages.slice(end)]
 
 	// Checked after the splice, not only before it. The edges being

package/src/compaction/salience/bm25.ts

@@ -27,8 +27,10 @@ export interface Bm25Index {
 const K1 = 1.2
 const B = 0.75
 
-export function indexDocument(text: string): Bm25Document {
-	const tokens = tokenize(text)
+export function indexDocument(
+	text: string,
+	tokens: readonly string[] = tokenize(text),
+): Bm25Document {
 	return { tf: termFrequencies(tokens), length: tokens.length }
 }
 

package/src/compaction/salience/score.ts

@@ -132,7 +132,9 @@ export function scoreMessages(
 	const texts = messages.map(messageText)
 	const richContent = messages.map(hasRichContent)
 	const tokenLists = texts.map(tokenize)
-	const documents: Bm25Document[] = texts.map(indexDocument)
+	const documents: Bm25Document[] = texts.map((text, i) =>
+		indexDocument(text, tokenLists[i] as string[]),
+	)
 	const index = buildIndex(documents)
 	const goalTokens = tokenize(options.goal)
 

package/src/compaction/salience/tokenize.ts

@@ -46,10 +46,24 @@ const STOP_WORDS: ReadonlySet<string> = new Set([
 
 const WORD = /[\p{L}\p{N}_$][\p{L}\p{N}_$.\-/\\:]*/gu
 
+const SEPARATORS: ReadonlySet<string> = new Set(['.', '-', '/', '\\', ':'])
+
+// A linear scan from each end: a `[sep]+$` regex is retried from every start of a
+// long separator run inside a token and fails at the end each time, quadratically.
+function trimSeparators(token: string): string {
+	let start = 0
+	let end = token.length
+	while (start < end && SEPARATORS.has(token[start] as string)) start++
+	while (end > start && SEPARATORS.has(token[end - 1] as string)) end--
+	return start === 0 && end === token.length ? token : token.slice(start, end)
+}
+
 function splitIdentifier(raw: string): string[] {
 	const parts = raw
 		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+		// Lookaround keeps this linear: a capturing `([A-Z]+)([A-Z][a-z])` backtracks
+		// quadratically on a long run of capitals that never reaches a lower-case letter.
+		.replace(/(?<=[A-Z])(?=[A-Z][a-z])/g, ' ')
 		.split(/[_\s]+/)
 		.filter((p) => p.length > 0)
 	return parts.length > 1 ? parts : []
@@ -59,7 +73,7 @@ function splitIdentifier(raw: string): string[] {
 export function tokenize(text: string): string[] {
 	const out: string[] = []
 	for (const match of text.matchAll(WORD)) {
-		const raw = match[0].replace(/^[.\-/\\:]+|[.\-/\\:]+$/g, '')
+		const raw = trimSeparators(match[0])
 		if (raw.length === 0) continue
 		const whole = raw.toLowerCase()
 		if (!STOP_WORDS.has(whole)) out.push(whole)

package/src/compaction/summary.ts

@@ -25,10 +25,24 @@ export function isCompactionMessage(content: string | null | undefined): boolean
 	return typeof content === 'string' && content.startsWith(COMPACTION_HEADER)
 }
 
-/** The summary, as the system message that replaces what it summarises. */
-export function buildCompactionMessage(body: string): Message {
+/**
+ * The line that tells the model where exact earlier text can still be had. A
+ * host that mounts `search_conversation` and `read_conversation` adds it to
+ * every summary; a host without them adds nothing, because a pointer to a tool
+ * that is not there is worse than none.
+ */
+export const COMPACTION_RECOVERY_NOTE =
+	'Earlier output was cut from this summary. To get exact earlier text, call search_conversation, then read_conversation.'
+
+/**
+ * The summary, as the system message that replaces what it summarises.
+ * `recoveryNote` is appended as its own paragraph.
+ */
+export function buildCompactionMessage(body: string, recoveryNote?: string): Message {
 	return {
-		...createSystemMessage(`${COMPACTION_HEADER}\n\n${body}`),
+		...createSystemMessage(
+			`${COMPACTION_HEADER}\n\n${body}${recoveryNote ? `\n\n${recoveryNote}` : ''}`,
+		),
 		source: { type: 'compaction-summary' },
 	}
 }

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

@@ -1,5 +1,8 @@
 import { CHARS_PER_TOKEN } from '../constants/limits.js'
-import { SPILL_MARKER } from '../runtime/query/tool-output-budget.js'
+import {
+	describeRetainedOutputRecovery,
+	retainedOutputPointer,
+} from '../runtime/query/tool-output-budget.js'
 import { toolResultToText } from '../types/message/content.js'
 import type { Message, ToolMessage, ToolResultBlock } from '../types/message/index.js'
 import { findRetainedIndices } from './retention.js'
@@ -68,8 +71,8 @@ const KEEP_TAIL_CHARS = 200
  * back to it. Replacing the whole content destroyed the cheapest recovery
  * route precisely for the largest results — and then told the model to
  * call the tool again, which is advice to re-run something that returned
- * megabytes. Keeping one line preserves a `read`/`grep` route worth far
- * more than the line costs.
+ * megabytes. Keeping the line and its recovery sentence preserves a route
+ * worth far more than the two lines cost.
  *
  * A HEAD AND TAIL, because a result is not uniformly valuable: what a
  * model needs from a long output is usually near one end, and keeping a
@@ -86,12 +89,12 @@ function clearedPlaceholder(
 		`${CLEARED_PREFIX} ${toolName} returned ${size.toLocaleString('en-US')} characters, cleared to reclaim context.`,
 	]
 
-	const spillLine = text.split('\n').find((line) => line.startsWith(SPILL_MARKER))
-	if (spillLine) {
-		parts.push(
-			spillLine,
-			'Read a window of it with `read` (offset/limit) or search it with `grep`.',
-		)
+	// The pointer is the spill line with the sentence that came with it, so the
+	// route is stated once, where the output was cut, and never contradicted here.
+	const pointer = retainedOutputPointer(text)
+	if (pointer) {
+		// A pointer written before the sentence existed gets the neutral one.
+		parts.push(pointer.includes('\n') ? pointer : `${pointer}\n${describeRetainedOutputRecovery()}`)
 	} else {
 		parts.push(
 			'Full result unavailable here. Recover from a saved artifact or a read-only observation; do not repeat a state-changing action to recover its output.',

package/src/manager/agent/lifecycle.ts

@@ -23,6 +23,11 @@ import type {
 	AgentLifecycleEvent,
 	AgentLifecycleListener,
 } from '../../types/agent/lifecycle-event.js'
+import type {
+	RestoreChildOptions,
+	RestoreChildRefusal,
+	RestoreChildResult,
+} from '../../types/agent/manager.js'
 import type {
 	AgentManagerConfig,
 	AgentTask,
@@ -53,7 +58,12 @@ import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { requireOpenProject } from '../project/lifecycle.js'
 import { type TopicManagerDependency, resolveTopicManager } from '../topic/dependency.js'
 import type { TopicManager } from '../topic/lifecycle.js'
-import { registerChildSessionLog, writeChildSessionMeta } from './child-session.js'
+import {
+	childSessionEnded,
+	readChildSessionMeta,
+	registerChildSessionLog,
+	writeChildSessionMeta,
+} from './child-session.js'
 
 /**
  * Dependencies threaded into {@link AgentManager}. Phase 6 promoted the
@@ -155,6 +165,7 @@ interface ChildSpawnRecord {
 		readonly toolCallId: string
 		readonly agentType: string
 		readonly description: string
+		readonly continuation?: NonNullable<ChildSessionMeta['continuation']>
 	}
 	/** Removes the child's log from the process-local lookup. */
 	releaseLog?: () => void
@@ -1236,6 +1247,7 @@ export class AgentManager {
 			description: placement.description,
 			status: 'running',
 			createdAt: placement.createdAt,
+			...(placement.continuation ? { continuation: placement.continuation } : {}),
 		}
 	}
 
@@ -1296,6 +1308,14 @@ export class AgentManager {
 			toolCallId: spawnToolCallId(taskId),
 			agentType: options.agentId,
 			description: describeSpawn(options),
+			...(options.continuationProfile
+				? {
+						continuation: {
+							workspace: options.workspace?.mode === 'isolated' ? 'isolated' : 'shared',
+							profile: { ...options.continuationProfile },
+						},
+					}
+				: {}),
 		}
 		await writeChildSessionMeta(spawnRecord.placement.metaPath, this.childMeta(spawnRecord))
 		return DiskSessionLog.at(paths, {
@@ -1796,6 +1816,166 @@ export class AgentManager {
 		})
 	}
 
+	/**
+	 * Make a child saved by an earlier process continuable again.
+	 *
+	 * Reads the child's meta document and log from the project layout under the
+	 * invoking parent, checks they describe a settled, shared-workspace child of
+	 * this very parent session, then re-creates the in-memory session and edge
+	 * and the retained conversation that {@link provisionContinuation} requires.
+	 * It runs nothing; the caller continues the child with `sendMessage` and
+	 * `resumeSessionId`, so the invoking turn's authority, limits and review
+	 * channel apply exactly as for a child that finished in this process.
+	 */
+	async restoreChildConversation(
+		options: RestoreChildOptions,
+		context: AgentTaskContext,
+	): Promise<RestoreChildResult> {
+		const refuse = (reason: RestoreChildRefusal): RestoreChildResult => ({
+			status: 'refused',
+			reason,
+		})
+		const id = options.childSessionId
+		const retained = this.childConversations.get(id)
+		if (retained?.activeSubSessionId) return refuse('running')
+		const paths =
+			context.childStorage?.kind === 'disk' ? context.childStorage.paths : this.deps.paths
+		if (!paths) return refuse('no-layout')
+		const store = this.deps.sessionStore
+		if (store.supportsInvocationSummaries !== true || store.supportsOwnerVersionCas !== true)
+			return refuse('not-resumable')
+		const ancestry = await store.getAncestry(context.sessionId, context.tenantId)
+		const parentLocator: SessionLocator = {
+			sessionId: context.sessionId,
+			ancestors: ancestry.slice(0, -1),
+		}
+		let meta: ChildSessionMeta | null
+		try {
+			meta = await readChildSessionMeta(paths.subagentMeta(parentLocator, id))
+		} catch {
+			return refuse('not-saved')
+		}
+		if (!meta) return refuse('not-saved')
+		if (meta.sessionId !== id || meta.parentSessionId !== context.sessionId)
+			return refuse('foreign')
+		const continuation = meta.continuation
+		if (!continuation || continuation.workspace !== 'shared') return refuse('not-resumable')
+		const agentId = options.agentFor(continuation.profile)
+		if (agentId === undefined || !this.registry.has(agentId)) return refuse('not-resumable')
+		const log = retained?.log ?? DiskSessionLog.at(paths, { sessionId: id, ancestors: ancestry })
+		// The child's own log wins over its meta document: a child that never
+		// recorded the end of a turn died mid-turn, and what it did is unknown.
+		const ended = await childSessionEnded(log)
+		if (!ended) return refuse('unsettled')
+		if (ended.status === 'cancelled' || meta.status === 'cancelled') return refuse('stopped')
+		// A log written under another project or topic cannot be continued here:
+		// the child's turn would refuse to open it.
+		const started = await log.head()
+		if (started === null) return refuse('unsettled')
+		for await (const { record } of log.read({ mode: 'tolerant' })) {
+			if (record.type !== 'session_started') continue
+			if (record.projectId !== context.projectId || record.topicId !== context.topicId)
+				return refuse('foreign')
+			break
+		}
+		const placement = {
+			paths,
+			metaPath: paths.subagentMeta(parentLocator, id),
+			createdAt: meta.createdAt,
+			toolCallId: meta.toolCallId,
+			agentType: meta.agentType,
+			description: meta.description,
+			continuation,
+		}
+		const restored: RestoreChildResult = {
+			status: 'restored',
+			childSessionId: id,
+			agentId,
+			profile: continuation.profile,
+			description: meta.description,
+		}
+		if (retained) return restored
+		if (this.childConversations.size >= RETAINED_CHILD_CONVERSATION_CAP) {
+			const oldest = [...this.childConversations].find(([, value]) => !value.activeSubSessionId)
+			if (!oldest) return refuse('full')
+			this.childConversations.delete(oldest[0])
+		}
+		const childActor: ActorRef = {
+			kind: 'agent',
+			agentId,
+			tenantId: context.tenantId,
+			parentActor: context.parentActor,
+		}
+		let child = await store.getSession(id, context.tenantId)
+		let createdChild = false
+		let edge: Awaited<ReturnType<typeof store.createSubSession>> | undefined
+		let createdEdge = false
+		try {
+			if (child) {
+				// A store that outlived the process still holds the child and its edge.
+				if (
+					child.status === 'active' ||
+					child.status === 'archived' ||
+					child.status === 'locked' ||
+					child.projectId !== context.projectId ||
+					child.topicId !== context.topicId ||
+					child.currentActor?.kind !== 'agent' ||
+					child.currentActor.agentId !== agentId
+				)
+					return refuse('running')
+			} else {
+				child = await store.createSession(
+					{ id, topicId: context.topicId, projectId: context.projectId, currentActor: childActor },
+					context.tenantId,
+				)
+				createdChild = true
+			}
+			edge = (await store.getChildren(context.sessionId, context.tenantId)).find(
+				(candidate) => candidate.childSessionId === id,
+			)
+			if (!edge) {
+				edge = await store.createSubSession(
+					{
+						parentSessionId: context.sessionId,
+						childSessionId: id,
+						kind: 'agent_spawn',
+						spawnedBy: context.parentActor,
+						failureMode: 'delegate',
+						completionMode: 'summary_ref',
+					},
+					context.tenantId,
+				)
+				createdEdge = true
+			}
+		} catch (error) {
+			if (edge && createdEdge)
+				await store.deleteSubSession(edge.id, context.tenantId).catch(() => undefined)
+			if (child && createdChild)
+				await store.deleteSession(id, context.tenantId).catch(() => undefined)
+			throw error
+		}
+		this.childConversations.set(id, {
+			definition: this.registry.getOrThrow(agentId),
+			origin: {
+				subSessionId: edge.id,
+				childSessionId: id,
+				tenantId: context.tenantId,
+				parentSessionId: context.sessionId,
+				parentTurnId: meta.parentTurnId,
+				rootSessionId: meta.rootSessionId,
+				ancestry,
+				childDepth: meta.depth,
+				childOwnerVersion: child.ownerVersion,
+				placement,
+			},
+			topicId: context.topicId,
+			projectId: context.projectId,
+			cwd: resolve(options.workingDirectory),
+			log,
+		})
+		return restored
+	}
+
 	private releaseChildConversation(record: ChildSpawnRecord): void {
 		const conversation = this.childConversations.get(record.childSessionId)
 		if (conversation?.activeSubSessionId !== record.subSessionId) return

package/src/public-runtime.ts

@@ -1275,7 +1275,7 @@ export { compactNow, compactRegion } from './compaction/manual.js'
 // A host persisting manual compaction has to recognise the system message on
 // resume. Export the identity predicate rather than making every host copy the
 // marker string and eventually disagree with the writer.
-export { isCompactionMessage } from './compaction/summary.js'
+export { COMPACTION_RECOVERY_NOTE, isCompactionMessage } from './compaction/summary.js'
 export {
 	DEFAULT_SALIENCE_CONFIG,
 	DEFAULT_SALIENCE_WEIGHTS,
@@ -1639,6 +1639,7 @@ export {
 	createSessionEvidenceSource,
 	createSessionTextEvidenceSource,
 } from './store/evidence/disk.js'
+export { SessionEvidenceOffsetError } from './store/evidence/source-text.js'
 export {
 	classifyEvidenceSource,
 	EVIDENCE_RECORD_GUIDANCE,

package/src/runtime/query/executor.ts

@@ -17,6 +17,7 @@ import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell
 import { isAlwaysDestructive } from '../../tools/defineTool.js'
 import { createFileReadTracker } from '../../tools/file-read-tracker.js'
 import { pathOutsideRoots, toolRoots } from '../../tools/paths.js'
+import { resolveRetainedOutput } from '../../tools/retained-output.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type { ToolSourceRef } from '../../toolsets/types.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
@@ -81,6 +82,7 @@ import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS,
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS_PER_MESSAGE,
+	type RetainedOutputRoutes,
 	type ToolOutputBudgetResult,
 	applyToolOutputBudget,
 	describeDroppedContent,
@@ -635,6 +637,17 @@ export function deniedToolOutput(toolName: string, reason: string): string {
 }
 
 export class ToolExecutor {
+	/** The recovery routes this turn actually has, so a pointer never names a missing tool. */
+	private recoveryRoutes(): RetainedOutputRoutes {
+		const tools = this.config.tools
+		return {
+			read: tools.get('read') !== undefined,
+			conversation:
+				tools.get('search_conversation') !== undefined &&
+				tools.get('read_conversation') !== undefined,
+		}
+	}
+
 	private outputDirectory(): string | undefined {
 		return typeof this.config.toolOutputDir === 'function'
 			? this.config.toolOutputDir()
@@ -1079,7 +1092,11 @@ export class ToolExecutor {
 		) {
 			const value = input[tool.pathArgument]
 			if (typeof value === 'string') {
-				const outside = await pathOutsideRoots(toolRoots(this.config), value)
+				// This session's own retained output is not "outside": it is where the
+				// result that was cut told the model to look.
+				const retained =
+					tool.name === 'read' && (await resolveRetainedOutput(this.outputDirectory(), value))
+				const outside = retained ? undefined : await pathOutsideRoots(toolRoots(this.config), value)
 				if (outside !== undefined) outsidePaths = [outside]
 			}
 		}
@@ -1526,6 +1543,7 @@ export class ToolExecutor {
 			{
 				maxChars,
 				spillDir: this.outputDirectory(),
+				recoveryRoutes: this.recoveryRoutes(),
 				onError: (message) =>
 					this.log.warn('Failed to retain a tool output replaced for the message budget', {
 						[NAMZU.TURN_ID]: this.config.turnId,
@@ -1806,6 +1824,7 @@ export class ToolExecutor {
 			maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
 			retainedPreviewChars: this.config.retainedToolPreviewChars,
 			spillDir: this.outputDirectory(),
+			recoveryRoutes: this.recoveryRoutes(),
 			onError: (message) =>
 				this.log.warn('Failed to spill oversized nested tool output', {
 					[NAMZU.TURN_ID]: this.config.turnId,
@@ -1901,6 +1920,9 @@ export class ToolExecutor {
 			...(this.config.additionalDirectories?.length
 				? { additionalDirectories: this.config.additionalDirectories }
 				: {}),
+			...(this.outputDirectory()
+				? { retainedOutputDirectory: this.outputDirectory() as string }
+				: {}),
 			abortSignal: this.config.abortSignal,
 			env: this.config.env,
 			log: (level, message) => this.log[level](message),
@@ -2287,6 +2309,7 @@ export class ToolExecutor {
 			maxChars: maxToolOutputChars,
 			retainedPreviewChars: this.config.retainedToolPreviewChars,
 			spillDir: this.outputDirectory(),
+			recoveryRoutes: this.recoveryRoutes(),
 			onError: (message) =>
 				this.log.warn('Failed to retain original tool output', {
 					[NAMZU.TURN_ID]: this.config.turnId,
@@ -3177,6 +3200,7 @@ export class ToolExecutor {
 						spillDir: this.outputDirectory()
 							? join(this.outputDirectory() as string, 'content')
 							: undefined,
+						recoveryRoutes: this.recoveryRoutes(),
 						onError: (message) =>
 							this.log.warn('Failed to spill oversized model tool content', {
 								[NAMZU.TURN_ID]: this.config.turnId,

package/src/runtime/query/iteration/phases/compaction.ts

@@ -13,7 +13,11 @@ import type { ContextReducer, ContextReduction } from '../../../../compaction/re
 import { createSlidingWindowReducer } from '../../../../compaction/reducer.js'
 import { findRetainedIndices } from '../../../../compaction/retention.js'
 import { serializeState } from '../../../../compaction/serializer.js'
-import { buildCompactionMessage, isCompactionMessage } from '../../../../compaction/summary.js'
+import {
+	COMPACTION_RECOVERY_NOTE,
+	buildCompactionMessage,
+	isCompactionMessage,
+} from '../../../../compaction/summary.js'
 import { estimateMessagesTokens } from '../../../../compaction/token-estimate.js'
 import { buildVerifiedSummaryWithBoundedProvider } from '../../../../compaction/verifier.js'
 import type { CompactionConfig } from '../../../../config/runtime.js'
@@ -999,7 +1003,14 @@ async function runCompactionCheckInner(
 		compactedContent = serializeState(manager.getState())
 	}
 
-	const compactionMessage = buildCompactionMessage(compactedContent)
+	// The pointer is only worth a line when both tools it names are mounted.
+	const mounted = new Set(ctx.tools?.listNames?.() ?? [])
+	const compactionMessage = buildCompactionMessage(
+		compactedContent,
+		mounted.has('search_conversation') && mounted.has('read_conversation')
+			? COMPACTION_RECOVERY_NOTE
+			: undefined,
+	)
 
 	// Drop a replaceable PRIOR `[COMPACTED CONTEXT]` summary from this turn's
 	// leading floor — `serializeState` is cumulative, so the new summary