@namzu/sdk 1.0.0 → 1.1.0

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -2,7 +2,7 @@ import { createUserMessage } from '../../../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { RunEvent } from '../../../../types/run/index.js'
 import type { VerificationGate } from '../../../../verification/index.js'
-import type { IterationContext } from './context.js'
+import { type IterationContext, awaitDecisionOrAbort } from './context.js'
 
 interface VerificationAwareContext extends IterationContext {
 	readonly verificationGate?: VerificationGate
@@ -94,7 +94,7 @@ export async function* runToolReview(
 	})
 	yield* ctx.drainPending()
 
-	const reviewDecision = await ctx.resumeHandler({
+	const reviewDecision = await awaitDecisionOrAbort(ctx, {
 		type: 'tool_review',
 		runId: ctx.runMgr.id,
 		checkpointId: reviewCheckpoint.id,
@@ -198,7 +198,11 @@ export async function* runToolReview(
 		}
 
 		case 'approve_plan':
-		case 'reject_plan': {
+		case 'reject_plan':
+		// 'answer_question' belongs to an ask_user_question park, not a
+		// tool review — like the misdirected plan decisions above, warn
+		// and proceed with execution rather than stalling the run.
+		case 'answer_question': {
 			ctx.log.warn('Unexpected plan decision during tool review', {
 				action: reviewDecision.action,
 			})

package/src/runtime/query/iteration/phases/working-memory-compaction.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Regression test for the ses_055 Layer-B SDK seam (#104):
+ *
+ *   1. **Compaction FIRES** under a small `contextWindowTokens` even with the
+ *      run-level `tokenBudget = 0` (UNLIMITED) — proving the F1 fix repointed
+ *      BOTH the `<= 0` guard AND the divisor, closing the silent-no-op trap.
+ *   2. **The pinned working-memory slot SURVIVES** the compaction pass (it is a
+ *      leading system message → preserved by header identity).
+ *   3. **No premature stop** from `tokenBudget = 0` alone: with NO
+ *      `contextWindowTokens`, the same overflowing run does NOT compact (the
+ *      legacy fallback), so consumers that never set the new field are
+ *      byte-identical.
+ *
+ * The test drives `refreshWorkingMemory` (to pin the slot) then
+ * `runCompactionCheck` directly against a mock `IterationContext`, which is the
+ * exact sequence the iteration loop runs each turn.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import { findDanglingMessages } from '../../../../compaction/dangling.js'
+import { WorkingStateManager } from '../../../../compaction/manager.js'
+import { CompactionConfigSchema } from '../../../../config/runtime.js'
+import type { RunId } from '../../../../types/ids/index.js'
+import {
+	type Message,
+	createAssistantMessage,
+	createSystemMessage,
+	createToolMessage,
+	createUserMessage,
+} from '../../../../types/message/index.js'
+import type { Logger } from '../../../../utils/logger.js'
+import { runCompactionCheck } from './compaction.js'
+import type { IterationContext } from './context.js'
+import { WORKING_MEMORY_HEADER, refreshWorkingMemory } from './working-memory.js'
+
+function makeLogger(): Logger {
+	const self = {
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		debug: vi.fn(),
+		child: vi.fn(),
+	} as unknown as Logger
+	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
+	return self
+}
+
+/** A long string so a handful of messages overflow a small context window. */
+const FILLER = 'x'.repeat(200)
+
+function buildOverflowingMessages(): Message[] {
+	const msgs: Message[] = [createSystemMessage(`STATIC SYSTEM PROMPT ${FILLER}`, 'cache')]
+	for (let i = 0; i < 8; i++) {
+		msgs.push(createUserMessage(`user turn ${i} ${FILLER}`))
+		msgs.push(createAssistantMessage(`assistant turn ${i} ${FILLER}`))
+	}
+	return msgs
+}
+
+function makeCtx(opts: {
+	messages: Message[]
+	contextWindowTokens?: number
+	workingMemoryProvider?: IterationContext['workingMemoryProvider']
+}): IterationContext {
+	const config = CompactionConfigSchema.parse({
+		strategy: 'structured',
+		llmVerification: false,
+		...(opts.contextWindowTokens !== undefined
+			? { contextWindowTokens: opts.contextWindowTokens }
+			: {}),
+	})
+	const manager = new WorkingStateManager(config)
+	// Seed a couple of slots so serializeState produces non-trivial output.
+	manager.addDecision('built the report as .docx')
+
+	return {
+		runConfig: { tokenBudget: 0 }, // UNLIMITED cumulative cost cap
+		compactionConfig: config,
+		workingStateManager: manager,
+		workingMemoryProvider: opts.workingMemoryProvider,
+		log: makeLogger(),
+		runMgr: {
+			id: 'run_1' as RunId,
+			currentIteration: 3,
+			messages: opts.messages,
+		},
+	} as unknown as IterationContext
+}
+
+const WM_BLOCK =
+	'ARTIFACTS\n  • report.docx · Word document · 48.2 KB · imp:H\n       path: /mnt/user-data/outputs/report.docx'
+
+describe('Layer-B compaction seam (ses_055 #104)', () => {
+	it('FIRES on small contextWindowTokens with tokenBudget=0 AND preserves the pinned WM slot', async () => {
+		const messages = buildOverflowingMessages()
+		const ctx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => WM_BLOCK,
+		})
+
+		await refreshWorkingMemory(ctx)
+		// The slot is pinned as the last leading system message (index 1).
+		expect(messages[1]?.role).toBe('system')
+		expect(messages[1]?.content?.startsWith(WORKING_MEMORY_HEADER)).toBe(true)
+
+		const before = messages.length
+		await runCompactionCheck(ctx)
+
+		// (1) compaction fired: a [COMPACTED CONTEXT] message appeared and the
+		// transcript shrank.
+		expect(messages.length).toBeLessThan(before)
+		expect(messages.some((m) => m.content?.includes('[COMPACTED CONTEXT]'))).toBe(true)
+
+		// (2) the pinned working-memory slot survived by header identity.
+		const wm = messages.filter(
+			(m) => m.role === 'system' && m.content?.startsWith(WORKING_MEMORY_HEADER),
+		)
+		expect(wm).toHaveLength(1)
+		expect(wm[0]?.content).toContain('report.docx')
+	})
+
+	it('does NOT compact when contextWindowTokens is absent and tokenBudget=0 (byte-identical fallback)', async () => {
+		const messages = buildOverflowingMessages()
+		const ctx = makeCtx({ messages })
+
+		const before = messages.length
+		await runCompactionCheck(ctx)
+
+		// budget = tokenBudget = 0 → guard returns; no compaction, no mutation.
+		expect(messages.length).toBe(before)
+		expect(messages.some((m) => m.content?.includes('[COMPACTED CONTEXT]'))).toBe(false)
+	})
+
+	it('removes the slot when the provider returns an empty block', async () => {
+		const messages = buildOverflowingMessages()
+		const ctx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => WM_BLOCK,
+		})
+		await refreshWorkingMemory(ctx)
+		expect(messages.some((m) => m.content?.startsWith(WORKING_MEMORY_HEADER))).toBe(true)
+
+		// Same transcript, provider now returns blank ⇒ the slot is removed.
+		const blankCtx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => '   ',
+		})
+		await refreshWorkingMemory(blankCtx)
+		expect(messages.some((m) => m.content?.startsWith(WORKING_MEMORY_HEADER))).toBe(false)
+	})
+
+	it('keeps the prior slot when the provider throws (failure-isolated)', async () => {
+		const messages = buildOverflowingMessages()
+		const ctx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => WM_BLOCK,
+		})
+		await refreshWorkingMemory(ctx)
+
+		const throwingCtx = makeCtx({
+			messages,
+			contextWindowTokens: 100,
+			workingMemoryProvider: () => {
+				throw new Error('provider boom')
+			},
+		})
+		await refreshWorkingMemory(throwingCtx)
+		// Prior slot retained; run not broken.
+		expect(messages.some((m) => m.content?.startsWith(WORKING_MEMORY_HEADER))).toBe(true)
+	})
+
+	it('does NOT orphan a tool_result when the recent-window cut splits a tool pair (C1)', async () => {
+		// keepRecentMessages defaults to 4. Lay the transcript out so the NAIVE
+		// cut (length - 4 = index 5) lands right AFTER the assistant-with-toolCall
+		// (index 4) but BEFORE... no — exactly ON its tool result (index 5), which
+		// a naive slice would keep in the recent window while dropping the
+		// assistant into the summarized older set → an orphaned tool_result at the
+		// head of the recent window → Anthropic 400. The fix snaps keepStart
+		// forward past the complete pair.
+		const toolCall = {
+			id: 't1',
+			type: 'function' as const,
+			function: { name: 'read', arguments: '{}' },
+		}
+		const messages: Message[] = [
+			createSystemMessage(`STATIC SYSTEM PROMPT ${FILLER}`, 'cache'),
+			createUserMessage(`user 0 ${FILLER}`),
+			createAssistantMessage(`assistant 0 ${FILLER}`),
+			createUserMessage(`user 1 ${FILLER}`),
+			createAssistantMessage(`calling a tool ${FILLER}`, [toolCall]), // idx 4
+			createToolMessage(`tool result ${FILLER}`, 't1'), // idx 5 — naive recent[0]
+			createAssistantMessage(`assistant 2 ${FILLER}`),
+			createUserMessage(`user 3 ${FILLER}`),
+			createAssistantMessage(`assistant 3 ${FILLER}`),
+		]
+		const ctx = makeCtx({ messages, contextWindowTokens: 100 })
+
+		await runCompactionCheck(ctx)
+
+		// Compaction fired.
+		expect(messages.some((m) => m.content?.includes('[COMPACTED CONTEXT]'))).toBe(true)
+		// The surviving transcript has NO dangling tool pair — the tool result
+		// whose assistant was summarized away was moved into the older set too,
+		// so no orphaned tool_result remains to 400 the next provider turn.
+		expect(findDanglingMessages(messages).isValid).toBe(true)
+		// And a `tool` message never leads the recent window.
+		const firstNonSystem = messages.find((m) => m.role !== 'system')
+		expect(firstNonSystem?.role).not.toBe('tool')
+	})
+})

