@n-dx/core 0.1.0

package/packages/llm-client/dist/provider-registry.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Provider registration and selection system for the llm-client.
+ *
+ * ## Design goals
+ *
+ * - **Dynamic registration** — vendors register factories at runtime, making
+ *   it possible to add new LLM providers without changing this file.
+ *
+ * - **Config-driven selection** — `getActiveProvider(config)` reads
+ *   `config.vendor` to pick the right factory, defaulting to `"claude"`.
+ *
+ * - **Extensible vendor names** — registry keys are plain strings, so
+ *   third-party vendors (e.g. `"gemini"`, `"bedrock"`) can be registered
+ *   without changing any core types.
+ *
+ * - **Singleton default** — `defaultRegistry` is pre-populated with the
+ *   built-in `"claude"` and `"codex"` factories. Most callers use it
+ *   directly. Tests and advanced consumers create isolated registries via
+ *   `new ProviderRegistry()` or `createDefaultRegistry()`.
+ *
+ * ## Adding a new vendor
+ *
+ * ```ts
+ * import { defaultRegistry } from "@n-dx/llm-client";
+ *
+ * defaultRegistry.register("my-vendor", (config) => {
+ *   return new MyVendorProvider(config);
+ * });
+ * ```
+ *
+ * ## Selecting the active provider
+ *
+ * ```ts
+ * const config = await loadLLMConfig(projectDir);
+ * const provider = defaultRegistry.getActiveProvider(config);
+ * const result = await provider.complete({ prompt: "Hello", model: "..." });
+ * ```
+ */
+import type { LLMProvider } from "./provider-interface.js";
+import type { LLMConfig } from "./llm-types.js";
+/**
+ * A function that creates an `LLMProvider` from the unified LLM config.
+ *
+ * Factories receive the full `LLMConfig` so they can extract their own
+ * vendor-specific section (e.g. `config.claude`, `config.codex`). They
+ * must return a fully initialized provider ready for `complete()` calls.
+ *
+ * @example
+ * ```ts
+ * const myFactory: ProviderFactory = (config) => {
+ *   return new MyProvider({ apiKey: config.myVendor?.api_key });
+ * };
+ * ```
+ */
+export type ProviderFactory = (config: LLMConfig) => LLMProvider;
+/**
+ * Registry mapping vendor names to provider factory functions.
+ *
+ * The registry enables dynamic provider registration and config-driven
+ * selection. Vendors are identified by string names (e.g. `"claude"`,
+ * `"codex"`) for extensibility beyond the built-in `LLMVendor` union.
+ *
+ * @example
+ * ```ts
+ * // Create an isolated registry (e.g. for testing)
+ * const registry = new ProviderRegistry();
+ * registry.register("test-vendor", (config) => makeTestProvider());
+ *
+ * const provider = registry.getActiveProvider({ vendor: "test-vendor" });
+ * ```
+ */
+export declare class ProviderRegistry {
+    private readonly factories;
+    /**
+     * Register a factory for the given vendor name.
+     *
+     * If a factory is already registered for this vendor, it is replaced.
+     * Registration is intentionally idempotent so callers can safely
+     * re-register without checking first.
+     *
+     * @param vendor - Vendor identifier string (e.g. `"claude"`, `"gemini"`).
+     * @param factory - Function that creates a provider from `LLMConfig`.
+     */
+    register(vendor: string, factory: ProviderFactory): void;
+    /**
+     * Remove the factory for the given vendor.
+     *
+     * @returns `true` if a factory existed and was removed, `false` otherwise.
+     */
+    unregister(vendor: string): boolean;
+    /**
+     * Returns `true` if a factory is registered for the given vendor.
+     */
+    has(vendor: string): boolean;
+    /**
+     * Returns all registered vendor names in insertion order.
+     */
+    vendors(): string[];
+    /**
+     * Create a provider for the given vendor using `config`.
+     *
+     * @throws {Error} if no factory is registered for `vendor`.
+     */
+    create(vendor: string, config: LLMConfig): LLMProvider;
+    /**
+     * Get the active provider based on `config.vendor`.
+     *
+     * Defaults to `"claude"` when `config.vendor` is not set. This mirrors
+     * the behaviour of `createLLMClient()` so the two APIs stay aligned.
+     *
+     * @throws {Error} if no factory is registered for the resolved vendor.
+     */
+    getActiveProvider(config: LLMConfig): LLMProvider;
+}
+/**
+ * Create a new `ProviderRegistry` pre-populated with the built-in providers.
+ *
+ * Built-in vendors:
+ * - `"claude"` — Dual provider stack (API + CLI) with automatic detection.
+ * - `"codex"` — Codex CLI provider (`codex exec`).
+ *
+ * Use this function when you need an isolated registry (e.g. in tests or
+ * when overriding a built-in vendor without affecting the global default).
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry();
+ * registry.register("my-vendor", myFactory);  // extend without touching defaultRegistry
+ * ```
+ */
+export declare function createDefaultRegistry(): ProviderRegistry;
+/**
+ * Shared default registry instance with built-in providers pre-registered.
+ *
+ * Most application code should use this singleton directly. Third-party
+ * providers can be registered here to make them available globally:
+ *
+ * ```ts
+ * import { defaultRegistry } from "@n-dx/llm-client";
+ *
+ * defaultRegistry.register("my-vendor", myFactory);
+ * ```
+ *
+ * Tests that need isolation should use `createDefaultRegistry()` instead
+ * to avoid cross-test contamination.
+ */
+export declare const defaultRegistry: ProviderRegistry;

