@moxxy/core 0.3.0

package/src/registries/commands.ts

@@ -0,0 +1,78 @@
+import type { CommandDef } from '@moxxy/sdk';
+
+/**
+ * Registry of `/<name>` slash commands shared across every channel.
+ * Plugins contribute via `PluginSpec.commands`; channels read with
+ * `list()` / `get()` / `match()` to render their picker and dispatch
+ * matching user input.
+ *
+ * Naming conflicts throw at registration time so two plugins can't
+ * silently shadow the same name — use `replace()` for explicit
+ * overrides (e.g. user-config tweaks of a built-in).
+ */
+export class CommandRegistry {
+  private readonly commands = new Map<string, CommandDef>();
+  /** Reverse-lookup table: alias → primary name. */
+  private readonly aliases = new Map<string, string>();
+
+  register(cmd: CommandDef): void {
+    if (this.commands.has(cmd.name)) {
+      throw new Error(`Command already registered: /${cmd.name}`);
+    }
+    if (this.aliases.has(cmd.name)) {
+      throw new Error(`Command name already in use as an alias: /${cmd.name}`);
+    }
+    this.commands.set(cmd.name, cmd);
+    for (const alias of cmd.aliases ?? []) {
+      if (this.aliases.has(alias) || this.commands.has(alias)) {
+        throw new Error(`Command alias already in use: /${alias}`);
+      }
+      this.aliases.set(alias, cmd.name);
+    }
+  }
+
+  replace(cmd: CommandDef): void {
+    // Clean up any aliases of the prior definition before re-adding.
+    const prior = this.commands.get(cmd.name);
+    if (prior) {
+      for (const alias of prior.aliases ?? []) this.aliases.delete(alias);
+    }
+    this.commands.set(cmd.name, cmd);
+    for (const alias of cmd.aliases ?? []) {
+      this.aliases.set(alias, cmd.name);
+    }
+  }
+
+  unregister(name: string): void {
+    const cmd = this.commands.get(name);
+    if (!cmd) return;
+    for (const alias of cmd.aliases ?? []) this.aliases.delete(alias);
+    this.commands.delete(name);
+  }
+
+  get(name: string): CommandDef | undefined {
+    const direct = this.commands.get(name);
+    if (direct) return direct;
+    const aliased = this.aliases.get(name);
+    return aliased ? this.commands.get(aliased) : undefined;
+  }
+
+  has(name: string): boolean {
+    return this.get(name) !== undefined;
+  }
+
+  list(): ReadonlyArray<CommandDef> {
+    return [...this.commands.values()];
+  }
+
+  /**
+   * Filter to commands visible in `channel`. Commands with no
+   * `channels` field are visible everywhere; commands with a list are
+   * visible only when `channel` appears in it.
+   */
+  listForChannel(channel: string): ReadonlyArray<CommandDef> {
+    return this.list().filter(
+      (c) => !c.channels || c.channels.includes(channel),
+    );
+  }
+}

package/src/registries/compactors.ts

@@ -0,0 +1,14 @@
+import type { CompactorDef } from '@moxxy/sdk';
+import { ActiveDefRegistry } from './active-def-registry.js';
+
+/**
+ * One active compaction strategy per session. Register throws on duplicate
+ * (use `replace()` to overwrite) and auto-activates the first registration;
+ * `unregister` clears the active slot rather than picking an arbitrary
+ * successor. See {@link ActiveDefRegistry}.
+ */
+export class CompactorRegistry extends ActiveDefRegistry<CompactorDef> {
+  constructor() {
+    super({ noun: 'Compactor' });
+  }
+}