package/src/runtime/query/iteration/phases/working-memory.ts

@@ -0,0 +1,86 @@
+import { createSystemMessage } from '../../../../types/message/index.js'
+import type { IterationContext } from './context.js'
+
+/**
+ * Sentinel header identifying the single PINNED working-memory system message.
+ *
+ * The SDK finds + replaces the slot by this header every turn and uses the same
+ * identity to re-pin it if compaction ever drops it (the OPAQUE survival guard
+ * in `compaction.ts` — no host-format knowledge required). The host's rendered
+ * block is stored verbatim AFTER this header; the SDK never parses it.
+ */
+export const WORKING_MEMORY_HEADER =
+	'[WORKING MEMORY] Authoritative state for this conversation — you produced these.'
+
+/**
+ * True when `content` is the pinned working-memory slot (header identity only).
+ * Shared with `compaction.ts` so the survival guard re-pins by the SAME rule.
+ */
+export function isWorkingMemoryMessage(content: string | null | undefined): boolean {
+	return typeof content === 'string' && content.startsWith(WORKING_MEMORY_HEADER)
+}
+
+/**
+ * Resolve the host's working-memory string and rewrite a single PINNED leading
+ * system message in place. Insert-or-replace keyed by {@link WORKING_MEMORY_HEADER};
+ * an empty/blank string removes the slot.
+ *
+ * The slot is an EPHEMERAL system message placed as the LAST leading system
+ * message (after the cached static + dynamic system messages), so it never
+ * busts the prompt-cache prefix yet still rides inside the compaction-preserved
+ * leading-system run (the primacy edge Lost-in-the-Middle / Context-Rot need).
+ *
+ * Failure-isolated (the `web-search` seam rule): a throwing/slow provider
+ * degrades to "no refresh this turn" (keeps the prior slot), never breaks the
+ * run. Early-returns when no provider is configured ⇒ byte-identical run path.
+ */
+export async function refreshWorkingMemory(ctx: IterationContext): Promise<void> {
+	const provider = ctx.workingMemoryProvider
+	if (!provider) return
+
+	let block: string
+	try {
+		block =
+			(await provider({
+				runId: ctx.runMgr.id,
+				iteration: ctx.runMgr.currentIteration,
+			})) ?? ''
+	} catch (err) {
+		ctx.log.warn('workingMemoryProvider failed; keeping prior slot', {
+			runId: ctx.runMgr.id,
+			error: err instanceof Error ? err.message : String(err),
+		})
+		return
+	}
+
+	const msgs = ctx.runMgr.messages
+
+	// Bound the search to the LEADING system run (the compaction-preserved
+	// region). A working-memory header appearing later in the transcript (e.g.
+	// echoed by a tool result) must not be mistaken for the pinned slot.
+	let leadEnd = 0
+	while (leadEnd < msgs.length && msgs[leadEnd]?.role === 'system') leadEnd++
+
+	let idx = -1
+	for (let i = 0; i < leadEnd; i++) {
+		const m = msgs[i]
+		if (m && m.role === 'system' && isWorkingMemoryMessage(m.content)) {
+			idx = i
+			break
+		}
+	}
+
+	if (!block.trim()) {
+		// Empty block ⇒ remove the slot (byte-identical-when-empty).
+		if (idx >= 0) msgs.splice(idx, 1)
+		return
+	}
+
+	const wm = createSystemMessage(`${WORKING_MEMORY_HEADER}\n\n${block}`, 'ephemeral')
+	if (idx >= 0) {
+		msgs[idx] = wm
+	} else {
+		// Insert as the LAST leading system message (after static + dynamic).
+		msgs.splice(leadEnd, 0, wm)
+	}
+}

