@namzu/sdk 2.0.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.ts

@@ -1,6 +1,6 @@
-import { SpanStatusCode } from '@opentelemetry/api'
-import { zodToJsonSchema } from 'zod-to-json-schema'
+import { SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api'
 import { GENAI, NAMZU, toolSpanName } from '../../telemetry/attributes.js'
+import { recordToolCall } from '../../telemetry/metrics.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
 import type {
 	LLMToolSchema,
@@ -13,6 +13,7 @@ import type {
 } from '../../types/tool/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { ManagedRegistry } from '../ManagedRegistry.js'
+import { renderToolSchema } from './schema.js'
 
 export type { ToolExecutionResult }
 
@@ -43,22 +44,73 @@ const SEARCH_STOP_TOKENS = new Set([
 // Weighted-scoring weights mirroring ToolCatalog.searchTools (the richer,
 // otherwise-unused catalog scorer): exact name 12, name substring 8,
 // description 5 — extended here with argument-name indexing (3), following
-// Anthropic's tool-search practice of searching argument names too.
+// argument names are searched too, not only the tool's own name.
 const SEARCH_WEIGHT_NAME_EXACT = 12
 const SEARCH_WEIGHT_NAME_PARTIAL = 8
 const SEARCH_WEIGHT_DESCRIPTION = 5
 const SEARCH_WEIGHT_ARGUMENT = 3
 
+/**
+ * What a tool name may be, everywhere it comes from.
+ *
+ * A tool name reaches the provider verbatim, and the major message APIs
+ * accept `[a-zA-Z0-9_-]` up to 64 characters. Nothing checked it: names
+ * were derived by concatenation at three separate construction sites —
+ * the remote-tool bridge, the plugin bridge, the CLI bridge — and any of
+ * them could produce something the wire rejects.
+ *
+ * The rejection is a 400 on the WHOLE request rather than on that tool,
+ * and the tools most likely to carry a bad name are registered deferred,
+ * so it fired the moment one was activated with nothing naming the
+ * culprit. Failing at registration instead names the tool, at the moment
+ * something can still be done about it, and costs the run nothing.
+ *
+ * One driver already ratified passing names through untouched, on the
+ * grounds that a confusing name is "a naming problem to fix in the
+ * registry, not something to paper over" — which is precisely why the
+ * registry has to be the one that checks.
+ */
+export const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/
+
+export function assertToolName(name: string): void {
+	if (TOOL_NAME_PATTERN.test(name)) return
+	const reason =
+		name.length > 64
+			? `it is ${name.length} characters, over the 64-character limit`
+			: 'it contains characters outside [a-zA-Z0-9_-]'
+	throw new Error(
+		`Tool name "${name}" cannot be sent to a provider: ${reason}. Providers reject the whole request for one bad name, so this is refused at registration where it can still be attributed.`,
+	)
+}
+
+/**
+ * Append a tool's declared return shape to its description.
+ *
+ * No provider's tool wire format has a slot for an output schema, so the
+ * description is the only channel that reaches the model. A remote server
+ * that publishes one had it dropped at the type boundary and the model was
+ * left inferring the return shape from prose — or from the first result it
+ * happened to see, which is worse, because a tool that returns an empty
+ * list once teaches the wrong lesson permanently.
+ *
+ * Rendered from JSON Schema verbatim rather than round-tripped through
+ * anything: this is shown, never validated, so there is nothing to gain by
+ * rebuilding it and fidelity to lose.
+ */
+export function describeWithOutput(
+	description: string,
+	outputSchema: Record<string, unknown> | undefined,
+): string {
+	if (outputSchema === undefined) return description
+	return `${description}\n\nReturns (JSON Schema): ${JSON.stringify(outputSchema)}`
+}
+
 export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	private availability: Map<string, ToolAvailability> = new Map()
 	private tierConfig?: ToolTierConfig
 
 	constructor(config?: ToolRegistryConfig) {
-		super({
-			componentName: 'ToolRegistry',
-			idField: 'name',
-			logger: config?.logger,
-		})
+		super({ componentName: 'ToolRegistry', idField: 'name', logger: config?.logger })
 		this.tierConfig = config?.tierConfig
 	}
 
@@ -92,6 +144,11 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	}
 
 	private registerOne(id: string, tool: ToolDefinition, state: ToolAvailability): void {
+		assertToolName(id)
+		// A model-facing schema is what the constraint is applied TO, so
+		// asking for enforcement without one is a request that cannot be
+		// honoured. Refusing at registration puts the error where the author
+		// can fix it rather than at the first request.
 		if (tool.enforceModelInput && !tool.modelInputSchema) {
 			throw new Error(
 				`Tool "${id}" enables enforceModelInput but does not define modelInputSchema. Constrained input generation requires an explicit provider-safe model schema.`,
@@ -287,13 +344,10 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				type: 'function' as const,
 				function: {
 					name: tool.name,
-					description,
+					description: describeWithOutput(description, tool.outputSchema),
 					parameters:
 						(tool.modelInputSchema ? structuredClone(tool.modelInputSchema) : undefined) ??
-						(zodToJsonSchema(tool.inputSchema, {
-							target: 'jsonSchema7',
-							$refStrategy: 'none',
-						}) as Record<string, unknown>),
+						renderToolSchema(tool.inputSchema),
 				},
 			}
 		})
@@ -310,7 +364,17 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 	): Promise<ToolExecutionResult> {
 		const tracer = getTracer()
 
-		return tracer.startActiveSpan(toolSpanName(toolName), async (span) => {
+		// Explicit parent, not the ambient context. Every span-owning body
+		// upstream is an async generator, and a generator resumes on its
+		// consumer's async context — so by the time a tool executes, whatever
+		// `startActiveSpan` established upstream is long gone and this span
+		// would emit as a root. `context.parentSpan` is threaded through
+		// `ToolContext`, which already reaches here.
+		const parentCtx = context.parentSpan
+			? trace.setSpan(otelContext.active(), context.parentSpan)
+			: otelContext.active()
+
+		return tracer.startActiveSpan(toolSpanName(toolName), {}, parentCtx, async (span) => {
 			span.setAttributes({
 				[GENAI.TOOL_NAME]: toolName,
 				[GENAI.TOOL_TYPE]: 'function',
@@ -364,7 +428,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 
 				// 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 (Anthropic
+				// 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-
@@ -381,6 +445,9 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						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()}`
 					: ''
@@ -412,12 +479,20 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 
 			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 })
@@ -479,18 +554,25 @@ export function toolDiscoveryHint(description: string, maxLength = 100): string
  */
 function listArgumentNames(tool: ToolDefinition): string[] {
 	try {
-		const json =
-			tool.modelInputSchema ??
-			(zodToJsonSchema(tool.inputSchema, {
-				target: 'jsonSchema7',
-				$refStrategy: 'none',
-			}) as Record<string, unknown>)
+		// The model-facing schema when there is one: that is what the model
+		// was shown, so it is what a search over "which tool takes this
+		// argument" has to match against.
+		const json = tool.modelInputSchema ?? renderToolSchema(tool.inputSchema)
 		return [...collectSchemaPropertyNames(json)].map((key) => key.toLowerCase())
 	} catch {
 		return []
 	}
 }
 
+/**
+ * Every property name a schema can accept, including the ones that only
+ * appear inside a branch.
+ *
+ * A conditional schema puts its real arguments under `anyOf`/`oneOf`, so
+ * reading the top-level `properties` alone finds nothing and the tool is
+ * unfindable by the very argument it takes. `seen` guards a schema that
+ * refers back to itself.
+ */
 function collectSchemaPropertyNames(
 	schema: unknown,
 	names: Set<string> = new Set(),
@@ -527,7 +609,7 @@ function collectSchemaPropertyNames(
  */
 function describeRequiredInput(schema: { _def?: unknown }): string {
 	try {
-		const json = zodToJsonSchema(schema as never) as {
+		const json = renderToolSchema(schema as never) as {
 			properties?: Record<string, { type?: string; description?: string }>
 			required?: string[]
 		}

package/src/registry/tool/schema.ts

@@ -0,0 +1,80 @@
+import type { z } from 'zod'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+
+/**
+ * The single place a tool's Zod schema becomes the JSON Schema that goes on
+ * the wire.
+ *
+ * Two things were wrong with converting at each call site:
+ *
+ * 1. **`$schema` leaked into every request.** `zodToJsonSchema` stamps
+ *    `"$schema": "http://json-schema.org/draft-07/schema#"` on the root.
+ *    No provider reads it, and it rides in the tools block — which renders
+ *    at position 0, inside the cached prefix — once per tool, per request,
+ *    forever.
+ *
+ * 2. **Conversion ran on the hot path.** `toLLMTools` is called once per
+ *    iteration and re-walked every registered tool's Zod tree each time. A
+ *    schema does not change between iterations; the work was pure waste,
+ *    and worse, it made byte-stability a hope rather than a guarantee. The
+ *    tools block sits at the head of the prompt-cache prefix, so a single
+ *    reordered key would invalidate the entire cache for the run.
+ *
+ * Memoizing on the schema OBJECT (a `WeakMap`, so an unregistered tool's
+ * entry is collectable) makes the rendering both free and identical across
+ * iterations.
+ */
+const CACHE = new WeakMap<object, Record<string, unknown>>()
+
+/**
+ * Render a tool's input schema for the wire: converted once, normalized,
+ * and deeply frozen.
+ *
+ * The freeze is not decoration. A cached object handed to a caller that
+ * mutates it would poison every later render — and the symptom would be a
+ * silently invalidated prompt cache, not an error. Freezing turns that
+ * into a throw at the mutation site.
+ */
+export function renderToolSchema(schema: z.ZodType): Record<string, unknown> {
+	const cached = CACHE.get(schema)
+	if (cached) return cached
+
+	const json = zodToJsonSchema(schema, {
+		target: 'jsonSchema7',
+		$refStrategy: 'none',
+	}) as Record<string, unknown>
+
+	const normalized = deepFreeze(normalizeToolSchema(json))
+	CACHE.set(schema, normalized)
+	return normalized
+}
+
+/**
+ * Strip what no provider reads.
+ *
+ * Only `$schema` today, and only at the root — `zodToJsonSchema` does not
+ * stamp it on nested nodes. Kept as a named function rather than an inline
+ * `delete` so the next "providers ignore this" field has an obvious home
+ * and a place to be justified.
+ */
+export function normalizeToolSchema(json: Record<string, unknown>): Record<string, unknown> {
+	if (!('$schema' in json)) return json
+	const { $schema: _dropped, ...rest } = json
+	return rest
+}
+
+/**
+ * Clear the render cache. Tests only — a schema object's identity is the
+ * cache key, so production has nothing to invalidate.
+ */
+export function clearToolSchemaCache(schemas: readonly z.ZodType[]): void {
+	for (const schema of schemas) CACHE.delete(schema)
+}
+
+function deepFreeze<T>(value: T): T {
+	if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return value
+	for (const key of Object.keys(value as Record<string, unknown>)) {
+		deepFreeze((value as Record<string, unknown>)[key])
+	}
+	return Object.freeze(value)
+}

package/src/registry/toolset/catalog.test.ts

@@ -49,7 +49,6 @@ describe('ToolCatalog', () => {
 				enabled: true,
 				loading: 'deferred',
 				preferred: true,
-				permissionPolicy: 'always_allow',
 			},
 		})
 		catalog.registerTool({

package/src/registry/toolset/catalog.ts

@@ -37,7 +37,6 @@ const DEFAULT_HOST_TOOLSET: ToolsetDefinition = {
 	defaultPolicy: {
 		enabled: true,
 		loading: 'eager',
-		permissionPolicy: 'default',
 	},
 }