package/packages/llm-client/dist/provider-registry.js

@@ -0,0 +1,175 @@
+/**
+ * Provider registration and selection system for the llm-client.
+ *
+ * ## Design goals
+ *
+ * - **Dynamic registration** — vendors register factories at runtime, making
+ *   it possible to add new LLM providers without changing this file.
+ *
+ * - **Config-driven selection** — `getActiveProvider(config)` reads
+ *   `config.vendor` to pick the right factory, defaulting to `"claude"`.
+ *
+ * - **Extensible vendor names** — registry keys are plain strings, so
+ *   third-party vendors (e.g. `"gemini"`, `"bedrock"`) can be registered
+ *   without changing any core types.
+ *
+ * - **Singleton default** — `defaultRegistry` is pre-populated with the
+ *   built-in `"claude"` and `"codex"` factories. Most callers use it
+ *   directly. Tests and advanced consumers create isolated registries via
+ *   `new ProviderRegistry()` or `createDefaultRegistry()`.
+ *
+ * ## Adding a new vendor
+ *
+ * ```ts
+ * import { defaultRegistry } from "@n-dx/llm-client";
+ *
+ * defaultRegistry.register("my-vendor", (config) => {
+ *   return new MyVendorProvider(config);
+ * });
+ * ```
+ *
+ * ## Selecting the active provider
+ *
+ * ```ts
+ * const config = await loadLLMConfig(projectDir);
+ * const provider = defaultRegistry.getActiveProvider(config);
+ * const result = await provider.complete({ prompt: "Hello", model: "..." });
+ * ```
+ */
+import { createClient } from "./create-client.js";
+import { createCodexCliClient } from "./codex-cli-provider.js";
+// ── ProviderRegistry ──────────────────────────────────────────────────────
+/**
+ * Registry mapping vendor names to provider factory functions.
+ *
+ * The registry enables dynamic provider registration and config-driven
+ * selection. Vendors are identified by string names (e.g. `"claude"`,
+ * `"codex"`) for extensibility beyond the built-in `LLMVendor` union.
+ *
+ * @example
+ * ```ts
+ * // Create an isolated registry (e.g. for testing)
+ * const registry = new ProviderRegistry();
+ * registry.register("test-vendor", (config) => makeTestProvider());
+ *
+ * const provider = registry.getActiveProvider({ vendor: "test-vendor" });
+ * ```
+ */
+export class ProviderRegistry {
+    factories = new Map();
+    /**
+     * Register a factory for the given vendor name.
+     *
+     * If a factory is already registered for this vendor, it is replaced.
+     * Registration is intentionally idempotent so callers can safely
+     * re-register without checking first.
+     *
+     * @param vendor - Vendor identifier string (e.g. `"claude"`, `"gemini"`).
+     * @param factory - Function that creates a provider from `LLMConfig`.
+     */
+    register(vendor, factory) {
+        this.factories.set(vendor, factory);
+    }
+    /**
+     * Remove the factory for the given vendor.
+     *
+     * @returns `true` if a factory existed and was removed, `false` otherwise.
+     */
+    unregister(vendor) {
+        return this.factories.delete(vendor);
+    }
+    /**
+     * Returns `true` if a factory is registered for the given vendor.
+     */
+    has(vendor) {
+        return this.factories.has(vendor);
+    }
+    /**
+     * Returns all registered vendor names in insertion order.
+     */
+    vendors() {
+        return [...this.factories.keys()];
+    }
+    /**
+     * Create a provider for the given vendor using `config`.
+     *
+     * @throws {Error} if no factory is registered for `vendor`.
+     */
+    create(vendor, config) {
+        const factory = this.factories.get(vendor);
+        if (!factory) {
+            const known = this.vendors().join(", ") || "(none registered)";
+            throw new Error(`No provider registered for vendor "${vendor}". Known vendors: ${known}`);
+        }
+        return factory(config);
+    }
+    /**
+     * Get the active provider based on `config.vendor`.
+     *
+     * Defaults to `"claude"` when `config.vendor` is not set. This mirrors
+     * the behaviour of `createLLMClient()` so the two APIs stay aligned.
+     *
+     * @throws {Error} if no factory is registered for the resolved vendor.
+     */
+    getActiveProvider(config) {
+        const vendor = config.vendor ?? "claude";
+        return this.create(vendor, config);
+    }
+}
+// ── Default registry ──────────────────────────────────────────────────────
+/**
+ * Create a new `ProviderRegistry` pre-populated with the built-in providers.
+ *
+ * Built-in vendors:
+ * - `"claude"` — Dual provider stack (API + CLI) with automatic detection.
+ * - `"codex"` — Codex CLI provider (`codex exec`).
+ *
+ * Use this function when you need an isolated registry (e.g. in tests or
+ * when overriding a built-in vendor without affecting the global default).
+ *
+ * @example
+ * ```ts
+ * const registry = createDefaultRegistry();
+ * registry.register("my-vendor", myFactory);  // extend without touching defaultRegistry
+ * ```
+ */
+export function createDefaultRegistry() {
+    const registry = new ProviderRegistry();
+    // Claude: delegate to the dual-provider factory (API + CLI auto-detection)
+    registry.register("claude", (config) => createClient({ claudeConfig: config.claude ?? {} }));
+    // Codex: wrap the CLI client in an LLMProvider adapter.
+    // createCodexCliClient returns ClaudeClient (no `info`), so we add the
+    // required ProviderInfo here until the codex adapter is refactored to
+    // implement LLMProvider directly (tracked in the sibling refactor task).
+    registry.register("codex", (config) => {
+        const client = createCodexCliClient({ codexConfig: config.codex });
+        const info = {
+            vendor: "codex",
+            mode: "cli",
+            model: config.codex?.model,
+            capabilities: [],
+        };
+        return {
+            info,
+            complete: (request) => client.complete(request),
+        };
+    });
+    return registry;
+}
+/**
+ * Shared default registry instance with built-in providers pre-registered.
+ *
+ * Most application code should use this singleton directly. Third-party
+ * providers can be registered here to make them available globally:
+ *
+ * ```ts
+ * import { defaultRegistry } from "@n-dx/llm-client";
+ *
+ * defaultRegistry.register("my-vendor", myFactory);
+ * ```
+ *
+ * Tests that need isolation should use `createDefaultRegistry()` instead
+ * to avoid cross-test contamination.
+ */
+export const defaultRegistry = createDefaultRegistry();
+//# sourceMappingURL=provider-registry.js.map

