@moxxy/core 0.3.0

package/src/registries/semantics.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import type { CompactorDef, ModeDef, ProviderDef } from '@moxxy/sdk';
+import { ProviderRegistry } from './providers.js';
+import { ModeRegistry } from './modes.js';
+import { CompactorRegistry } from './compactors.js';
+import { SkillRegistryImpl } from './skills.js';
+
+/**
+ * PR3-1 regression suite: every registry behaves the same way on
+ * duplicate register (throws), exposes an explicit `replace()`, and
+ * has predictable active-slot behavior on unregister.
+ */
+
+const fakeProvider = (name: string): ProviderDef => ({
+  name,
+  models: [],
+  createClient: () => ({ name, models: [], stream: async function* () {}, countTokens: async () => 0 }),
+});
+const fakeLoop = (name: string): ModeDef => ({ name, run: async function* () {} });
+const fakeCompactor = (name: string): CompactorDef => ({
+  name,
+  shouldCompact: () => false,
+  compact: async () => ({}) as never,
+});
+
+describe('Registry consistency (PR3-1)', () => {
+  it('ProviderRegistry: throws on duplicate, replace() overrides + drops cached instance', () => {
+    const r = new ProviderRegistry();
+    r.register(fakeProvider('a'));
+    expect(() => r.register(fakeProvider('a'))).toThrow(/already registered/);
+
+    r.setActive('a'); // caches an instance
+    r.replace(fakeProvider('a'));
+    // Replacing should drop the old instance so the new createClient runs on next setActive
+    let constructed = 0;
+    r.replace({
+      name: 'a',
+      models: [],
+      createClient: () => {
+        constructed++;
+        return { name: 'a', models: [], stream: async function* () {}, countTokens: async () => 0 };
+      },
+    });
+    r.setActive('a');
+    expect(constructed).toBe(1);
+  });
+
+  it('ProviderRegistry: unregister clears active', () => {
+    const r = new ProviderRegistry();
+    r.register(fakeProvider('a'));
+    r.setActive('a');
+    r.unregister('a');
+    expect(r.getActiveName()).toBeNull();
+  });
+
+  it('ModeRegistry: throws on duplicate, auto-activates first, unregister clears active', () => {
+    const r = new ModeRegistry();
+    r.register(fakeLoop('first'));
+    r.register(fakeLoop('second'));
+    expect(() => r.register(fakeLoop('first'))).toThrow(/already registered/);
+    expect(r.getActive().name).toBe('first');
+
+    r.unregister('first');
+    // Don't silently pick "second" — caller must setActive explicitly.
+    expect(() => r.getActive()).toThrow(/no active/i);
+
+    r.setActive('second');
+    expect(r.getActive().name).toBe('second');
+  });
+
+  it('CompactorRegistry: throws on duplicate, auto-activates first, unregister clears active', () => {
+    const r = new CompactorRegistry();
+    r.register(fakeCompactor('first'));
+    r.register(fakeCompactor('second'));
+    expect(() => r.register(fakeCompactor('first'))).toThrow(/already registered/);
+    expect(r.getActive()?.name).toBe('first');
+
+    r.unregister('first');
+    // getActive returns null after the active is gone (no arbitrary fallback).
+    expect(r.getActive()).toBeNull();
+  });
+
+  it('SkillRegistryImpl: throws on duplicate id, replace() overrides', () => {
+    const r = new SkillRegistryImpl();
+    const skill = {
+      id: 'project/foo' as never,
+      path: '/a.md',
+      scope: 'project' as const,
+      frontmatter: { name: 'foo', description: 'd' },
+      body: 'one',
+    };
+    r.register(skill);
+    expect(() => r.register(skill)).toThrow(/already registered/);
+    r.replace({ ...skill, body: 'two' });
+    expect(r.get('project/foo' as never)?.body).toBe('two');
+  });
+
+  it('SkillRegistryImpl: replace() drops the old name index entry when frontmatter.name changes', () => {
+    const r = new SkillRegistryImpl();
+    const skill = {
+      id: 'project/x' as never,
+      path: '/a.md',
+      scope: 'project' as const,
+      frontmatter: { name: 'foo', description: 'd' },
+      body: 'one',
+    };
+    r.register(skill);
+    expect(r.byName('foo')?.id).toBe('project/x');
+    // Same id, new frontmatter.name (an edited skill re-registered).
+    r.replace({ ...skill, frontmatter: { name: 'bar', description: 'd' }, body: 'two' });
+    // The stale old-name index entry must be reclaimed — two live names for
+    // one id was the bug.
+    expect(r.byName('foo')).toBeUndefined();
+    expect(r.byName('bar')?.body).toBe('two');
+    expect(r.list()).toHaveLength(1);
+  });
+});

