@moxxy/plugin-voice-admin 0.26.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { Session } from '@moxxy/core';
+import { type Plugin } from '@moxxy/sdk';
+/**
+ * Voice/TTS control plugin — lets the agent switch which text-to-speech backend
+ * read-aloud surfaces (the desktop's speaker button) use, without a settings UI.
+ * `set_voice` activates a registered synthesizer by name, or 'system' to
+ * deactivate (fall back to the OS voice). `list_voices` reports what's available
+ * + which is active. A synthesizer authored via self-update auto-activates on
+ * load, so this is for switching afterwards.
+ *
+ * The synthesizer registry lives on the live Session, so this is built via a
+ * factory closing over it (mirroring `buildViewPlugin` / `buildSubagentsPlugin`)
+ * and wired into the cli's builtin `entries` list.
+ */
+export declare function buildVoiceAdminPlugin(session: Session): Plugin;
+/**
+ * Discovery-loadable default export: resolves the synthesizer registry from the
+ * inter-plugin service registry in `onInit` (the host publishes `'synthesizers'`),
+ * so the tools control the live session's TTS backend without a host-injected
+ * `session` closure.
+ */
+export declare const voiceAdminPlugin: Plugin;
+export default voiceAdminPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAuB,MAAM,aAAa,CAAC;AAChE,OAAO,EAAoD,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAE3F;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE9D;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAe3B,CAAC;AA+EL,eAAe,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,107 @@
+import { definePlugin, defineTool, z } from '@moxxy/sdk';
+/**
+ * Voice/TTS control plugin — lets the agent switch which text-to-speech backend
+ * read-aloud surfaces (the desktop's speaker button) use, without a settings UI.
+ * `set_voice` activates a registered synthesizer by name, or 'system' to
+ * deactivate (fall back to the OS voice). `list_voices` reports what's available
+ * + which is active. A synthesizer authored via self-update auto-activates on
+ * load, so this is for switching afterwards.
+ *
+ * The synthesizer registry lives on the live Session, so this is built via a
+ * factory closing over it (mirroring `buildViewPlugin` / `buildSubagentsPlugin`)
+ * and wired into the cli's builtin `entries` list.
+ */
+export function buildVoiceAdminPlugin(session) {
+    return makeVoiceAdminPlugin(() => session.synthesizers);
+}
+/**
+ * Discovery-loadable default export: resolves the synthesizer registry from the
+ * inter-plugin service registry in `onInit` (the host publishes `'synthesizers'`),
+ * so the tools control the live session's TTS backend without a host-injected
+ * `session` closure.
+ */
+export const voiceAdminPlugin = (() => {
+    let reg = null;
+    const hooks = {
+        onInit: (ctx) => {
+            reg = ctx.services.get('synthesizers') ?? null;
+        },
+    };
+    return makeVoiceAdminPlugin(() => {
+        if (!reg) {
+            throw new Error('@moxxy/plugin-voice-admin: the "synthesizers" registry is unavailable — the host must publish it');
+        }
+        return reg;
+    }, hooks);
+})();
+function makeVoiceAdminPlugin(getSynths, hooks) {
+    // 'system' (the OS voice) plus every registered synthesizer — the one
+    // list both tools speak in terms of (list_voices' result and
+    // set_voice's "unknown name" hint). The synthesizer namespace is
+    // attacker-influenced (any plugin / a self-update-authored backend can
+    // register a name), so de-dupe in case one is literally named 'system' —
+    // otherwise it would be listed twice.
+    const voiceNames = () => [
+        'system',
+        ...getSynths()
+            .list()
+            .map((s) => s.name)
+            .filter((n) => n !== 'system'),
+    ];
+    return definePlugin({
+        name: '@moxxy/plugin-voice-admin',
+        version: '0.0.1',
+        ...(hooks ? { hooks } : {}),
+        tools: [
+            defineTool({
+                name: 'list_voices',
+                description: 'List the text-to-speech (synthesizer) backends registered on this ' +
+                    'session and which one is active. "system" means the OS voice (no ' +
+                    'plugin synthesizer active).',
+                inputSchema: z.object({}),
+                permission: { action: 'allow' },
+                handler: () => ({
+                    active: getSynths().getActiveName() ?? 'system',
+                    available: voiceNames(),
+                }),
+            }),
+            defineTool({
+                name: 'set_voice',
+                description: 'Choose which text-to-speech backend read-aloud uses. Pass a ' +
+                    'registered synthesizer name (see list_voices) to activate it, or ' +
+                    '"system" to fall back to the OS voice. Use this to switch between ' +
+                    'an installed TTS plugin (e.g. ElevenLabs) and the built-in voice.',
+                inputSchema: z.object({
+                    synthesizer: z
+                        .string()
+                        .min(1)
+                        .describe('Synthesizer name to activate, or "system" for the OS voice.'),
+                }),
+                // Auto-allowed because switching the active TTS backend has a low blast
+                // radius: it only flips the registry's active slot. The synthesizer is
+                // not built here (the registry is buildOnRead), so no secret read or
+                // network call happens at set_voice time — the first read-aloud builds
+                // it under the same vault/network gates a registered plugin already has.
+                permission: { action: 'allow' },
+                handler: ({ synthesizer }) => {
+                    // Treat 'system' as the OS-voice sentinel only when no real
+                    // synthesizer claims that name. A backend literally named 'system'
+                    // (registrations are attacker-influenced) is otherwise permanently
+                    // unreachable; fall through to activate it.
+                    if (synthesizer === 'system' && !getSynths().has('system')) {
+                        getSynths().clearActive();
+                        return { active: 'system' };
+                    }
+                    if (!getSynths().has(synthesizer)) {
+                        throw new Error(`No synthesizer named "${synthesizer}". Available: ${voiceNames().join(', ')}.`);
+                    }
+                    getSynths().setActive(synthesizer);
+                    return { active: synthesizer };
+                },
+            }),
+        ],
+    });
+}
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default voiceAdminPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@moxxy/plugin-voice-admin",
+  "version": "0.26.0",
+  "description": "Voice/TTS control for moxxy. set_voice / list_voices let the agent switch which text-to-speech backend read-aloud surfaces use (a registered synthesizer, or 'system' for the OS voice) without a settings UI.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "voice",
+    "tts",
+    "tools"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-voice-admin"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "tools"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@moxxy/sdk": "0.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/core": "0.26.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/discovery.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import type { ServiceRegistry } from '@moxxy/sdk';
+import { voiceAdminPlugin } from './index.js';
+
+function fakeSynths(active: string | null, names: string[]) {
+  let cur = active;
+  return {
+    list: () => names.map((name) => ({ name })),
+    has: (n: string) => names.includes(n),
+    getActiveName: () => cur,
+    setActive: (n: string) => {
+      cur = n;
+    },
+    clearActive: () => {
+      cur = null;
+    },
+  };
+}
+
+/**
+ * The discovery-loadable default export resolves the synthesizer registry from
+ * the inter-plugin service registry in onInit instead of a `build*(session)`
+ * closure.
+ */
+describe('voiceAdminPlugin (discovery-loadable)', () => {
+  it('exposes list_voices/set_voice + an onInit hook', () => {
+    expect(voiceAdminPlugin.tools?.map((t) => t.name).sort()).toEqual(['list_voices', 'set_voice']);
+    expect(typeof voiceAdminPlugin.hooks?.onInit).toBe('function');
+  });
+
+  it('onInit wires the synthesizers registry; the tools read it live', async () => {
+    const synths = fakeSynths('eleven', ['eleven', 'openai']);
+    const services = {
+      get: () => synths,
+      require: () => synths,
+      has: () => true,
+      register: () => {},
+    } as unknown as ServiceRegistry;
+    voiceAdminPlugin.hooks!.onInit!({ services } as never);
+
+    const listVoices = voiceAdminPlugin.tools!.find((t) => t.name === 'list_voices')!;
+    const listed = await listVoices.handler({} as never, {} as never);
+    expect(listed).toEqual({ active: 'eleven', available: ['system', 'eleven', 'openai'] });
+
+    const setVoice = voiceAdminPlugin.tools!.find((t) => t.name === 'set_voice')!;
+    const set = await setVoice.handler({ synthesizer: 'openai' } as never, {} as never);
+    expect(set).toEqual({ active: 'openai' });
+    expect(synths.getActiveName()).toBe('openai');
+  });
+});