package/packages/llm-client/dist/provider-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registry.js","sourceRoot":"","sources":["../src/provider-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAoB/D,6EAA6E;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,gBAAgB;IACV,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEhE;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,MAAc;QACvB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,MAAc;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAc,EAAE,MAAiB;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC;YAC/D,MAAM,IAAI,KAAK,CACb,sCAAsC,MAAM,qBAAqB,KAAK,EAAE,CACzE,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IAED;;;;;;;OAOG;IACH,iBAAiB,CAAC,MAAiB;QACjC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC;QACzC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;CACF;AAED,6EAA6E;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,QAAQ,GAAG,IAAI,gBAAgB,EAAE,CAAC;IAExC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE,CACrC,YAAY,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,CACpD,CAAC;IAEF,wDAAwD;IACxD,uEAAuE;IACvE,sEAAsE;IACtE,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE;QACpC,MAAM,MAAM,GAAG,oBAAoB,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACnE,MAAM,IAAI,GAAiB;YACzB,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,KAAK;YACX,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK;YAC1B,YAAY,EAAE,EAAE;SACjB,CAAC;QACF,OAAO;YACL,IAAI;YACJ,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;SAC1B,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqB,qBAAqB,EAAE,CAAC"}

package/packages/llm-client/dist/provider-session.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Session-based LLM provider management with vendor switching support.
+ *
+ * ## What is a ProviderSession?
+ *
+ * A `ProviderSession` wraps a `ProviderRegistry` and maintains the
+ * currently active provider instance. It tracks:
+ *
+ * - **Active vendor** — which vendor is currently selected.
+ * - **Active provider** — the instantiated `LLMProvider` for that vendor.
+ * - **Current config** — the full `LLMConfig` in effect.
+ *
+ * ## Why session state matters
+ *
+ * Provider instances may hold resources (connections, auth tokens, internal
+ * state). The session reuses the same provider instance across requests
+ * **as long as the vendor does not change**. Switching vendors creates a
+ * fresh provider for the new vendor so the old instance can be released.
+ *
+ * This means:
+ * - Same vendor + updated config → existing provider reused.
+ * - Different vendor → new provider instantiated, old one released.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createProviderSession, loadLLMConfig } from "@n-dx/llm-client";
+ *
+ * const config = await loadLLMConfig(projectDir);
+ * const session = createProviderSession(config);
+ *
+ * // Use the active provider
+ * const result = await session.provider.complete({ prompt: "Hi", model: "..." });
+ *
+ * // Switch to a different vendor
+ * session.switchVendor("codex");
+ * const codexResult = await session.provider.complete({ prompt: "Hi", model: "..." });
+ * ```
+ */
+import type { LLMProvider } from "./provider-interface.js";
+import type { LLMConfig } from "./llm-types.js";
+import { ProviderRegistry } from "./provider-registry.js";
+/**
+ * Maintains active provider state and supports vendor switching.
+ *
+ * Create via `new ProviderSession(registry, config)` or the convenience
+ * function `createProviderSession(config)`.
+ */
+export declare class ProviderSession {
+    private readonly registry;
+    private _provider;
+    private _vendor;
+    private _config;
+    /**
+     * @param registry - Registry used to resolve and instantiate providers.
+     * @param initialConfig - Starting configuration. `config.vendor` (or
+     *   `"claude"` when absent) selects the initial active provider.
+     */
+    constructor(registry: ProviderRegistry, initialConfig: LLMConfig);
+    /**
+     * The currently active `LLMProvider` instance.
+     *
+     * The same instance is returned across multiple calls as long as the
+     * vendor has not changed. Switch vendors via `switchVendor()` or
+     * `updateConfig()` to get a fresh provider for a different backend.
+     */
+    get provider(): LLMProvider;
+    /**
+     * The currently active vendor name (e.g. `"claude"`, `"codex"`).
+     */
+    get vendor(): string;
+    /**
+     * The current `LLMConfig` held by this session.
+     *
+     * Updated whenever `switchVendor()` or `updateConfig()` is called.
+     */
+    get config(): LLMConfig;
+    /**
+     * Switch to a different vendor and create a new provider for it.
+     *
+     * The previous provider instance is released (no longer referenced by
+     * the session). If `config` is provided, it replaces the session config
+     * entirely; otherwise the existing config is carried over.
+     *
+     * @param vendor - Target vendor name (must be registered in the registry).
+     * @param config - Optional new config. Defaults to the current config.
+     * @returns The newly created provider for the target vendor.
+     *
+     * @throws {Error} if no factory is registered for `vendor`.
+     *
+     * @example
+     * ```ts
+     * // Switch to codex, keeping existing config settings
+     * session.switchVendor("codex");
+     *
+     * // Switch and provide codex-specific config
+     * session.switchVendor("codex", { ...session.config, vendor: "codex", codex: { ... } });
+     * ```
+     */
+    switchVendor(vendor: string, config?: LLMConfig): LLMProvider;
+    /**
+     * Update the session configuration, refreshing the provider if needed.
+     *
+     * - **Same vendor** → existing provider instance is reused, preserving
+     *   any internal state (connections, cached auth, etc.). Config is updated.
+     * - **Different vendor** → a new provider is instantiated for the new
+     *   vendor. The old provider is released.
+     *
+     * Returns the active provider (new or reused).
+     *
+     * @example
+     * ```ts
+     * // Config update that keeps the same vendor — provider reused
+     * session.updateConfig({ ...session.config, claude: { model: "claude-opus-4-20250514" } });
+     *
+     * // Config update that changes vendor — new provider created
+     * session.updateConfig({ vendor: "codex", codex: { cli_path: "/usr/local/bin/codex" } });
+     * ```
+     */
+    updateConfig(config: LLMConfig): LLMProvider;
+}
+/**
+ * Create a `ProviderSession` backed by the default built-in registry.
+ *
+ * This is the recommended entry point for most callers. The session starts
+ * with the vendor declared in `initialConfig.vendor` (or `"claude"` when
+ * omitted) and can switch vendors dynamically via `switchVendor()`.
+ *
+ * @param initialConfig - Starting LLM config. Defaults to `{}` (claude, CLI mode).
+ *
+ * @example
+ * ```ts
+ * import { createProviderSession, loadLLMConfig } from "@n-dx/llm-client";
+ *
+ * const config = await loadLLMConfig(projectDir);
+ * const session = createProviderSession(config);
+ *
+ * const result = await session.provider.complete({ prompt: "Hello", model: "..." });
+ * ```
+ */
+export declare function createProviderSession(initialConfig?: LLMConfig): ProviderSession;

package/packages/llm-client/dist/provider-session.js

@@ -0,0 +1,174 @@
+/**
+ * Session-based LLM provider management with vendor switching support.
+ *
+ * ## What is a ProviderSession?
+ *
+ * A `ProviderSession` wraps a `ProviderRegistry` and maintains the
+ * currently active provider instance. It tracks:
+ *
+ * - **Active vendor** — which vendor is currently selected.
+ * - **Active provider** — the instantiated `LLMProvider` for that vendor.
+ * - **Current config** — the full `LLMConfig` in effect.
+ *
+ * ## Why session state matters
+ *
+ * Provider instances may hold resources (connections, auth tokens, internal
+ * state). The session reuses the same provider instance across requests
+ * **as long as the vendor does not change**. Switching vendors creates a
+ * fresh provider for the new vendor so the old instance can be released.
+ *
+ * This means:
+ * - Same vendor + updated config → existing provider reused.
+ * - Different vendor → new provider instantiated, old one released.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createProviderSession, loadLLMConfig } from "@n-dx/llm-client";
+ *
+ * const config = await loadLLMConfig(projectDir);
+ * const session = createProviderSession(config);
+ *
+ * // Use the active provider
+ * const result = await session.provider.complete({ prompt: "Hi", model: "..." });
+ *
+ * // Switch to a different vendor
+ * session.switchVendor("codex");
+ * const codexResult = await session.provider.complete({ prompt: "Hi", model: "..." });
+ * ```
+ */
+import { createDefaultRegistry, } from "./provider-registry.js";
+// ── ProviderSession ───────────────────────────────────────────────────────
+/**
+ * Maintains active provider state and supports vendor switching.
+ *
+ * Create via `new ProviderSession(registry, config)` or the convenience
+ * function `createProviderSession(config)`.
+ */
+export class ProviderSession {
+    registry;
+    _provider;
+    _vendor;
+    _config;
+    /**
+     * @param registry - Registry used to resolve and instantiate providers.
+     * @param initialConfig - Starting configuration. `config.vendor` (or
+     *   `"claude"` when absent) selects the initial active provider.
+     */
+    constructor(registry, initialConfig) {
+        this.registry = registry;
+        this._config = initialConfig;
+        this._vendor = initialConfig.vendor ?? "claude";
+        this._provider = registry.create(this._vendor, initialConfig);
+    }
+    // ── Accessors ────────────────────────────────────────────────────────────
+    /**
+     * The currently active `LLMProvider` instance.
+     *
+     * The same instance is returned across multiple calls as long as the
+     * vendor has not changed. Switch vendors via `switchVendor()` or
+     * `updateConfig()` to get a fresh provider for a different backend.
+     */
+    get provider() {
+        return this._provider;
+    }
+    /**
+     * The currently active vendor name (e.g. `"claude"`, `"codex"`).
+     */
+    get vendor() {
+        return this._vendor;
+    }
+    /**
+     * The current `LLMConfig` held by this session.
+     *
+     * Updated whenever `switchVendor()` or `updateConfig()` is called.
+     */
+    get config() {
+        return this._config;
+    }
+    // ── Mutation ──────────────────────────────────────────────────────────────
+    /**
+     * Switch to a different vendor and create a new provider for it.
+     *
+     * The previous provider instance is released (no longer referenced by
+     * the session). If `config` is provided, it replaces the session config
+     * entirely; otherwise the existing config is carried over.
+     *
+     * @param vendor - Target vendor name (must be registered in the registry).
+     * @param config - Optional new config. Defaults to the current config.
+     * @returns The newly created provider for the target vendor.
+     *
+     * @throws {Error} if no factory is registered for `vendor`.
+     *
+     * @example
+     * ```ts
+     * // Switch to codex, keeping existing config settings
+     * session.switchVendor("codex");
+     *
+     * // Switch and provide codex-specific config
+     * session.switchVendor("codex", { ...session.config, vendor: "codex", codex: { ... } });
+     * ```
+     */
+    switchVendor(vendor, config) {
+        const newConfig = config ?? this._config;
+        const newProvider = this.registry.create(vendor, newConfig);
+        this._vendor = vendor;
+        this._config = newConfig;
+        this._provider = newProvider;
+        return newProvider;
+    }
+    /**
+     * Update the session configuration, refreshing the provider if needed.
+     *
+     * - **Same vendor** → existing provider instance is reused, preserving
+     *   any internal state (connections, cached auth, etc.). Config is updated.
+     * - **Different vendor** → a new provider is instantiated for the new
+     *   vendor. The old provider is released.
+     *
+     * Returns the active provider (new or reused).
+     *
+     * @example
+     * ```ts
+     * // Config update that keeps the same vendor — provider reused
+     * session.updateConfig({ ...session.config, claude: { model: "claude-opus-4-20250514" } });
+     *
+     * // Config update that changes vendor — new provider created
+     * session.updateConfig({ vendor: "codex", codex: { cli_path: "/usr/local/bin/codex" } });
+     * ```
+     */
+    updateConfig(config) {
+        const newVendor = config.vendor ?? "claude";
+        if (newVendor !== this._vendor) {
+            // Vendor changed — create a fresh provider for the new backend
+            this._provider = this.registry.create(newVendor, config);
+            this._vendor = newVendor;
+        }
+        // Always update config, even when vendor is unchanged
+        this._config = config;
+        return this._provider;
+    }
+}
+// ── Convenience factory ───────────────────────────────────────────────────
+/**
+ * Create a `ProviderSession` backed by the default built-in registry.
+ *
+ * This is the recommended entry point for most callers. The session starts
+ * with the vendor declared in `initialConfig.vendor` (or `"claude"` when
+ * omitted) and can switch vendors dynamically via `switchVendor()`.
+ *
+ * @param initialConfig - Starting LLM config. Defaults to `{}` (claude, CLI mode).
+ *
+ * @example
+ * ```ts
+ * import { createProviderSession, loadLLMConfig } from "@n-dx/llm-client";
+ *
+ * const config = await loadLLMConfig(projectDir);
+ * const session = createProviderSession(config);
+ *
+ * const result = await session.provider.complete({ prompt: "Hello", model: "..." });
+ * ```
+ */
+export function createProviderSession(initialConfig = {}) {
+    return new ProviderSession(createDefaultRegistry(), initialConfig);
+}
+//# sourceMappingURL=provider-session.js.map

