@namzu/sdk 1.4.0 → 2.0.0

package/src/registry/tool/execute.ts

@@ -54,7 +54,11 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	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
 	}
 
@@ -88,6 +92,11 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	}
 
 	private registerOne(id: string, tool: ToolDefinition, state: ToolAvailability): void {
+		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)) {
@@ -279,10 +288,12 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				function: {
 					name: tool.name,
 					description,
-					parameters: zodToJsonSchema(tool.inputSchema, {
-						target: 'jsonSchema7',
-						$refStrategy: 'none',
-					}) as Record<string, unknown>,
+					parameters:
+						(tool.modelInputSchema ? structuredClone(tool.modelInputSchema) : undefined) ??
+						(zodToJsonSchema(tool.inputSchema, {
+							target: 'jsonSchema7',
+							$refStrategy: 'none',
+						}) as Record<string, unknown>),
 				},
 			}
 		})
@@ -468,16 +479,40 @@ 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())
+		const json =
+			tool.modelInputSchema ??
+			(zodToJsonSchema(tool.inputSchema, {
+				target: 'jsonSchema7',
+				$refStrategy: 'none',
+			}) as Record<string, unknown>)
+		return [...collectSchemaPropertyNames(json)].map((key) => key.toLowerCase())
 	} catch {
 		return []
 	}
 }
 
+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

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()
@@ -162,4 +174,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

@@ -64,6 +64,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 +246,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/runtime/query/__tests__/capability-negotiation.test.ts

@@ -46,6 +46,32 @@ class CapturingProvider implements LLMProvider {
 	}
 }
 
+class ClosingSummaryProvider implements LLMProvider {
+	readonly id = 'closing-summary'
+	readonly name = 'Closing Summary Provider'
+	readonly calls: ChatCompletionParams[] = []
+
+	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		this.calls.push(params)
+		if (this.calls.length === 1) {
+			yield {
+				id: 'msg_empty',
+				delta: {},
+				finishReason: 'stop',
+				usage: ZERO_USAGE,
+			}
+			return
+		}
+		yield { id: 'msg_summary', delta: { content: 'closing summary' } }
+		yield {
+			id: 'msg_summary',
+			delta: {},
+			finishReason: 'stop',
+			usage: ZERO_USAGE,
+		}
+	}
+}
+
 const NO_TOOLS_CAPABILITIES: ProviderCapabilities = {
 	supportsTools: false,
 	supportsStreaming: true,
@@ -69,6 +95,25 @@ function registerEchoTool(tools: ToolRegistry): void {
 	})
 }
 