package/src/registries/skills.ts

@@ -0,0 +1,87 @@
+import type { Skill, SkillRegistry } from '@moxxy/sdk';
+
+export class SkillRegistryImpl implements SkillRegistry {
+  private readonly byId = new Map<string, Skill>();
+  private readonly byNameIdx = new Map<string, Skill>();
+
+  list(): ReadonlyArray<Skill> {
+    return [...this.byId.values()];
+  }
+
+  get(id: string): Skill | undefined {
+    return this.byId.get(id);
+  }
+
+  byName(name: string): Skill | undefined {
+    return this.byNameIdx.get(name);
+  }
+
+  filterByTriggers(prompt: string): ReadonlyArray<Skill> {
+    const lower = prompt.toLowerCase();
+    const matches: Skill[] = [];
+    for (const skill of this.byId.values()) {
+      const triggers = skill.frontmatter.triggers ?? [];
+      if (triggers.some((t) => lower.includes(t.toLowerCase()))) matches.push(skill);
+    }
+    return matches;
+  }
+
+  /**
+   * Register a skill. Throws on duplicate id — use `replace()` for
+   * overwrite (or `replaceAll()` for atomic bulk swap).
+   */
+  register(skill: Skill): void {
+    if (this.byId.has(skill.id)) {
+      throw new Error(`Skill already registered: ${skill.id}`);
+    }
+    this.byId.set(skill.id, skill);
+    this.byNameIdx.set(skill.frontmatter.name, skill);
+  }
+
+  replace(skill: Skill): void {
+    // Drop the prior definition's name from the index when it changed —
+    // otherwise an edited skill re-registered under the same id but a new
+    // frontmatter.name leaves the OLD name pointing at the stale skill
+    // forever (two live names for one id). Mirrors CommandRegistry.replace's
+    // alias cleanup.
+    const prior = this.byId.get(skill.id);
+    if (prior && prior.frontmatter.name !== skill.frontmatter.name) {
+      this.byNameIdx.delete(prior.frontmatter.name);
+    }
+    this.byId.set(skill.id, skill);
+    this.byNameIdx.set(skill.frontmatter.name, skill);
+  }
+
+  unregister(id: string): void {
+    const skill = this.byId.get(id);
+    if (!skill) return;
+    this.byId.delete(id);
+    this.byNameIdx.delete(skill.frontmatter.name);
+  }
+
+  clear(): void {
+    this.byId.clear();
+    this.byNameIdx.clear();
+  }
+
+  /**
+   * Replace the registry's entire contents atomically (no observable empty
+   * window). Used by `reload_skills` so a concurrent lookup never sees
+   * zero skills while a rescan is in flight.
+   */
+  replaceAll(skills: ReadonlyArray<Skill>): void {
+    const nextById = new Map<string, Skill>();
+    const nextByName = new Map<string, Skill>();
+    for (const s of skills) {
+      nextById.set(s.id, s);
+      nextByName.set(s.frontmatter.name, s);
+    }
+    // Synchronous swap: callers between these lines still see the OLD
+    // registry (Maps aren't replaced, only repopulated). Clear+set is the
+    // shortest synchronous window we can achieve in JS for Map fields.
+    this.byId.clear();
+    this.byNameIdx.clear();
+    for (const [k, v] of nextById) this.byId.set(k, v);
+    for (const [k, v] of nextByName) this.byNameIdx.set(k, v);
+  }
+}

package/src/registries/surfaces.ts

@@ -0,0 +1,18 @@
+import type { SurfaceDef, SurfaceKind, SurfaceRegistry } from '@moxxy/sdk';
+import { DefMapRegistry } from './def-map-registry.js';
+
+/**
+ * Registry of surface defs contributed by plugins (terminal, browser, …),
+ * keyed by `kind`. A flat name→def map ({@link DefMapRegistry}) with
+ * register/unregister so the PluginHost can add and remove a plugin's
+ * surfaces on load/unload. The live, open instances are managed separately by
+ * the {@link SurfaceHostImpl}; this registry only knows the available kinds.
+ */
+export class SurfaceRegistryImpl
+  extends DefMapRegistry<SurfaceDef, SurfaceKind>
+  implements SurfaceRegistry
+{
+  constructor() {
+    super({ noun: 'Surface', keyOf: (def) => def.kind });
+  }
+}