package/packages/llm-client/dist/provider-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-session.js","sourceRoot":"","sources":["../src/provider-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,EAEL,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,6EAA6E;AAE7E;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IAWP;IAVX,SAAS,CAAc;IACvB,OAAO,CAAS;IAChB,OAAO,CAAY;IAE3B;;;;OAIG;IACH,YACmB,QAA0B,EAC3C,aAAwB;QADP,aAAQ,GAAR,QAAQ,CAAkB;QAG3C,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,MAAM,IAAI,QAAQ,CAAC;QAChD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAChE,CAAC;IAED,4EAA4E;IAE5E;;;;;;OAMG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,6EAA6E;IAE7E;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,YAAY,CAAC,MAAc,EAAE,MAAkB;QAC7C,MAAM,SAAS,GAAG,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC;QACzC,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC5D,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC;QAC7B,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,MAAiB;QAC5B,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC;QAC5C,IAAI,SAAS,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;YAC/B,+DAA+D;YAC/D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YACzD,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QAC3B,CAAC;QACD,sDAAsD;QACtD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF;AAED,6EAA6E;AAE7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,gBAA2B,EAAE;IACjE,OAAO,IAAI,eAAe,CAAC,qBAAqB,EAAE,EAAE,aAAa,CAAC,CAAC;AACrE,CAAC"}