package/src/registries/def-map-registry.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { DefMapRegistry } from './def-map-registry.js';
+
+/**
+ * Contract test for the shared base behind agents, channels and surfaces.
+ * Covers the default `name`-keyed shape and a `kind`-keyed variant (surfaces).
+ */
+
+interface NamedThing {
+  name: string;
+  v?: number;
+}
+const named = (name: string, v?: number): NamedThing => ({ name, v });
+
+interface KindThing {
+  kind: string;
+}
+
+describe('DefMapRegistry (shared base)', () => {
+  const make = () =>
+    new DefMapRegistry<NamedThing>({ noun: 'Thing', keyOf: (d) => d.name });
+
+  it('register / get / has / list round-trip', () => {
+    const r = make();
+    expect(r.list()).toEqual([]);
+    expect(r.get('a')).toBeUndefined();
+    expect(r.has('a')).toBe(false);
+    const a = named('a');
+    r.register(a);
+    expect(r.get('a')).toBe(a);
+    expect(r.has('a')).toBe(true);
+    r.register(named('b'));
+    expect(r.list().map((x) => x.name)).toEqual(['a', 'b']);
+  });
+
+  it('throws the exact noun-prefixed message on duplicate register', () => {
+    const r = make();
+    r.register(named('a'));
+    expect(() => r.register(named('a'))).toThrow('Thing already registered: a');
+  });
+
+  it('replace overwrites without throwing', () => {
+    const r = make();
+    r.register(named('a', 1));
+    r.replace(named('a', 2));
+    expect(r.get('a')?.v).toBe(2);
+    expect(r.list()).toHaveLength(1);
+  });
+
+  it('unregister removes by key', () => {
+    const r = make();
+    r.register(named('a'));
+    r.register(named('b'));
+    r.unregister('a');
+    expect(r.has('a')).toBe(false);
+    expect(r.list().map((x) => x.name)).toEqual(['b']);
+  });
+
+  it('supports a non-name key field (kind) and interpolates it in the error', () => {
+    const r = new DefMapRegistry<KindThing>({ noun: 'Surface', keyOf: (d) => d.kind });
+    r.register({ kind: 'terminal' });
+    expect(r.get('terminal')).toEqual({ kind: 'terminal' });
+    expect(() => r.register({ kind: 'terminal' })).toThrow('Surface already registered: terminal');
+    r.unregister('terminal');
+    expect(r.has('terminal')).toBe(false);
+  });
+});

package/src/registries/def-map-registry.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared base for the "flat name→def, no active slot" registries (agents,
+ * channels, surfaces). A `Map<key, def>` exposing register (throws on
+ * duplicate), replace (overwrite), unregister, list, get and has. The three
+ * registries differ only in their noun and key field (`name` vs `kind`),
+ * supplied via {@link DefMapRegistryOptions}.
+ *
+ * `ChannelRegistryImpl` extends this and adds `listWithAvailability`;
+ * `SurfaceRegistryImpl` keys on `kind` rather than `name`.
+ */
+export interface DefMapRegistryOptions<TDef, K> {
+  /** Capitalised singular noun for error messages, e.g. `'Agent'`. */
+  readonly noun: string;
+  /** Extract the map key from a def, e.g. `(d) => d.name` or `(d) => d.kind`. */
+  readonly keyOf: (def: TDef) => K;
+}
+
+export class DefMapRegistry<TDef, K = string> {
+  protected readonly defs = new Map<K, TDef>();
+  private readonly noun: string;
+  private readonly keyOf: (def: TDef) => K;
+
+  constructor(opts: DefMapRegistryOptions<TDef, K>) {
+    this.noun = opts.noun;
+    this.keyOf = opts.keyOf;
+  }
+
+  /**
+   * Register a definition. Throws on duplicate so two plugins can't silently
+   * shadow each other — use `replace()` when you really want to override.
+   */
+  register(def: TDef): void {
+    const key = this.keyOf(def);
+    if (this.defs.has(key)) {
+      throw new Error(`${this.noun} already registered: ${String(key)}`);
+    }
+    this.defs.set(key, def);
+  }
+
+  replace(def: TDef): void {
+    this.defs.set(this.keyOf(def), def);
+  }
+
+  unregister(key: K): void {
+    this.defs.delete(key);
+  }
+
+  list(): ReadonlyArray<TDef> {
+    return [...this.defs.values()];
+  }
+
+  get(key: K): TDef | undefined {
+    return this.defs.get(key);
+  }
+
+  has(key: K): boolean {
+    return this.defs.has(key);
+  }
+}

package/src/registries/embedders.test.ts