package/src/registries/synthesizers.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import type { Synthesizer, SynthesizerDef } from '@moxxy/sdk';
+import { SynthesizerRegistry } from './synthesizers.js';
+
+function def(name: string, onCreate?: (ctx: { getSecret?: (n: string) => Promise<string | null> }) => void): SynthesizerDef {
+  return {
+    name,
+    create: (ctx): Synthesizer => {
+      onCreate?.(ctx);
+      return {
+        name,
+        synthesize: async () => ({ audio: new Uint8Array([1, 2, 3]), mimeType: 'audio/mpeg' }),
+      };
+    },
+  };
+}
+
+describe('SynthesizerRegistry', () => {
+  it('auto-activates the first registered synthesizer', () => {
+    const reg = new SynthesizerRegistry();
+    expect(reg.getActiveName()).toBeNull();
+    reg.register(def('elevenlabs'));
+    expect(reg.getActiveName()).toBe('elevenlabs');
+    // A second registration does NOT steal the active slot.
+    reg.register(def('openai'));
+    expect(reg.getActiveName()).toBe('elevenlabs');
+  });
+
+  it('setActive / clearActive switch the active backend', () => {
+    const reg = new SynthesizerRegistry();
+    reg.register(def('elevenlabs'));
+    reg.register(def('openai'));
+    reg.setActive('openai');
+    expect(reg.getActiveName()).toBe('openai');
+    reg.clearActive();
+    expect(reg.getActiveName()).toBeNull();
+    expect(reg.tryGetActive()).toBeNull();
+  });
+
+  it('unregistering the active backend clears active', () => {
+    const reg = new SynthesizerRegistry();
+    reg.register(def('elevenlabs'));
+    reg.unregister('elevenlabs');
+    expect(reg.getActiveName()).toBeNull();
+    expect(reg.has('elevenlabs')).toBe(false);
+  });
+
+  it('passes the vault-backed getSecret into create()', async () => {
+    let seen: ((n: string) => Promise<string | null>) | undefined;
+    const reg = new SynthesizerRegistry({
+      secretResolver: async (n) => (n === 'ELEVENLABS_API_KEY' ? 'sk-1' : null),
+    });
+    reg.register(def('elevenlabs', (ctx) => (seen = ctx.getSecret)));
+    reg.getActive(); // forces create()
+    expect(typeof seen).toBe('function');
+    expect(await seen!('ELEVENLABS_API_KEY')).toBe('sk-1');
+  });
+
+  it('getActive throws when none is active', () => {
+    const reg = new SynthesizerRegistry();
+    expect(() => reg.getActive()).toThrow(/No active synthesizer/);
+  });
+});

package/src/registries/synthesizers.ts

@@ -0,0 +1,36 @@
+import type { Synthesizer, SynthesizerDef } from '@moxxy/sdk';
+import { ActiveBackendRegistry } from './active-backend-registry.js';
+
+/**
+ * Registry of text-to-speech backends:
+ *   - plugins call `register(def)` at load time
+ *   - read-aloud surfaces read `tryGetActive()` to turn text into audio
+ *   - the agent switches/deactivates via the `set_voice` tool
+ *
+ * Unlike transcribers/embedders (where the host picks a backend explicitly),
+ * TTS has a sensible default: the first synthesizer registered auto-becomes
+ * active (`autoAdoptFirst`), so a user who asks the agent to author an
+ * ElevenLabs plugin gets read-aloud through it immediately — no extra activate
+ * step. Because `active` can thus be set without a built instance, the active
+ * synthesizer is (re)built lazily on read (`buildOnRead`). `getActive()` throws
+ * when none is active so the desktop falls back to the OS `speechSynthesis`.
+ *
+ * `secretResolver` is the vault-backed `getSecret` (the same one wired into
+ * tool contexts), handed to each synthesizer's `create(ctx)` so a TTS plugin
+ * can read its API key without touching `process.env`.
+ */
+export class SynthesizerRegistry extends ActiveBackendRegistry<SynthesizerDef, Synthesizer> {
+  constructor(opts: { secretResolver?: (name: string) => Promise<string | null> } = {}) {
+    const { secretResolver } = opts;
+    super({
+      noun: 'Synthesizer',
+      autoAdoptFirst: true,
+      buildOnRead: true,
+      build: (def, config) =>
+        def.create({
+          config,
+          ...(secretResolver ? { getSecret: secretResolver } : {}),
+        }),
+    });
+  }
+}

