@namzu/sdk 0.1.6 → 0.1.8

package/dist/provider/registry.js

@@ -0,0 +1,89 @@
+export class UnknownProviderError extends Error {
+    providerType;
+    constructor(providerType) {
+        super(`Unsupported provider type: ${providerType}`);
+        this.name = 'UnknownProviderError';
+        this.providerType = providerType;
+    }
+}
+export class DuplicateProviderError extends Error {
+    providerType;
+    constructor(providerType) {
+        super(`Provider type "${providerType}" is already registered. Pass { replace: true } to override an existing registration.`);
+        this.name = 'DuplicateProviderError';
+        this.providerType = providerType;
+    }
+}
+// Module-private state. Only the exported functions below can read/mutate.
+const providers = new Map();
+const capabilities = new Map();
+/**
+ * Central registry for LLM providers.
+ *
+ * Provider packages (@namzu/bedrock, @namzu/openai, etc.) export a
+ * `register<Vendor>()` function that calls `ProviderRegistry.register()`
+ * with a vendor-specific type string, provider class, and capabilities.
+ *
+ * The core sdk pre-registers `MockLLMProvider` under type `'mock'`.
+ *
+ * @example
+ * ```ts
+ * import { ProviderRegistry } from '@namzu/sdk'
+ * import { registerBedrock } from '@namzu/bedrock'
+ *
+ * registerBedrock()
+ *
+ * const { provider, capabilities } = ProviderRegistry.create({
+ *   type: 'bedrock',
+ *   region: 'us-east-1',
+ * })
+ * ```
+ */
+export class ProviderRegistry {
+    static register(type, ctor, caps, options) {
+        if (providers.has(type) && !options?.replace) {
+            throw new DuplicateProviderError(type);
+        }
+        providers.set(type, ctor);
+        capabilities.set(type, caps);
+    }
+    static create(config) {
+        const provider = ProviderRegistry.createProvider(config);
+        const caps = ProviderRegistry.getCapabilities(config.type);
+        return { provider, capabilities: caps };
+    }
+    static createProvider(config) {
+        const Ctor = providers.get(config.type);
+        if (!Ctor) {
+            throw new UnknownProviderError(config.type);
+        }
+        return new Ctor(config);
+    }
+    static getCapabilities(type) {
+        const caps = capabilities.get(type);
+        if (!caps) {
+            throw new UnknownProviderError(type);
+        }
+        return caps;
+    }
+    static isSupported(type) {
+        return providers.has(type);
+    }
+    static unregister(type) {
+        capabilities.delete(type);
+        return providers.delete(type);
+    }
+    static listTypes() {
+        return Array.from(providers.keys());
+    }
+}
+/**
+ * @internal — not exported from the package barrel. Do not use in production code.
+ * Available to in-tree tests via relative import (`./provider/registry.js`).
+ * External consumers cannot reach this because `@namzu/sdk` only exports `.`.
+ */
+export function __resetProviderRegistryInternal() {
+    providers.clear();
+    capabilities.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/provider/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/provider/registry.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACrC,YAAY,CAAQ;IAE7B,YAAY,YAAoB;QAC/B,KAAK,CAAC,8BAA8B,YAAY,EAAE,CAAC,CAAA;QACnD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IACjC,CAAC;CACD;AAED,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACvC,YAAY,CAAQ;IAE7B,YAAY,YAAoB;QAC/B,KAAK,CACJ,kBAAkB,YAAY,uFAAuF,CACrH,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;QACpC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IACjC,CAAC;CACD;AAED,2EAA2E;AAC3E,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2C,CAAA;AACpE,MAAM,YAAY,GAAG,IAAI,GAAG,EAAgC,CAAA;AAE5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,gBAAgB;IAC5B,MAAM,CAAC,QAAQ,CACd,IAAO,EACP,IAAuD,EACvD,IAA0B,EAC1B,OAAyB;QAEzB,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;YAC9C,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,CAAA;QACvC,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAuC,CAAC,CAAA;QAC5D,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAC7B,CAAC;IAED,MAAM,CAAC,MAAM,CAAC,MAA6B;QAC1C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;QACxD,MAAM,IAAI,GAAG,gBAAgB,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC1D,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,CAAA;IACxC,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,MAA6B;QAClD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,CAAC,IAAI,EAAE,CAAC;YACX,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAC5C,CAAC;QACD,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,CAAA;IACxB,CAAC;IAED,MAAM,CAAC,eAAe,CAAC,IAAY;QAClC,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,CAAC,IAAI,EAAE,CAAC;YACX,MAAM,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAA;QACrC,CAAC;QACD,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,IAAY;QAC9B,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,IAAkB;QACnC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACzB,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAED,MAAM,CAAC,SAAS;QACf,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAmB,CAAA;IACtD,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B;IAC9C,SAAS,CAAC,KAAK,EAAE,CAAA;IACjB,YAAY,CAAC,KAAK,EAAE,CAAA;AACrB,CAAC"}

package/dist/rag/rag-tool.d.ts

@@ -1,7 +1,7 @@
 import type { RAGToolConfig } from '../types/rag/index.js';
 export declare function createRAGTool(config: RAGToolConfig): import("../index.js").ToolDefinition<{
     query: string;
-    top_k?: number | undefined;
     knowledge_base_id?: string | undefined;
+    top_k?: number | undefined;
 }>;
 //# sourceMappingURL=rag-tool.d.ts.map

package/dist/types/provider/config.d.ts

@@ -1,32 +1,35 @@
 import type { LLMProvider } from './interface.js';
-export type ProviderType = 'openrouter' | 'bedrock' | 'mock';
-export interface OpenRouterConfig {
-    apiKey: string;
-    baseUrl?: string;
-    siteUrl?: string;
-    siteName?: string;
-    timeout?: number;
-}
-export interface OpenRouterProviderConfig extends OpenRouterConfig {
-    type: 'openrouter';
-}
-export interface BedrockConfig {
-    region?: string;
-    accessKeyId?: string;
-    secretAccessKey?: string;
-    sessionToken?: string;
-    timeout?: number;
-}
-export interface BedrockProviderConfig extends BedrockConfig {
-    type: 'bedrock';
+/**
+ * Registry of provider config shapes keyed by provider type string.
+ *
+ * Third-party provider packages extend this interface via TypeScript module
+ * augmentation. Each key in the registry becomes a valid `ProviderType`, and
+ * consumers of `ProviderRegistry.create({ type: 'X', ... })` get discriminated
+ * union narrowing to the correct config shape.
+ *
+ * @example
+ * ```ts
+ * // @namzu/bedrock package
+ * declare module '@namzu/sdk' {
+ *   interface ProviderConfigRegistry {
+ *     bedrock: BedrockProviderConfig
+ *   }
+ * }
+ * ```
+ */
+export interface ProviderConfigRegistry {
+    mock: MockProviderConfig;
 }
+export type ProviderType = keyof ProviderConfigRegistry & string;
+export type ProviderFactoryConfig = {
+    [K in ProviderType]: ProviderConfigRegistry[K];
+}[ProviderType];
 export interface MockProviderConfig {
     type: 'mock';
     model?: string;
     responseText?: string;
     responseDelayMs?: number;
 }
-export type ProviderFactoryConfig = OpenRouterProviderConfig | BedrockProviderConfig | MockProviderConfig;
 export interface ProviderCapabilities {
     supportsTools: boolean;
     supportsStreaming: boolean;
@@ -37,4 +40,9 @@ export interface ProviderFactoryResult {
     provider: LLMProvider;
     capabilities: ProviderCapabilities;
 }
+export interface RegisterOptions {
+    /** When true, replace an existing registration. Default false → throw on duplicate. */
+    replace?: boolean;
+}
+export type LLMProviderConstructor<C = unknown> = new (config: C) => LLMProvider;
 //# sourceMappingURL=config.d.ts.map

package/dist/types/provider/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/provider/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAAA;AAE5D,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IACjE,IAAI,EAAE,YAAY,CAAA;CAClB;AAED,MAAM,WAAW,aAAa;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC3D,IAAI,EAAE,SAAS,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,qBAAqB,GAC9B,wBAAwB,GACxB,qBAAqB,GACrB,kBAAkB,CAAA;AAErB,MAAM,WAAW,oBAAoB;IACpC,aAAa,EAAE,OAAO,CAAA;IACtB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,uBAAuB,EAAE,OAAO,CAAA;IAChC,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,WAAW,CAAA;IACrB,YAAY,EAAE,oBAAoB,CAAA;CAClC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/provider/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,kBAAkB,CAAA;CACxB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,sBAAsB,GAAG,MAAM,CAAA;AAEhE,MAAM,MAAM,qBAAqB,GAAG;KAClC,CAAC,IAAI,YAAY,GAAG,sBAAsB,CAAC,CAAC,CAAC;CAC9C,CAAC,YAAY,CAAC,CAAA;AAEf,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,oBAAoB;IACpC,aAAa,EAAE,OAAO,CAAA;IACtB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,uBAAuB,EAAE,OAAO,CAAA;IAChC,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,WAAW,CAAA;IACrB,YAAY,EAAE,oBAAoB,CAAA;CAClC;AAED,MAAM,WAAW,eAAe;IAC/B,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,MAAM,sBAAsB,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,MAAM,EAAE,CAAC,KAAK,WAAW,CAAA"}

package/dist/types/provider/index.d.ts

@@ -2,5 +2,5 @@ export type { ToolChoice, ResponseFormat, CacheControl, ChatCompletionParams, Ch
 export type { StreamChunk } from './stream.js';
 export type { ModelInfo } from './model.js';
 export type { LLMProvider } from './interface.js';
-export type { ProviderType, OpenRouterConfig, OpenRouterProviderConfig, BedrockConfig, BedrockProviderConfig, MockProviderConfig, ProviderFactoryConfig, ProviderCapabilities, ProviderFactoryResult, } from './config.js';
+export type { ProviderConfigRegistry, ProviderType, MockProviderConfig, ProviderFactoryConfig, ProviderCapabilities, ProviderFactoryResult, RegisterOptions, LLMProviderConstructor, } from './config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/provider/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/provider/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,GACtB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EACX,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,aAAa,EACb,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GACrB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/provider/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,GACtB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EACX,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,GACtB,MAAM,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",
@@ -27,12 +27,14 @@
     "README.md",
     "CHANGELOG.md"
   ],
+  "sideEffects": [
+    "./dist/provider/mock-register.js"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@aws-sdk/client-bedrock-runtime": "^3.700.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.57.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",

package/src/constants/provider/index.ts

@@ -1,23 +1 @@
-import type { ProviderCapabilities, ProviderType } from '../../types/provider/index.js'
-
 export const FALLBACK_MOCK_MODEL = 'mock-model'
-
-export const PROVIDER_CAPABILITIES: Record<ProviderType, ProviderCapabilities> = {
-	openrouter: {
-		supportsTools: true,
-		supportsStreaming: true,
-		supportsFunctionCalling: true,
-	},
-	bedrock: {
-		supportsTools: true,
-		supportsStreaming: true,
-		supportsFunctionCalling: true,
-	},
-	mock: {
-		supportsTools: false,
-		supportsStreaming: true,
-		supportsFunctionCalling: false,
-	},
-}
-
-export const OPENROUTER_BASE_URL = process.env.OPENROUTER_BASE_URL ?? 'https://openrouter.ai/api/v1'

package/src/index.ts

@@ -180,11 +180,12 @@ export { buildMemoryTools } from './tools/memory/index.js'
 export { LocalTaskGateway } from './gateway/local.js'
 
 export {
-	OpenRouterProvider,
-	BedrockProvider,
-	ProviderFactory,
-	MockLLMProvider,
+	ProviderRegistry,
 	UnknownProviderError,
+	DuplicateProviderError,
+	MockLLMProvider,
+	registerMock,
+	MOCK_CAPABILITIES,
 } from './provider/index.js'
 
 export {

package/src/provider/__tests__/registry.test.ts

@@ -0,0 +1,155 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { LLMProvider, ProviderCapabilities } from '../../types/provider/index.js'
+import { registerMock } from '../mock-register.js'
+import { MockLLMProvider } from '../mock.js'
+import {
+	DuplicateProviderError,
+	ProviderRegistry,
+	UnknownProviderError,
+	__resetProviderRegistryInternal,
+} from '../registry.js'
+
+// Simulate a downstream provider package's type registration via module augmentation.
+// This is the pattern @namzu/bedrock, @namzu/openai, etc. use in their own code.
+interface TestProviderConfig {
+	type: 'test'
+	value?: string
+}
+
+declare module '../../types/provider/config.js' {
+	interface ProviderConfigRegistry {
+		test: TestProviderConfig
+	}
+}
+
+class TestProvider implements LLMProvider {
+	readonly id = 'test'
+	readonly name = 'Test'
+	constructor(public readonly config: TestProviderConfig) {}
+	async chat() {
+		return {
+			id: 'x',
+			model: 'm',
+			message: { role: 'assistant' as const, content: 'ok' },
+			finishReason: 'stop' as const,
+			usage: {
+				promptTokens: 0,
+				completionTokens: 0,
+				totalTokens: 0,
+				cachedTokens: 0,
+				cacheWriteTokens: 0,
+			},
+		}
+	}
+	async *chatStream() {
+		yield { id: 'x', delta: { content: 'ok' } }
+	}
+}
+
+const TEST_CAPS: ProviderCapabilities = {
+	supportsTools: false,
+	supportsStreaming: true,
+	supportsFunctionCalling: false,
+}
+
+describe('ProviderRegistry', () => {
+	beforeEach(() => {
+		__resetProviderRegistryInternal()
+		registerMock()
+	})
+
+	describe('register', () => {
+		it('registers a provider and stores capabilities', () => {
+			ProviderRegistry.register('test', TestProvider, {
+				supportsTools: true,
+				supportsStreaming: false,
+				supportsFunctionCalling: true,
+			})
+
+			expect(ProviderRegistry.isSupported('test')).toBe(true)
+			expect(ProviderRegistry.getCapabilities('test').supportsTools).toBe(true)
+		})
+
+		it('throws DuplicateProviderError on re-register without replace', () => {
+			ProviderRegistry.register('test', TestProvider, TEST_CAPS)
+			expect(() => ProviderRegistry.register('test', TestProvider, TEST_CAPS)).toThrowError(
+				DuplicateProviderError,
+			)
+		})
+
+		it('allows replacement when { replace: true }', () => {
+			ProviderRegistry.register('test', TestProvider, TEST_CAPS)
+			const newCaps: ProviderCapabilities = {
+				supportsTools: true,
+				supportsStreaming: true,
+				supportsFunctionCalling: true,
+			}
+			expect(() =>
+				ProviderRegistry.register('test', TestProvider, newCaps, { replace: true }),
+			).not.toThrow()
+			expect(ProviderRegistry.getCapabilities('test').supportsTools).toBe(true)
+		})
+	})
+
+	describe('create', () => {
+		it('instantiates the registered provider with typed config', () => {
+			const { provider, capabilities } = ProviderRegistry.create({
+				type: 'mock',
+				model: 'test-model',
+			})
+			expect(provider).toBeInstanceOf(MockLLMProvider)
+			expect(capabilities.supportsStreaming).toBe(true)
+		})
+
+		it('throws UnknownProviderError for unregistered type', () => {
+			expect(() =>
+				ProviderRegistry.create({ type: 'nonexistent' } as unknown as { type: 'mock' }),
+			).toThrowError(UnknownProviderError)
+		})
+	})
+
+	describe('isSupported', () => {
+		it('returns true for registered types', () => {
+			expect(ProviderRegistry.isSupported('mock')).toBe(true)
+		})
+
+		it('returns false for unregistered types', () => {
+			expect(ProviderRegistry.isSupported('nope')).toBe(false)
+		})
+	})
+
+	describe('unregister', () => {
+		it('removes provider and capabilities', () => {
+			ProviderRegistry.register('test', TestProvider, TEST_CAPS)
+			expect(ProviderRegistry.unregister('test')).toBe(true)
+			expect(ProviderRegistry.isSupported('test')).toBe(false)
+		})
+
+		it('returns false when type is not registered', () => {
+			expect(ProviderRegistry.unregister('test')).toBe(false)
+		})
+	})
+
+	describe('listTypes', () => {
+		it('returns all registered types', () => {
+			ProviderRegistry.register('test', TestProvider, TEST_CAPS)
+			const types = ProviderRegistry.listTypes()
+			expect(types).toContain('mock')
+			expect(types).toContain('test')
+		})
+	})
+
+	describe('error types', () => {
+		it('UnknownProviderError preserves type', () => {
+			const err = new UnknownProviderError('foo')
+			expect(err.providerType).toBe('foo')
+			expect(err.name).toBe('UnknownProviderError')
+		})
+
+		it('DuplicateProviderError preserves type', () => {
+			const err = new DuplicateProviderError('bar')
+			expect(err.providerType).toBe('bar')
+			expect(err.name).toBe('DuplicateProviderError')
+		})
+	})
+})

package/src/provider/index.ts

@@ -1,3 +1,3 @@
-export { OpenRouterProvider } from './openrouter/client.js'
-export { BedrockProvider } from './bedrock/client.js'
-export { ProviderFactory, MockLLMProvider, UnknownProviderError } from './factory.js'
+export { ProviderRegistry, UnknownProviderError, DuplicateProviderError } from './registry.js'
+export { MockLLMProvider } from './mock.js'
+export { registerMock, MOCK_CAPABILITIES } from './mock-register.js'

package/src/provider/mock-register.ts

@@ -0,0 +1,27 @@
+import type { ProviderCapabilities } from '../types/provider/index.js'
+import { MockLLMProvider } from './mock.js'
+import { ProviderRegistry } from './registry.js'
+
+export const MOCK_CAPABILITIES: ProviderCapabilities = {
+	supportsTools: false,
+	supportsStreaming: true,
+	supportsFunctionCalling: false,
+}
+
+/**
+ * Register the built-in MockLLMProvider under type `'mock'`.
+ *
+ * This is invoked automatically on `@namzu/sdk` import (side-effect whitelisted
+ * via `package.json#sideEffects`). Users never need to call this explicitly.
+ *
+ * Exposed for tests that reset the registry via `ProviderRegistry._reset()`.
+ */
+export function registerMock(): void {
+	if (!ProviderRegistry.isSupported('mock')) {
+		ProviderRegistry.register('mock', MockLLMProvider, MOCK_CAPABILITIES)
+	}
+}
+
+// Auto-register on module load. This module is listed in sdk's
+// `package.json#sideEffects` so bundlers preserve this line under tree-shaking.
+registerMock()

package/src/provider/{factory.ts → mock.ts}

@@ -1,20 +1,14 @@
-import { FALLBACK_MOCK_MODEL, PROVIDER_CAPABILITIES } from '../constants/provider/index.js'
+import { FALLBACK_MOCK_MODEL } from '../constants/provider/index.js'
 import type { TokenUsage } from '../types/common/index.js'
 import type {
 	ChatCompletionParams,
 	ChatCompletionResponse,
 	LLMProvider,
 	MockProviderConfig,
-	ProviderCapabilities,
-	ProviderFactoryConfig,
-	ProviderFactoryResult,
-	ProviderType,
 	StreamChunk,
 } from '../types/provider/index.js'
-import { BedrockProvider } from './bedrock/client.js'
-import { OpenRouterProvider } from './openrouter/client.js'
 
-class MockLLMProvider implements LLMProvider {
+export class MockLLMProvider implements LLMProvider {
 	readonly id = 'mock'
 	readonly name = 'Mock LLM Provider'
 
@@ -103,52 +97,3 @@ class MockLLMProvider implements LLMProvider {
 		return true
 	}
 }
-
-export class UnknownProviderError extends Error {
-	readonly providerType: string
-
-	constructor(providerType: string) {
-		super(`Unsupported provider type: ${providerType}`)
-		this.name = 'UnknownProviderError'
-		this.providerType = providerType
-	}
-}
-
-export class ProviderFactory {
-	static create(config: ProviderFactoryConfig): ProviderFactoryResult {
-		const provider = ProviderFactory.createProvider(config)
-		const capabilities = ProviderFactory.getCapabilities(config.type)
-		return { provider, capabilities }
-	}
-
-	static createProvider(config: ProviderFactoryConfig): LLMProvider {
-		if (config.type === 'openrouter') {
-			const { type, ...openrouterConfig } = config
-			return new OpenRouterProvider(openrouterConfig)
-		}
-		if (config.type === 'bedrock') {
-			const { type, ...bedrockConfig } = config
-			return new BedrockProvider(bedrockConfig)
-		}
-		if (config.type === 'mock') {
-			return new MockLLMProvider(config)
-		}
-
-		throw new UnknownProviderError((config as { type: string }).type)
-	}
-
-	static getCapabilities(type: ProviderType): ProviderCapabilities {
-		const capabilities = PROVIDER_CAPABILITIES[type]
-		if (!capabilities) {
-			throw new UnknownProviderError(type)
-		}
-
-		return capabilities
-	}
-
-	static isSupported(type: string): type is ProviderType {
-		return type === 'openrouter' || type === 'bedrock' || type === 'mock'
-	}
-}
-
-export { OpenRouterProvider, BedrockProvider, MockLLMProvider }

package/src/provider/registry.ts

@@ -0,0 +1,118 @@
+import type {
+	LLMProvider,
+	LLMProviderConstructor,
+	ProviderCapabilities,
+	ProviderConfigRegistry,
+	ProviderFactoryConfig,
+	ProviderFactoryResult,
+	ProviderType,
+	RegisterOptions,
+} from '../types/provider/index.js'
+
+export class UnknownProviderError extends Error {
+	readonly providerType: string
+
+	constructor(providerType: string) {
+		super(`Unsupported provider type: ${providerType}`)
+		this.name = 'UnknownProviderError'
+		this.providerType = providerType
+	}
+}
+
+export class DuplicateProviderError extends Error {
+	readonly providerType: string
+
+	constructor(providerType: string) {
+		super(
+			`Provider type "${providerType}" is already registered. Pass { replace: true } to override an existing registration.`,
+		)
+		this.name = 'DuplicateProviderError'
+		this.providerType = providerType
+	}
+}
+
+// Module-private state. Only the exported functions below can read/mutate.
+const providers = new Map<string, LLMProviderConstructor<unknown>>()
+const capabilities = new Map<string, ProviderCapabilities>()
+
+/**
+ * Central registry for LLM providers.
+ *
+ * Provider packages (@namzu/bedrock, @namzu/openai, etc.) export a
+ * `register<Vendor>()` function that calls `ProviderRegistry.register()`
+ * with a vendor-specific type string, provider class, and capabilities.
+ *
+ * The core sdk pre-registers `MockLLMProvider` under type `'mock'`.
+ *
+ * @example
+ * ```ts
+ * import { ProviderRegistry } from '@namzu/sdk'
+ * import { registerBedrock } from '@namzu/bedrock'
+ *
+ * registerBedrock()
+ *
+ * const { provider, capabilities } = ProviderRegistry.create({
+ *   type: 'bedrock',
+ *   region: 'us-east-1',
+ * })
+ * ```
+ */
+export class ProviderRegistry {
+	static register<K extends ProviderType>(
+		type: K,
+		ctor: LLMProviderConstructor<ProviderConfigRegistry[K]>,
+		caps: ProviderCapabilities,
+		options?: RegisterOptions,
+	): void {
+		if (providers.has(type) && !options?.replace) {
+			throw new DuplicateProviderError(type)
+		}
+		providers.set(type, ctor as LLMProviderConstructor<unknown>)
+		capabilities.set(type, caps)
+	}
+
+	static create(config: ProviderFactoryConfig): ProviderFactoryResult {
+		const provider = ProviderRegistry.createProvider(config)
+		const caps = ProviderRegistry.getCapabilities(config.type)
+		return { provider, capabilities: caps }
+	}
+
+	static createProvider(config: ProviderFactoryConfig): LLMProvider {
+		const Ctor = providers.get(config.type)
+		if (!Ctor) {
+			throw new UnknownProviderError(config.type)
+		}
+		return new Ctor(config)
+	}
+
+	static getCapabilities(type: string): ProviderCapabilities {
+		const caps = capabilities.get(type)
+		if (!caps) {
+			throw new UnknownProviderError(type)
+		}
+		return caps
+	}
+
+	static isSupported(type: string): type is ProviderType {
+		return providers.has(type)
+	}
+
+	static unregister(type: ProviderType): boolean {
+		capabilities.delete(type)
+		return providers.delete(type)
+	}
+
+	static listTypes(): ProviderType[] {
+		return Array.from(providers.keys()) as ProviderType[]
+	}
+}
+
+/**
+ * @internal — not exported from the package barrel. Do not use in production code.
+ * Available to in-tree tests via relative import (`./provider/registry.js`).
+ * External consumers cannot reach this because `@namzu/sdk` only exports `.`.
+ */
+export function __resetProviderRegistryInternal(): void {
+	providers.clear()
+	capabilities.clear()
+}