@namzu/sdk 1.4.0 → 3.0.0

package/src/registry/tool/__tests__/schema.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { mcpJsonSchemaToZod } from '../../../connector/mcp/adapter.js'
+import type { MCPJsonSchema } from '../../../types/connector/index.js'
+import type { ToolDefinition } from '../../../types/tool/index.js'
+import { ToolRegistry } from '../execute.js'
+import { renderToolSchema } from '../schema.js'
+
+/**
+ * The tools block renders at position 0 of every request — inside the
+ * prompt-cache prefix — so its exact bytes are a contract, not an
+ * implementation detail. These tests pin them.
+ */
+
+function tool(name: string, inputSchema: z.ZodType): ToolDefinition {
+	return {
+		name,
+		description: `${name} tool`,
+		inputSchema: inputSchema as ToolDefinition['inputSchema'],
+		execute: () => Promise.resolve({ success: true, output: 'ok' }),
+	}
+}
+
+describe('renderToolSchema', () => {
+	it('drops `$schema`, which no provider reads', () => {
+		// It rode in the tools block once per tool, per request, forever.
+		const raw = renderToolSchema(z.object({ path: z.string() }))
+		expect(raw).not.toHaveProperty('$schema')
+	})
+
+	it('pins the wire shape of an ordinary tool schema', () => {
+		expect(
+			renderToolSchema(
+				z.object({
+					path: z.string().describe('File to read'),
+					limit: z.number().int().optional(),
+				}),
+			),
+		).toEqual({
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'File to read' },
+				limit: { type: 'integer' },
+			},
+			required: ['path'],
+			additionalProperties: false,
+		})
+	})
+
+	it('closes nested objects and array items too', () => {
+		// `additionalProperties: false` at the root only constrains the top
+		// level; a model can invent keys inside a nested object otherwise.
+		const json = renderToolSchema(
+			z.object({ edits: z.array(z.object({ from: z.string(), to: z.string() })) }),
+		) as Record<string, never>
+		expect(json).toMatchObject({
+			additionalProperties: false,
+			properties: {
+				edits: { type: 'array', items: { additionalProperties: false } },
+			},
+		})
+	})
+
+	it('returns the identical object for the same schema — byte-stable across iterations', () => {
+		// `toLLMTools` runs once per iteration. A re-render that reordered a
+		// single key would invalidate the whole cached prefix for the run.
+		const schema = z.object({ a: z.string() })
+		const first = renderToolSchema(schema)
+		const second = renderToolSchema(schema)
+		expect(second).toBe(first)
+	})
+
+	it('is frozen, so a caller cannot poison the cache', () => {
+		// The symptom of a mutated cache entry would be a silently
+		// invalidated prompt cache, not an error. Freezing makes it a throw.
+		const rendered = renderToolSchema(z.object({ a: z.string() })) as Record<string, unknown>
+		expect(() => {
+			rendered.injected = true
+		}).toThrow()
+		expect(Object.isFrozen((rendered as { properties: object }).properties)).toBe(true)
+	})
+
+	it('renders the same object through the registry, iteration after iteration', () => {
+		const registry = new ToolRegistry()
+		registry.register(tool('read_file', z.object({ path: z.string() })))
+
+		const a = registry.toLLMTools()[0]?.function.parameters
+		const b = registry.toLLMTools()[0]?.function.parameters
+		expect(a).toBe(b)
+		expect(a).not.toHaveProperty('$schema')
+	})
+})
+
+describe('MCP schema round trip', () => {
+	const render = (schema: MCPJsonSchema) => renderToolSchema(mcpJsonSchemaToZod(schema))
+
+	it('preserves a nested object instead of flattening it to "any keys"', () => {
+		// This is what the model is shown for a bridged tool. Collapsing it
+		// to `z.record(z.unknown())` left the model guessing at a shape the
+		// server had spelled out precisely.
+		const rendered = render({
+			type: 'object',
+			properties: {
+				filter: {
+					type: 'object',
+					properties: { status: { type: 'string' }, limit: { type: 'integer' } },
+					required: ['status'],
+				},
+			},
+			required: ['filter'],
+		} as unknown as MCPJsonSchema)
+
+		expect(rendered).toMatchObject({
+			properties: {
+				filter: {
+					type: 'object',
+					properties: { status: { type: 'string' }, limit: { type: 'integer' } },
+					required: ['status'],
+				},
+			},
+		})
+	})
+
+	it('preserves array item types instead of "array of anything"', () => {
+		const rendered = render({
+			type: 'object',
+			properties: { ids: { type: 'array', items: { type: 'string' } } },
+		} as unknown as MCPJsonSchema)
+
+		expect(rendered).toMatchObject({
+			properties: { ids: { type: 'array', items: { type: 'string' } } },
+		})
+	})
+
+	it('preserves enums, descriptions and defaults', () => {
+		const rendered = render({
+			type: 'object',
+			properties: {
+				mode: { type: 'string', enum: ['fast', 'thorough'], description: 'Search depth' },
+			},
+		} as unknown as MCPJsonSchema)
+
+		expect(rendered).toMatchObject({
+			properties: {
+				mode: { type: 'string', enum: ['fast', 'thorough'], description: 'Search depth' },
+			},
+		})
+	})
+
+	it('models a nullable field rather than erasing its type', () => {
+		const zod = mcpJsonSchemaToZod({
+			type: 'object',
+			properties: { cursor: { type: ['string', 'null'] } },
+			required: ['cursor'],
+		} as unknown as MCPJsonSchema)
+
+		expect(zod.safeParse({ cursor: null }).success).toBe(true)
+		expect(zod.safeParse({ cursor: 'abc' }).success).toBe(true)
+		expect(zod.safeParse({ cursor: 7 }).success).toBe(false)
+	})
+
+	it('resolves anyOf to a union', () => {
+		const zod = mcpJsonSchemaToZod({
+			type: 'object',
+			properties: { id: { anyOf: [{ type: 'string' }, { type: 'integer' }] } },
+			required: ['id'],
+		} as unknown as MCPJsonSchema)
+
+		expect(zod.safeParse({ id: 'x' }).success).toBe(true)
+		expect(zod.safeParse({ id: 3 }).success).toBe(true)
+		expect(zod.safeParse({ id: true }).success).toBe(false)
+	})
+
+	it('tells the model it may NOT invent arguments the server never declared', () => {
+		// The old default was `.passthrough()`, rendering
+		// `additionalProperties: true`.
+		const rendered = render({
+			type: 'object',
+			properties: { q: { type: 'string' } },
+		} as unknown as MCPJsonSchema)
+		expect(rendered).toMatchObject({ additionalProperties: false })
+	})
+
+	it('still honors a server that explicitly opens its schema', () => {
+		const rendered = render({
+			type: 'object',
+			properties: { q: { type: 'string' } },
+			additionalProperties: true,
+		} as unknown as MCPJsonSchema)
+		expect(rendered).toMatchObject({ additionalProperties: true })
+	})
+
+	it('validates a nested payload the old converter would have waved through', () => {
+		const zod = mcpJsonSchemaToZod({
+			type: 'object',
+			properties: {
+				filter: { type: 'object', properties: { limit: { type: 'integer' } }, required: ['limit'] },
+			},
+			required: ['filter'],
+		} as unknown as MCPJsonSchema)
+
+		expect(zod.safeParse({ filter: { limit: 10 } }).success).toBe(true)
+		// `z.record(z.unknown())` accepted both of these.
+		expect(zod.safeParse({ filter: { limit: 'ten' } }).success).toBe(false)
+		expect(zod.safeParse({ filter: {} }).success).toBe(false)
+	})
+})