package/src/registries/tools.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineTool } from '@moxxy/sdk';
+import { silentLogger } from '../logger.js';
+import { ToolRegistryImpl } from './tools.js';
+
+describe('ToolRegistryImpl', () => {
+  const make = () => new ToolRegistryImpl({ logger: silentLogger, cwd: '/tmp' });
+
+  it('registers, lists, and looks up tools', () => {
+    const reg = make();
+    const tool = defineTool({
+      name: 'echo',
+      description: 'e',
+      inputSchema: z.object({ msg: z.string() }),
+      handler: (i) => i.msg,
+    });
+    reg.register(tool);
+    expect(reg.list()).toHaveLength(1);
+    expect(reg.has('echo')).toBe(true);
+    expect(reg.get('echo')?.name).toBe('echo');
+  });
+
+  it('rejects duplicate registration', () => {
+    const reg = make();
+    const tool = defineTool({
+      name: 'echo',
+      description: 'e',
+      inputSchema: z.string(),
+      handler: (s) => s,
+    });
+    reg.register(tool);
+    expect(() => reg.register(tool)).toThrow(/already registered/);
+  });
+
+  it('throws on unknown tool', async () => {
+    const reg = make();
+    await expect(reg.execute('nope', {}, new AbortController().signal)).rejects.toThrow(/Unknown tool/);
+  });
+
+  it('validates input via schema', async () => {
+    const reg = make();
+    reg.register(
+      defineTool({
+        name: 'echo',
+        description: 'e',
+        inputSchema: z.object({ msg: z.string() }),
+        handler: (i) => i.msg.toUpperCase(),
+      }),
+    );
+    await expect(
+      reg.execute('echo', { msg: 123 }, new AbortController().signal),
+    ).rejects.toThrow(/Expected string/);
+    const result = await reg.execute('echo', { msg: 'hi' }, new AbortController().signal);
+    expect(result).toBe('HI');
+  });
+
+  it('validates output if outputSchema present, formatting the issues into one line', async () => {
+    const reg = make();
+    reg.register(
+      defineTool({
+        name: 'badShape',
+        description: 'e',
+        inputSchema: z.object({}),
+        outputSchema: z.object({ ok: z.literal(true) }),
+        handler: () => ({ ok: false }) as never,
+      }),
+    );
+    // Mirrors the input path: names the tool + offending field on a single
+    // line instead of dumping the raw multi-line ZodError.
+    await expect(
+      reg.execute('badShape', {}, new AbortController().signal),
+    ).rejects.toThrow(/Tool badShape produced invalid output: ok: /);
+  });
+
+  it('returns the parsed output when outputSchema passes', async () => {
+    const reg = make();
+    reg.register(
+      defineTool({
+        name: 'goodShape',
+        description: 'e',
+        inputSchema: z.object({}),
+        outputSchema: z.object({ ok: z.literal(true) }),
+        handler: () => ({ ok: true, extra: 'stripped' }) as never,
+      }),
+    );
+    // outputSchema.safeParse strips unknown keys exactly like the prior .parse did.
+    const result = await reg.execute('goodShape', {}, new AbortController().signal);
+    expect(result).toEqual({ ok: true });
+  });
+
+  it('unregisters', () => {
+    const reg = make();
+    const tool = defineTool({
+      name: 'echo',
+      description: 'e',
+      inputSchema: z.string(),
+      handler: (s) => s,
+    });
+    reg.register(tool);
+    reg.unregister('echo');
+    expect(reg.has('echo')).toBe(false);
+  });
+
+  it('exposes ctx.getSecret backed by the secretResolver', async () => {
+    const secrets: Record<string, string> = { ELEVENLABS_API_KEY: 'sk-123' };
+    const reg = new ToolRegistryImpl({
+      logger: silentLogger,
+      cwd: '/tmp',
+      secretResolver: async (name) => secrets[name] ?? null,
+    });
+    reg.register(
+      defineTool({
+        name: 'reads_secret',
+        description: 'reads a secret',
+        inputSchema: z.object({ name: z.string() }),
+        handler: async ({ name }, ctx) => ({
+          hasGetSecret: typeof ctx.getSecret === 'function',
+          value: (await ctx.getSecret?.(name)) ?? null,
+        }),
+      }),
+    );
+    const hit = await reg.execute('reads_secret', { name: 'ELEVENLABS_API_KEY' }, new AbortController().signal);
+    expect(hit).toEqual({ hasGetSecret: true, value: 'sk-123' });
+    const miss = await reg.execute('reads_secret', { name: 'NOPE' }, new AbortController().signal);
+    expect(miss).toEqual({ hasGetSecret: true, value: null });
+  });
+
+  it('omits ctx.getSecret when no secretResolver is wired', async () => {
+    const reg = make();
+    reg.register(
+      defineTool({
+        name: 'no_secret',
+        description: 'no secret resolver',
+        inputSchema: z.object({}),
+        handler: async (_i, ctx) => ({ hasGetSecret: typeof ctx.getSecret === 'function' }),
+      }),
+    );
+    const result = await reg.execute('no_secret', {}, new AbortController().signal);
+    expect(result).toEqual({ hasGetSecret: false });
+  });
+});

