@namzu/sdk 14.0.7 → 15.1.0

package/src/connector/mcp/__tests__/structured-result.test.ts

@@ -1,143 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { z } from 'zod'
-
-import { ToolRegistry, describeWithOutput } from '../../../registry/tool/execute.js'
-import type { MCPToolDefinition, MCPToolResult } from '../../../types/connector/index.js'
-import type { ToolDefinition } from '../../../types/tool/index.js'
-import { mcpToolResultToToolResult, mcpToolToToolDefinition } from '../adapter.js'
-
-/**
- * Two halves of the same omission.
- *
- * `outputSchema` is unconditional: servers publish it on a tool listing
- * regardless of negotiated protocol revision, and the result type had no
- * slot for it — so a declared return shape never reached the model, which
- * was left inferring one from prose.
- *
- * `structuredContent` is conditional on a server that answers with a
- * machine-readable payload and omits the compatibility text block. When
- * that happens the model got an EMPTY tool result for a call that
- * succeeded: `isError` false, content array legitimately empty, no
- * diagnostic anywhere.
- */
-
-const result = (partial: Partial<MCPToolResult>): MCPToolResult => ({
-	content: [],
-	...partial,
-})
-
-describe('a structured payload', () => {
-	it('reaches the model instead of an empty result', () => {
-		const converted = mcpToolResultToToolResult(
-			result({ structuredContent: { temperature: 21, unit: 'C' } }),
-		)
-
-		expect(converted.success).toBe(true)
-		expect(converted.output).toContain('temperature')
-		expect(converted.output).toContain('21')
-	})
-
-	it('yields to the text block when the server sent one', () => {
-		// The text block is what the server wrote FOR the model; the
-		// structured payload is for a program. Duplicating both would spend
-		// context saying the same thing twice.
-		const converted = mcpToolResultToToolResult(
-			result({
-				content: [{ type: 'text', text: 'It is 21 degrees.' }],
-				structuredContent: { temperature: 21 },
-			}),
-		)
-
-		expect(converted.output).toBe('It is 21 degrees.')
-	})
-
-	it('stays reachable by the host through data', () => {
-		const converted = mcpToolResultToToolResult(result({ structuredContent: { id: 7 } }))
-		expect(converted.data).toEqual({ content: [], structuredContent: { id: 7 } })
-	})
-
-	it('leaves data as the content array when there is no structured payload', () => {
-		// The pre-existing shape for every server that does not send one.
-		const blocks = [{ type: 'text' as const, text: 'plain' }]
-		expect(mcpToolResultToToolResult(result({ content: blocks })).data).toEqual(blocks)
-	})
-
-	it('names an unserializable payload rather than returning nothing', () => {
-		const cyclic: Record<string, unknown> = {}
-		cyclic.self = cyclic
-
-		const converted = mcpToolResultToToolResult(result({ structuredContent: cyclic }))
-		// An empty output reads to the model as "nothing was found", which is
-		// a different answer from "this could not be rendered".
-		expect(converted.output).toMatch(/could not be serialized/)
-	})
-
-	it('carries a structured error into the error field too', () => {
-		const converted = mcpToolResultToToolResult(
-			result({ isError: true, structuredContent: { code: 'RATE_LIMIT' } }),
-		)
-		expect(converted.success).toBe(false)
-		expect(converted.error).toContain('RATE_LIMIT')
-	})
-
-	it('passes a plain string through without quoting it', () => {
-		expect(mcpToolResultToToolResult(result({ structuredContent: 'done' })).output).toBe('done')
-	})
-})
-
-describe('a declared return shape', () => {
-	const tool: MCPToolDefinition = {
-		name: 'forecast',
-		description: 'Weather for a city',
-		inputSchema: { type: 'object', properties: { city: { type: 'string' } } },
-		outputSchema: {
-			type: 'object',
-			properties: { temperature: { type: 'number' }, unit: { type: 'string' } },
-			required: ['temperature'],
-		},
-	}
-
-	it('survives the bridge', () => {
-		const bridged = mcpToolToToolDefinition(tool, {} as never, 'weather')
-		expect(bridged.outputSchema).toEqual(tool.outputSchema)
-	})
-
-	it('resolves its own refs', () => {
-		const bridged = mcpToolToToolDefinition(
-			{
-				...tool,
-				outputSchema: {
-					type: 'object',
-					properties: { at: { $ref: '#/$defs/Point' } },
-					$defs: { Point: { type: 'object', properties: { lat: { type: 'number' } } } },
-				},
-			},
-			{} as never,
-			'weather',
-		)
-
-		expect(JSON.stringify(bridged.outputSchema)).not.toContain('$ref')
-		expect(JSON.stringify(bridged.outputSchema)).toContain('lat')
-	})
-
-	it('reaches the model, since no provider has a slot for it', () => {
-		const registry = new ToolRegistry()
-		registry.register({
-			name: 'forecast',
-			description: 'Weather for a city',
-			inputSchema: z.object({ city: z.string() }),
-			outputSchema: { type: 'object', properties: { temperature: { type: 'number' } } },
-			execute: async () => ({ success: true as const, output: '' }),
-		} as ToolDefinition)
-
-		const rendered = registry.toLLMTools()[0]
-		expect(rendered?.function.description).toContain('Returns (JSON Schema)')
-		expect(rendered?.function.description).toContain('temperature')
-	})
-
-	it('leaves a tool without one untouched', () => {
-		// Every tool schema rides in the cached prefix of every request, so
-		// an empty "Returns:" line would be pure waste repeated forever.
-		expect(describeWithOutput('Just a tool', undefined)).toBe('Just a tool')
-	})
-})

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