package/src/registry/tool/__tests__/tool-name-validation.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { PLUGIN_NAMESPACE_SEPARATOR } from '../../../constants/plugin/index.js'
+import { ToolRegistry, assertToolName } from '../execute.js'
+
+/**
+ * A tool name reaches the provider verbatim, and the major message APIs
+ * accept `[a-zA-Z0-9_-]` only. Nothing checked it: names were derived by
+ * concatenation at three separate construction sites, and the plugin
+ * bridge's separator was a colon — so EVERY plugin-contributed tool name
+ * was illegal, unconditionally.
+ *
+ * The rejection is a 400 on the whole request rather than on that tool,
+ * and those tools are registered deferred, so it fired the moment one was
+ * activated with nothing naming the culprit.
+ */
+
+const tool = (name: string) => ({
+	name,
+	description: 'x',
+	inputSchema: z.object({}),
+	execute: async () => ({ success: true as const, output: 'ok' }),
+})
+
+describe('what a name may be', () => {
+	it.each(['read', 'read_file', 'read-file', 'mcp__srv__read', 'a'.repeat(64)])(
+		'accepts %s',
+		(name) => {
+			expect(() => assertToolName(name)).not.toThrow()
+		},
+	)
+
+	it.each([
+		['a colon', 'plugin:tool'],
+		['a space', 'read file'],
+		['a dot', 'fs.read'],
+		['a slash', 'fs/read'],
+		['an empty name', ''],
+	])('refuses %s', (_why, name) => {
+		expect(() => assertToolName(name)).toThrow(/cannot be sent to a provider/)
+	})
+
+	it('refuses a name over the length limit and says so', () => {
+		expect(() => assertToolName('a'.repeat(65))).toThrow(/65 characters, over the 64/)
+	})
+
+	it('names the offending tool', () => {
+		// A 400 on the whole request names nothing; this has to.
+		expect(() => assertToolName('bad:name')).toThrow(/"bad:name"/)
+	})
+})
+
+describe('the registry', () => {
+	it('refuses at registration rather than at request time', () => {
+		const registry = new ToolRegistry()
+		// Failing here costs the run nothing and can still be attributed.
+		expect(() => registry.register(tool('plugin:tool') as never)).toThrow(
+			/cannot be sent to a provider/,
+		)
+	})
+
+	it('still registers a legal name', () => {
+		const registry = new ToolRegistry()
+		registry.register(tool('read_file') as never)
+		expect(registry.listNames()).toContain('read_file')
+	})
+
+	it('checks the id when one is passed separately', () => {
+		const registry = new ToolRegistry()
+		expect(() => registry.register('bad:id', tool('fine') as never)).toThrow(
+			/cannot be sent to a provider/,
+		)
+	})
+})
+
+describe('the plugin namespace separator', () => {
+	it('is itself legal, so plugin tools can register at all', () => {
+		// It was a colon, which made every plugin-contributed tool name
+		// illegal — the check above would refuse all of them.
+		expect(() => assertToolName(`plugin${PLUGIN_NAMESPACE_SEPARATOR}tool`)).not.toThrow()
+	})
+
+	it('produces a legal name for a bridged remote tool', () => {
+		const name = `fs-plugin${PLUGIN_NAMESPACE_SEPARATOR}mcp__fs__read_file`
+		expect(() => assertToolName(name)).not.toThrow()
+	})
+})

