@namzu/sdk 1.4.0 → 3.0.0

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,12 +44,67 @@ 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
@@ -88,6 +144,16 @@ 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.`,
+			)
+		}
 		if (tool.tier && this.tierConfig) {
 			const validIds = this.tierConfig.tiers.map((t) => t.id)
 			if (!validIds.includes(tool.tier)) {
@@ -278,11 +344,10 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				type: 'function' as const,
 				function: {
 					name: tool.name,
-					description,
-					parameters: zodToJsonSchema(tool.inputSchema, {
-						target: 'jsonSchema7',
-						$refStrategy: 'none',
-					}) as Record<string, unknown>,
+					description: describeWithOutput(description, tool.outputSchema),
+					parameters:
+						(tool.modelInputSchema ? structuredClone(tool.modelInputSchema) : undefined) ??
+						renderToolSchema(tool.inputSchema),
 				},
 			}
 		})
@@ -299,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',
@@ -353,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-
@@ -370,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()}`
 					: ''
@@ -401,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 })
@@ -468,16 +554,47 @@ export function toolDiscoveryHint(description: string, maxLength = 100): string
  */
 function listArgumentNames(tool: ToolDefinition): string[] {
 	try {
-		const json = zodToJsonSchema(tool.inputSchema, {
-			target: 'jsonSchema7',
-			$refStrategy: 'none',
-		}) as { properties?: Record<string, unknown> }
-		return Object.keys(json.properties ?? {}).map((key) => key.toLowerCase())
+		// 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(),
+	seen: Set<object> = new Set(),
+): Set<string> {
+	if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return names
+	if (seen.has(schema)) return names
+	seen.add(schema)
+
+	const record = schema as Record<string, unknown>
+	const properties = record.properties
+	if (properties && typeof properties === 'object' && !Array.isArray(properties)) {
+		for (const name of Object.keys(properties)) names.add(name)
+	}
+	for (const keyword of ['anyOf', 'oneOf', 'allOf'] as const) {
+		const branches = record[keyword]
+		if (!Array.isArray(branches)) continue
+		for (const branch of branches) collectSchemaPropertyNames(branch, names, seen)
+	}
+	return names
+}
+
 /**
  * Build a one-sentence "Required: <field>: <type>, <field>: <type>"
  * hint from a Zod schema, used to enrich tool-input validation
@@ -492,7 +609,7 @@ function listArgumentNames(tool: ToolDefinition): string[] {
  */
 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

@@ -16,6 +16,18 @@ function makeTool(name: string, description = `${name} tool`): ToolDefinition {
 	}
 }
 