package/src/session/workspace/__tests__/shared-run.test.ts

@@ -148,7 +148,7 @@ describe('SharedRunWorkspace', () => {
 			runtimeRoot: '/mnt/user-data/outputs/_work',
 		})
 
-		const big = '# Task Context\n\n' + 'A'.repeat(40_000)
+		const big = `# Task Context\n\n${'A'.repeat(40_000)}`
 		const path = await workspace.writeTaskContext(big)
 		expect(path).toBe('/mnt/user-data/outputs/_work/01_task_context.md')
 		expect(workspace.refs().taskContextPath).toBe(path)

package/src/session/workspace/shared-run.ts

@@ -295,6 +295,7 @@ function ensureTrailingNewline(value: string): string {
 }
 
 async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
+	await mkdir(dirnameFor(path), { recursive: true })
 	const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`
 	await writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
 	await rename(tmpPath, path)

package/src/skills/loader.test.ts

@@ -16,11 +16,11 @@ describe('Agent Skills loader', () => {
 		const root = await mkdtemp(join(tmpdir(), 'namzu-skills-'))
 		const dir = await writeSkill(
 			root,
-			'project-documents',
+			'delivery-briefing',
 			[
 				'---',
-				'name: project-documents',
-				'description: Draft and edit grounded project documents.',
+				'name: delivery-briefing',
+				'description: Draft and edit grounded delivery briefings.',
 				'license: MIT',
 				'compatibility: Requires filesystem tools',
 				'allowed-tools: read write edit',
@@ -36,8 +36,8 @@ describe('Agent Skills loader', () => {
 		const result = await loadSkill(dir, 'metadata')
 
 		expect(result.skill.metadata).toEqual({
-			name: 'project-documents',
-			description: 'Draft and edit grounded project documents.',
+			name: 'delivery-briefing',
+			description: 'Draft and edit grounded delivery briefings.',
 			license: 'MIT',
 			compatibility: 'Requires filesystem tools',
 			allowedTools: 'read write edit',
@@ -53,11 +53,11 @@ describe('Agent Skills loader', () => {
 		const root = await mkdtemp(join(tmpdir(), 'namzu-skills-'))
 		const dir = await writeSkill(
 			root,
-			'long-form-files',
+			'structured-file-authoring',
 			[
 				'---',
-				'name: long-form-files',
-				'description: Create long files with bounded edit chunks.',
+				'name: structured-file-authoring',
+				'description: Create structured files with bounded edit chunks.',
 				'---',
 				'Use skeleton-first writes.',
 				'',

package/src/streaming/coalesce.test.ts

@@ -117,14 +117,14 @@ describe('coalesce()', () => {
 	})
 
 	it('emits new event after window expires', async () => {
-		const events: RunEvent[] = [
+		const events: [RunEvent, RunEvent] = [
 			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'a' },
 			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'b' },
 		]
 		const stream: AsyncIterable<RunEvent> = (async function* () {
-			yield events[0]!
+			yield events[0]
 			await new Promise((r) => setTimeout(r, 30))
-			yield events[1]!
+			yield events[1]
 		})()
 		const result = await drain(coalesce(stream, { windowMs: 16 }))
 		expect(result).toHaveLength(2)

package/src/tools/builtins/__tests__/payload-budget.test.ts

@@ -1,4 +1,8 @@
+import { mkdtempSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
+import type { ToolContext } from '../../../types/tool/index.js'
 import { EditTool } from '../edit.js'
 import { getBuiltinTools } from '../index.js'
 import { WriteFileTool } from '../write-file.js'
@@ -26,4 +30,63 @@ describe('filesystem tool payload budgeting', () => {
 		expect(names).toContain('edit')
 		expect(names).not.toContain('append')
 	})
+
+	it('assembles long documents with bounded write plus edit insert chunks', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-long-doc-'))
+		const ctx: ToolContext = {
+			runId: 'run_test' as ToolContext['runId'],
+			workingDirectory: dir,
+			abortSignal: new AbortController().signal,
+			env: {},
+			log: () => {},
+		}
+		const opening = '# Long document regression\n\n{{BODY}}\n'
+		const chunks = Array.from({ length: 6 }, (_, sectionIndex) => {
+			const lines = Array.from({ length: 45 }, (_, lineIndex) => {
+				const section = sectionIndex + 1
+				const line = lineIndex + 1
+				return `Section ${section}.${line}: this bounded paragraph proves long-form output grows through edit insertions rather than one oversized JSON tool argument.`
+			})
+			const chunk = [`## Section ${sectionIndex + 1}`, ...lines, ''].join('\n')
+			expect(chunk.length).toBeLessThan(12_000)
+			return chunk
+		})
+
+		const writeResult = await WriteFileTool.execute(
+			{ path: 'outputs/regression-long-document.md', content: opening },
+			ctx,
+		)
+		expect(writeResult.success).toBe(true)
+
+		const firstEdit = await EditTool.execute(
+			{
+				path: 'outputs/regression-long-document.md',
+				oldStr: '{{BODY}}',
+				newStr: chunks[0],
+				replace_all: false,
+			},
+			ctx,
+		)
+		expect(firstEdit.success).toBe(true)
+
+		for (const chunk of chunks.slice(1)) {
+			const result = await EditTool.execute(
+				{
+					path: 'outputs/regression-long-document.md',
+					insertLine: 'end',
+					newStr: chunk,
+					replace_all: false,
+				},
+				ctx,
+			)
+			expect(result.success).toBe(true)
+		}
+
+		const final = readFileSync(join(dir, 'outputs/regression-long-document.md'), 'utf-8')
+		expect(final).not.toContain('{{BODY}}')
+		expect(final.split('\n').length).toBeGreaterThan(250)
+		expect(final).toContain('## Section 1')
+		expect(final).toContain('## Section 6')
+		expect(final).toContain('Section 6.45')
+	})
 })