@@ -1,249 +0,0 @@
-/**
- * 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/connector/mcp/client.test.ts

@@ -1,159 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-
-import type {
-	MCPJsonRpcMessage,
-	MCPTransport,
-	MCPTransportUnion,
-} from '../../types/connector/index.js'
-import { MCPClient } from './client.js'
-
-/**
- * `client.ts` had zero test coverage, and three ways to hang a run:
- *
- * - `request()` armed no timer, so a wedged stdio server left every caller
- *   pending forever — no error, no `run_failed`, just a process that stopped.
- * - Pending requests were only rejected by `disconnect()`, so a transport
- *   that dropped on its own leaked them.
- * - A frame carrying BOTH an id and a method (a server-initiated request:
- *   `sampling/createMessage`, `elicitation/create`, `roots/list`, `ping`)
- *   matched neither branch of `handleMessage` and was silently discarded,
- *   leaving the server waiting for a reply that never came.
- *
- * This is a first-party MCP implementation with no `@modelcontextprotocol/sdk`
- * dependency, so nothing is inherited from upstream.
- */
-
-interface Harness {
-	client: MCPClient
-	sent: MCPJsonRpcMessage[]
-	/** Deliver a frame as if the server sent it. */
-	receive(msg: MCPJsonRpcMessage): void
-	closeTransport(): void
-	failTransport(err: Error): void
-}
-
-function harness(opts: { autoInitialize?: boolean; requestTimeoutMs?: number } = {}): Harness {
-	const sent: MCPJsonRpcMessage[] = []
-	let onMessage: ((m: MCPJsonRpcMessage) => void) | undefined
-	let onClose: (() => void) | undefined
-	let onError: ((e: Error) => void) | undefined
-
-	let open = true
-	const transport: MCPTransport = {
-		connect: async () => {},
-		close: async () => {
-			open = false
-		},
-		isConnected: () => open,
-		send: async (message) => {
-			sent.push(message)
-			// Answer `initialize` so `connect()` can complete.
-			if (opts.autoInitialize !== false && message.method === 'initialize') {
-				queueMicrotask(() =>
-					onMessage?.({
-						jsonrpc: '2.0',
-						id: message.id,
-						result: { serverInfo: { name: 'fake', version: '1' }, capabilities: {} },
-					}),
-				)
-			}
-		},
-		onMessage: (h) => {
-			onMessage = h
-		},
-		onClose: (h) => {
-			onClose = h
-		},
-		onError: (h) => {
-			onError = h
-		},
-	}
-
-	const client = new MCPClient({
-		serverName: 'fake',
-		transport: { type: 'stdio', command: 'noop' } as MCPTransportUnion,
-		...(opts.requestTimeoutMs !== undefined ? { requestTimeoutMs: opts.requestTimeoutMs } : {}),
-	})
-	// Swap in the fake transport; `createTransport` would spawn a process.
-	;(client as unknown as { transport: MCPTransport }).transport = transport
-
-	return {
-		client,
-		sent,
-		receive: (msg) => onMessage?.(msg),
-		closeTransport: () => onClose?.(),
-		failTransport: (err) => onError?.(err),
-	}
-}
-
-describe('MCPClient — a wedged server cannot hang the run', () => {
-	it('times out a request that is never answered', async () => {
-		const h = harness({ requestTimeoutMs: 25 })
-		await h.client.connect()
-
-		await expect(h.client.listTools()).rejects.toThrow(/timed out after 25ms/)
-	})
-
-	it('rejects in-flight requests when the transport closes on its own', async () => {
-		const h = harness({ requestTimeoutMs: 10_000 })
-		await h.client.connect()
-
-		const pending = h.client.listTools()
-		h.closeTransport()
-
-		await expect(pending).rejects.toThrow(/closed/)
-	})
-
-	it('rejects in-flight requests when the transport errors', async () => {
-		const h = harness({ requestTimeoutMs: 10_000 })
-		await h.client.connect()
-
-		const pending = h.client.listTools()
-		h.failTransport(new Error('broken pipe'))
-
-		await expect(pending).rejects.toThrow(/broken pipe/)
-	})
-
-	it('clears the timer on a normal reply — no late rejection', async () => {
-		const h = harness({ requestTimeoutMs: 50 })
-		await h.client.connect()
-
-		const pending = h.client.listTools()
-		h.receive({ jsonrpc: '2.0', id: 2, result: { tools: [{ name: 'a' }] } })
-
-		await expect(pending).resolves.toEqual([{ name: 'a' }])
-		// Outlive the timeout; a stale timer would surface as an unhandled
-		// rejection here.
-		await new Promise((r) => setTimeout(r, 80))
-	})
-})
-
-describe('MCPClient — server-initiated requests are answered, not dropped', () => {
-	it('replies -32601 to an unsupported server request instead of going silent', async () => {
-		const h = harness()
-		await h.client.connect()
-		h.sent.length = 0
-
-		h.receive({ jsonrpc: '2.0', id: 99, method: 'sampling/createMessage', params: {} })
-		await new Promise((r) => setTimeout(r, 0))
-
-		const reply = h.sent.find((m) => m.id === 99)
-		expect(reply).toBeDefined()
-		expect(reply?.error?.code).toBe(-32601)
-		expect(reply?.error?.message).toContain('sampling/createMessage')
-	})
-
-	it('still routes notifications (no id) to notification handlers', async () => {
-		const h = harness()
-		await h.client.connect()
-		const seen = vi.fn()
-		h.client.onNotification(seen)
-		h.sent.length = 0
-
-		h.receive({ jsonrpc: '2.0', method: 'notifications/tools/list_changed', params: {} })
-
-		expect(seen).toHaveBeenCalledWith('notifications/tools/list_changed', {})
-		// A notification must NOT be answered.
-		expect(h.sent).toHaveLength(0)
-	})
-})