+function makeCatalog(): ToolCatalog {
+	const catalog = new ToolCatalog()
+	catalog.registerSource({ id: 'host', kind: 'host_tool', name: 'Host' })
+	catalog.registerToolset({
+		id: 'tools',
+		sourceId: 'host',
+		name: 'Tools',
+		defaultPolicy: { enabled: true, loading: 'eager' },
+	})
+	return catalog
+}
+
 describe('ToolCatalog', () => {
 	it('keeps sources, toolsets, and tools as separate records', () => {
 		const catalog = new ToolCatalog()
@@ -37,7 +49,6 @@ describe('ToolCatalog', () => {
 				enabled: true,
 				loading: 'deferred',
 				preferred: true,
-				permissionPolicy: 'always_allow',
 			},
 		})
 		catalog.registerTool({
@@ -162,4 +173,110 @@ describe('ToolCatalog', () => {
 		expect(catalog.getTool('write_file')?.policy.loading).toBe('suspended')
 		expect(catalog.toLLMTools({ loading: ['suspended'] })).toEqual([])
 	})
+
+	it('rejects catalog, definition, and LLM schema name mismatches', () => {
+		const catalog = makeCatalog()
+		expect(() =>
+			catalog.registerTool({
+				name: 'edit',
+				description: 'Edit a file',
+				sourceId: 'host',
+				toolsetId: 'tools',
+				policy: { enabled: true, loading: 'eager' },
+				definition: makeTool('write'),
+			}),
+		).toThrow(/definition name mismatch/)
+
+		expect(() =>
+			catalog.registerTool({
+				name: 'edit',
+				description: 'Edit a file',
+				sourceId: 'host',
+				toolsetId: 'tools',
+				policy: { enabled: true, loading: 'eager' },
+				llmSchema: {
+					type: 'function',
+					function: {
+						name: 'write',
+						description: 'Write',
+						parameters: { type: 'object' },
+					},
+				},
+			}),
+		).toThrow(/LLM schema name mismatch/)
+	})
+
+	it('rejects an explicit LLM schema that could replace an enforced definition schema', () => {
+		const catalog = makeCatalog()
+		const definition: ToolDefinition = {
+			...makeTool('edit'),
+			modelInputSchema: {
+				type: 'object',
+				properties: { path: { type: 'string' } },
+				required: ['path'],
+				additionalProperties: false,
+			},
+			enforceModelInput: true,
+		}
+
+		expect(() =>
+			catalog.registerTool({
+				name: 'edit',
+				description: 'Edit a file',
+				sourceId: 'host',
+				toolsetId: 'tools',
+				policy: { enabled: true, loading: 'eager' },
+				definition,
+				llmSchema: {
+					type: 'function',
+					function: {
+						name: 'edit',
+						description: 'Unsafe override',
+						parameters: { type: 'object' },
+					},
+				},
+			}),
+		).toThrow(/cannot combine an explicit llmSchema with enforceModelInput/)
+	})
+
+	it('rejects an enforced catalog definition without an explicit model schema', () => {
+		const catalog = makeCatalog()
+		expect(() =>
+			catalog.registerTool({
+				name: 'edit',
+				description: 'Edit a file',
+				sourceId: 'host',
+				toolsetId: 'tools',
+				policy: { enabled: true, loading: 'eager' },
+				definition: {
+					...makeTool('edit'),
+					enforceModelInput: true,
+				},
+			}),
+		).toThrow(/enforceModelInput.*modelInputSchema/)
+	})
+
+	it('uses a definition model schema when no explicit catalog schema overrides it', () => {
+		const registry = new ToolRegistry()
+		const modelInputSchema = {
+			type: 'object',
+			properties: { new_string: { type: 'string' } },
+			required: ['new_string'],
+			additionalProperties: false,
+		}
+		registry.register({
+			...makeTool('edit'),
+			modelInputSchema,
+		})
+
+		const catalog = createToolCatalogFromRegistry(registry)
+		const firstSchema = catalog.toLLMTools()[0]?.function.parameters
+		expect(firstSchema).toEqual(modelInputSchema)
+		expect(firstSchema).not.toBe(modelInputSchema)
+		;(firstSchema?.properties as Record<string, unknown>).newStr = { type: 'string' }
+
+		const nextSchema = catalog.toLLMTools()[0]?.function.parameters
+		expect(nextSchema).toEqual(modelInputSchema)
+		expect(JSON.stringify(nextSchema)).not.toContain('newStr')
+	})
 })

package/src/registry/toolset/catalog.ts

@@ -37,7 +37,6 @@ const DEFAULT_HOST_TOOLSET: ToolsetDefinition = {
 	defaultPolicy: {
 		enabled: true,
 		loading: 'eager',
-		permissionPolicy: 'default',
 	},
 }
 
@@ -64,6 +63,26 @@ export class ToolCatalog {
 		if (!this.toolsets.has(tool.toolsetId)) {
 			throw new Error(`Tool "${tool.name}" references unknown toolset "${tool.toolsetId}"`)
 		}
+		if (tool.definition && tool.definition.name !== tool.name) {
+			throw new Error(
+				`Tool "${tool.name}" definition name mismatch: received "${tool.definition.name}"`,
+			)
+		}
+		if (tool.llmSchema && tool.llmSchema.function.name !== tool.name) {
+			throw new Error(
+				`Tool "${tool.name}" LLM schema name mismatch: received "${tool.llmSchema.function.name}"`,
+			)
+		}
+		if (tool.definition?.enforceModelInput && !tool.definition.modelInputSchema) {
+			throw new Error(
+				`Tool "${tool.name}" enables enforceModelInput but does not define modelInputSchema.`,
+			)
+		}
+		if (tool.definition?.enforceModelInput && tool.llmSchema) {
+			throw new Error(
+				`Tool "${tool.name}" cannot combine an explicit llmSchema with enforceModelInput. Put the provider-safe schema on definition.modelInputSchema so enforcement and schema precedence stay paired.`,
+			)
+		}
 		this.tools.set(tool.name, tool)
 	}
 
@@ -226,10 +245,12 @@ function toolDefinitionToLLMTool(definition: ToolDefinition | undefined): LLMToo
 		function: {
 			name: definition.name,
 			description: definition.description,
-			parameters: zodToJsonSchema(definition.inputSchema, {
-				target: 'jsonSchema7',
-				$refStrategy: 'none',
-			}) as Record<string, unknown>,
+			parameters:
+				(definition.modelInputSchema ? structuredClone(definition.modelInputSchema) : undefined) ??
+				(zodToJsonSchema(definition.inputSchema, {
+					target: 'jsonSchema7',
+					$refStrategy: 'none',
+				}) as Record<string, unknown>),
 		},
 	}
 }

package/src/run/reporter.ts

@@ -78,6 +78,12 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				log.error('Run failed', {
 					runId: event.runId,
 					error: event.error,
+					// A greppable id and a sentence saying what to change,
+					// where before there was only whatever prose the vendor
+					// SDK happened to write.
+					code: event.failure?.code,
+					reason: event.explanation?.id,
+					hint: event.explanation?.hint,
 				})
 				break
 
@@ -225,6 +231,45 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'reasoning_started':
+			case 'reasoning_delta':
+				// High-frequency and content-bearing; the completed block
+				// below carries everything a log needs.
+				break
+
+			case 'reasoning_completed':
+				log.debug('Reasoning block completed', {
+					runId: event.runId,
+					iteration: event.iteration,
+					blockIndex: event.blockIndex,
+					signed: event.signed,
+					chars: event.text?.length ?? 0,
+				})
+				break
+
+			case 'guardrail_triggered':
+				log.warn('Guardrail triggered', {
+					runId: event.runId,
+					stage: event.stage,
+					action: event.action,
+					guardrail: event.guardrail,
+					reason: event.reason,
+				})
+				break
+
+			case 'compaction_completed':
+				log.info('Context compacted', {
+					runId: event.runId,
+					iteration: event.iteration,
+					messagesDropped: event.messagesBefore - event.messagesAfter,
+					tokensBefore: event.tokensBefore,
+					tokensAfter: event.tokensAfter,
+					measuredBy: event.measuredBy,
+					contextWindowTokens: event.contextWindowTokens,
+					windowSource: event.windowSource,
+				})
+				break
+
 			case 'capability_warning':
 				log.warn('Provider capability mismatch', {
 					runId: event.runId,
@@ -234,6 +279,45 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'tool_progress':
+				// Debug, not info: a long tool can emit many of these and they
+				// are a live-view signal, not a run milestone.
+				log.debug(`Tool progress: ${event.toolName}`, {
+					runId: event.runId,
+					tool: event.toolName,
+					message: event.message,
+				})
+				break
+
+			case 'user_question_asked':
+				log.info('Question asked — the run is parked on an answer', {
+					runId: event.runId,
+					checkpointId: event.checkpointId,
+					questionId: event.questionId,
+				})
+				break
+
+			case 'user_question_answered':
+				log.info(event.answered ? 'Question answered' : 'Question closed unanswered', {
+					runId: event.runId,
+					checkpointId: event.checkpointId,
+				})
+				break
+
+			case 'provider_retry':
+				// `warn`, not debug: this is the run going quiet for a
+				// measurable stretch, and the delay it names is still ahead.
+				log.warn(`Model call failed — retrying in ${event.delayMs}ms`, {
+					runId: event.runId,
+					iteration: event.iteration,
+					attempt: event.attempt,
+					maxRetries: event.maxRetries,
+					code: event.code,
+					status: event.status,
+					serverDirected: event.serverDirected,
+				})
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)