package/src/tools/builtins/__tests__/read-file.test.ts

@@ -28,4 +28,16 @@ describe('ReadFileTool', () => {
 		expect(result.success).toBe(true)
 		expect(result.output).toBe('2\ttwo\n3\tthree')
 	})
+
+	it('guides binary Office documents through extractor tooling', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-read-'))
+		writeFileSync(join(dir, 'transcript.docx'), Buffer.from('PK\x03\x04binary-docx'))
+
+		const result = await ReadFileTool.execute({ path: 'transcript.docx' }, makeContext(dir))
+
+		expect(result.success).toBe(false)
+		expect(result.output).toContain('DOCX document package')
+		expect(result.output).toContain('python-docx')
+		expect(result.data).toMatchObject({ binary: true })
+	})
 })

package/src/tools/builtins/read-file.ts

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { extname, resolve } from 'node:path'
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
 
@@ -35,6 +35,18 @@ export const ReadFileTool = defineTool({
 		// Sandbox-aware: route through sandbox.readFile() when available
 		if (context.sandbox) {
 			const buffer = await context.sandbox.readFile(input.path)
+			const binaryGuidance = describeStructuredBinaryRead(input.path, buffer)
+			if (binaryGuidance) {
+				return {
+					success: false,
+					output: binaryGuidance,
+					data: {
+						path: input.path,
+						sandboxed: true,
+						binary: true,
+					},
+				}
+			}
 			const content = buffer.toString('utf-8')
 			const lines = content.split('\n')
 
@@ -58,7 +70,19 @@ export const ReadFileTool = defineTool({
 		}
 
 		const filePath = resolve(context.workingDirectory, input.path)
-		const content = await readFile(filePath, 'utf-8')
+		const buffer = await readFile(filePath)
+		const binaryGuidance = describeStructuredBinaryRead(filePath, buffer)
+		if (binaryGuidance) {
+			return {
+				success: false,
+				output: binaryGuidance,
+				data: {
+					path: filePath,
+					binary: true,
+				},
+			}
+		}
+		const content = buffer.toString('utf-8')
 		const lines = content.split('\n')
 
 		const { start, end } = resolveReadWindow(input, lines.length)
@@ -80,6 +104,30 @@ export const ReadFileTool = defineTool({
 	},
 })
 
+function describeStructuredBinaryRead(path: string, buffer: Buffer): string | null {
+	const ext = extname(path).toLowerCase()
+	if (ext === '.docx') return buildStructuredBinaryGuidance(path, 'DOCX', 'python-docx')
+	if (ext === '.pptx') return buildStructuredBinaryGuidance(path, 'PPTX', 'python-pptx')
+	if (ext === '.xlsx') return buildStructuredBinaryGuidance(path, 'XLSX', 'openpyxl')
+	if (ext === '.pdf' || startsWithPdfHeader(buffer)) {
+		return buildStructuredBinaryGuidance(path, 'PDF', 'pdftotext or PyMuPDF')
+	}
+	return null
+}
+
+function startsWithPdfHeader(buffer: Buffer): boolean {
+	return buffer.length >= 4 && buffer.subarray(0, 4).toString('utf8') === '%PDF'
+}
+
+function buildStructuredBinaryGuidance(path: string, format: string, extractor: string): string {
+	return [
+		`The file "${path}" is a ${format} document package, not UTF-8 text.`,
+		'Do not use the read/cat tools as evidence for this raw file.',
+		`Extract its text with shell/Python tooling already available in the sandbox (${extractor}), write the extracted text or summary under scratch, then read that text file.`,
+		'If extraction fails, report the exact filename and extraction error instead of claiming the attachment is unavailable.',
+	].join('\n')
+}
+
 function resolveReadWindow(
 	input: z.infer<typeof inputSchema>,
 	totalLines: number,

package/src/tools/builtins/search-tools.ts

@@ -1,10 +1,22 @@
 import { z } from 'zod'
+import { toolDiscoveryHint } from '../../registry/tool/execute.js'
 import { defineTool } from '../defineTool.js'
 
 const inputSchema = z.object({
 	query: z.string().describe('Tool name or capability keyword to search for'),
 })
 
+// Activate only the best-ranked matches. Top-5 is the literature's sweet
+// spot (retrieval at k=5 matches oracle toolsets) and bounds how much
+// schema weight a single search can add to every subsequent iteration —
+// each activation also busts the prompt-cache prefix once.
+const ACTIVATION_TOP_K = 5
+
+// Near-misses are reported name+hint WITHOUT activating, so a retrieval
+// miss becomes one cheap re-query instead of a dead end (the fixed-top-k
+// hard-tail failure mode: the right tool ranked 6th-10th).
+const NEAR_MISS_LIMIT = 5
+
 export const SearchToolsTool = defineTool({
 	name: 'search_tools',
 	description:
@@ -28,27 +40,46 @@ export const SearchToolsTool = defineTool({
 
 		const allowed =
 			context.allowedTools && context.allowedTools.length > 0 ? new Set(context.allowedTools) : null
-		const matches = context.toolRegistry
+		// `searchDeferred` returns a ranked list (score-descending), so slicing
+		// the head is a true top-k activation, not an arbitrary subset.
+		const ranked = context.toolRegistry
 			.searchDeferred(input.query)
 			.filter((tool) => !allowed || allowed.has(tool.name))
 
-		if (matches.length === 0) {
+		if (ranked.length === 0) {
 			return {
 				success: true,
 				output: `No deferred tools matching "${input.query}". All matching tools are already active.`,
 			}
 		}
 
-		context.toolRegistry.activate(matches.map((t) => t.name))
+		const activated = ranked.slice(0, ACTIVATION_TOP_K)
+		const nearMisses = ranked.slice(ACTIVATION_TOP_K, ACTIVATION_TOP_K + NEAR_MISS_LIMIT)
+
+		context.toolRegistry.activate(activated.map((t) => t.name))
 
-		const descriptions = matches.map((t) => `- ${t.name}: ${t.description}`).join('\n')
+		const descriptions = activated.map((t) => `- ${t.name}: ${t.description}`).join('\n')
+		const sections = [`Activated ${activated.length} tool(s):\n${descriptions}`]
+
+		if (nearMisses.length > 0) {
+			const hints = nearMisses
+				.map((t) => {
+					const hint = toolDiscoveryHint(t.description)
+					return hint.length > 0 ? `- ${t.name}: ${hint}` : `- ${t.name}`
+				})
+				.join('\n')
+			sections.push(
+				`Also matched but NOT loaded (search again with a more specific query, e.g. the tool name, to load one of these):\n${hints}`,
+			)
+		}
 
 		return {
 			success: true,
-			output: `Activated ${matches.length} tool(s):\n${descriptions}`,
+			output: sections.join('\n\n'),
 			data: {
-				activated: matches.map((t) => t.name),
-				count: matches.length,
+				activated: activated.map((t) => t.name),
+				count: activated.length,
+				nearMisses: nearMisses.map((t) => t.name),
 			},
 		}
 	},