@namzu/sdk 1.1.0 → 1.3.0

package/src/provider/registry.ts

@@ -1,13 +1,17 @@
 import type {
 	LLMProvider,
 	LLMProviderConstructor,
+	LazyProviderLoader,
+	LazyProviderModule,
 	ProviderCapabilities,
 	ProviderConfigRegistry,
 	ProviderFactoryConfig,
 	ProviderFactoryResult,
 	ProviderType,
+	RegisterLazyOptions,
 	RegisterOptions,
 } from '../types/provider/index.js'
+import { PERMISSIVE_PROVIDER_CAPABILITIES } from './capabilities.js'
 
 export class UnknownProviderError extends Error {
 	readonly providerType: string
@@ -31,9 +35,99 @@ export class DuplicateProviderError extends Error {
 	}
 }
 
+/**
+ * The loader passed to `ProviderRegistry.registerLazy()` rejected (or
+ * resolved to something without a `create(config)` function). Wraps the
+ * original failure as `cause`. The failed load is NOT cached — the next
+ * `createAsync()` for the type re-invokes the loader, so a transient
+ * failure (network hiccup during a dynamic import) does not permanently
+ * poison the type.
+ */
+export class LazyProviderLoadError extends Error {
+	readonly providerType: string
+
+	constructor(providerType: string, cause: unknown) {
+		const detail = cause instanceof Error ? cause.message : String(cause)
+		super(`Failed to load lazy provider "${providerType}": ${detail}`, { cause })
+		this.name = 'LazyProviderLoadError'
+		this.providerType = providerType
+	}
+}
+
+/**
+ * A synchronous `create()`/`createProvider()` was called for a type
+ * registered via `registerLazy()`. Lazy types are only constructible
+ * through the async path — deterministically, even after the loader has
+ * resolved, so calling code never depends on load-order timing.
+ */
+export class LazyProviderSyncCreateError extends Error {
+	readonly providerType: string
+
+	constructor(providerType: string) {
+		super(
+			`Provider type "${providerType}" is registered lazily; synchronous create()/createProvider() cannot load it. Use ProviderRegistry.createAsync() or createProviderAsync().`,
+		)
+		this.name = 'LazyProviderSyncCreateError'
+		this.providerType = providerType
+	}
+}
+
+interface LazyProviderEntry {
+	loader: LazyProviderLoader<unknown>
+	/** In-flight load shared by concurrent first-creates (dedupe). */
+	loading?: Promise<LazyProviderModule<unknown>>
+	/** Cached module — set only on SUCCESS, so failures retry. */
+	module?: LazyProviderModule<unknown>
+}
+
 // Module-private state. Only the exported functions below can read/mutate.
 const providers = new Map<string, LLMProviderConstructor<unknown>>()
 const capabilities = new Map<string, ProviderCapabilities>()