package/src/index.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+import { Session, silentLogger } from '@moxxy/core';
+import { buildVoiceAdminPlugin } from './index.js';
+
+/**
+ * Focused unit test for the voice-admin tools. Drives the tool handlers
+ * directly against a bare Session's synthesizer registry.
+ */
+function tools(session: Session) {
+  const plugin = buildVoiceAdminPlugin(session);
+  const byName = new Map((plugin.tools ?? []).map((t) => [t.name, t]));
+  return {
+    listVoices: byName.get('list_voices')!,
+    setVoice: byName.get('set_voice')!,
+  };
+}
+
+const ctx = { sessionId: 's', turnId: 't' } as never;
+
+/** Minimal registrable synthesizer def (create() is never invoked here — the
+ *  registry is buildOnRead, so set_voice only flips the active slot). */
+function fakeSynth(name: string) {
+  return {
+    name,
+    create: () => ({
+      name,
+      synthesize: async () => ({ audio: new Uint8Array(), mimeType: 'audio/mpeg' }),
+    }),
+  };
+}
+
+describe('voice-admin plugin', () => {
+  it('registers list_voices and set_voice', () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    const plugin = buildVoiceAdminPlugin(session);
+    expect(plugin.name).toBe('@moxxy/plugin-voice-admin');
+    expect((plugin.tools ?? []).map((t) => t.name).sort()).toEqual(['list_voices', 'set_voice']);
+  });
+
+  it('list_voices reports "system" active by default and lists registered synthesizers', async () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    const { listVoices } = tools(session);
+    const result = (await listVoices.handler({}, ctx)) as { active: string; available: string[] };
+    expect(result.active).toBe('system');
+    expect(result.available).toContain('system');
+  });
+
+  it('set_voice "system" clears the active synthesizer', async () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    const { setVoice } = tools(session);
+    const result = (await setVoice.handler({ synthesizer: 'system' }, ctx)) as { active: string };
+    expect(result.active).toBe('system');
+    expect(session.synthesizers.getActiveName() ?? 'system').toBe('system');
+  });
+
+  it('set_voice throws on an unknown synthesizer name', async () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    const { setVoice } = tools(session);
+    // The handler is synchronous, so it throws synchronously.
+    expect(() => setVoice.handler({ synthesizer: 'nope' }, ctx)).toThrow(/No synthesizer named "nope"/);
+  });
+
+  it('set_voice activates a registered synthesizer and list_voices reflects it', async () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    session.synthesizers.register(fakeSynth('elevenlabs'));
+    const { setVoice, listVoices } = tools(session);
+
+    const result = (await setVoice.handler({ synthesizer: 'elevenlabs' }, ctx)) as { active: string };
+    expect(result.active).toBe('elevenlabs');
+    expect(session.synthesizers.getActiveName()).toBe('elevenlabs');
+
+    const listed = (await listVoices.handler({}, ctx)) as { active: string; available: string[] };
+    expect(listed.active).toBe('elevenlabs');
+    expect(listed.available).toContain('elevenlabs');
+  });
+
+  it('a synthesizer literally named "system" is reachable and not double-listed', async () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    session.synthesizers.register(fakeSynth('system'));
+    const { setVoice, listVoices } = tools(session);
+
+    // "system" no longer always clears — it activates the real backend.
+    const result = (await setVoice.handler({ synthesizer: 'system' }, ctx)) as { active: string };
+    expect(result.active).toBe('system');
+    expect(session.synthesizers.getActiveName()).toBe('system');
+
+    // ...and it appears exactly once in the listing (sentinel de-duped).
+    const listed = (await listVoices.handler({}, ctx)) as { active: string; available: string[] };
+    expect(listed.available.filter((n) => n === 'system')).toHaveLength(1);
+  });
+
+  // --- failure-path / hostile-input regressions ---------------------------
+
+  it('the input schema (the production gate) rejects empty / missing synthesizer', () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    const { setVoice } = tools(session);
+    // The framework parses tool input against `inputSchema` BEFORE the handler
+    // runs (see defineTool). An empty string or a missing field must be rejected
+    // at that gate, never reaching the handler.
+    expect(setVoice.inputSchema.safeParse({ synthesizer: '' }).success).toBe(false);
+    expect(setVoice.inputSchema.safeParse({}).success).toBe(false);
+    expect(setVoice.inputSchema.safeParse({ synthesizer: 42 }).success).toBe(false);
+    expect(setVoice.inputSchema.safeParse({ synthesizer: 'elevenlabs' }).success).toBe(true);
+  });
+
+  it('set_voice degrades (does not crash) on whitespace-only and space-padded names', () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    session.synthesizers.register(fakeSynth('elevenlabs'));
+    const { setVoice } = tools(session);
+    // A single space passes the schema's min(1) but is not a real synthesizer
+    // and must NOT be coerced into the 'system' sentinel — it throws cleanly.
+    expect(() => setVoice.handler({ synthesizer: ' ' }, ctx)).toThrow(/No synthesizer named " "/);
+    // A padded form of a real name does not match (no trimming/normalization):
+    // hostile/typo'd input is rejected, the active backend is untouched.
+    expect(() => setVoice.handler({ synthesizer: ' elevenlabs ' }, ctx)).toThrow(
+      /No synthesizer named/,
+    );
+    // The pre-existing active backend (auto-adopted on register) survives the
+    // rejected switches — hostile input never silently flips or clears it.
+    expect(session.synthesizers.getActiveName()).toBe('elevenlabs');
+  });
+
+  it('the unknown-name error hint lists available voices without crashing', () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    session.synthesizers.register(fakeSynth('elevenlabs'));
+    const { setVoice } = tools(session);
+    // The error message is the model's recovery hint — it must enumerate the
+    // real options (including the 'system' sentinel) and not throw building it.
+    expect(() => setVoice.handler({ synthesizer: 'nope' }, ctx)).toThrow(
+      /Available: system, elevenlabs\./,
+    );
+  });
+
+  it('after activating "system" (the real backend), switching to another name then back to the sentinel still works', async () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    session.synthesizers.register(fakeSynth('system'));
+    session.synthesizers.register(fakeSynth('elevenlabs'));
+    const { setVoice } = tools(session);
+
+    // Activate the real 'system' backend (collision branch).
+    await setVoice.handler({ synthesizer: 'system' }, ctx);
+    expect(session.synthesizers.getActiveName()).toBe('system');
+    // Switch away to another registered backend.
+    await setVoice.handler({ synthesizer: 'elevenlabs' }, ctx);
+    expect(session.synthesizers.getActiveName()).toBe('elevenlabs');
+    // Switch back to the 'system'-named backend — still resolves the real def,
+    // never the clear-active sentinel, because `has('system')` is true.
+    await setVoice.handler({ synthesizer: 'system' }, ctx);
+    expect(session.synthesizers.getActiveName()).toBe('system');
+  });
+
+  it('list_voices puts the "system" sentinel first and is deterministic', async () => {
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger });
+    session.synthesizers.register(fakeSynth('zeta'));
+    session.synthesizers.register(fakeSynth('alpha'));
+    const { listVoices } = tools(session);
+    const listed = (await listVoices.handler({}, ctx)) as { active: string; available: string[] };
+    // Stable, registration-order output with the sentinel always leading — the
+    // agent gets a predictable list to reason over.
+    expect(listed.available).toEqual(['system', 'zeta', 'alpha']);
+  });
+});

