@namzu/sdk 0.4.2 → 0.4.3

package/src/connector/mcp/adapter.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 5):
+ *
+ *   - `mcpJsonSchemaToZod(schema)`:
+ *     - Empty / no-properties object → passthrough `z.object({})`.
+ *     - Maps primitive types (string, number, integer, boolean, array,
+ *       object) to zod equivalents.
+ *     - Unknown / null property types → `z.unknown()`.
+ *     - Fields not in `required[]` are `.optional()`.
+ *   - `zodToMCPJsonSchema(zodSchema)` wraps `zodToJsonSchema` with
+ *     `type: 'object'` prefixed.
+ *   - `mcpToolToToolDefinition(tool, client, serverName)` produces a
+ *     ToolDefinition:
+ *     - name = `mcp_<server>_<tool.name>`
+ *     - description prefixed `[MCP:<server>] <tool.description or name>`
+ *     - category = 'network', permissions = ['network_access']
+ *     - readOnly + destructive reflect MCP annotations; concurrency
+ *       safe defaults to true.
+ *     - `execute(input, ctx)` calls `client.callTool(tool.name, input)`
+ *       and adapts the MCPToolResult.
+ *   - `toolDefinitionToMCPTool(tool)` projects name/description +
+ *     converts inputSchema + copies annotations.
+ *   - `mcpToolResultToToolResult`:
+ *     - success = !isError.
+ *     - output = text content joined with '\n' (non-text blocks
+ *       kept in `data` only).
+ *     - error = same joined text when isError, else undefined.
+ *   - `toolResultToMCPToolResult`:
+ *     - success + output → single text block.
+ *     - failure + error → single text block + isError.
+ *     - Empty output on success → single empty-text block.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+
+import type { MCPJsonSchema, MCPToolResult } from '../../types/connector/index.js'
+import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
+
+import {
+	mcpJsonSchemaToZod,
+	mcpToolResultToToolResult,
+	mcpToolToToolDefinition,
+	toolDefinitionToMCPTool,
+	toolResultToMCPToolResult,
+	zodToMCPJsonSchema,
+} from './adapter.js'
+import type { MCPClient } from './client.js'
+
+function mockClient(result: MCPToolResult): MCPClient {
+	return {
+		callTool: vi.fn(async () => result),
+	} as unknown as MCPClient
+}
+
+describe('mcpJsonSchemaToZod', () => {
+	it('empty schema → passthrough empty object', () => {
+		const schema = mcpJsonSchemaToZod({ type: 'object' } as MCPJsonSchema)
+		expect(() => schema.parse({ extra: 'x' })).not.toThrow()
+	})
+
+	it('maps primitive types', () => {
+		const schema = mcpJsonSchemaToZod({
+			type: 'object',
+			required: ['s', 'n', 'b', 'arr', 'obj'],
+			properties: {
+				s: { type: 'string' },
+				n: { type: 'number' },
+				b: { type: 'boolean' },
+				arr: { type: 'array' },
+				obj: { type: 'object' },
+			},
+		} as MCPJsonSchema)
+		expect(() => schema.parse({ s: 'x', n: 1, b: true, arr: [], obj: {} })).not.toThrow()
+		expect(() => schema.parse({ s: 123, n: 1, b: true, arr: [], obj: {} })).toThrow()
+	})
+
+	it('optional fields are not required', () => {
+		const schema = mcpJsonSchemaToZod({
+			type: 'object',
+			required: ['a'],
+			properties: {
+				a: { type: 'string' },
+				b: { type: 'string' },
+			},
+		} as MCPJsonSchema)
+		expect(() => schema.parse({ a: 'x' })).not.toThrow()
+	})
+
+	it('unknown property types map to z.unknown (pass any value)', () => {
+		const schema = mcpJsonSchemaToZod({
+			type: 'object',
+			required: ['x'],
+			properties: { x: { type: 'weird' } },
+		} as MCPJsonSchema)
+		expect(() => schema.parse({ x: { nested: [1, 2] } })).not.toThrow()
+	})
+})
+
+describe('zodToMCPJsonSchema', () => {
+	it('wraps zod schema with type: object', () => {
+		const out = zodToMCPJsonSchema(z.object({ a: z.string() }))
+		expect(out.type).toBe('object')
+	})
+})
+
+describe('mcpToolToToolDefinition', () => {
+	it('prefixes name + description with the server handle', () => {
+		const tool = mcpToolToToolDefinition(
+			{
+				name: 'search',
+				description: 'search docs',
+				inputSchema: { type: 'object' } as MCPJsonSchema,
+			},
+			mockClient({ content: [{ type: 'text', text: 'ok' }], isError: false }),
+			'serverA',
+		)
+		expect(tool.name).toBe('mcp_serverA_search')
+		expect(tool.description).toBe('[MCP:serverA] search docs')
+		expect(tool.category).toBe('network')
+	})
+
+	it('uses tool.name as description fallback when no description', () => {
+		const tool = mcpToolToToolDefinition(
+			{ name: 'search', inputSchema: { type: 'object' } as MCPJsonSchema },
+			mockClient({ content: [{ type: 'text', text: 'ok' }], isError: false }),
+			'serverA',
+		)
+		expect(tool.description).toBe('[MCP:serverA] search')
+	})
+
+	it('reflects MCP annotations into tool flags', () => {
+		const tool = mcpToolToToolDefinition(
+			{
+				name: 't',
+				inputSchema: { type: 'object' } as MCPJsonSchema,
+				annotations: { readOnlyHint: true, destructiveHint: true },
+			},
+			mockClient({ content: [], isError: false }),
+			's',
+		)
+		expect(tool.isReadOnly?.({})).toBe(true)
+		expect(tool.isDestructive?.({})).toBe(true)
+		expect(tool.isConcurrencySafe?.({})).toBe(true)
+	})
+
+	it('default flags when annotations are absent', () => {
+		const tool = mcpToolToToolDefinition(
+			{ name: 't', inputSchema: { type: 'object' } as MCPJsonSchema },
+			mockClient({ content: [], isError: false }),
+			's',
+		)
+		expect(tool.isReadOnly?.({})).toBe(false)
+		expect(tool.isDestructive?.({})).toBe(false)
+	})
+
+	it('execute calls client.callTool(tool.name, input) and adapts result', async () => {
+		const client = mockClient({
+			content: [{ type: 'text', text: 'hello' }],
+			isError: false,
+		})
+		const tool = mcpToolToToolDefinition(
+			{ name: 'search', inputSchema: { type: 'object' } as MCPJsonSchema },
+			client,
+			's',
+		)
+		const result = await tool.execute({ q: 'hi' }, {} as ToolContext)
+		expect(client.callTool).toHaveBeenCalledWith('search', { q: 'hi' })
+		expect(result.success).toBe(true)
+		expect(result.output).toBe('hello')
+	})
+})
+
+describe('toolDefinitionToMCPTool', () => {
+	it('projects name / description / inputSchema / annotations', () => {
+		const tool: ToolDefinition = {
+			name: 't',
+			description: 'd',
+			inputSchema: z.object({ a: z.string() }),
+			async execute() {
+				return { success: true, output: '' }
+			},
+			isReadOnly: () => true,
+			isDestructive: () => false,
+		}
+		const out = toolDefinitionToMCPTool(tool)
+		expect(out.name).toBe('t')
+		expect(out.description).toBe('d')
+		expect(out.inputSchema.type).toBe('object')
+		expect(out.annotations).toEqual({ readOnlyHint: true, destructiveHint: false })
+	})
+})
+
+describe('mcpToolResultToToolResult', () => {
+	it('joins text blocks with \\n for output', () => {
+		const result = mcpToolResultToToolResult({
+			content: [
+				{ type: 'text', text: 'line 1' },
+				{ type: 'text', text: 'line 2' },
+			],
+			isError: false,
+		})
+		expect(result.output).toBe('line 1\nline 2')
+		expect(result.success).toBe(true)
+	})
+
+	it('filters out non-text blocks from output but keeps them in data', () => {
+		const result = mcpToolResultToToolResult({
+			content: [
+				{ type: 'text', text: 'text' },
+				{ type: 'image', data: 'b64', mimeType: 'image/png' },
+			],
+			isError: false,
+		})
+		expect(result.output).toBe('text')
+		expect(Array.isArray(result.data)).toBe(true)
+	})
+
+	it('sets error field when isError is true', () => {
+		const result = mcpToolResultToToolResult({
+			content: [{ type: 'text', text: 'boom' }],
+			isError: true,
+		})
+		expect(result.success).toBe(false)
+		expect(result.error).toBe('boom')
+	})
+})
+
+describe('toolResultToMCPToolResult', () => {
+	it('success + output → single text block', () => {
+		const result: ToolResult = { success: true, output: 'ok' }
+		const out = toolResultToMCPToolResult(result)
+		expect(out.content).toEqual([{ type: 'text', text: 'ok' }])
+		expect(out.isError).toBe(false)
+	})
+
+	it('failure + error → text block + isError', () => {
+		const result: ToolResult = { success: false, output: '', error: 'boom' }
+		const out = toolResultToMCPToolResult(result)
+		expect(out.content.some((b) => b.type === 'text' && b.text === 'boom')).toBe(true)
+		expect(out.isError).toBe(true)
+	})
+
+	it('success with empty output → one empty-text block', () => {
+		const result: ToolResult = { success: true, output: '' }
+		const out = toolResultToMCPToolResult(result)
+		expect(out.content).toEqual([{ type: 'text', text: '' }])
+	})
+})