package/src/registry/tool/execute.test.ts

@@ -98,6 +98,17 @@ describe('ToolRegistry — register + availability', () => {
 		expect(() => r.register('oops', 'not-a-tool' as never)).toThrow(/requires a ToolDefinition/)
 	})
 
+	it('rejects enforced model input without an explicit model schema', () => {
+		const r = new ToolRegistry()
+		expect(() =>
+			r.register(
+				makeTool('unsafe_strict', {
+					enforceModelInput: true,
+				}),
+			),
+		).toThrow(/enforceModelInput.*modelInputSchema/)
+	})
+
 	it('getAvailability returns active for unknown names (current default)', () => {
 		const r = new ToolRegistry()
 		expect(r.getAvailability('never-registered')).toBe('active')
@@ -228,7 +239,10 @@ describe('ToolRegistry — searchDeferred', () => {
 		r.register(
 			[
 				makeTool('send_invoice', {
-					inputSchema: z.object({ customerEmail: z.string(), amount: z.number() }),
+					inputSchema: z.object({
+						customerEmail: z.string(),
+						amount: z.number(),
+					}),
 				}),
 			],
 			'deferred',
@@ -237,10 +251,50 @@ describe('ToolRegistry — searchDeferred', () => {
 		expect(r.searchDeferred('customerEmail').map((t) => t.name)).toEqual(['send_invoice'])
 	})
 
+	it('indexes canonical model-schema branches without re-advertising runtime aliases', () => {
+		const r = new ToolRegistry()
+		r.register(
+			[
+				makeTool('edit_document', {
+					inputSchema: z.object({ oldStr: z.string(), newStr: z.string() }),
+					modelInputSchema: {
+						type: 'object',
+						properties: {
+							path: { type: 'string' },
+							old_string: { type: 'string' },
+							new_string: { type: 'string' },
+						},
+						required: ['path', 'new_string'],
+						additionalProperties: false,
+						anyOf: [
+							{
+								type: 'object',
+								properties: {
+									path: { type: 'string' },
+									old_string: { type: 'string' },
+									new_string: { type: 'string' },
+								},
+								required: ['path', 'old_string', 'new_string'],
+								additionalProperties: false,
+							},
+						],
+					},
+				}),
+			],
+			'deferred',
+		)
+		expect(r.searchDeferred('old_string').map((t) => t.name)).toEqual(['edit_document'])
+		expect(r.searchDeferred('oldStr')).toEqual([])
+	})
+
 	it('stops generic CRUD verbs so they cannot activate catalog slices', () => {
 		const r = new ToolRegistry()
 		r.register(
-			[makeTool('list_deals', { description: 'List the deals in an account.' })],
+			[
+				makeTool('list_deals', {
+					description: 'List the deals in an account.',
+				}),
+			],
 			'deferred',
 		)
 		r.register([makeTool('list_workflows', { description: 'List workflows.' })], 'deferred')
@@ -370,6 +424,34 @@ describe('ToolRegistry — toPromptSection + toLLMTools', () => {
 		expect(names).toEqual(['a', 'c'])
 	})
 
+	it('toLLMTools: prefers a canonical model schema over runtime compatibility aliases', () => {
+		const r = new ToolRegistry()
+		const modelInputSchema = {
+			type: 'object',
+			properties: { new_string: { type: 'string' } },
+			required: ['new_string'],
+			additionalProperties: false,
+		}
+		r.register(
+			makeTool('edit', {
+				inputSchema: z.object({
+					new_string: z.string().optional(),
+					newStr: z.string().optional(),
+				}),
+				modelInputSchema,
+			}),
+		)
+
+		const firstSchema = r.toLLMTools()[0]?.function.parameters
+		expect(firstSchema).toEqual(modelInputSchema)
+		expect(firstSchema).not.toBe(modelInputSchema)
+		;(firstSchema?.properties as Record<string, unknown>).newStr = { type: 'string' }
+
+		const nextSchema = r.toLLMTools()[0]?.function.parameters
+		expect(nextSchema).toEqual(modelInputSchema)
+		expect(JSON.stringify(nextSchema)).not.toContain('newStr')
+	})
+
 	it('toLLMTools: prefixes description with tier label when labelInDescription is true', () => {
 		const tierConfig: ToolTierConfig = {
 			tiers: [{ id: 'safe', label: 'Safe', priority: 1 }],
@@ -398,7 +480,11 @@ describe('ToolRegistry — execute', () => {
 			'write',
 			{},
 			makeContext({
-				permissionContext: { mode: 'plan', runId: 'run_1', workingDirectory: '/tmp' },
+				permissionContext: {
+					mode: 'plan',
+					runId: 'run_1',
+					workingDirectory: '/tmp',
+				},
 			}),
 		)
 		expect(result.success).toBe(false)
@@ -413,7 +499,11 @@ describe('ToolRegistry — execute', () => {
 			'read',
 			{},
 			makeContext({
-				permissionContext: { mode: 'plan', runId: 'run_1', workingDirectory: '/tmp' },
+				permissionContext: {
+					mode: 'plan',
+					runId: 'run_1',
+					workingDirectory: '/tmp',
+				},
 			}),
 		)
 		expect(result.success).toBe(true)
@@ -451,7 +541,10 @@ describe('ToolRegistry — execute', () => {
 		const r = new ToolRegistry()
 		r.register(
 			makeTool('needs', {
-				inputSchema: z.object({ q: z.string().describe('the query'), n: z.number() }),
+				inputSchema: z.object({
+					q: z.string().describe('the query'),
+					n: z.number(),
+				}),
 			}),
 		)
 		const result = await r.execute('needs', {}, makeContext())
@@ -472,7 +565,10 @@ describe('ToolRegistry — execute', () => {
 	it('validation hint tolerates a schema it cannot introspect', async () => {
 		const r = new ToolRegistry()
 		const bogusSchema = {
-			safeParse: () => ({ success: false, error: { issues: [{ path: [], message: 'nope' }] } }),
+			safeParse: () => ({
+				success: false,
+				error: { issues: [{ path: [], message: 'nope' }] },
+			}),
 		}
 		r.register(makeTool('weird', { inputSchema: bogusSchema as never }))
 		const result = await r.execute('weird', { a: 1 }, makeContext())
@@ -530,7 +626,11 @@ describe('ToolRegistry — execute', () => {
 			'mutate',
 			{},
 			makeContext({
-				permissionContext: { mode: 'plan', runId: 'run_1', workingDirectory: '/tmp' },
+				permissionContext: {
+					mode: 'plan',
+					runId: 'run_1',
+					workingDirectory: '/tmp',
+				},
 			}),
 		)
 		expect(result.success).toBe(false)