package/src/registries/tools.ts

@@ -0,0 +1,145 @@
+import type { EventLogReader, SubagentSpawner, ToolContext, ToolDef } from '@moxxy/sdk';
+import type { Logger } from '../logger.js';
+import { asToolCallId, asSessionId, asTurnId } from '@moxxy/sdk';
+
+export interface ToolRegistry {
+  list(): ReadonlyArray<ToolDef>;
+  get(name: string): ToolDef | undefined;
+  has(name: string): boolean;
+  register(tool: ToolDef): void;
+  unregister(name: string): void;
+  execute(name: string, input: unknown, signal: AbortSignal, opts?: ExecuteOptions): Promise<unknown>;
+}
+
+interface ExecuteOptions {
+  readonly callId?: string;
+  readonly sessionId?: string;
+  readonly turnId?: string;
+  readonly log?: EventLogReader;
+  readonly logger?: Logger;
+  readonly cwd?: string;
+  /**
+   * Optional spawner — passed by run-turn so multi-agent tools (e.g.
+   * `dispatch_agent`) can fan work out from inside the tool-use loop.
+   * Plain `tools.execute()` callers (tests, one-off scripts) may omit it.
+   */
+  readonly subagents?: SubagentSpawner;
+}
+
+export class ToolRegistryImpl implements ToolRegistry {
+  private readonly tools = new Map<string, ToolDef>();
+  private readonly defaultLogger: Logger;
+  private readonly defaultCwd: string;
+  /**
+   * Vault-backed secret resolver, when the host wires one. Surfaced to
+   * every tool handler as `ctx.getSecret(name)` so plugins can read an
+   * API key at call time without the value ever entering the model's
+   * context or `process.env`.
+   */
+  private readonly secretResolver?: (name: string) => Promise<string | null>;
+
+  constructor(opts: {
+    logger: Logger;
+    cwd: string;
+    secretResolver?: (name: string) => Promise<string | null>;
+  }) {
+    this.defaultLogger = opts.logger;
+    this.defaultCwd = opts.cwd;
+    this.secretResolver = opts.secretResolver;
+  }
+
+  list(): ReadonlyArray<ToolDef> {
+    return [...this.tools.values()];
+  }
+
+  get(name: string): ToolDef | undefined {
+    return this.tools.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  register(tool: ToolDef): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool already registered: ${tool.name}`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  unregister(name: string): void {
+    this.tools.delete(name);
+  }
+
+  async execute(
+    name: string,
+    input: unknown,
+    signal: AbortSignal,
+    opts: ExecuteOptions = {},
+  ): Promise<unknown> {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`Unknown tool: ${name}`);
+    // Use safeParse so a validation failure surfaces as a clean,
+    // single-line error in the tool_result instead of the raw ZodError
+    // (which JSON-stringifies into 20+ lines of red noise — observed
+    // with memory_save and synthesize_skill). The formatted message tells
+    // the model exactly which fields are off and why, so it can retry.
+    const parseResult = tool.inputSchema.safeParse(input);
+    if (!parseResult.success) {
+      throw new Error(`Invalid input for ${name}: ${formatZodIssues(parseResult.error)}`);
+    }
+    const parsed = parseResult.data;
+
+    const ctx: ToolContext = {
+      sessionId: asSessionId(opts.sessionId ?? 'no-session'),
+      turnId: asTurnId(opts.turnId ?? 'no-turn'),
+      callId: asToolCallId(opts.callId ?? 'no-call'),
+      cwd: opts.cwd ?? this.defaultCwd,
+      signal,
+      log: opts.log ?? emptyLog(),
+      logger: opts.logger ?? this.defaultLogger,
+      ...(opts.subagents ? { subagents: opts.subagents } : {}),
+      ...(this.secretResolver ? { getSecret: this.secretResolver } : {}),
+    };
+
+    const result = await tool.handler(parsed, ctx);
+    if (tool.outputSchema) {
+      // Mirror the input path: format an output-schema mismatch (a plugin bug)
+      // into the same single-line message instead of letting the raw 20-line
+      // ZodError surface, and name the offending tool + fields.
+      const outResult = tool.outputSchema.safeParse(result);
+      if (!outResult.success) {
+        throw new Error(
+          `Tool ${name} produced invalid output: ${formatZodIssues(outResult.error)}`,
+        );
+      }
+      return outResult.data;
+    }
+    return result;
+  }
+}
+
+/**
+ * Format a ZodError's issues into a single-line, model-friendly string
+ * (`path: message; path: message`). Used by both input and output validation
+ * so the raw multi-line ZodError JSON noise never reaches the model.
+ */
+function formatZodIssues(error: { issues: ReadonlyArray<{ path: ReadonlyArray<PropertyKey>; message: string }> }): string {
+  return error.issues
+    .map((iss) => {
+      const path = iss.path.length ? iss.path.join('.') : '(root)';
+      return `${path}: ${iss.message}`;
+    })
+    .join('; ');
+}
+
+function emptyLog(): EventLogReader {
+  return {
+    length: 0,
+    at: () => undefined,
+    slice: () => [],
+    ofType: () => [],
+    byTurn: () => [],
+    toJSON: () => [],
+  };
+}

package/src/registries/transcribers.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { defineTranscriber } from '@moxxy/sdk';
+import { TranscriberRegistry } from './transcribers.js';
+
+const fake = (name: string, echo = '') =>
+  defineTranscriber({
+    name,
+    createClient: (cfg) => ({
+      name,
+      transcribe: async () => ({ text: String(cfg.echo ?? echo) }),
+    }),
+  });
+
+describe('TranscriberRegistry', () => {
+  it('registers, lists, and looks up', () => {
+    const reg = new TranscriberRegistry();
+    reg.register(fake('whisper'));
+    expect(reg.has('whisper')).toBe(true);
+    expect(reg.list()).toHaveLength(1);
+  });
+
+  it('rejects duplicate registration', () => {
+    const reg = new TranscriberRegistry();
+    const t = fake('whisper');
+    reg.register(t);
+    expect(() => reg.register(t)).toThrow(/already registered/);
+  });
+
+  it('setActive instantiates lazily and getActive returns the instance', async () => {
+    const reg = new TranscriberRegistry();
+    reg.register(fake('whisper'));
+    expect(reg.getActiveName()).toBeNull();
+    const inst = reg.setActive('whisper', { echo: 'hello' });
+    expect(reg.getActiveName()).toBe('whisper');
+    expect(reg.getActive()).toBe(inst);
+    const out = await inst.transcribe(new Uint8Array());
+    expect(out.text).toBe('hello');
+  });
+
+  it('tryGetActive returns null without an active one', () => {
+    const reg = new TranscriberRegistry();
+    expect(reg.tryGetActive()).toBeNull();
+    expect(() => reg.getActive()).toThrow(/No active transcriber/);
+  });
+
+  it('unregister clears active when it matches', () => {
+    const reg = new TranscriberRegistry();
+    reg.register(fake('whisper'));
+    reg.setActive('whisper');
+    reg.unregister('whisper');
+    expect(reg.getActiveName()).toBeNull();
+    expect(reg.tryGetActive()).toBeNull();
+  });
+
+  it('setActive throws for unknown name', () => {
+    const reg = new TranscriberRegistry();
+    expect(() => reg.setActive('nope')).toThrow(/not registered/);
+  });
+
+  it('replace overwrites def and drops cached instance', () => {
+    const reg = new TranscriberRegistry();
+    reg.register(fake('whisper', 'old'));
+    reg.setActive('whisper');
+    reg.replace(fake('whisper', 'new'));
+    const inst = reg.setActive('whisper');
+    return inst.transcribe(new Uint8Array()).then((r) => {
+      expect(r.text).toBe('new');
+    });
+  });
+});