@namzu/sdk 0.6.0 → 1.1.0

package/src/registry/index.ts

@@ -4,6 +4,13 @@ export type { ManagedRegistryConfig } from './ManagedRegistry.js'
 
 export { ToolRegistry } from './tool/execute.js'
 export type { ToolExecutionResult } from './tool/execute.js'
+export {
+	ToolCatalog,
+	createToolCatalogFromRegistry,
+	loadingFromAvailability,
+	toolDefinitionToCatalogEntry,
+} from './toolset/catalog.js'
+export type { ToolCatalogFromRegistryOptions, ToolCatalogSearchOptions } from './toolset/catalog.js'
 
 export { ConnectorRegistry } from './connector/definitions.js'
 export { ScopedConnectorRegistry } from './connector/scoped.js'

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

@@ -20,16 +20,21 @@
  *     reports true iff at least one tool is suspended.
  *   - `getAvailability(name)` returns 'active' as a default even for
  *     unknown names (this is non-obvious but is the current behavior).
- *   - `searchDeferred(q)` is a case-insensitive filter against name OR
- *     description of every DEFERRED tool.
+ *   - `searchDeferred(q)` is a RANKED weighted search over DEFERRED tools:
+ *     per meaningful term (≥3 chars, not a stop token) the score is
+ *     exact-name 12 / name-substring 8 / description 5 / argument-name 3;
+ *     results sort score-descending with name ties broken alphabetically.
+ *     Generic/short tokens (`clawtool`, `tool`, CRUD verbs like `list`,
+ *     `read`, …) are stopped so they can't over-activate the catalog.
  *   - `assignTiers(mapping)` mutates `tool.tier` on existing tools;
  *     throws via `getOrThrow` on unknown name; throws if the tier id
  *     is not in `tierConfig.tiers`.
  *   - `toTierGuidance` returns null without a guidanceTemplate; calls
  *     the template with every defined tier otherwise.
  *   - `toPromptSection`: returns '' when no active or deferred tools;
- *     otherwise produces `<available_tools>` + `<deferred_tools>`
- *     fragments.
+ *     otherwise produces `<available_tools>` (name-only — descriptions
+ *     already ride the runtime tools param) + `<deferred_tools>` (name +
+ *     first-sentence hint ≤100 chars) fragments.
  *   - `toLLMTools`: converts active + suspended tools (filtered by
  *     `toolNames` if provided) into LLM tool schemas via
  *     `zodToJsonSchema`. When `tierConfig.labelInDescription` is true,
@@ -84,6 +89,15 @@ describe('ToolRegistry — register + availability', () => {
 		expect(r.getAvailability('b')).toBe('deferred')
 	})
 
