@namzu/sdk 0.4.1 → 0.4.3

package/src/rag/context-assembler.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `assembleRAGContext([], cfg)` returns `{content: '', sources: [],
+ *     tokenCount: 0}` immediately.
+ *   - Token estimation: `Math.ceil(text.length / 4)`.
+ *   - `headerTemplate` is prepended before any chunks.
+ *   - Chunks are included in order while their accumulated token count
+ *     stays below `maxTokens`; the first chunk that would overflow is
+ *     dropped along with every subsequent chunk (early break).
+ *   - `includeMetadata: true` prefixes each chunk with a bracketed
+ *     metadata line (`Source: …`, `Title: …`, `Relevance: XX.X%`).
+ *   - `sources[]` captures a truncated preview (first 200 chars) of
+ *     each INCLUDED chunk; skipped chunks are NOT present.
+ *   - `content` is the joined parts with `config.separator`;
+ *     `tokenCount` is re-estimated from the joined content.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ChunkId, DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { VectorSearchResult } from '../types/rag/index.js'
+
+import { assembleRAGContext } from './context-assembler.js'
+
+function result(
+	content: string,
+	score = 0.9,
+	meta: Record<string, unknown> = {},
+): VectorSearchResult {
+	return {
+		chunk: {
+			id: `c_${content.slice(0, 3)}` as ChunkId,
+			documentId: 'doc_1' as DocumentId,
+			knowledgeBaseId: 'kb_1' as KnowledgeBaseId,
+			tenantId: 't_1' as TenantId,
+			content,
+			index: 0,
+			tokenCount: 0,
+			metadata: meta,
+			createdAt: 0,
+		},
+		score,
+	}
+}
+
+describe('assembleRAGContext', () => {
+	it('returns empty for empty input', () => {
+		expect(assembleRAGContext([])).toEqual({ content: '', sources: [], tokenCount: 0 })
+	})
+
+	it('joins non-empty chunks with the configured separator', () => {
+		const ctx = assembleRAGContext([result('alpha'), result('beta')], {
+			separator: ' | ',
+			maxTokens: 1000,
+			includeMetadata: false,
+			headerTemplate: undefined,
+		})
+		expect(ctx.content).toBe('alpha | beta')
+	})
+
+	it('includes a headerTemplate before chunks when provided', () => {
+		const ctx = assembleRAGContext([result('body')], {
+			separator: '\n',
+			maxTokens: 1000,
+			includeMetadata: false,
+			headerTemplate: '### Knowledge',
+		})
+		expect(ctx.content.startsWith('### Knowledge\n')).toBe(true)
+	})
+
+	it('early-breaks once a chunk would overflow maxTokens (and drops subsequent)', () => {
+		const long = 'a'.repeat(200) // ~50 tokens per the /4 estimate
+		const ctx = assembleRAGContext([result('tiny'), result(long), result('also-tiny')], {
+			separator: '\n',
+			maxTokens: 20,
+			includeMetadata: false,
+			headerTemplate: undefined,
+		})
+		expect(ctx.content).toBe('tiny')
+		// third chunk was NOT included even though it would fit — the loop breaks on first overflow.
+		expect(ctx.sources.map((s) => s.chunk.slice(0, 10))).toEqual(['tiny'])
+	})
+
+	it('includeMetadata prefixes entries with bracketed metadata', () => {
+		const ctx = assembleRAGContext([result('body', 0.7567, { source: 'repo', title: 'README' })], {
+			separator: '\n',
+			maxTokens: 1000,
+			includeMetadata: true,
+		})
+		expect(ctx.content).toContain('[Source: repo | Title: README | Relevance: 75.7%]')
+	})
+
+	it('sources[] carries the first 200 chars of each included chunk', () => {
+		const long = 'x'.repeat(500)
+		const ctx = assembleRAGContext([result(long)], {
+			separator: '\n',
+			maxTokens: 10000,
+			includeMetadata: false,
+		})
+		expect(ctx.sources[0]?.chunk).toHaveLength(200)
+	})
+
+	it('tokenCount is derived from the final joined content', () => {
+		const ctx = assembleRAGContext([result('abcd'), result('efgh')], {
+			separator: '',
+			maxTokens: 1000,
+			includeMetadata: false,
+			headerTemplate: undefined,
+		})
+		// 'abcdefgh' → Math.ceil(8 / 4) = 2
+		expect(ctx.tokenCount).toBe(2)
+	})
+})

