@namzu/sdk 3.0.0 → 3.2.0

package/src/public-types.ts

@@ -134,6 +134,7 @@ export type {
 	HybridExecutionContextOptions,
 	LocalExecutionContextOptions,
 	MCPServerResourceProvider,
+	MCPServerPromptProvider,
 	MCPServerToolProvider,
 	RemoteExecutionContextOptions,
 	TenantConnectorManagerConfig,
@@ -157,6 +158,10 @@ export type { ToolCallContext } from './verification/index.js'
 export type { DiskSessionStoreConfig, LinkageView } from './store/session/index.js'
 
 export type {
+	ContextReducer,
+	ContextReduction,
+	ContextReductionReason,
+	SlidingWindowOptions,
 	ConversationManager,
 	CompactionStrategy,
 	DanglingResult,

package/src/rag/__tests__/namespace-isolation.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest'
+
+import type { EmbeddingProvider, TenantScope } from '../../types/rag/index.js'
+import { DefaultIngestionPipeline } from '../ingestion.js'
+import { DefaultRetriever } from '../retriever.js'
+import { InMemoryVectorStore } from '../vector-store.js'
+
+/**
+ * `TenantScope.namespace` and `KnowledgeBaseConfig.namespace` were declared
+ * from the start and neither reached storage. Ingestion copied
+ * `scope.tenantId` onto every chunk and dropped the namespace; the store
+ * filtered on tenant alone. So a partition a host asked for did not exist,
+ * and every namespace in a tenant saw every other one's documents.
+ */
+
+/** Deterministic and content-derived, so similarity is stable across runs. */
+const embedder: EmbeddingProvider = {
+	async embed(texts: string[]) {
+		return texts.map((t) => [t.length % 7, t.charCodeAt(0) % 5, 1])
+	},
+	async embedQuery(text: string) {
+		return [text.length % 7, text.charCodeAt(0) % 5, 1]
+	},
+	dimensions: 3,
+	model: 'test-embedder',
+	id: 'test-embedder',
+}
+
+const tenant = 'tnt_one' as TenantScope['tenantId']
+
+function scope(namespace?: string): TenantScope {
+	return { tenantId: tenant, ...(namespace !== undefined ? { namespace } : {}) }
+}
+
+async function seed() {
+	const store = new InMemoryVectorStore()
+	const ingestion = new DefaultIngestionPipeline(store, embedder)
+	const kb = 'kb_one' as never
+
+	await ingestion.ingest('alpha partition content', {}, scope('alpha'), kb)
+	await ingestion.ingest('beta partition content', {}, scope('beta'), kb)
+	await ingestion.ingest('default partition content', {}, scope(), kb)
+
+	return { store, retriever: new DefaultRetriever(store, embedder), kb }
+}
+
+const texts = (r: { chunks: { chunk: { content: string } }[] }) =>
+	r.chunks.map((c) => c.chunk.content)
+
+describe('a namespace partitions what a query can see', () => {
+	it('returns only its own partition', async () => {
+		const { retriever, kb } = await seed()
+
+		const found = await retriever.retrieve({ text: 'partition content' }, scope('alpha'), kb)
+
+		expect(texts(found)).toEqual(['alpha partition content'])
+	})
+
+	it('does not leak the other partition', async () => {
+		const { retriever, kb } = await seed()
+
+		const found = await retriever.retrieve({ text: 'partition content' }, scope('beta'), kb)
+
+		expect(texts(found).join()).not.toContain('alpha')
+	})
+
+	it('treats an absent namespace as the default partition, not as no filter', async () => {
+		const { retriever, kb } = await seed()
+
+		const found = await retriever.retrieve({ text: 'partition content' }, scope(), kb)
+
+		// The whole point. Reading absence as "no filter" is how the boundary
+		// leaks: a caller who never asked for a namespace would see every
+		// namespaced chunk in the tenant.
+		expect(texts(found)).toEqual(['default partition content'])
+	})
+
+	it('keeps tenants apart as it always did', async () => {
+		const { retriever, kb } = await seed()
+
+		const found = await retriever.retrieve(
+			{ text: 'partition content' },
+			{
+				tenantId: 'tnt_other' as TenantScope['tenantId'],
+				namespace: 'alpha',
+			},
+			kb,
+		)
+
+		expect(found.chunks).toEqual([])
+	})
+
+	it('stamps the namespace onto the chunk at ingest', async () => {
+		const { store } = await seed()
+
+		const results = await store.search({
+			embedding: await embedder.embedQuery('partition content'),
+			topK: 10,
+			tenantId: tenant,
+			namespace: 'alpha',
+		})
+
+		// Ingest is where it has to land — filtering at search against a value
+		// nothing writes returns zero rows, and "no results" reads as "nothing
+		// matched" rather than "this scope was never stored".
+		expect(results.every((r) => r.chunk.content.startsWith('alpha'))).toBe(true)
+		expect(results.length).toBeGreaterThan(0)
+	})
+})

package/src/rag/ingestion.ts

@@ -48,6 +48,7 @@ export class DefaultIngestionPipeline implements IngestionPipeline {
 			documentId,
 			knowledgeBaseId,
 			tenantId: scope.tenantId,
+			...(scope.namespace !== undefined ? { namespace: scope.namespace } : {}),
 			content: cc.content,
 			index: cc.index,
 			tokenCount: estimateTokens(cc.content),

package/src/rag/retriever.ts

@@ -76,6 +76,7 @@ export class DefaultRetriever implements Retriever {
 			embedding,
 			topK: config.topK,
 			tenantId: scope.tenantId,
+			...(scope.namespace !== undefined ? { namespace: scope.namespace } : {}),
 			knowledgeBaseId,
 			minScore: config.minScore,
 		})
@@ -92,6 +93,7 @@ export class DefaultRetriever implements Retriever {
 			embedding,
 			topK: config.topK * 2,
 			tenantId: scope.tenantId,
+			...(scope.namespace !== undefined ? { namespace: scope.namespace } : {}),
 			knowledgeBaseId,
 			minScore: 0,
 		})

package/src/rag/vector-store.ts

@@ -20,6 +20,11 @@ export class InMemoryVectorStore implements VectorStore {
 
 		for (const chunk of this.chunks.values()) {
 			if (chunk.tenantId !== query.tenantId) continue
+			// Equality INCLUDING absence: an omitted namespace is the default
+			// partition, not the absence of a filter. Treating it as no filter
+			// is how the boundary leaks — a caller who never asked for a
+			// namespace would see every namespaced chunk in the tenant.
+			if (chunk.namespace !== query.namespace) continue
 			if (query.knowledgeBaseId && chunk.knowledgeBaseId !== query.knowledgeBaseId) continue
 			if (!chunk.embedding) continue
 

package/src/registry/tool/execute.ts

@@ -375,151 +375,155 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 			: otelContext.active()
 
 		return tracer.startActiveSpan(toolSpanName(toolName), {}, parentCtx, async (span) => {
-			span.setAttributes({
-				[GENAI.TOOL_NAME]: toolName,
-				[GENAI.TOOL_TYPE]: 'function',
-			})
-
-			const tool = this.getOrThrow(toolName)
-
-			const availability = this.getAvailability(toolName)
-			if (availability !== 'active') {
-				const msg = `Tool "${toolName}" is ${availability} and cannot be executed`
-				this.log.warn(msg)
+			try {
 				span.setAttributes({
-					[NAMZU.TOOL_SUCCESS]: false,
-					[NAMZU.TOOL_ERROR]: msg,
+					[GENAI.TOOL_NAME]: toolName,
+					[GENAI.TOOL_TYPE]: 'function',
 				})
-				span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
-				span.end()
-				return {
-					success: false,
-					output: '',
-					error: msg,
-				}
-			}
 
-			const mode = context.permissionContext?.mode ?? 'auto'
-			if (mode === 'plan') {
-				const isReadOnly = tool.isReadOnly ? tool.isReadOnly(rawInput) : false
-				if (!isReadOnly) {
-					const msg = `plan mode: non-read-only tool "${toolName}" blocked`
+				const tool = this.getOrThrow(toolName)
+
+				const availability = this.getAvailability(toolName)
+				if (availability !== 'active') {
+					const msg = `Tool "${toolName}" is ${availability} and cannot be executed`
+					this.log.warn(msg)
 					span.setAttributes({
 						[NAMZU.TOOL_SUCCESS]: false,
 						[NAMZU.TOOL_ERROR]: msg,
 					})
 					span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
-					span.end()
 					return {
 						success: false,
 						output: '',
 						error: msg,
-						permissionDenied: true,
-						permissionMessage: msg,
 					}
 				}
-			}
 
-			const parseResult = tool.inputSchema.safeParse(rawInput)
-			if (!parseResult.success) {
-				const errorMessage = parseResult.error.issues
-					.map((i) => `${i.path.join('.')}: ${i.message}`)
-					.join('; ')
-
-				// Distinguish "model sent an empty/no-arg call" from
-				// "model sent partial args" — the first is most often a
-				// streaming hiccup or a definition-test ping (a provider
-				// occasionally pings tool surfaces with `{}` while the
-				// schema is still loading), the second is a genuine
-				// programming mistake by the model. The model self-
-				// corrects MUCH more reliably when the error tells it
-				// (a) which fields are required, (b) their types, and
-				// (c) a minimal example call. Without these hints the
-				// downstream UI just shows a red "Failed" row and the
-				// model rarely retries with the right args.
-				const isEmptyInput =
-					rawInput === null ||
-					rawInput === undefined ||
-					(typeof rawInput === 'object' &&
-						!Array.isArray(rawInput) &&
-						Object.keys(rawInput as Record<string, unknown>).length === 0)
-
-				const requiredHint = describeRequiredInput(tool.inputSchema)
-				// A conditional schema's required shape cannot be reconstructed
-				// from JSON Schema's top-level `required`, so the author gets to
-				// say what a valid retry looks like.
-				const recoveryHint = tool.validationErrorHint?.trim()
-					? ` ${tool.validationErrorHint.trim()}`
-					: ''
-
-				const enrichedMessage = isEmptyInput
-					? `Tool "${toolName}" was called with no arguments. ${requiredHint}${recoveryHint} Retry the call with the required parameters populated.`
-					: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}${recoveryHint}`
-
-				this.log.error(`Tool input validation failed: ${toolName}`, {
-					errors: errorMessage,
-					empty: isEmptyInput,
-				})
+				const mode = context.permissionContext?.mode ?? 'auto'
+				if (mode === 'plan') {
+					const isReadOnly = tool.isReadOnly ? tool.isReadOnly(rawInput) : false
+					if (!isReadOnly) {
+						const msg = `plan mode: non-read-only tool "${toolName}" blocked`
+						span.setAttributes({
+							[NAMZU.TOOL_SUCCESS]: false,
+							[NAMZU.TOOL_ERROR]: msg,
+						})
+						span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
+						return {
+							success: false,
+							output: '',
+							error: msg,
+							permissionDenied: true,
+							permissionMessage: msg,
+						}
+					}
+				}
 
-				span.setAttributes({
-					[NAMZU.TOOL_SUCCESS]: false,
-					[NAMZU.TOOL_ERROR]: `Validation: ${errorMessage}`,
-				})
-				span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
-				span.end()
+				const parseResult = tool.inputSchema.safeParse(rawInput)
+				if (!parseResult.success) {
+					const errorMessage = parseResult.error.issues
+						.map((i) => `${i.path.join('.')}: ${i.message}`)
+						.join('; ')
+
+					// Distinguish "model sent an empty/no-arg call" from
+					// "model sent partial args" — the first is most often a
+					// streaming hiccup or a definition-test ping (a provider
+					// occasionally pings tool surfaces with `{}` while the
+					// schema is still loading), the second is a genuine
+					// programming mistake by the model. The model self-
+					// corrects MUCH more reliably when the error tells it
+					// (a) which fields are required, (b) their types, and
+					// (c) a minimal example call. Without these hints the
+					// downstream UI just shows a red "Failed" row and the
+					// model rarely retries with the right args.
+					const isEmptyInput =
+						rawInput === null ||
+						rawInput === undefined ||
+						(typeof rawInput === 'object' &&
+							!Array.isArray(rawInput) &&
+							Object.keys(rawInput as Record<string, unknown>).length === 0)
+
+					const requiredHint = describeRequiredInput(tool.inputSchema)
+					// A conditional schema's required shape cannot be reconstructed
+					// from JSON Schema's top-level `required`, so the author gets to
+					// say what a valid retry looks like.
+					const recoveryHint = tool.validationErrorHint?.trim()
+						? ` ${tool.validationErrorHint.trim()}`
+						: ''
+
+					const enrichedMessage = isEmptyInput
+						? `Tool "${toolName}" was called with no arguments. ${requiredHint}${recoveryHint} Retry the call with the required parameters populated.`
+						: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}${recoveryHint}`
+
+					this.log.error(`Tool input validation failed: ${toolName}`, {
+						errors: errorMessage,
+						empty: isEmptyInput,
+					})
 
-				return {
-					success: false,
-					output: '',
-					error: enrichedMessage,
+					span.setAttributes({
+						[NAMZU.TOOL_SUCCESS]: false,
+						[NAMZU.TOOL_ERROR]: `Validation: ${errorMessage}`,
+					})
+					span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
+
+					return {
+						success: false,
+						output: '',
+						error: enrichedMessage,
+					}
 				}
-			}
 
-			const finalInput = parseResult.data
+				const finalInput = parseResult.data
 
-			try {
-				this.log.debug(`Executing tool: ${toolName}`)
-				const startedAt = Date.now()
-				const result = await tool.execute(finalInput, context)
-				const durationMs = Date.now() - startedAt
-				this.log.debug(`Tool completed: ${toolName}`, {
-					success: result.success,
-				})
+				try {
+					this.log.debug(`Executing tool: ${toolName}`)
+					const startedAt = Date.now()
+					const result = await tool.execute(finalInput, context)
+					const durationMs = Date.now() - startedAt
+					this.log.debug(`Tool completed: ${toolName}`, {
+						success: result.success,
+					})
 
-				span.setAttribute(NAMZU.TOOL_SUCCESS, result.success)
-				recordToolCall(
-					toolName,
-					result.success,
-					result.success ? undefined : result.error,
-					durationMs,
-				)
-				if (!result.success && result.error) {
-					span.setAttribute(NAMZU.TOOL_ERROR, result.error)
-					span.setStatus({ code: SpanStatusCode.ERROR, message: result.error })
-				} else {
-					span.setStatus({ code: SpanStatusCode.OK })
-				}
+					span.setAttribute(NAMZU.TOOL_SUCCESS, result.success)
+					recordToolCall(
+						toolName,
+						result.success,
+						result.success ? undefined : result.error,
+						durationMs,
+					)
+					if (!result.success && result.error) {
+						span.setAttribute(NAMZU.TOOL_ERROR, result.error)
+						span.setStatus({ code: SpanStatusCode.ERROR, message: result.error })
+					} else {
+						span.setStatus({ code: SpanStatusCode.OK })
+					}
 
-				return result
-			} catch (err) {
-				const errorMessage = toErrorMessage(err)
-				this.log.error(`Tool execution error: ${toolName}`, {
-					error: errorMessage,
-				})
+					return result
+				} catch (err) {
+					const errorMessage = toErrorMessage(err)
+					this.log.error(`Tool execution error: ${toolName}`, {
+						error: errorMessage,
+					})
 
-				span.setAttributes({
-					[NAMZU.TOOL_SUCCESS]: false,
-					[NAMZU.TOOL_ERROR]: errorMessage,
-				})
-				span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
-				span.recordException(err instanceof Error ? err : new Error(errorMessage))
+					span.setAttributes({
+						[NAMZU.TOOL_SUCCESS]: false,
+						[NAMZU.TOOL_ERROR]: errorMessage,
+					})
+					span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
+					span.recordException(err instanceof Error ? err : new Error(errorMessage))
 
-				return {
-					success: false,
-					output: '',
-					error: `Tool "${toolName}" execution failed: ${errorMessage}`,
+					return {
+						success: false,
+						output: '',
+						error: `Tool "${toolName}" execution failed: ${errorMessage}`,
+					}
 				}
 			} finally {
+				// The only place this span ends. It used to be ended at three
+				// early returns and in a finally that opened below them, so
+				// anything throwing before that try — `getOrThrow` on a name the
+				// registry does not hold, for one — left the span open and the
+				// tool's trace unclosed.
 				span.end()
 			}
 		})

package/src/runtime/query/__tests__/capability-negotiation.test.ts

@@ -44,6 +44,26 @@ const NO_VISION_CAPABILITIES: ProviderCapabilities = {
 	supportsVision: false,
 }
 
+/**
+ * A tool that opts in to constrained generation, which is the only thing
+ * that makes `enforceToolInputSchema` non-empty on the wire.
+ */
+function registerEnforcedTool(tools: ToolRegistry, name: string): void {
+	tools.register({
+		name,
+		description: `${name} tool`,
+		inputSchema: z.object({ new_string: z.string().optional(), newStr: z.string().optional() }),
+		modelInputSchema: {
+			type: 'object',
+			properties: { new_string: { type: 'string' } },
+			required: ['new_string'],
+			additionalProperties: false,
+		},
+		enforceModelInput: true,
+		execute: async () => ({ success: true, output: 'ok' }),
+	})
+}
+
 function registerEchoTool(tools: ToolRegistry): void {
 	tools.register({
 		name: 'echo',
@@ -229,4 +249,53 @@ describe('query() capability negotiation', () => {
 			}),
 		).rejects.toThrow(/supportsVision: false/)
 	})
+
+	it('names the enforced tools on the request, so a driver can constrain them', async () => {
+		const provider = capturingProvider()
+		const tools = new ToolRegistry()
+		registerEnforcedTool(tools, 'edit')
+		registerEnforcedTool(tools, 'write')
+		registerEchoTool(tools)
+
+		const run = await drainQuery({
+			...baseParams(provider, tools, await mkWorkdir()),
+			messages: [createUserMessage('hello')],
+		})
+
+		expect(run.status).toBe('completed')
+		// The producer was deleted, so this was undefined on every request and
+		// the three drivers that read it were reading a field nothing ever
+		// set — `enforceModelInput` on a tool meant nothing end to end.
+		expect(provider.requests.at(-1)?.enforceToolInputSchema).toEqual(['edit', 'write'])
+	})
+
+	it('omits the field entirely when no tool opts in', async () => {
+		const provider = capturingProvider()
+		const tools = new ToolRegistry()
+		registerEchoTool(tools)
+
+		await drainQuery({
+			...baseParams(provider, tools, await mkWorkdir()),
+			messages: [createUserMessage('hello')],
+		})
+
+		// An empty array would read as "enforce nothing" rather than "nothing
+		// asked", and a driver cannot tell those two apart.
+		expect(provider.requests.at(-1)?.enforceToolInputSchema).toBeUndefined()
+	})
+
+	it('follows the allowed set rather than everything registered', async () => {
+		const provider = capturingProvider()
+		const tools = new ToolRegistry()
+		registerEnforcedTool(tools, 'edit')
+		registerEnforcedTool(tools, 'excluded')
+
+		await drainQuery({
+			...baseParams(provider, tools, await mkWorkdir()),
+			allowedTools: ['edit'],
+			messages: [createUserMessage('hello')],
+		})
+
+		expect(provider.requests.at(-1)?.enforceToolInputSchema).toEqual(['edit'])
+	})
 })

package/src/runtime/query/__tests__/per-step-skills.test.ts

@@ -0,0 +1,154 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { MockLLMProvider } from '../../../provider/mock.js'
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import type { SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import type { Skill } from '../../../types/skills/index.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * A run's skills are fixed at `query()` time and rendered into the cached
+ * system prefix, so every skill a run might ever need is paid for on every
+ * turn. A phased agent rarely needs them all at once.
+ *
+ * A peer runtime resolves instructions, model, tools, skills and subagents
+ * from context at run time. namzu had the first three; this is the fourth.
+ * The fifth is deliberately absent — see the note at the bottom.
+ */
+
+let workdirs: string[] = []
+
+afterEach(async () => {
+	await Promise.all(workdirs.map((d) => rm(d, { recursive: true, force: true })))
+	workdirs = []
+})
+
+function skill(name: string, body?: string): Skill {
+	return {
+		metadata: { name, description: `${name} description` },
+		dirPath: `/skills/${name}`,
+		...(body !== undefined ? { body } : {}),
+	}
+}
+
+async function run(provider: MockLLMProvider, over: Record<string, unknown> = {}): Promise<void> {
+	const dir = await mkdtemp(join(tmpdir(), 'namzu-skills-'))
+	workdirs.push(dir)
+	await drainQuery({
+		provider,
+		tools: new ToolRegistry(),
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 30_000,
+			tokenBudget: 100_000,
+			maxIterations: 4,
+			maxResponseTokens: 256,
+		},
+		agentId: 'agent_sk',
+		agentName: 'Skill Agent',
+		workingDirectory: dir,
+		sessionId: 'ses_sk' as SessionId,
+		threadId: 'thd_sk' as ThreadId,
+		projectId: 'prj_sk' as ProjectId,
+		tenantId: 'tnt_sk' as TenantId,
+		messages: [createUserMessage('go')],
+		...over,
+	} as never)
+}
+
+const sent = (provider: MockLLMProvider, index = 0): string =>
+	JSON.stringify(provider.requests.at(index)?.messages ?? [])
+
+describe('a step can put a skill in front of the model', () => {
+	it('renders the skill it named', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] })
+
+		await run(provider, { prepareStep: () => ({ skills: [skill('search-the-web')] }) })
+
+		expect(sent(provider)).toContain('search-the-web')
+	})
+
+	it('sends nothing extra when the step names none', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] })
+
+		await run(provider)
+
+		expect(sent(provider)).not.toContain('Available Skills')
+	})
+
+	it('treats an empty list as naming none', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] })
+
+		await run(provider, { prepareStep: () => ({ skills: [] }) })
+
+		// An empty list is a caller saying "no skills this step", not a
+		// request for an empty section header.
+		expect(sent(provider)).not.toContain('Available Skills')
+	})
+
+	it('carries the step guidance alongside it', async () => {
+		const provider = new MockLLMProvider({ turns: [{ text: 'done' }] })
+
+		await run(provider, {
+			prepareStep: () => ({ system: 'You are researching.', skills: [skill('search-the-web')] }),
+		})
+
+		// Both ride the same ephemeral trailing message; neither should
+		// displace the other.
+		const body = sent(provider)
+		expect(body).toContain('You are researching.')
+		expect(body).toContain('search-the-web')
+	})
+})
+
+describe('a step skill does not outlive its step', () => {
+	it('is absent from the next step that does not ask for it', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ toolCalls: [] as never, text: 'thinking' }, { text: 'done' }],
+		})
+
+		await run(provider, {
+			prepareStep: ({ stepNumber }: { stepNumber: number }) =>
+				stepNumber === 1 ? { skills: [skill('search-the-web')] } : {},
+		})
+
+		expect(sent(provider, 0)).toContain('search-the-web')
+		if (provider.requests.length > 1) {
+			expect(sent(provider, 1)).not.toContain('search-the-web')
+		}
+	})
+
+	it('does not accumulate across steps', async () => {
+		const provider = new MockLLMProvider({
+			turns: [{ text: 'still working' }, { text: 'done' }],
+		})
+
+		await run(provider, {
+			maxIterations: 2,
+			prepareStep: () => ({ skills: [skill('search-the-web')] }),
+		})
+
+		// Appended for the call, never retained. Were it written into the run's
+		// history the section would stack up turn after turn — the same
+		// message repeated, growing the prompt and invalidating the cached
+		// prefix every iteration.
+		const systemCounts = provider.requests.map(
+			(r) => (r.messages ?? []).filter((m) => m.role === 'system').length,
+		)
+		expect(new Set(systemCounts).size).toBe(1)
+	})
+})
+
+/**
+ * Sub-agents are deliberately NOT per-step, and this is the note rather than
+ * a test that would pretend otherwise. Which agents `create_task` can reach
+ * is baked into that tool's input schema, so varying it per step would
+ * rebuild the tool catalogue every turn — a worse prompt-cache trade than
+ * moving tools around, for a narrowing a step can already express by
+ * withholding `create_task` through `activeTools`.
+ */