package/src/rag/chunking.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `TextChunker.chunk(content, config)` dispatches by
+ *     `config.strategy`. Unknown strategy hits an exhaustive-check
+ *     throw (unreachable via types).
+ *   - `fixed` strategy: slides a window of `chunkSize` by
+ *     `chunkSize − chunkOverlap` (min 1) and emits trimmed non-empty
+ *     slices. Indices are 0-based and contiguous.
+ *   - `sentence` / `paragraph` strategies split by their separator
+ *     sets and then merge small parts until the budget fills.
+ *   - `recursive` strategy: short content returns as a single chunk;
+ *     otherwise it splits by the first separator that produces >1
+ *     parts, merges, and recurses into parts that still exceed
+ *     `chunkSize`. Falls back to `fixed` when no separator splits.
+ *   - Overlap is applied in `mergeSmallParts` via
+ *     `current.slice(current.length - chunkOverlap) + part`.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ChunkingConfig } from '../types/rag/index.js'
+
+import { TextChunker } from './chunking.js'
+
+const chunker = new TextChunker()
+
+describe('TextChunker — fixed', () => {
+	const fixed: ChunkingConfig = { strategy: 'fixed', chunkSize: 10, chunkOverlap: 2 }
+
+	it('emits trimmed non-empty slices with contiguous indices', () => {
+		const result = chunker.chunk('0123456789abcdefghij', fixed)
+		expect(result).toHaveLength(3)
+		expect(result.map((c) => c.index)).toEqual([0, 1, 2])
+	})
+
+	it('skips whitespace-only slices', () => {
+		const result = chunker.chunk('abc           def', {
+			strategy: 'fixed',
+			chunkSize: 5,
+			chunkOverlap: 0,
+		})
+		expect(result.map((c) => c.content)).not.toContain('')
+	})
+
+	it('clamps step to at least 1 when overlap >= chunkSize', () => {
+		const result = chunker.chunk('abcdefghij', {
+			strategy: 'fixed',
+			chunkSize: 3,
+			chunkOverlap: 3,
+		})
+		// step = max(1, 3-3) = 1; eagerly emits many overlapping slices
+		expect(result.length).toBeGreaterThan(1)
+	})
+})
+
+describe('TextChunker — sentence', () => {
+	it('splits by sentence separators and merges up to the budget', () => {
+		const result = chunker.chunk('First sentence. Second sentence. Third sentence.', {
+			strategy: 'sentence',
+			chunkSize: 100,
+			chunkOverlap: 0,
+		})
+		expect(result.length).toBeGreaterThanOrEqual(1)
+		expect(result[0]?.content).toContain('First sentence')
+	})
+})
+
+describe('TextChunker — paragraph', () => {
+	it('splits by paragraph separators', () => {
+		const result = chunker.chunk('para one\n\npara two\n\npara three', {
+			strategy: 'paragraph',
+			chunkSize: 200,
+			chunkOverlap: 0,
+		})
+		expect(result.length).toBeGreaterThanOrEqual(1)
+	})
+})
+
+describe('TextChunker — recursive', () => {
+	it('short content fits into a single chunk', () => {
+		const result = chunker.chunk('tiny', {
+			strategy: 'recursive',
+			chunkSize: 100,
+			chunkOverlap: 0,
+		})
+		expect(result).toEqual([{ content: 'tiny', index: 0 }])
+	})
+
+	it('long content recursively splits to stay within chunkSize', () => {
+		const content = 'paragraph one. more text.\n\nparagraph two. more.'
+		const result = chunker.chunk(content, {
+			strategy: 'recursive',
+			chunkSize: 30,
+			chunkOverlap: 0,
+		})
+		for (const c of result) {
+			expect(c.content.length).toBeLessThanOrEqual(30)
+		}
+	})
+
+	it('empty or whitespace-only content yields empty result', () => {
+		expect(chunker.chunk('   ', { strategy: 'recursive', chunkSize: 10, chunkOverlap: 0 })).toEqual(
+			[],
+		)
+	})
+})

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/)
+	})
+})