package/src/rag/embedding.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `OpenRouterEmbeddingProvider`:
+ *     - Defaults: dimensions = 1536; baseUrl = openrouter.ai/api/v1;
+ *       batchSize = 64.
+ *     - `embed(texts)` batches into `batchSize` slices and concatenates
+ *       results in input order.
+ *     - Each HTTP call posts `{model, input, dimensions}` to
+ *       `${baseUrl}/embeddings` with the Bearer authorization header.
+ *     - The API response is sorted by `index` ascending before extracting
+ *       `.embedding`, so results match input order even if the server
+ *       re-orders.
+ *     - `embedQuery(query)` returns the first result from `embed([query])`;
+ *       throws when the response is empty.
+ *     - `!response.ok` → throws with `Embedding API error (<status>): <body>`.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { OpenRouterEmbeddingProvider } from './embedding.js'
+
+describe('OpenRouterEmbeddingProvider', () => {
+	let fetchMock: ReturnType<typeof vi.fn>
+
+	beforeEach(() => {
+		fetchMock = vi.fn()
+		global.fetch = fetchMock as unknown as typeof fetch
+	})
+
+	afterEach(() => {
+		vi.restoreAllMocks()
+	})
+
+	it('carries model / dimensions defaults + batchSize', () => {
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		expect(p.model).toBe('m')
+		expect(p.dimensions).toBe(1536)
+	})
+
+	it('honors overrides for dimensions + baseUrl + batchSize', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({ data: [{ index: 0, embedding: [1, 2, 3] }] }),
+		})
+		const p = new OpenRouterEmbeddingProvider({
+			apiKey: 'k',
+			model: 'm',
+			dimensions: 256,
+			baseUrl: 'https://custom.example/api',
+		})
+		await p.embed(['x'])
+
+		expect(fetchMock).toHaveBeenCalledWith(
+			'https://custom.example/api/embeddings',
+			expect.objectContaining({
+				method: 'POST',
+				headers: expect.objectContaining({
+					Authorization: 'Bearer k',
+					'Content-Type': 'application/json',
+				}),
+			}),
+		)
+		const body = JSON.parse((fetchMock.mock.calls[0]?.[1] as { body: string }).body)
+		expect(body).toEqual({ model: 'm', input: ['x'], dimensions: 256 })
+		expect(p.dimensions).toBe(256)
+	})
+
+	it('batches into batchSize slices', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({
+				data: [
+					{ index: 0, embedding: [1] },
+					{ index: 1, embedding: [2] },
+				],
+			}),
+		})
+		const p = new OpenRouterEmbeddingProvider({
+			apiKey: 'k',
+			model: 'm',
+			batchSize: 2,
+		})
+		await p.embed(['a', 'b', 'c', 'd'])
+		expect(fetchMock).toHaveBeenCalledTimes(2)
+	})
+
+	it('sorts response by index before extracting embeddings', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({
+				data: [
+					{ index: 2, embedding: [3] },
+					{ index: 0, embedding: [1] },
+					{ index: 1, embedding: [2] },
+				],
+			}),
+		})
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		expect(await p.embed(['a', 'b', 'c'])).toEqual([[1], [2], [3]])
+	})
+
+	it('embedQuery returns the first result', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({ data: [{ index: 0, embedding: [9, 9] }] }),
+		})
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		expect(await p.embedQuery('hi')).toEqual([9, 9])
+	})
+
+	it('embedQuery throws when the response is empty', async () => {
+		fetchMock.mockResolvedValue({
+			ok: true,
+			json: async () => ({ data: [] }),
+		})
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		await expect(p.embedQuery('hi')).rejects.toThrow(/no results/)
+	})
+
+	it('throws on non-OK HTTP response', async () => {
+		fetchMock.mockResolvedValue({
+			ok: false,
+			status: 503,
+			text: async () => 'service unavailable',
+		})
+		const p = new OpenRouterEmbeddingProvider({ apiKey: 'k', model: 'm' })
+		await expect(p.embed(['hi'])).rejects.toThrow(/503.*service unavailable/)
+	})
+})