package/src/index.ts

@@ -0,0 +1,120 @@
+import type { Session, SynthesizerRegistry } from '@moxxy/core';
+import { definePlugin, defineTool, z, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+
+/**
+ * Voice/TTS control plugin — lets the agent switch which text-to-speech backend
+ * read-aloud surfaces (the desktop's speaker button) use, without a settings UI.
+ * `set_voice` activates a registered synthesizer by name, or 'system' to
+ * deactivate (fall back to the OS voice). `list_voices` reports what's available
+ * + which is active. A synthesizer authored via self-update auto-activates on
+ * load, so this is for switching afterwards.
+ *
+ * The synthesizer registry lives on the live Session, so this is built via a
+ * factory closing over it (mirroring `buildViewPlugin` / `buildSubagentsPlugin`)
+ * and wired into the cli's builtin `entries` list.
+ */
+export function buildVoiceAdminPlugin(session: Session): Plugin {
+  return makeVoiceAdminPlugin(() => session.synthesizers);
+}
+
+/**
+ * Discovery-loadable default export: resolves the synthesizer registry from the
+ * inter-plugin service registry in `onInit` (the host publishes `'synthesizers'`),
+ * so the tools control the live session's TTS backend without a host-injected
+ * `session` closure.
+ */
+export const voiceAdminPlugin: Plugin = (() => {
+  let reg: SynthesizerRegistry | null = null;
+  const hooks: LifecycleHooks = {
+    onInit: (ctx) => {
+      reg = ctx.services.get<SynthesizerRegistry>('synthesizers') ?? null;
+    },
+  };
+  return makeVoiceAdminPlugin(() => {
+    if (!reg) {
+      throw new Error(
+        '@moxxy/plugin-voice-admin: the "synthesizers" registry is unavailable — the host must publish it',
+      );
+    }
+    return reg;
+  }, hooks);
+})();
+
+function makeVoiceAdminPlugin(
+  getSynths: () => SynthesizerRegistry,
+  hooks?: LifecycleHooks,
+): Plugin {
+  // 'system' (the OS voice) plus every registered synthesizer — the one
+  // list both tools speak in terms of (list_voices' result and
+  // set_voice's "unknown name" hint). The synthesizer namespace is
+  // attacker-influenced (any plugin / a self-update-authored backend can
+  // register a name), so de-dupe in case one is literally named 'system' —
+  // otherwise it would be listed twice.
+  const voiceNames = (): string[] => [
+    'system',
+    ...getSynths()
+      .list()
+      .map((s) => s.name)
+      .filter((n) => n !== 'system'),
+  ];
+  return definePlugin({
+    name: '@moxxy/plugin-voice-admin',
+    version: '0.0.1',
+    ...(hooks ? { hooks } : {}),
+    tools: [
+      defineTool({
+        name: 'list_voices',
+        description:
+          'List the text-to-speech (synthesizer) backends registered on this ' +
+          'session and which one is active. "system" means the OS voice (no ' +
+          'plugin synthesizer active).',
+        inputSchema: z.object({}),
+        permission: { action: 'allow' },
+        handler: () => ({
+          active: getSynths().getActiveName() ?? 'system',
+          available: voiceNames(),
+        }),
+      }),
+      defineTool({
+        name: 'set_voice',
+        description:
+          'Choose which text-to-speech backend read-aloud uses. Pass a ' +
+          'registered synthesizer name (see list_voices) to activate it, or ' +
+          '"system" to fall back to the OS voice. Use this to switch between ' +
+          'an installed TTS plugin (e.g. ElevenLabs) and the built-in voice.',
+        inputSchema: z.object({
+          synthesizer: z
+            .string()
+            .min(1)
+            .describe('Synthesizer name to activate, or "system" for the OS voice.'),
+        }),
+        // Auto-allowed because switching the active TTS backend has a low blast
+        // radius: it only flips the registry's active slot. The synthesizer is
+        // not built here (the registry is buildOnRead), so no secret read or
+        // network call happens at set_voice time — the first read-aloud builds
+        // it under the same vault/network gates a registered plugin already has.
+        permission: { action: 'allow' },
+        handler: ({ synthesizer }) => {
+          // Treat 'system' as the OS-voice sentinel only when no real
+          // synthesizer claims that name. A backend literally named 'system'
+          // (registrations are attacker-influenced) is otherwise permanently
+          // unreachable; fall through to activate it.
+          if (synthesizer === 'system' && !getSynths().has('system')) {
+            getSynths().clearActive();
+            return { active: 'system' };
+          }
+          if (!getSynths().has(synthesizer)) {
+            throw new Error(
+              `No synthesizer named "${synthesizer}". Available: ${voiceNames().join(', ')}.`,
+            );
+          }
+          getSynths().setActive(synthesizer);
+          return { active: synthesizer };
+        },
+      }),
+    ],
+  });
+}
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default voiceAdminPlugin;