+const lazyProviders = new Map<string, LazyProviderEntry>()
+
+async function loadLazyModule(
+	type: string,
+	entry: LazyProviderEntry,
+): Promise<LazyProviderModule<unknown>> {
+	if (entry.module) {
+		return entry.module
+	}
+	let inflight = entry.loading
+	if (!inflight) {
+		// Promise.resolve().then(...) also catches loaders that throw synchronously.
+		inflight = Promise.resolve()
+			.then(() => entry.loader())
+			.then((mod) => {
+				if (typeof mod?.create !== 'function') {
+					throw new TypeError(
+						'loader resolved to a value without a create(config) function — map your dynamic import to { create: (config) => new Provider(config) }',
+					)
+				}
+				return mod
+			})
+		entry.loading = inflight
+	}
+	try {
+		const mod = await inflight
+		entry.module = mod
+		if (entry.loading === inflight) {
+			entry.loading = undefined
+		}
+		// The loaded module's declaration is authoritative at the type level:
+		// it replaces any registration-time hint for future getCapabilities().
+		if (mod.capabilities) {
+			capabilities.set(type, mod.capabilities)
+		}
+		return mod
+	} catch (cause) {
+		// Clear only OUR in-flight promise; a retry started by another caller
+		// after an earlier failure must not be dropped.
+		if (entry.loading === inflight) {
+			entry.loading = undefined
+		}
+		throw new LazyProviderLoadError(type, cause)
+	}
+}
 
 /**
  * Central registry for LLM providers.
@@ -56,6 +150,23 @@ const capabilities = new Map<string, ProviderCapabilities>()
  *   region: 'us-east-1',
  * })
  * ```
+ *
+ * Hosts that must not eagerly bundle every provider client register a
+ * LOADER instead and construct through the async path:
+ *
+ * @example
+ * ```ts
+ * ProviderRegistry.registerLazy(
+ *   'anthropic',
+ *   async () => {
+ *     const m = await import('@namzu/anthropic')
+ *     return { create: (c) => new m.AnthropicProvider(c), capabilities: m.ANTHROPIC_CAPABILITIES }
+ *   },
+ *   { capabilities: { supportsTools: true, supportsStreaming: true, supportsFunctionCalling: true } },
+ * )
+ *
+ * const { provider } = await ProviderRegistry.createAsync({ type: 'anthropic', apiKey })
+ * ```
  */
 export class ProviderRegistry {
 	static register<K extends ProviderType>(
@@ -64,46 +175,129 @@ export class ProviderRegistry {
 		caps: ProviderCapabilities,
 		options?: RegisterOptions,
 	): void {
-		if (providers.has(type) && !options?.replace) {
+		if ((providers.has(type) || lazyProviders.has(type)) && !options?.replace) {
 			throw new DuplicateProviderError(type)
 		}
+		lazyProviders.delete(type)
 		providers.set(type, ctor as LLMProviderConstructor<unknown>)
 		capabilities.set(type, caps)
 	}
 
+	/**
+	 * Register a provider type WITHOUT importing its implementation. The
+	 * loader is not invoked here; the first `createAsync()` for the type
+	 * awaits it, validates the resolved `{ create }` module, and caches it.
+	 * Subsequent creates reuse the cached factory. Only SUCCESS is cached:
+	 * a rejected load surfaces as `LazyProviderLoadError` and the next
+	 * `createAsync()` retries the loader. Concurrent first-creates share a
+	 * single in-flight load.
+	 *
+	 * Capability precedence (weakest first):
+	 * 1. `options.capabilities` — pre-load HINT so `getCapabilities(type)`
+	 *    answers without loading (absent hint ⇒ permissive default, matching
+	 *    `resolveProviderCapabilities`'s treatment of undeclared providers).
+	 * 2. the loaded module's `capabilities` — replaces the hint on load.
+	 * 3. the constructed instance's own `LLMProvider.capabilities` — the
+	 *    query runtime negotiates against the INSTANCE
+	 *    (`resolveProviderCapabilities(provider)`), so if it differs from
+	 *    both of the above, the instance wins where it matters.
+	 *
+	 * Lazy types are deliberately NOT constructible via the sync
+	 * `create()`/`createProvider()` (throws `LazyProviderSyncCreateError`),
+	 * even after the loader has resolved — sync behavior must not depend on
+	 * whether some earlier call happened to load the module.
+	 */
+	static registerLazy<K extends ProviderType>(
+		type: K,
+		loader: LazyProviderLoader<ProviderConfigRegistry[K]>,
+		options?: RegisterLazyOptions,
+	): void {
+		if ((providers.has(type) || lazyProviders.has(type)) && !options?.replace) {
+			throw new DuplicateProviderError(type)
+		}
+		providers.delete(type)
+		capabilities.delete(type)
+		lazyProviders.set(type, { loader: loader as LazyProviderLoader<unknown> })
+		if (options?.capabilities) {
+			capabilities.set(type, options.capabilities)
+		}
+	}
+
 	static create(config: ProviderFactoryConfig): ProviderFactoryResult {
 		const provider = ProviderRegistry.createProvider(config)
 		const caps = ProviderRegistry.getCapabilities(config.type)
 		return { provider, capabilities: caps }
 	}
 
+	/**
+	 * Async twin of `create()`. Works for BOTH eager and lazy registrations,
+	 * so hosts can use one code path; for lazy types it performs the
+	 * load-on-first-use described on `registerLazy()`.
+	 */
+	static async createAsync(config: ProviderFactoryConfig): Promise<ProviderFactoryResult> {
+		const provider = await ProviderRegistry.createProviderAsync(config)
+		// Read capabilities AFTER construction so a lazily-loaded module's
+		// authoritative declaration (set during load) is what gets returned.
+		const caps = ProviderRegistry.getCapabilities(config.type)
+		return { provider, capabilities: caps }
+	}
+
 	static createProvider(config: ProviderFactoryConfig): LLMProvider {
 		const Ctor = providers.get(config.type)
 		if (!Ctor) {
+			if (lazyProviders.has(config.type)) {
+				throw new LazyProviderSyncCreateError(config.type)
+			}
 			throw new UnknownProviderError(config.type)
 		}
 		return new Ctor(config)
 	}
 
+	static async createProviderAsync(config: ProviderFactoryConfig): Promise<LLMProvider> {
+		const Ctor = providers.get(config.type)
+		if (Ctor) {
+			return new Ctor(config)
+		}
+		const entry = lazyProviders.get(config.type)
+		if (!entry) {
+			throw new UnknownProviderError(config.type)
+		}
+		const mod = await loadLazyModule(config.type, entry)
+		return mod.create(config)
+	}
+
+	/**
+	 * Type-level capabilities. For a lazily-registered type this answers
+	 * WITHOUT invoking the loader: the registration hint if one was given,
+	 * otherwise the permissive default (assume everything — consistent with
+	 * how `resolveProviderCapabilities` treats an undeclared provider). Once
+	 * loaded, a module-shipped declaration replaces the hint. Note the query
+	 * runtime negotiates against the constructed INSTANCE's own
+	 * `capabilities`, which wins over anything stored here.
+	 */
 	static getCapabilities(type: string): ProviderCapabilities {
 		const caps = capabilities.get(type)
-		if (!caps) {
-			throw new UnknownProviderError(type)
+		if (caps) {
+			return caps
+		}
+		if (lazyProviders.has(type)) {
+			return PERMISSIVE_PROVIDER_CAPABILITIES
 		}
-		return caps
+		throw new UnknownProviderError(type)
 	}
 
 	static isSupported(type: string): type is ProviderType {
-		return providers.has(type)
+		return providers.has(type) || lazyProviders.has(type)
 	}
 
 	static unregister(type: ProviderType): boolean {
 		capabilities.delete(type)
-		return providers.delete(type)
+		const hadLazy = lazyProviders.delete(type)
+		return providers.delete(type) || hadLazy
 	}
 
 	static listTypes(): ProviderType[] {
-		return Array.from(providers.keys()) as ProviderType[]
+		return Array.from(new Set([...providers.keys(), ...lazyProviders.keys()])) as ProviderType[]
 	}
 }
 
@@ -115,4 +309,5 @@ export class ProviderRegistry {
 export function __resetProviderRegistryInternal(): void {
 	providers.clear()
 	capabilities.clear()
+	lazyProviders.clear()
 }

package/src/public-runtime.ts

@@ -99,6 +99,7 @@ export {
 
 export {
 	ActivityStore,
+	DiskCheckpointStore,
 	DiskMemoryStore,
 	DiskTaskStore,
 	InMemoryMemoryIndex,
@@ -144,10 +145,14 @@ export { LocalTaskGateway } from './gateway/local.js'
 
 export {
 	DuplicateProviderError,
+	LazyProviderLoadError,
+	LazyProviderSyncCreateError,
 	MOCK_CAPABILITIES,
 	MockLLMProvider,
+	PERMISSIVE_PROVIDER_CAPABILITIES,
 	ProviderRegistry,
 	registerMock,
+	resolveProviderCapabilities,
 	UnknownProviderError,
 } from './provider/index.js'
 
@@ -248,6 +253,7 @@ export {
 
 export { wrapProviderWithProbes } from './provider/instrumentation.js'
 export type { ProviderInstrumentationOptions } from './provider/instrumentation.js'
+export type { ResolvedProviderCapabilities } from './provider/capabilities.js'
 export { collect } from './provider/collect.js'
 
 export { wrapVaultWithProbes } from './vault/instrumentation.js'

package/src/run/reporter.ts

@@ -225,6 +225,15 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'capability_warning':
+				log.warn('Provider capability mismatch', {
+					runId: event.runId,
+					capability: event.capability,
+					providerId: event.providerId,
+					message: event.message,
+				})
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)

package/src/runtime/query/__tests__/capability-negotiation.test.ts

@@ -0,0 +1,248 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import {
+	PERMISSIVE_PROVIDER_CAPABILITIES,
+	resolveProviderCapabilities,
+} from '../../../provider/capabilities.js'
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import type { SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type {
+	ChatCompletionParams,
+	LLMProvider,
+	ProviderCapabilities,
+	StreamChunk,
+} from '../../../types/provider/index.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+class CapturingProvider implements LLMProvider {
+	readonly id = 'capturing'
+	readonly name = 'Capturing Provider'
+	readonly capabilities?: ProviderCapabilities
+	lastParams?: ChatCompletionParams
+
+	constructor(capabilities?: ProviderCapabilities) {
+		this.capabilities = capabilities
+	}
+
+	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		this.lastParams = params
+		yield { id: 'msg_1', delta: { content: 'done' } }
+		yield { id: 'msg_1', delta: {}, finishReason: 'stop', usage: ZERO_USAGE }
+	}
+}
+
+const NO_TOOLS_CAPABILITIES: ProviderCapabilities = {
+	supportsTools: false,
+	supportsStreaming: true,
+	supportsFunctionCalling: false,
+	supportsVision: true,
+}
+
+const NO_VISION_CAPABILITIES: ProviderCapabilities = {
+	supportsTools: true,
+	supportsStreaming: true,
+	supportsFunctionCalling: true,
+	supportsVision: false,
+}
+
+function registerEchoTool(tools: ToolRegistry): void {
+	tools.register({
+		name: 'echo',
+		description: 'Echo the text back.',
+		inputSchema: z.object({ text: z.string() }),
+		execute: async () => ({ success: true, output: 'ok' }),
+	})
+}
+
+function baseParams(provider: LLMProvider, tools: ToolRegistry, workingDirectory: string) {
+	return {
+		provider,
+		tools,
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 5_000,
+			tokenBudget: 100_000,
+			maxIterations: 1,
+			maxResponseTokens: 256,
+		},
+		agentId: 'agent_test',
+		agentName: 'Test Agent',
+		workingDirectory,
+		sessionId: 'ses_capability' as SessionId,
+		threadId: 'thd_capability' as ThreadId,
+		projectId: 'prj_capability' as ProjectId,
+		tenantId: 'tnt_capability' as TenantId,
+	}
+}
+
+describe('resolveProviderCapabilities', () => {
+	it('resolves an undeclared provider to the permissive default', () => {
+		expect(resolveProviderCapabilities(new CapturingProvider())).toEqual(
+			PERMISSIVE_PROVIDER_CAPABILITIES,
+		)
+	})
+
+	it('fills a partial declaration (missing supportsVision) permissively per field', () => {
+		const resolved = resolveProviderCapabilities({
+			capabilities: {
+				supportsTools: false,
+				supportsStreaming: true,
+				supportsFunctionCalling: false,
+			},
+		})
+		expect(resolved.supportsTools).toBe(false)
+		expect(resolved.supportsVision).toBe(true)
+	})
+})
+
+describe('query() capability negotiation', () => {
+	let workdirs: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+		workdirs = []
+	})
+
+	async function mkWorkdir(): Promise<string> {
+		const dir = await mkdtemp(join(tmpdir(), 'namzu-capability-'))
+		workdirs.push(dir)
+		return dir
+	}
+
+	it('strips tool surfaces and emits a capability_warning for a no-tools provider', async () => {
+		const provider = new CapturingProvider(NO_TOOLS_CAPABILITIES)
+		const tools = new ToolRegistry()
+		registerEchoTool(tools)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				...baseParams(provider, tools, await mkWorkdir()),
+				messages: [createUserMessage('hello')],
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(run.status).toBe('completed')
+
+		// The model was never told about tools: no tools param on the wire…
+		expect(provider.lastParams?.tools).toBeUndefined()
+		// …and no tool section in the system prompt.
+		const systemPrompt = (provider.lastParams?.messages ?? [])
+			.filter((m) => m.role === 'system')
+			.map((m) => m.content)
+			.join('\n')
+		expect(systemPrompt).not.toContain('<available_tools>')
+		expect(systemPrompt).not.toContain('echo')
+
+		// The host got the machine-readable warning.
+		const warning = events.find(
+			(e): e is Extract<RunEvent, { type: 'capability_warning' }> =>
+				e.type === 'capability_warning',
+		)
+		expect(warning?.capability).toBe('tools')
+		expect(warning?.providerId).toBe('capturing')
+		expect(warning?.message).toContain('stripped')
+	})
+
+	it('keeps tool surfaces intact for an undeclared (permissive-default) provider', async () => {
+		const provider = new CapturingProvider()
+		const tools = new ToolRegistry()
+		registerEchoTool(tools)
+
+		const run = await drainQuery({
+			...baseParams(provider, tools, await mkWorkdir()),
+			messages: [createUserMessage('hello')],
+		})
+
+		expect(run.status).toBe('completed')
+		expect(provider.lastParams?.tools?.map((t) => t.function.name)).toContain('echo')
+	})
+
+	it('emits a vision capability_warning when attachments hit a no-vision provider', async () => {
+		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				...baseParams(provider, new ToolRegistry(), await mkWorkdir()),
+				messages: [
+					createUserMessage('what is in this image?', [
+						{ data: 'aGVsbG8=', mediaType: 'image/png' },
+					]),
+				],
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(run.status).toBe('completed')
+		const warning = events.find(
+			(e): e is Extract<RunEvent, { type: 'capability_warning' }> =>
+				e.type === 'capability_warning',
+		)
+		expect(warning?.capability).toBe('vision')
+		expect(warning?.providerId).toBe('capturing')
+	})
+
+	it('does not warn when no attachments are present on a no-vision provider', async () => {
+		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+		const events: RunEvent[] = []
+
+		await drainQuery(
+			{
+				...baseParams(provider, new ToolRegistry(), await mkWorkdir()),
+				messages: [createUserMessage('plain text')],
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(events.some((e) => e.type === 'capability_warning')).toBe(false)
+	})
+
+	it('strictCapabilities: true throws on a tools mismatch instead of degrading', async () => {
+		const provider = new CapturingProvider(NO_TOOLS_CAPABILITIES)
+		const tools = new ToolRegistry()
+		registerEchoTool(tools)
+
+		await expect(
+			drainQuery({
+				...baseParams(provider, tools, await mkWorkdir()),
+				messages: [createUserMessage('hello')],
+				strictCapabilities: true,
+			}),
+		).rejects.toThrow(/supportsTools: false/)
+	})
+
+	it('strictCapabilities: true throws on a vision mismatch instead of degrading', async () => {
+		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+
+		await expect(
+			drainQuery({
+				...baseParams(provider, new ToolRegistry(), await mkWorkdir()),
+				messages: [createUserMessage('describe', [{ data: 'aGVsbG8=', mediaType: 'image/png' }])],
+				strictCapabilities: true,
+			}),
+		).rejects.toThrow(/supportsVision: false/)
+	})
+})