package/src/rag/ingestion.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `DefaultIngestionPipeline.ingest(content, metadata, scope, kbId)`:
+ *     - Generates a fresh `documentId` per call.
+ *     - Chunks via `TextChunker.chunk(content, chunkingConfig)`.
+ *     - Returns zero-chunk result when the chunker emits nothing.
+ *     - Calls `embeddingProvider.embed([...chunkTexts])` exactly once
+ *       with every chunk in order.
+ *     - Each resulting `Chunk` carries:
+ *       - a fresh `id`,
+ *       - the generated `documentId`,
+ *       - the passed `knowledgeBaseId`,
+ *       - `scope.tenantId`,
+ *       - the original `chunkContent` + `chunkIndex` metadata,
+ *       - `tokenCount = Math.ceil(content.length / 4)`.
+ *     - Calls `vectorStore.upsert(chunks)` exactly once.
+ *     - Totals `tokenCount` across chunks and reports `durationMs`.
+ *   - `remove(documentId)` delegates to `vectorStore.deleteByDocument`.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+
+import type { DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { Chunk, EmbeddingProvider, TenantScope, VectorStore } from '../types/rag/index.js'
+
+import { DefaultIngestionPipeline } from './ingestion.js'
+
+const KB = 'kb_1' as KnowledgeBaseId
+const TENANT = 't_1' as TenantId
+const scope: TenantScope = { tenantId: TENANT }
+
+function makeVectorStore(): VectorStore {
+	return {
+		upsert: vi.fn<(chunks: Chunk[]) => Promise<void>>(),
+		search: vi.fn(),
+		delete: vi.fn(),
+		deleteByDocument: vi.fn(),
+		deleteByKnowledgeBase: vi.fn(),
+	} as unknown as VectorStore
+}
+
+function makeEmbedder(): EmbeddingProvider {
+	return {
+		id: 'mock',
+		model: 'x',
+		dimensions: 3,
+		embed: vi.fn(async (texts: string[]) => texts.map(() => [1, 0, 0])),
+		embedQuery: vi.fn(async () => [1, 0, 0]),
+	}
+}
+
+describe('DefaultIngestionPipeline — ingest', () => {
+	it('returns zero-chunk result when the chunker emits nothing', async () => {
+		const vs = makeVectorStore()
+		const emb = makeEmbedder()
+		// chunkSize 10, no content at all → chunker returns []
+		const pipeline = new DefaultIngestionPipeline(vs, emb, {
+			strategy: 'fixed',
+			chunkSize: 10,
+			chunkOverlap: 0,
+		})
+		const result = await pipeline.ingest('   ', {}, scope, KB)
+		expect(result.chunkCount).toBe(0)
+		expect(result.totalTokens).toBe(0)
+		expect(vs.upsert).not.toHaveBeenCalled()
+	})
+
+	it('chunks content, embeds every chunk once, upserts once', async () => {
+		const vs = makeVectorStore()
+		const emb = makeEmbedder()
+		const pipeline = new DefaultIngestionPipeline(vs, emb, {
+			strategy: 'fixed',
+			chunkSize: 10,
+			chunkOverlap: 0,
+		})
+
+		const result = await pipeline.ingest('a'.repeat(25), { source: 'repo' }, scope, KB)
+
+		expect(emb.embed).toHaveBeenCalledTimes(1)
+		expect(vs.upsert).toHaveBeenCalledTimes(1)
+		expect(result.chunkCount).toBeGreaterThan(1)
+
+		const upsertedChunks = vi.mocked(vs.upsert).mock.calls[0]?.[0] ?? []
+		for (const c of upsertedChunks) {
+			expect(c.documentId).toBe(result.documentId)
+			expect(c.knowledgeBaseId).toBe(KB)
+			expect(c.tenantId).toBe(TENANT)
+			expect(c.metadata.source).toBe('repo')
+			expect(c.metadata.chunkIndex).toBeDefined()
+			expect(c.tokenCount).toBe(Math.ceil(c.content.length / 4))
+		}
+	})
+
+	it('generates a fresh documentId per ingest call', async () => {
+		const pipeline = new DefaultIngestionPipeline(makeVectorStore(), makeEmbedder())
+		const a = await pipeline.ingest('alpha', {}, scope, KB)
+		const b = await pipeline.ingest('beta', {}, scope, KB)
+		expect(a.documentId).not.toBe(b.documentId)
+	})
+})
+
+describe('DefaultIngestionPipeline — remove', () => {
+	it('delegates to vectorStore.deleteByDocument', async () => {
+		const vs = makeVectorStore()
+		const pipeline = new DefaultIngestionPipeline(vs, makeEmbedder())
+		await pipeline.remove('doc_9' as DocumentId)
+		expect(vs.deleteByDocument).toHaveBeenCalledWith('doc_9')
+	})
+})
+
+// Avoid the unused zod import — used in type coverage indirectly.
+void z

package/src/rag/knowledge-base.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `DefaultKnowledgeBase` is a composition layer: it builds an
+ *     ingestion pipeline + a retriever from its config and delegates
+ *     `ingest` / `query` / `remove` / `clear` to them.
+ *   - `id` is set from `config.id` if provided, else generated once
+ *     via `generateKnowledgeBaseId` — never regenerated later.
+ *   - `ingest(content, metadata)` invokes the ingestion pipeline with
+ *     the configured scope + kb id; returns whatever the pipeline
+ *     returns.
+ *   - `query(query)` invokes the retriever with scope + kb id.
+ *   - `clear()` calls `vectorStore.deleteByKnowledgeBase(id, tenantId)`.
+ *   - `remove(documentId)` calls `vectorStore.deleteByDocument`.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { EmbeddingProvider, VectorStore } from '../types/rag/index.js'
+
+import { DefaultKnowledgeBase } from './knowledge-base.js'
+
+const TENANT = 't_1' as TenantId
+
+function makeVectorStore(): VectorStore {
+	return {
+		upsert: vi.fn(),
+		search: vi.fn(async () => []),
+		delete: vi.fn(),
+		deleteByDocument: vi.fn(),
+		deleteByKnowledgeBase: vi.fn(),
+	}
+}
+
+function makeEmbedder(): EmbeddingProvider {
+	return {
+		id: 'mock',
+		model: 'x',
+		dimensions: 3,
+		embed: vi.fn(async (texts: string[]) => texts.map(() => [1, 0, 0])),
+		embedQuery: vi.fn(async () => [1, 0, 0]),
+	}
+}
+
+describe('DefaultKnowledgeBase', () => {
+	it('uses the id provided in config when set', () => {
+		const kb = new DefaultKnowledgeBase(
+			{ id: 'kb_fixed' as KnowledgeBaseId, name: 'kb', tenantId: TENANT },
+			makeVectorStore(),
+			makeEmbedder(),
+		)
+		expect(kb.id).toBe('kb_fixed')
+		expect(kb.config.id).toBe('kb_fixed')
+	})
+
+	it('generates an id when none is provided', () => {
+		const kb = new DefaultKnowledgeBase(
+			{ name: 'kb', tenantId: TENANT },
+			makeVectorStore(),
+			makeEmbedder(),
+		)
+		expect(kb.id).toMatch(/^kb_/)
+	})
+
+	it('ingest delegates to the ingestion pipeline and carries metadata through', async () => {
+		const vs = makeVectorStore()
+		const kb = new DefaultKnowledgeBase(
+			{ id: 'kb_fixed' as KnowledgeBaseId, name: 'kb', tenantId: TENANT },
+			vs,
+			makeEmbedder(),
+		)
+		const result = await kb.ingest('hello world', { source: 'readme' })
+		expect(result.documentId).toMatch(/^doc_/)
+		expect(vs.upsert).toHaveBeenCalled()
+		const chunks = vi.mocked(vs.upsert).mock.calls[0]?.[0] ?? []
+		expect(chunks[0]?.knowledgeBaseId).toBe('kb_fixed')
+		expect(chunks[0]?.tenantId).toBe(TENANT)
+	})
+
+	it('remove delegates to vectorStore.deleteByDocument', async () => {
+		const vs = makeVectorStore()
+		const kb = new DefaultKnowledgeBase({ name: 'kb', tenantId: TENANT }, vs, makeEmbedder())
+		await kb.remove('doc_1' as DocumentId)
+		expect(vs.deleteByDocument).toHaveBeenCalledWith('doc_1')
+	})
+
+	it('clear delegates to vectorStore.deleteByKnowledgeBase with id + tenantId', async () => {
+		const vs = makeVectorStore()
+		const kb = new DefaultKnowledgeBase(
+			{ id: 'kb_fixed' as KnowledgeBaseId, name: 'kb', tenantId: TENANT },
+			vs,
+			makeEmbedder(),
+		)
+		await kb.clear()
+		expect(vs.deleteByKnowledgeBase).toHaveBeenCalledWith('kb_fixed', TENANT)
+	})
+
+	it('query delegates to retriever', async () => {
+		const vs = makeVectorStore()
+		const kb = new DefaultKnowledgeBase({ name: 'kb', tenantId: TENANT }, vs, makeEmbedder())
+		const out = await kb.query({ text: 'hi' })
+		expect(out.mode).toBeDefined()
+		expect(vs.search).toHaveBeenCalled()
+	})
+})

package/src/rag/rag-tool.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `createRAGTool(config)` returns a `defineTool`-wrapped
+ *     `knowledge_search` tool with `category: 'analysis'`,
+ *     `permissions: ['network_access']`, read-only.
+ *   - Knowledge base selection:
+ *     - If `input.knowledge_base_id` is set, looks up by it.
+ *     - Else uses `config.defaultKnowledgeBaseId`.
+ *     - Else picks the first value from
+ *       `config.knowledgeBases.values().next()`.
+ *   - Returns `{success: false, error: ...}` if no knowledge base is
+ *     resolved.
+ *   - When the query returns no chunks, returns the literal
+ *     "No relevant information found..." message.
+ *   - When chunks exist, assembles them via `assembleRAGContext` and
+ *     returns `{success: true, output: content, data: {sources, mode, durationMs}}`.
+ *   - `top_k` override precedence: input > config.topK > 5.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ChunkId, DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { KnowledgeBase, RetrievalResult, VectorSearchResult } from '../types/rag/index.js'
+import type { ToolContext } from '../types/tool/index.js'
+
+import { createRAGTool } from './rag-tool.js'
+
+const TENANT = 't_1' as TenantId
+const KB_A = 'kb_a' as KnowledgeBaseId
+const KB_B = 'kb_b' as KnowledgeBaseId
+
+function makeKB(retrievalResult: RetrievalResult): KnowledgeBase {
+	const kb = {
+		id: KB_A,
+		config: { id: KB_A, tenantId: TENANT },
+		ingest: vi.fn(),
+		remove: vi.fn(),
+		query: vi.fn(async () => retrievalResult),
+		clear: vi.fn(),
+	} as unknown as KnowledgeBase
+	return kb
+}
+
+function searchResult(content: string): VectorSearchResult {
+	return {
+		chunk: {
+			id: 'c_1' as ChunkId,
+			documentId: 'd_1' as DocumentId,
+			knowledgeBaseId: KB_A,
+			tenantId: TENANT,
+			content,
+			index: 0,
+			tokenCount: 0,
+			metadata: {},
+			createdAt: 0,
+		},
+		score: 0.9,
+	}
+}
+
+const ctx: ToolContext = {} as ToolContext
+
+describe('createRAGTool', () => {
+	it('is named knowledge_search + read-only', () => {
+		const tool = createRAGTool({ knowledgeBases: new Map() })
+		expect(tool.name).toBe('knowledge_search')
+		expect(tool.isReadOnly?.({ query: 'x' })).toBe(true)
+	})
+
+	it('returns an error when no knowledge base is resolved', async () => {
+		const tool = createRAGTool({ knowledgeBases: new Map() })
+		const result = await tool.execute({ query: 'hi' }, ctx)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/Knowledge base not found/)
+	})
+
+	it('picks KB by explicit input.knowledge_base_id when set', async () => {
+		const kbA = makeKB({
+			chunks: [searchResult('from A')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const kbB = makeKB({
+			chunks: [searchResult('from B')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const tool = createRAGTool({
+			knowledgeBases: new Map([
+				[KB_A, kbA],
+				[KB_B, kbB],
+			]),
+		})
+		const out = await tool.execute({ query: 'hi', knowledge_base_id: KB_B }, ctx)
+		expect(out.success).toBe(true)
+		expect(kbB.query).toHaveBeenCalled()
+		expect(kbA.query).not.toHaveBeenCalled()
+	})
+
+	it('falls back to defaultKnowledgeBaseId when input.knowledge_base_id is absent', async () => {
+		const kbA = makeKB({
+			chunks: [searchResult('from A')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const kbB = makeKB({
+			chunks: [],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const tool = createRAGTool({
+			knowledgeBases: new Map([
+				[KB_A, kbA],
+				[KB_B, kbB],
+			]),
+			defaultKnowledgeBaseId: KB_B,
+		})
+		await tool.execute({ query: 'hi' }, ctx)
+		expect(kbB.query).toHaveBeenCalled()
+		expect(kbA.query).not.toHaveBeenCalled()
+	})
+
+	it('returns "No relevant information..." when the query returns zero chunks', async () => {
+		const kb = makeKB({ chunks: [], query: 'hi', mode: 'vector', durationMs: 1 })
+		const tool = createRAGTool({ knowledgeBases: new Map([[KB_A, kb]]) })
+		const result = await tool.execute({ query: 'hi' }, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toBe(
+			'No relevant information found in the knowledge base for this query.',
+		)
+	})
+
+	it('returns assembled content + metadata on hit', async () => {
+		const kb = makeKB({
+			chunks: [searchResult('answer text')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 42,
+		})
+		const tool = createRAGTool({ knowledgeBases: new Map([[KB_A, kb]]) })
+		const result = await tool.execute({ query: 'hi' }, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toContain('answer text')
+		expect((result.data as { mode?: string })?.mode).toBe('vector')
+		expect((result.data as { durationMs?: number })?.durationMs).toBe(42)
+	})
+
+	it('top_k override: input > config.topK > 5 default', async () => {
+		const kb = makeKB({
+			chunks: [searchResult('x')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const tool = createRAGTool({
+			knowledgeBases: new Map([[KB_A, kb]]),
+			topK: 8,
+		})
+		await tool.execute({ query: 'hi', top_k: 3 }, ctx)
+		expect(kb.query).toHaveBeenCalledWith(expect.objectContaining({ config: { topK: 3 } }))
+	})
+})