@@ -0,0 +1,54 @@
+import type { EmbedderDef, EmbeddingProvider } from '@moxxy/sdk';
+import { describe, expect, it, vi } from 'vitest';
+import { EmbedderRegistry } from './embedders.js';
+
+function fakeEmbedder(name: string): EmbeddingProvider {
+  return { name, dim: 3, embed: async (t) => t.map(() => [0, 0, 0]) };
+}
+
+function def(name: string, create: () => EmbeddingProvider): EmbedderDef {
+  return { name, createClient: create };
+}
+
+describe('EmbedderRegistry', () => {
+  it('does not call createClient until the embedder is activated (lazy)', () => {
+    const reg = new EmbedderRegistry();
+    const create = vi.fn(() => fakeEmbedder('x'));
+    reg.register(def('x', create));
+    expect(create).not.toHaveBeenCalled();
+    expect(reg.has('x')).toBe(true);
+
+    const inst = reg.setActive('x');
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(inst.name).toBe('x');
+    // Re-activating reuses the cached instance.
+    reg.setActive('x');
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('has no active embedder until one is selected (opt-in)', () => {
+    const reg = new EmbedderRegistry();
+    reg.register(def('x', () => fakeEmbedder('x')));
+    expect(reg.tryGetActive()).toBeNull();
+    expect(reg.getActiveName()).toBeNull();
+    reg.setActive('x');
+    expect(reg.tryGetActive()?.name).toBe('x');
+    expect(reg.getActiveName()).toBe('x');
+  });
+
+  it('throws on duplicate registration and on activating an unknown name', () => {
+    const reg = new EmbedderRegistry();
+    reg.register(def('x', () => fakeEmbedder('x')));
+    expect(() => reg.register(def('x', () => fakeEmbedder('x')))).toThrow(/already registered/);
+    expect(() => reg.setActive('nope')).toThrow(/not registered/);
+  });
+
+  it('unregister clears the active slot', () => {
+    const reg = new EmbedderRegistry();
+    reg.register(def('x', () => fakeEmbedder('x')));
+    reg.setActive('x');
+    reg.unregister('x');
+    expect(reg.has('x')).toBe(false);
+    expect(reg.tryGetActive()).toBeNull();
+  });
+});

package/src/registries/embedders.ts

@@ -0,0 +1,18 @@
+import type { EmbedderDef, EmbeddingProvider } from '@moxxy/sdk';
+import { ActiveBackendRegistry } from './active-backend-registry.js';
+
+/**
+ * Registry of text-embedding backends:
+ *   - plugins call `register(def)` at load time (via `PluginSpec.embedders`)
+ *   - the host/CLI calls `setActive(name, config)` once an embedder is chosen
+ *   - @moxxy/plugin-memory reads `getActive()` / `tryGetActive()` for recall
+ *
+ * At most one embedder is active at a time, selected explicitly. `createClient`
+ * is called lazily on first activation, so a registered-but-unselected embedder
+ * (e.g. the heavy transformers one) never instantiates its runtime.
+ */
+export class EmbedderRegistry extends ActiveBackendRegistry<EmbedderDef, EmbeddingProvider> {
+  constructor() {
+    super({ noun: 'Embedder', build: (def, config) => def.createClient(config) });
+  }
+}

package/src/registries/isolators.test.ts

@@ -0,0 +1,43 @@
+import type { Isolator } from '@moxxy/sdk';
+import { describe, expect, it } from 'vitest';
+import { IsolatorRegistry } from './isolators.js';
+
+function fakeIsolator(name: string): Isolator {
+  return {
+    name,
+    strength: 'none',
+    run: async (_call, bound, _caps) => bound(undefined),
+  } as unknown as Isolator;
+}
+
+describe('IsolatorRegistry (core contribution collection)', () => {
+  it('registers, looks up, lists, and unregisters by name', () => {
+    const reg = new IsolatorRegistry();
+    expect(reg.has('docker')).toBe(false);
+    reg.register(fakeIsolator('docker'));
+    expect(reg.has('docker')).toBe(true);
+    expect(reg.get('docker')?.name).toBe('docker');
+    expect(reg.list().map((i) => i.name)).toEqual(['docker']);
+    reg.unregister('docker');
+    expect(reg.has('docker')).toBe(false);
+  });
+
+  it('overwrites by name (an isolator may arrive via more than one path)', () => {
+    const reg = new IsolatorRegistry();
+    const first = fakeIsolator('worker');
+    const second = fakeIsolator('worker');
+    reg.register(first);
+    reg.register(second);
+    expect(reg.list()).toHaveLength(1);
+    expect(reg.get('worker')).toBe(second);
+  });
+
+  it('has no concept of an active isolator (selection stays with the security layer)', () => {
+    const reg = new IsolatorRegistry();
+    reg.register(fakeIsolator('wasm'));
+    // The registry is a plain collection — merely registering never activates
+    // anything; the security layer picks one by `security.isolator` config.
+    expect('getActive' in reg).toBe(false);
+    expect('setActive' in reg).toBe(false);
+  });
+});

package/src/registries/isolators.ts

@@ -0,0 +1,38 @@
+import type { Isolator } from '@moxxy/sdk';
+
+/**
+ * Collection of capability isolators contributed by plugins via
+ * `PluginSpec.isolators`. Unlike the single-active registries, this is just the
+ * set of AVAILABLE isolators — selection (and ownership of the security
+ * boundary) stays with the active security layer (`@moxxy/plugin-security`),
+ * which reads these and picks one by `security.isolator` config.
+ *
+ * A contributed isolator is therefore NEVER auto-activated: registration only
+ * makes it available; the user must opt in by name, so a rogue plugin can't
+ * silently weaken isolation just by being installed.
+ */
+export class IsolatorRegistry {
+  private readonly impls = new Map<string, Isolator>();
+
+  register(iso: Isolator): void {
+    // Overwrite by name: an isolator may arrive via more than one path (a
+    // bundled built-in AND a discovered copy). Same name → same role; last wins.
+    this.impls.set(iso.name, iso);
+  }
+
+  unregister(name: string): void {
+    this.impls.delete(name);
+  }
+
+  get(name: string): Isolator | undefined {
+    return this.impls.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.impls.has(name);
+  }
+
+  list(): ReadonlyArray<Isolator> {
+    return [...this.impls.values()];
+  }
+}

package/src/registries/modes.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { defineMode } from '@moxxy/sdk';
+import { ModeRegistry } from './modes.js';
+
+const mode = (name: string) => defineMode({ name, run: async function* () {} });
+
+describe('ModeRegistry legacy-name migration', () => {
+  it('resolves a legacy mode name to the current one on setActive', () => {
+    const reg = new ModeRegistry();
+    reg.register(mode('default'));
+    reg.register(mode('research'));
+
+    // Old names persisted in config/preferences/RPCs must not crash.
+    reg.setActive('tool-use');
+    expect(reg.getActive().name).toBe('default');
+
+    reg.setActive('deep-research');
+    expect(reg.getActive().name).toBe('research');
+
+    // Removed modes fall back to the default mode rather than throwing.
+    reg.setActive('plan-execute');
+    expect(reg.getActive().name).toBe('default');
+  });
+
+  it('still throws on a genuinely unknown mode (not a known legacy name)', () => {
+    const reg = new ModeRegistry();
+    reg.register(mode('default'));
+    expect(() => reg.setActive('totally-made-up')).toThrow(/Mode not registered: totally-made-up/);
+  });
+
+  it('passes a current name through unchanged', () => {
+    const reg = new ModeRegistry();
+    reg.register(mode('default'));
+    reg.register(mode('goal'));
+    reg.setActive('goal');
+    expect(reg.getActive().name).toBe('goal');
+  });
+
+  it('notifies onActiveChange when the ACTIVE mode def is replaced in place', () => {
+    // u42-3: a hot-reloaded active mode must tell observers its behaviour
+    // swapped, even though the active name is unchanged.
+    const reg = new ModeRegistry();
+    reg.register(mode('default')); // auto-active
+    let fired = 0;
+    reg.onActiveChange(() => {
+      fired += 1;
+    });
+    const replacement = mode('default');
+    reg.replace(replacement);
+    expect(fired).toBe(1);
+    // getActive() returns the new def reference.
+    expect(reg.getActive()).toBe(replacement);
+  });
+
+  it('does NOT notify onActiveChange when replacing a NON-active mode', () => {
+    const reg = new ModeRegistry();
+    reg.register(mode('default')); // auto-active
+    reg.register(mode('goal'));
+    let fired = 0;
+    reg.onActiveChange(() => {
+      fired += 1;
+    });
+    reg.replace(mode('goal')); // not the active mode
+    expect(fired).toBe(0);
+  });
+});

package/src/registries/modes.ts

@@ -0,0 +1,80 @@
+import { migrateModeName, type ModeDef } from '@moxxy/sdk';
+
+export class ModeRegistry {
+  private readonly modes = new Map<string, ModeDef>();
+  private active: string | null = null;
+  private readonly changeListeners = new Set<() => void>();
+
+  /** Observe active-mode changes — used by the runner to broadcast
+   *  InfoChanged so remote clients track a mode switch (whether it came from
+   *  a `setMode` RPC or a mode handing off to another mode mid-session). */
+  onActiveChange(fn: () => void): () => void {
+    this.changeListeners.add(fn);
+    return () => this.changeListeners.delete(fn);
+  }
+
+  /**
+   * Register a mode. Throws on duplicate — use `replace()` for
+   * overwrite. Auto-activates on first registration (modes need a default
+   * for any session to work).
+   */
+  register(mode: ModeDef): void {
+    if (this.modes.has(mode.name)) {
+      throw new Error(`Mode already registered: ${mode.name}`);
+    }
+    this.modes.set(mode.name, mode);
+    if (!this.active) this.activate(mode);
+  }
+
+  replace(mode: ModeDef): void {
+    this.modes.set(mode.name, mode);
+    if (!this.active) {
+      this.activate(mode);
+    } else if (this.active === mode.name) {
+      // The active mode's def was swapped in place (e.g. a hot-reloaded mode
+      // plugin). `getActive()` already returns the new def, but observers of
+      // `onActiveChange` (the runner broadcasting InfoChanged) must be told the
+      // active behaviour changed under them, or remote clients keep driving the
+      // stale def. `activate()` would early-return on the name match, so notify
+      // directly.
+      for (const fn of this.changeListeners) fn();
+    }
+  }
+
+  /**
+   * Remove a mode. If it was active, the active slot is cleared —
+   * callers must `setActive()` explicitly rather than silently picking
+   * some arbitrary "next" mode.
+   */
+  unregister(name: string): void {
+    this.modes.delete(name);
+    if (this.active === name) this.active = null;
+  }
+
+  list(): ReadonlyArray<ModeDef> {
+    return [...this.modes.values()];
+  }
+
+  setActive(name: string): void {
+    // Prefer the literal name; only when it isn't registered fall back to the
+    // legacy-name map (e.g. a persisted "tool-use" → "default"). This never
+    // overrides a validly-registered name and keeps an old config / preference
+    // / setMode RPC value from crashing a session with "Mode not registered".
+    const mode = this.modes.get(name) ?? this.modes.get(migrateModeName(name));
+    if (!mode) throw new Error(`Mode not registered: ${name}`);
+    this.activate(mode);
+  }
+
+  getActive(): ModeDef {
+    if (!this.active) throw new Error('No active mode registered.');
+    const mode = this.modes.get(this.active);
+    if (!mode) throw new Error(`Active mode missing: ${this.active}`);
+    return mode;
+  }
+
+  private activate(mode: ModeDef): void {
+    if (this.active === mode.name) return;
+    this.active = mode.name;
+    for (const fn of this.changeListeners) fn();
+  }
+}

package/src/registries/providers.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import type { LLMProvider, ProviderDef } from '@moxxy/sdk';
+import { ProviderRegistry } from './providers.js';
+
+function def(name: string): ProviderDef {
+  return {
+    name,
+    models: [{ id: `${name}-model`, contextWindow: 1000 }],
+    createClient: () => ({ name, models: [] }) as unknown as LLMProvider,
+  } as ProviderDef;
+}
+
+describe('ProviderRegistry enable/disable', () => {
+  it('providers are enabled by default; disabling blocks setActive', () => {
+    const reg = new ProviderRegistry();
+    reg.register(def('a'));
+    expect(reg.isEnabled('a')).toBe(true);
+
+    reg.setEnabled('a', false);
+    expect(reg.isEnabled('a')).toBe(false);
+    expect(() => reg.setActive('a')).toThrow(/disabled/);
+
+    reg.setEnabled('a', true);
+    expect(() => reg.setActive('a')).not.toThrow();
+  });
+
+  it('refuses to disable the ACTIVE provider', () => {
+    const reg = new ProviderRegistry();
+    reg.register(def('a'));
+    reg.setActive('a');
+    expect(() => reg.setEnabled('a', false)).toThrow(/active provider/i);
+    // Still enabled after the refused toggle.
+    expect(reg.isEnabled('a')).toBe(true);
+  });
+
+  it('accepts seeding unknown names before their defs register (boot order)', () => {
+    const reg = new ProviderRegistry();
+    reg.setEnabled('later', false);
+    reg.register(def('later'));
+    expect(reg.isEnabled('later')).toBe(false);
+    expect(() => reg.setActive('later')).toThrow(/disabled/);
+  });
+
+  it('keeps disabled providers listed (visible but inactive)', () => {
+    const reg = new ProviderRegistry();
+    reg.register(def('a'));
+    reg.setEnabled('a', false);
+    expect(reg.list().map((d) => d.name)).toContain('a');
+  });
+});

package/src/registries/providers.ts

@@ -0,0 +1,97 @@
+import type { LLMProvider, ProviderDef } from '@moxxy/sdk';
+
+export class ProviderRegistry {
+  private readonly defs = new Map<string, ProviderDef>();
+  private readonly instances = new Map<string, LLMProvider>();
+  private active: string | null = null;
+  /**
+   * Names the user disabled. Kept name-based (not def-based) so it can be
+   * seeded from preferences BEFORE the plugins register their defs — boot
+   * order doesn't matter. A disabled provider stays registered/listable but
+   * can't be activated.
+   */
+  private readonly disabled = new Set<string>();
+
+  /**
+   * Register a provider def. Throws on duplicate — use `replace()` for
+   * explicit overwrite. Matches the semantics of `tools` and `channels`.
+   */
+  register(def: ProviderDef, instance?: LLMProvider): void {
+    if (this.defs.has(def.name)) {
+      throw new Error(`Provider already registered: ${def.name}`);
+    }
+    this.defs.set(def.name, def);
+    if (instance) this.instances.set(def.name, instance);
+  }
+
+  /**
+   * Overwrite an existing def (also drops the cached instance so the new
+   * createClient gets called).
+   *
+   * Invariant: replacing the ACTIVE provider's def leaves `active` pointing at
+   * it but with no cached instance, so `getActive()` throws until the caller
+   * rebuilds the instance. Callers replacing the active provider MUST follow
+   * with `setActive(name, config)` (replace can't rebuild itself — it has no
+   * config). The sole production caller does exactly that.
+   */
+  replace(def: ProviderDef, instance?: LLMProvider): void {
+    this.defs.set(def.name, def);
+    this.instances.delete(def.name);
+    if (instance) this.instances.set(def.name, instance);
+  }
+
+  unregister(name: string): void {
+    this.defs.delete(name);
+    this.instances.delete(name);
+    if (this.active === name) this.active = null;
+  }
+
+  list(): ReadonlyArray<ProviderDef> {
+    return [...this.defs.values()];
+  }
+
+  /**
+   * Enable/disable a provider by name. Disabling the ACTIVE provider is
+   * refused — switch first, then disable — so a session never ends up with an
+   * active-but-disabled provider. Unknown names are accepted (the set seeds
+   * from preferences before plugins register), except when disabling via a
+   * live toggle is meaningless because the provider is active.
+   */
+  setEnabled(name: string, enabled: boolean): void {
+    if (!enabled && this.active === name) {
+      throw new Error(`Cannot disable the active provider "${name}" — switch providers first.`);
+    }
+    if (enabled) this.disabled.delete(name);
+    else this.disabled.add(name);
+  }
+
+  isEnabled(name: string): boolean {
+    return !this.disabled.has(name);
+  }
+
+  setActive(name: string, config?: Record<string, unknown>): LLMProvider {
+    const def = this.defs.get(name);
+    if (!def) throw new Error(`Provider not registered: ${name}`);
+    if (this.disabled.has(name)) {
+      throw new Error(`Provider "${name}" is disabled — enable it first.`);
+    }
+    let instance = this.instances.get(name);
+    if (!instance) {
+      instance = def.createClient(config ?? {});
+      this.instances.set(name, instance);
+    }
+    this.active = name;
+    return instance;
+  }
+
+  getActive(): LLMProvider {
+    if (!this.active) throw new Error('No active provider. Call setActive(name) first.');
+    const inst = this.instances.get(this.active);
+    if (!inst) throw new Error(`Active provider has no instance: ${this.active}`);
+    return inst;
+  }
+
+  getActiveName(): string | null {
+    return this.active;
+  }
+}