+	it('register overloads: array w/o state defaults active, (id, tool) form, bad id throws', () => {
+		const r = new ToolRegistry()
+		r.register([makeTool('arr')])
+		expect(r.getAvailability('arr')).toBe('active')
+		r.register('byid', makeTool('byid'))
+		expect(r.get('byid')).toBeDefined()
+		expect(() => r.register('oops', 'not-a-tool' as never)).toThrow(/requires a ToolDefinition/)
+	})
+
 	it('getAvailability returns active for unknown names (current default)', () => {
 		const r = new ToolRegistry()
 		expect(r.getAvailability('never-registered')).toBe('active')
@@ -180,6 +194,79 @@ describe('ToolRegistry — searchDeferred', () => {
 		expect(r.searchDeferred('does').map((t) => t.name)).toEqual(['alpha', 'beta'])
 		expect(r.searchDeferred('gamma')).toEqual([])
 	})
+
+	it('tokenizes a multi-term query so a batch of tool names each match', () => {
+		const r = new ToolRegistry()
+		r.register([makeTool('clawtool_A2aCard')], 'deferred')
+		r.register([makeTool('clawtool_PeerRegister')], 'deferred')
+		r.register([makeTool('clawtool_PeerList')], 'deferred')
+		r.register([makeTool('clawtool_Unrelated')], 'deferred')
+		// A whole-phrase substring match would find none of these. Equal
+		// scores tie-break alphabetically by name (deterministic ranking).
+		expect(r.searchDeferred('A2aCard PeerRegister PeerList').map((t) => t.name)).toEqual([
+			'clawtool_A2aCard',
+			'clawtool_PeerList',
+			'clawtool_PeerRegister',
+		])
+		expect(r.searchDeferred('   ')).toEqual([])
+	})
+
+	it('ranks exact name above name substring above description-only matches', () => {
+		const r = new ToolRegistry()
+		r.register([makeTool('release_notes', { description: 'Write deploy notes.' })], 'deferred')
+		r.register([makeTool('deploy_preview', { description: 'Stage a preview build.' })], 'deferred')
+		r.register([makeTool('deploy', { description: 'Ship the current build.' })], 'deferred')
+		expect(r.searchDeferred('deploy').map((t) => t.name)).toEqual([
+			'deploy', // exact name → 12
+			'deploy_preview', // name substring → 8
+			'release_notes', // description only → 5
+		])
+	})
+
+	it('indexes argument names so a parameter term can locate a tool', () => {
+		const r = new ToolRegistry()
+		r.register(
+			[
+				makeTool('send_invoice', {
+					inputSchema: z.object({ customerEmail: z.string(), amount: z.number() }),
+				}),
+			],
+			'deferred',
+		)
+		r.register([makeTool('send_reminder')], 'deferred')
+		expect(r.searchDeferred('customerEmail').map((t) => t.name)).toEqual(['send_invoice'])
+	})
+
+	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.' })],
+			'deferred',
+		)
+		r.register([makeTool('list_workflows', { description: 'List workflows.' })], 'deferred')
+		r.register([makeTool('read_document', { description: 'Read a document body.' })], 'deferred')
+		// Bare CRUD verbs identify nothing.
+		expect(r.searchDeferred('list')).toEqual([])
+		expect(r.searchDeferred('read')).toEqual([])
+		expect(r.searchDeferred('create update delete')).toEqual([])
+		// The non-generic remainder carries the query.
+		expect(r.searchDeferred('list deals').map((t) => t.name)).toEqual(['list_deals'])
+		expect(r.searchDeferred('read document').map((t) => t.name)).toEqual(['read_document'])
+	})
+
+	it('does not over-activate on generic/shared tokens', () => {
+		const r = new ToolRegistry()
+		r.register([makeTool('clawtool_A2aCard', { description: 'peer card' })], 'deferred')
+		r.register([makeTool('clawtool_PeerList', { description: 'list peers' })], 'deferred')
+		r.register([makeTool('clawtool_WebSearch', { description: 'search the web' })], 'deferred')
+		// The shared "clawtool" prefix token must not drag in every tool.
+		expect(r.searchDeferred('clawtool WebSearch').map((t) => t.name)).toEqual([
+			'clawtool_WebSearch',
+		])
+		// A bare generic token identifies nothing — must not activate the catalog.
+		expect(r.searchDeferred('clawtool')).toEqual([])
+		expect(r.searchDeferred('tool')).toEqual([])
+	})
 })
 
 describe('ToolRegistry — tier mutation + guidance', () => {
@@ -227,10 +314,49 @@ describe('ToolRegistry — toPromptSection + toLLMTools', () => {
 		r.register(makeTool('a'))
 		r.register([makeTool('b')], 'deferred')
 		const s = r.toPromptSection()
+		expect(s).toContain('<tool_runtime_contract>')
+		expect(s).toContain('runtime tools parameter')
 		expect(s).toContain('<available_tools>')
-		expect(s).toContain('- a: a tool')
+		// Active entries are NAME-ONLY: the description already rides the
+		// runtime tools param every request — repeating it double-bills.
+		expect(s).toContain('- a\n')
+		expect(s).not.toContain('- a: a tool')
 		expect(s).toContain('<deferred_tools>')
-		expect(s).toContain('- b')
+		expect(s).toContain('Deferred tools are discoverable')
+		// Deferred entries carry a one-line hint — their schema is off the
+		// wire, so the hint is the model's only capability signal.
+		expect(s).toContain('- b: b tool')
+	})
+
+	it('toPromptSection truncates deferred hints to the first sentence, capped at 100 chars', () => {
+		const r = new ToolRegistry()
+		r.register(
+			[
+				makeTool('two_sentences', {
+					description: 'Reads the document. Second sentence that must not appear.',
+				}),
+				makeTool('long_sentence', {
+					description: `${'x'.repeat(150)} end`,
+				}),
+			],
+			'deferred',
+		)
+		const s = r.toPromptSection()
+		expect(s).toContain('- two_sentences: Reads the document.')
+		expect(s).not.toContain('Second sentence')
+		const longLine = s.split('\n').find((line) => line.startsWith('- long_sentence:'))
+		expect(longLine).toBeDefined()
+		const hint = (longLine ?? '').replace('- long_sentence: ', '')
+		expect(hint.length).toBeLessThanOrEqual(100)
+		expect(hint.endsWith('…')).toBe(true)
+	})
+
+	it('toPromptSection references search_tools only when it is active', () => {
+		const r = new ToolRegistry()
+		r.register(makeTool('search_tools'))
+		r.register([makeTool('b')], 'deferred')
+		const s = r.toPromptSection()
+		expect(s).toContain('Use search_tools to load these before use')
 	})
 
 	it('toLLMTools: converts active + suspended tools', () => {
@@ -303,7 +429,41 @@ describe('ToolRegistry — execute', () => {
 		)
 		const result = await r.execute('strict', { required: 123 }, makeContext())
 		expect(result.success).toBe(false)
-		expect(result.error).toMatch(/Invalid input/)
+		expect(result.error).toMatch(/Validation failed for "strict"/)
+		expect(result.error).toContain('Expected string, received number')
+	})
+
+	it('empty-args validation lists required params with descriptions', async () => {
+		const r = new ToolRegistry()
+		r.register(
+			makeTool('needs', {
+				inputSchema: z.object({ q: z.string().describe('the query'), n: z.number() }),
+			}),
+		)
+		const result = await r.execute('needs', {}, makeContext())
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/called with no arguments/)
+		expect(result.error).toContain('q: string — the query')
+		expect(result.error).toContain('n: number')
+	})
+
+	it('validation hint reports when there are no required params', async () => {
+		const r = new ToolRegistry()
+		r.register(makeTool('opt', { inputSchema: z.object({ k: z.string().optional() }) }))
+		const result = await r.execute('opt', { k: 123 }, makeContext())
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('No required parameters known.')
+	})
+
+	it('validation hint tolerates a schema it cannot introspect', async () => {
+		const r = new ToolRegistry()
+		const bogusSchema = {
+			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())
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('Could not introspect required parameters.')
 	})
 
 	it('wraps thrown errors in the execute function', async () => {
@@ -320,6 +480,50 @@ describe('ToolRegistry — execute', () => {
 		expect(result.error).toMatch(/execution failed: boom/)
 	})
 
+	it('wraps a non-Error throw', async () => {
+		const r = new ToolRegistry()
+		r.register(
+			makeTool('throws-string', {
+				async execute() {
+					throw 'plain string failure'
+				},
+			}),
+		)
+		const result = await r.execute('throws-string', {}, makeContext())
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/execution failed/)
+	})
+
+	it('passes through a tool result that is unsuccessful with an error', async () => {
+		const r = new ToolRegistry()
+		r.register(
+			makeTool('soft-fail', {
+				async execute() {
+					return { success: false, output: '', error: 'soft failure' }
+				},
+			}),
+		)
+		const result = await r.execute('soft-fail', {}, makeContext())
+		expect(result.success).toBe(false)
+		expect(result.error).toBe('soft failure')
+	})
+
+	it('blocks a non-read-only tool in plan mode (no isReadOnly hint)', async () => {
+		const r = new ToolRegistry()
+		const execute = vi.fn(async () => ({ success: true, output: 'ok' }))
+		r.register(makeTool('mutate', { execute }))
+		const result = await r.execute(
+			'mutate',
+			{},
+			makeContext({
+				permissionContext: { mode: 'plan', runId: 'run_1', workingDirectory: '/tmp' },
+			}),
+		)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/plan mode/)
+		expect(execute).not.toHaveBeenCalled()
+	})
+
 	it('returns the tool result on happy path', async () => {
 		const r = new ToolRegistry()
 		r.register(makeTool('good'))

package/src/registry/tool/execute.ts

@@ -16,6 +16,39 @@ import { ManagedRegistry } from '../ManagedRegistry.js'
 
 export type { ToolExecutionResult }
 
+// Tokens too generic to identify a tool by name — ignored when matching a
+// batched `search_tools` query so they can't activate the whole catalog
+// (every bridged tool name shares the `clawtool` prefix, for instance).
+// Generic CRUD verbs are stopped too: a query like "list deals" must rank
+// by "deals", not token-match every `list_*` tool in the deferred catalog.
+const SEARCH_STOP_TOKENS = new Set([
+	'clawtool',
+	'tool',
+	'tools',
+	'mcp',
+	'the',
+	'and',
+	'for',
+	'use',
+	'list',
+	'read',
+	'create',
+	'update',
+	'get',
+	'find',
+	'delete',
+	'search',
+])
+
+// 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.
+const SEARCH_WEIGHT_NAME_EXACT = 12
+const SEARCH_WEIGHT_NAME_PARTIAL = 8
+const SEARCH_WEIGHT_DESCRIPTION = 5
+const SEARCH_WEIGHT_ARGUMENT = 3
+
 export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	private availability: Map<string, ToolAvailability> = new Map()
 	private tierConfig?: ToolTierConfig
@@ -113,11 +146,58 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 		return this.availability.get(name) ?? 'active'
 	}
 
+	/**
+	 * Ranked lexical search over DEFERRED tools, score-descending (ties broken
+	 * by name) so callers can cap activation at a top-k. Each meaningful query
+	 * term (≥3 chars, not a stop token) is scored against the tool name
+	 * (exact/substring), description, and argument names; only tools with a
+	 * positive score are returned. Description matching is safe here precisely
+	 * because the result is RANKED — the `search_tools` builtin activates only
+	 * the top slice, so a shared word can no longer drag in the whole catalog.
+	 *
+	 * PARKED (phase 5 of the tool-loading plan): an embedding-backed semantic
+	 * upgrade was evaluated and deliberately NOT built — at ≤~35 deferred
+	 * in-house tools with distinct names, weighted lexical scoring sits inside
+	 * the literature's safe zone, and a weak retriever underperforms no
+	 * retriever at all. Revisit only when (a) the deferred catalog grows past
+	 * ~75-100 tools (realistic driver: connector-MCP growth), or (b) telemetry
+	 * shows a search_tools miss-rate above ~10%. Sticky activation is also
+	 * deliberate: activating inserts the schema into the tools array at its
+	 * registry position (a one-time prompt-cache prefix bust); re-defer/TTL
+	 * would churn that prefix repeatedly and is rejected.
+	 */
 	searchDeferred(query: string): ToolDefinition[] {
-		const q = query.toLowerCase()
-		return this.getByAvailability(['deferred']).filter(
-			(t) => t.name.toLowerCase().includes(q) || t.description.toLowerCase().includes(q),
-		)
+		const q = query.toLowerCase().trim()
+		if (q.length === 0) return []
+		const terms = q.split(/\s+/).filter((tok) => tok.length >= 3 && !SEARCH_STOP_TOKENS.has(tok))
+		if (terms.length === 0) return []
+
+		const scored: Array<{ tool: ToolDefinition; score: number }> = []
+		for (const tool of this.getByAvailability(['deferred'])) {
+			const name = tool.name.toLowerCase()
+			const description = tool.description.toLowerCase()
+			const argumentNames = listArgumentNames(tool)
+			let score = 0
+			for (const term of terms) {
+				if (name === term) {
+					score += SEARCH_WEIGHT_NAME_EXACT
+				} else if (name.includes(term)) {
+					score += SEARCH_WEIGHT_NAME_PARTIAL
+				}
+				if (description.includes(term)) {
+					score += SEARCH_WEIGHT_DESCRIPTION
+				}
+				if (argumentNames.some((arg) => arg.includes(term))) {
+					score += SEARCH_WEIGHT_ARGUMENT
+				}
+			}
+			if (score > 0) {
+				scored.push({ tool, score })
+			}
+		}
+
+		scored.sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name))
+		return scored.map((entry) => entry.tool)
 	}
 
 	assignTiers(mapping: Record<string, string>): void {
@@ -149,21 +229,38 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 		const deferred = this.getByAvailability(['deferred'], toolNames)
 
 		const parts: string[] = []
+		const contractNote = `<tool_runtime_contract>
+Executable tool names, descriptions, and JSON input schemas are attached through the runtime tools parameter. Treat that runtime schema as authoritative; this prompt section is a discoverability summary only.
+</tool_runtime_contract>`
 
 		if (active.length > 0) {
-			const entries = active.map((t) => `- ${t.name}: ${t.description}`).join('\n')
+			// Name-only: every active tool's full description + JSON schema
+			// already rides the runtime tools parameter on each request —
+			// repeating descriptions here double-bills the same tokens.
+			const entries = active.map((t) => `- ${t.name}`).join('\n')
 			parts.push(`<available_tools>\n${entries}\n</available_tools>`)
 		}
 
 		if (deferred.length > 0) {
-			const entries = deferred.map((t) => `- ${t.name}`).join('\n')
-			parts.push(
-				`<deferred_tools>\nUse search_tools to load these before use:\n${entries}\n</deferred_tools>`,
-			)
+			// Name + one-line hint: deferred schemas stay off the wire, so the
+			// hint is the model's only signal of what a deferred tool does. A
+			// bare name list caused a real discovery failure in production
+			// (the agent never found read_document behind search_tools).
+			const entries = deferred
+				.map((t) => {
+					const hint = toolDiscoveryHint(t.description)
+					return hint.length > 0 ? `- ${t.name}: ${hint}` : `- ${t.name}`
+				})
+				.join('\n')
+			const deferredIntro =
+				this.has('search_tools') && this.getAvailability('search_tools') === 'active'
+					? 'Use search_tools to load these before use:'
+					: 'Deferred tools are discoverable but not executable until the runtime activates them:'
+			parts.push(`<deferred_tools>\n${deferredIntro}\n${entries}\n</deferred_tools>`)
 		}
 
 		if (parts.length === 0) return ''
-		return parts.join('\n\n')
+		return [contractNote, ...parts].join('\n\n')
 	}
 
 	toLLMTools(toolNames?: string[]): LLMToolSchema[] {
@@ -254,8 +351,33 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 					.map((i) => `${i.path.join('.')}: ${i.message}`)
 					.join('; ')
 
+				// 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
+				// occasionally pings tool surfaces with `{}` while the
+				// schema is still loading), the second is a genuine
+				// programming mistake by the model. The model self-
+				// corrects MUCH more reliably when the error tells it
+				// (a) which fields are required, (b) their types, and
+				// (c) a minimal example call. Without these hints the
+				// downstream UI just shows a red "Failed" row and the
+				// model rarely retries with the right args.
+				const isEmptyInput =
+					rawInput === null ||
+					rawInput === undefined ||
+					(typeof rawInput === 'object' &&
+						!Array.isArray(rawInput) &&
+						Object.keys(rawInput as Record<string, unknown>).length === 0)
+
+				const requiredHint = describeRequiredInput(tool.inputSchema)
+
+				const enrichedMessage = isEmptyInput
+					? `Tool "${toolName}" was called with no arguments. ${requiredHint} Retry the call with the required parameters populated.`
+					: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}`
+
 				this.log.error(`Tool input validation failed: ${toolName}`, {
 					errors: errorMessage,
+					empty: isEmptyInput,
 				})
 
 				span.setAttributes({
@@ -268,7 +390,7 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 				return {
 					success: false,
 					output: '',
-					error: `Invalid input for tool "${toolName}": ${errorMessage}`,
+					error: enrichedMessage,
 				}
 			}
 
@@ -319,3 +441,69 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 		return candidates.filter((t) => states.includes(this.getAvailability(t.name)))
 	}
 }
+
+/**
+ * One-line discoverability hint for a deferred tool: the first sentence of
+ * its description, capped at ~100 chars. Used for the `<deferred_tools>`
+ * prompt listing and for `search_tools` near-miss suggestions, where the
+ * full description would re-import the token weight deferral avoids.
+ */
+export function toolDiscoveryHint(description: string, maxLength = 100): string {
+	const normalized = description.trim().replace(/\s+/g, ' ')
+	if (normalized.length === 0) return ''
+	const sentenceMatch = normalized.match(/^.*?[.!?](?=\s|$)/)
+	const sentence = sentenceMatch ? sentenceMatch[0] : normalized
+	if (sentence.length <= maxLength) return sentence
+	return `${sentence.slice(0, maxLength - 1).trimEnd()}…`
+}
+
+/**
+ * Lower-cased argument (property) names of a tool's input schema, used by
+ * `searchDeferred` ranking. Walks the JSON-Schema rendering (already a
+ * registration dependency) instead of Zod internals; opaque schemas simply
+ * contribute no argument matches.
+ */
+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())
+	} catch {
+		return []
+	}
+}
+
+/**
+ * Build a one-sentence "Required: <field>: <type>, <field>: <type>"
+ * hint from a Zod schema, used to enrich tool-input validation
+ * errors so the model can self-correct without round-tripping the
+ * full JSON schema again. Walks the schema's JSON-Schema rendering
+ * (already a dependency for tool registration) so we don't have to
+ * branch over Zod's internal type tree.
+ *
+ * Returns a fallback string for opaque/non-object schemas — the
+ * caller still ships the raw Zod issues separately, so the hint
+ * here is bonus context, not the only signal.
+ */
+function describeRequiredInput(schema: { _def?: unknown }): string {
+	try {
+		const json = zodToJsonSchema(schema as never) as {
+			properties?: Record<string, { type?: string; description?: string }>
+			required?: string[]
+		}
+		const required = json.required ?? []
+		if (required.length === 0) return 'No required parameters known.'
+		const props = json.properties ?? {}
+		const lines = required.map((name) => {
+			const def = props[name] ?? {}
+			const type = def.type ?? 'value'
+			const desc = def.description ? ` — ${def.description}` : ''
+			return `${name}: ${type}${desc}`
+		})
+		return `Required: ${lines.join(', ')}.`
+	} catch {
+		return 'Could not introspect required parameters.'
+	}
+}