+function registerEnforcedTool(tools: ToolRegistry, name: string): void {
+	tools.register({
+		name,
+		description: `${name} tool`,
+		inputSchema: z.object({
+			new_string: z.string().optional(),
+			newStr: z.string().optional(),
+		}),
+		modelInputSchema: {
+			type: 'object',
+			properties: { new_string: { type: 'string' } },
+			required: ['new_string'],
+			additionalProperties: false,
+		},
+		enforceModelInput: true,
+		execute: async () => ({ success: true, output: 'ok' }),
+	})
+}
+
 function baseParams(provider: LLMProvider, tools: ToolRegistry, workingDirectory: string) {
 	return {
 		provider,
@@ -176,6 +221,49 @@ describe('query() capability negotiation', () => {
 		expect(provider.lastParams?.tools?.map((t) => t.function.name)).toContain('echo')
 	})
 
+	it('propagates enforcement names from the exact allowed and cache-stable tool schemas', async () => {
+		const provider = new CapturingProvider()
+		const tools = new ToolRegistry()
+		registerEnforcedTool(tools, 'edit')
+		registerEnforcedTool(tools, 'cached_edit')
+		registerEnforcedTool(tools, 'excluded_edit')
+		tools.suspendAll()
+		tools.activate(['edit'])
+
+		const run = await drainQuery({
+			...baseParams(provider, tools, await mkWorkdir()),
+			allowedTools: ['edit', 'cached_edit'],
+			messages: [createUserMessage('hello')],
+		})
+
+		expect(run.status).toBe('completed')
+		expect(provider.lastParams?.tools?.map((tool) => tool.function.name)).toEqual([
+			'edit',
+			'cached_edit',
+		])
+		expect(provider.lastParams?.enforceToolInputSchema).toEqual(['edit', 'cached_edit'])
+		expect(JSON.stringify(provider.lastParams?.tools)).not.toContain('newStr')
+	})
+
+	it('keeps the same enforcement hint on the closing-summary provider call', async () => {
+		const provider = new ClosingSummaryProvider()
+		const tools = new ToolRegistry()
+		registerEnforcedTool(tools, 'edit')
+
+		const run = await drainQuery({
+			...baseParams(provider, tools, await mkWorkdir()),
+			messages: [createUserMessage('hello')],
+		})
+
+		expect(run.status).toBe('completed')
+		expect(provider.calls).toHaveLength(2)
+		for (const call of provider.calls) {
+			expect(call.tools?.map((tool) => tool.function.name)).toEqual(['edit'])
+			expect(call.enforceToolInputSchema).toEqual(['edit'])
+		}
+		expect(provider.calls[1]?.toolChoice).toBe('none')
+	})
+
 	it('emits a vision capability_warning when attachments hit a no-vision provider', async () => {
 		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
 		const events: RunEvent[] = []

package/src/runtime/query/__tests__/deferred-tools.test.ts

@@ -44,6 +44,58 @@ class CapturingProvider implements LLMProvider {
 	}
 }
 
+class DeferredActivationProvider implements LLMProvider {
+	readonly id = 'deferred-activation'
+	readonly name = 'Deferred Activation Provider'
+	readonly calls: ChatCompletionParams[] = []
+
+	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		this.calls.push(params)
+		if (this.calls.length === 1) {
+			yield {
+				id: 'msg_search',
+				delta: {
+					toolCalls: [
+						{
+							index: 0,
+							id: 'toolu_search',
+							type: 'function',
+							function: { name: SearchToolsTool.name },
+						},
+					],
+				},
+			}
+			yield {
+				id: 'msg_search',
+				delta: {
+					toolCalls: [
+						{
+							index: 0,
+							id: 'toolu_search',
+							function: { arguments: '{"query":"canonical_key"}' },
+						},
+					],
+				},
+			}
+			yield {
+				id: 'msg_search',
+				delta: {},
+				finishReason: 'tool_calls',
+				usage: ZERO_USAGE,
+			}
+			return
+		}
+
+		yield { id: 'msg_done', delta: { content: 'done' } }
+		yield {
+			id: 'msg_done',
+			delta: {},
+			finishReason: 'stop',
+			usage: ZERO_USAGE,
+		}
+	}
+}
+
 function registerDeferredDocumentTool(tools: ToolRegistry, name = 'generate_document'): void {
 	tools.register(
 		{
@@ -156,6 +208,65 @@ describe('query deferred tool discovery', () => {
 		expect(systemPrompt).toContain('- generate_document')
 	})
 
+	it('adds enforcement only after a deferred model-schema tool is activated', async () => {
+		const provider = new DeferredActivationProvider()
+		const tools = new ToolRegistry()
+		tools.register(
+			{
+				name: 'deferred_edit',
+				description: 'Mutate a document using the provided content.',
+				inputSchema: z.object({ legacyKey: z.string() }),
+				modelInputSchema: {
+					type: 'object',
+					properties: { canonical_key: { type: 'string' } },
+					required: ['canonical_key'],
+					additionalProperties: false,
+				},
+				enforceModelInput: true,
+				execute: async () => ({ success: true, output: 'edited' }),
+			},
+			'deferred',
+		)
+
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-deferred-enforcement-'))
+		workdirs.push(workingDirectory)
+		const run = await drainQuery({
+			provider,
+			tools,
+			allowedTools: ['deferred_edit'],
+			runConfig: {
+				model: 'mock-model',
+				timeoutMs: 5_000,
+				tokenBudget: 100_000,
+				maxIterations: 3,
+				maxResponseTokens: 256,
+			},
+			agentId: 'agent_test',
+			agentName: 'Test Agent',
+			messages: [createUserMessage('find and load the right tool')],
+			workingDirectory,
+			sessionId: 'ses_deferred_enforcement' as SessionId,
+			threadId: 'thd_deferred_enforcement' as ThreadId,
+			projectId: 'prj_deferred_enforcement' as ProjectId,
+			tenantId: 'tnt_deferred_enforcement' as TenantId,
+		})
+
+		expect(run.status).toBe('completed')
+		expect(provider.calls).toHaveLength(2)
+		expect(provider.calls[0]?.tools?.map((tool) => tool.function.name)).toEqual([
+			SearchToolsTool.name,
+		])
+		expect(provider.calls[0]?.enforceToolInputSchema).toBeUndefined()
+		expect(provider.calls[1]?.tools?.map((tool) => tool.function.name)).toEqual([
+			'deferred_edit',
+			SearchToolsTool.name,
+		])
+		expect(provider.calls[1]?.enforceToolInputSchema).toEqual(['deferred_edit'])
+		expect(provider.calls[1]?.tools?.[0]?.function.parameters).toEqual(
+			tools.get('deferred_edit')?.modelInputSchema,
+		)
+	})
+
 	it('does not let search_tools reveal or activate deferred tools outside allowedTools', async () => {
 		const tools = new ToolRegistry()
 		registerDeferredDocumentTool(tools)

package/src/runtime/query/__tests__/long-document-flow.test.ts

@@ -107,27 +107,27 @@ describe('query long-document tool flow', () => {
 				name: 'write',
 				input: {
 					path: 'outputs/long-document-flow.md',
-					content: '# Long document flow\n\n{{BODY}}\n',
+					content: '# Long document flow\n\n{{CHUNK_001}}\n',
 				},
 			},
-			{
+			...chunks.map((chunk, index) => ({
 				name: 'edit',
 				input: {
 					path: 'outputs/long-document-flow.md',
-					oldStr: '{{BODY}}',
-					newStr: chunks[0],
+					old_string: `{{CHUNK_${String(index + 1).padStart(3, '0')}}}`,
+					new_string: `${chunk}\n{{CHUNK_${String(index + 2).padStart(3, '0')}}}`,
 					replace_all: false,
 				},
-			},
-			...chunks.slice(1).map((chunk) => ({
+			})),
+			{
 				name: 'edit',
 				input: {
 					path: 'outputs/long-document-flow.md',
-					insertLine: 'end',
-					newStr: chunk,
+					old_string: `{{CHUNK_${String(chunks.length + 1).padStart(3, '0')}}}`,
+					new_string: '',
 					replace_all: false,
 				},
-			})),
+			},
 		])
 		const tools = new ToolRegistry()
 		tools.register(WriteFileTool)
@@ -169,9 +169,9 @@ describe('query long-document tool flow', () => {
 
 		expect(run.status).toBe('completed')
 		expect(run.result).toBe('Long document created and verified.')
-		expect(provider.calls).toBe(6)
-		expect(executingTools).toEqual(['write', 'edit', 'edit', 'edit', 'edit'])
-		expect(final).not.toContain('{{BODY}}')
+		expect(provider.calls).toBe(7)
+		expect(executingTools).toEqual(['write', 'edit', 'edit', 'edit', 'edit', 'edit'])
+		expect(final).not.toContain('{{CHUNK_')
 		expect(final.split('\n').length).toBeGreaterThan(160)
 		expect(final).toContain('## Section 1')
 		expect(final).toContain('## Section 4')

package/src/runtime/query/__tests__/stream-recovery.test.ts

@@ -170,7 +170,7 @@ describe('query stream recovery', () => {
 			'call was cut off',
 		)
 		expect(completedTool?.type === 'tool_completed' ? completedTool.result : '').toContain(
-			'extend it with edit using insertLine',
+			'advance that marker with bounded exact edit calls',
 		)
 	})
 

package/src/runtime/query/executor.ts

@@ -103,7 +103,7 @@ export class ToolExecutor {
 
 		// Respect each tool's `concurrencySafe` flag. Read-only tools
 		// (ls/grep/glob/…) run in parallel; tools that mutate shared state
-		// (edit/write/append/bash — `concurrencySafe: false`) are serialized in
+		// (edit/write/bash — `concurrencySafe: false`) are serialized in
 		// a single chain, so e.g. several `edit` calls to the SAME file in one
 		// turn apply one-after-another instead of racing read→modify→write
 		// (which let the last writer clobber the rest). Results are written by
@@ -497,5 +497,5 @@ function formatFailedToolOutput(output: string | undefined, error: string | unde
 }
 
 function truncatedToolInputMessage(toolName: string): string {
-	return `Error: Tool "${toolName}" call was cut off while the model was streaming JSON arguments. The tool was NOT executed. Retry with a much shorter input. Self-budget any content/newStr payload under 12000 characters before calling file tools. For long files, create a short opening with write, then extend it with edit using insertLine: "end" in bounded section chunks; for delegated work, pass a shared workspace filename/reference instead of embedding the content in the tool call.`
+	return `Error: Tool "${toolName}" call was cut off while the model was streaming JSON arguments. The tool was NOT executed. Retry with a much shorter input. Self-budget content/new_string under 12000 characters before calling file tools. For long files, create a short opening with write and a deterministic marker, then advance that marker with bounded exact edit calls; for delegated work, pass a shared workspace filename/reference instead of embedding the content in the tool call.`
 }

package/src/runtime/query/iteration/index.ts

@@ -6,6 +6,7 @@ import { GENAI, NAMZU, agentIterationSpanName } from '../../../telemetry/attribu
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { createAssistantMessage, createUserMessage } from '../../../types/message/index.js'
 import type { RunEvent, StopReason } from '../../../types/run/index.js'
+import type { LLMToolSchema, ToolRegistryContract } from '../../../types/tool/index.js'
 import { toErrorMessage } from '../../../utils/error.js'
 import { generateMessageId } from '../../../utils/id.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
@@ -118,6 +119,7 @@ export class IterationOrchestrator {
 				// risks a 400 because the history still carries
 				// tool_use/tool_result blocks.
 				const openAITools = this.ctx.tools.toLLMTools(this.ctx.allowedTools)
+				const enforceToolInputSchema = enforcedModelInputToolNames(this.ctx.tools, openAITools)
 
 				const messages = forceFinalize
 					? [
@@ -152,6 +154,7 @@ export class IterationOrchestrator {
 						model,
 						messages,
 						tools: openAITools.length > 0 ? openAITools : undefined,
+						enforceToolInputSchema,
 						toolChoice: forceFinalize && openAITools.length > 0 ? 'none' : undefined,
 						temperature: runConfig.temperature,
 						maxTokens: runConfig.maxResponseTokens,
@@ -428,11 +431,13 @@ export class IterationOrchestrator {
 			// tools param identical to prior iterations (cache prefix intact,
 			// no 400 on tool blocks in history) and forbid use via tool_choice.
 			const finalTools = this.ctx.tools.toLLMTools(this.ctx.allowedTools)
+			const enforceToolInputSchema = enforcedModelInputToolNames(this.ctx.tools, finalTools)
 			const response = await collect(
 				this.ctx.provider.chatStream({
 					model,
 					messages: finalMessages,
 					tools: finalTools.length > 0 ? finalTools : undefined,
+					enforceToolInputSchema,
 					toolChoice: finalTools.length > 0 ? 'none' : undefined,
 					temperature: this.ctx.runConfig.temperature,
 					maxTokens: this.ctx.runConfig.maxResponseTokens,
@@ -471,3 +476,13 @@ export class IterationOrchestrator {
 		}
 	}
 }
+
+function enforcedModelInputToolNames(
+	registry: ToolRegistryContract,
+	tools: readonly LLMToolSchema[],
+): readonly string[] | undefined {
+	const names = tools
+		.map((tool) => tool.function.name)
+		.filter((name) => registry.get(name)?.enforceModelInput === true)
+	return names.length > 0 ? names : undefined
+}