@moxxy/plugin-tts-elevenlabs 0.28.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/elevenlabs-tts.d.ts

@@ -0,0 +1,84 @@
+import { type Synthesizer, type SynthesizeOptions, type SynthesisResult } from '@moxxy/sdk';
+/** ElevenLabs `output_format` query values we expose, mapped to the MIME type
+ *  the desktop/channels play the returned bytes as. Deliberately a small closed
+ *  map of only the mp3 variants — every one is a self-contained, playable
+ *  container that maps cleanly to `audio/mpeg`. `mp3_44100_128` is the default
+ *  (44.1 kHz / 128 kbps).
+ *
+ *  Formats intentionally NOT surfaced, and why:
+ *   - `pcm_*` (raw 16-bit LE PCM): headerless — there is no container, so the
+ *     honest options are to WAV-wrap the bytes or omit them. We omit rather than
+ *     hand a caller unplayable bytes under a bogus `audio/wav`/`audio/pcm` label.
+ *   - `ulaw_8000` / `alaw_8000`: telephony codecs, likewise headerless.
+ *   - opus: some newer API versions document an `opus_48000_*` family, but we
+ *     are not confident of the exact stable token on this endpoint, and inventing
+ *     a query value would 4xx the request — so it is left out rather than guessed. */
+declare const MIME_BY_FORMAT: {
+    readonly mp3_44100_128: "audio/mpeg";
+    readonly mp3_44100_64: "audio/mpeg";
+    readonly mp3_22050_32: "audio/mpeg";
+};
+export type ElevenLabsTtsFormat = keyof typeof MIME_BY_FORMAT;
+/** Injectable `fetch` — the default is the global; tests pass a stub. Widened
+ *  from the global signature so a plain `(url, init) => Response` stub fits. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export interface ElevenLabsSynthesizerOptions {
+    /** Explicit API key. Normally omitted — the key is read via `getSecret`. */
+    readonly apiKey?: string;
+    /** Vault-backed secret resolver handed in by `SynthesizerCreateContext`. */
+    readonly getSecret?: (name: string) => Promise<string | null>;
+    /** API base, default `https://api.elevenlabs.io/v1`. Trailing slashes trimmed. */
+    readonly baseURL?: string;
+    /** TTS model, default `eleven_multilingual_v2`. */
+    readonly model?: string;
+    /** Default voice id, default Rachel (`21m00Tcm4TlvDq8ikWAM`). Overridden
+     *  per-call by `opts.voice`. */
+    readonly voiceId?: string;
+    /** Output container, default `mp3_44100_128`. Determines the returned `mimeType`. */
+    readonly format?: ElevenLabsTtsFormat;
+    /** Injected `fetch` (tests). Defaults to the global. */
+    readonly fetchImpl?: FetchLike;
+    /** Per-request timeout in ms. Default 60000. */
+    readonly timeoutMs?: number;
+}
+/**
+ * `Synthesizer` backed by ElevenLabs' `POST /v1/text-to-speech/{voiceId}`
+ * endpoint — one JSON POST returning raw audio bytes, so there's no need for a
+ * vendor SDK. The API key rides the vault (`ctx.getSecret('ELEVENLABS_API_KEY')`)
+ * with a `process.env.ELEVENLABS_API_KEY` fallback, resolved lazily on the first
+ * `synthesize` and cached so `create()` stays cheap. This is the "quality"
+ * Synthesizer option alongside the OpenAI backend.
+ */
+export declare class ElevenLabsSynthesizer implements Synthesizer {
+    readonly name = "elevenlabs";
+    /** MIME type of the bytes this instance returns (derived from `format`). */
+    readonly mimeType: string;
+    private readonly explicitKey;
+    private readonly getSecret;
+    private readonly baseURL;
+    private readonly model;
+    private readonly voiceId;
+    private readonly format;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private key;
+    constructor(opts?: ElevenLabsSynthesizerOptions);
+    synthesize(text: string, opts?: SynthesizeOptions): Promise<SynthesisResult>;
+    /**
+     * Resolve the API key lazily: explicit option → vault (`ELEVENLABS_API_KEY`) →
+     * `process.env.ELEVENLABS_API_KEY`. Cache only a successful resolution so a key
+     * added after a first failed attempt is still picked up on retry. A missing
+     * key becomes a classified, actionable `MoxxyError`.
+     */
+    private resolveKey;
+}
+/**
+ * Cap `text` to ElevenLabs' input limit. When over, truncate at the last
+ * sentence boundary (`. `, `! `, `? `, newline) inside the budget — as long as
+ * that keeps most of the text — else hard-slice, and append a single ellipsis so
+ * the result is always ≤ {@link MAX_INPUT_CHARS} characters.
+ */
+export declare function capInput(text: string): string;
+export declare function createElevenLabsSynthesizer(opts?: ElevenLabsSynthesizerOptions): ElevenLabsSynthesizer;
+export {};
+//# sourceMappingURL=elevenlabs-tts.d.ts.map

package/dist/elevenlabs-tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elevenlabs-tts.d.ts","sourceRoot":"","sources":["../src/elevenlabs-tts.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;sFAasF;AACtF,QAAA,MAAM,cAAc;;;;CAIV,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,cAAc,CAAC;AAe9D;gFACgF;AAChF,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhF,MAAM,WAAW,4BAA4B;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;oCACgC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IACtC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,WAAW;IACvD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyD;IACnF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,GAAG,CAAuB;gBAEtB,IAAI,GAAE,4BAAiC;IAY7C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;IAgFtF;;;;;OAKG;YACW,UAAU;CAkBzB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc7C;AAED,wBAAgB,2BAA2B,CACzC,IAAI,GAAE,4BAAiC,GACtC,qBAAqB,CAEvB"}

package/dist/elevenlabs-tts.js

@@ -0,0 +1,191 @@
+import { classifyHttpStatus, classifyNetworkError, MoxxyError, } from '@moxxy/sdk';
+/** Provider tag attached to classified errors for logs/debug context. */
+const ELEVENLABS_TTS_PROVIDER_ID = 'elevenlabs';
+/** ElevenLabs `output_format` query values we expose, mapped to the MIME type
+ *  the desktop/channels play the returned bytes as. Deliberately a small closed
+ *  map of only the mp3 variants — every one is a self-contained, playable
+ *  container that maps cleanly to `audio/mpeg`. `mp3_44100_128` is the default
+ *  (44.1 kHz / 128 kbps).
+ *
+ *  Formats intentionally NOT surfaced, and why:
+ *   - `pcm_*` (raw 16-bit LE PCM): headerless — there is no container, so the
+ *     honest options are to WAV-wrap the bytes or omit them. We omit rather than
+ *     hand a caller unplayable bytes under a bogus `audio/wav`/`audio/pcm` label.
+ *   - `ulaw_8000` / `alaw_8000`: telephony codecs, likewise headerless.
+ *   - opus: some newer API versions document an `opus_48000_*` family, but we
+ *     are not confident of the exact stable token on this endpoint, and inventing
+ *     a query value would 4xx the request — so it is left out rather than guessed. */
+const MIME_BY_FORMAT = {
+    mp3_44100_128: 'audio/mpeg',
+    mp3_44100_64: 'audio/mpeg',
+    mp3_22050_32: 'audio/mpeg',
+};
+/** Rachel — a stock ElevenLabs voice present on every account. */
+const DEFAULT_VOICE_ID = '21m00Tcm4TlvDq8ikWAM';
+/** ElevenLabs' input length caps vary by plan/model (roughly 2500–5000 chars).
+ *  We truncate at the conservative 2500 so a long channel reply never 4xx's the
+ *  whole read-aloud regardless of the caller's plan; the cut lands on a sentence
+ *  boundary, same mechanism as the OpenAI sibling. */
+const MAX_INPUT_CHARS = 2500;
+/** Default per-request deadline. Read-aloud is cancellable, but a hung socket
+ *  should still free itself so callers can fall back to the OS voice. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * `Synthesizer` backed by ElevenLabs' `POST /v1/text-to-speech/{voiceId}`
+ * endpoint — one JSON POST returning raw audio bytes, so there's no need for a
+ * vendor SDK. The API key rides the vault (`ctx.getSecret('ELEVENLABS_API_KEY')`)
+ * with a `process.env.ELEVENLABS_API_KEY` fallback, resolved lazily on the first
+ * `synthesize` and cached so `create()` stays cheap. This is the "quality"
+ * Synthesizer option alongside the OpenAI backend.
+ */
+export class ElevenLabsSynthesizer {
+    name = 'elevenlabs';
+    /** MIME type of the bytes this instance returns (derived from `format`). */
+    mimeType;
+    explicitKey;
+    getSecret;
+    baseURL;
+    model;
+    voiceId;
+    format;
+    fetchImpl;
+    timeoutMs;
+    key = null;
+    constructor(opts = {}) {
+        this.explicitKey = opts.apiKey;
+        this.getSecret = opts.getSecret;
+        this.baseURL = (opts.baseURL ?? 'https://api.elevenlabs.io/v1').replace(/\/+$/, '');
+        this.model = opts.model ?? 'eleven_multilingual_v2';
+        this.voiceId = opts.voiceId ?? DEFAULT_VOICE_ID;
+        this.format = opts.format ?? 'mp3_44100_128';
+        this.mimeType = MIME_BY_FORMAT[this.format];
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async synthesize(text, opts = {}) {
+        // Fast-path a caller who cancelled before we started — propagate their reason.
+        opts.signal?.throwIfAborted();
+        const key = await this.resolveKey();
+        const input = capInput(text);
+        const voiceId = opts.voice ?? this.voiceId;
+        // `opts.rate` is intentionally ignored: ElevenLabs has no reliable, model-
+        // agnostic speaking-rate parameter (`voice_settings` covers stability /
+        // similarity / style, not speed), so mapping it would be guesswork. We omit
+        // `voice_settings` entirely and let the model use its own defaults.
+        const body = {
+            text: input,
+            model_id: this.model,
+        };
+        // `output_format` is a QUERY parameter on this endpoint, not a body field.
+        const url = `${this.baseURL}/text-to-speech/${encodeURIComponent(voiceId)}?output_format=${this.format}`;
+        // Chain the caller's abort signal with our own timeout onto one controller
+        // passed to fetch, so either cancels the request and frees the socket.
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, this.timeoutMs);
+        const forward = () => controller.abort();
+        if (opts.signal) {
+            // The signal may have fired during key resolution above; a listener added
+            // to an already-aborted signal is never called, so abort directly here.
+            if (opts.signal.aborted)
+                controller.abort();
+            else
+                opts.signal.addEventListener('abort', forward, { once: true });
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: 'POST',
+                headers: { 'xi-api-key': key, 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            // Caller-initiated cancellation: re-throw their reason unchanged so a
+            // stopped read-aloud isn't masked as a provider/network error.
+            if (opts.signal?.aborted && !timedOut)
+                throw opts.signal.reason ?? err;
+            if (timedOut) {
+                throw new MoxxyError({
+                    code: 'NETWORK_TIMEOUT',
+                    message: `ElevenLabs text-to-speech request timed out after ${this.timeoutMs} ms.`,
+                    hint: 'Retry, or shorten the text being read aloud.',
+                    context: { provider: ELEVENLABS_TTS_PROVIDER_ID, url },
+                });
+            }
+            const network = classifyNetworkError(err, { provider: ELEVENLABS_TTS_PROVIDER_ID, url });
+            if (network)
+                throw network;
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', forward);
+        }
+        if (!res.ok) {
+            const classified = classifyHttpStatus(res.status, {
+                provider: ELEVENLABS_TTS_PROVIDER_ID,
+                url,
+                body: await res.text().catch(() => ''),
+            });
+            if (classified)
+                throw classified;
+            throw new MoxxyError({
+                code: 'PROVIDER_BAD_REQUEST',
+                message: `ElevenLabs text-to-speech returned HTTP ${res.status}.`,
+                context: { provider: ELEVENLABS_TTS_PROVIDER_ID, url, status: res.status },
+            });
+        }
+        const audio = new Uint8Array(await res.arrayBuffer());
+        return { audio, mimeType: this.mimeType };
+    }
+    /**
+     * Resolve the API key lazily: explicit option → vault (`ELEVENLABS_API_KEY`) →
+     * `process.env.ELEVENLABS_API_KEY`. Cache only a successful resolution so a key
+     * added after a first failed attempt is still picked up on retry. A missing
+     * key becomes a classified, actionable `MoxxyError`.
+     */
+    async resolveKey() {
+        if (this.key)
+            return this.key;
+        const resolved = this.explicitKey ??
+            (await this.getSecret?.('ELEVENLABS_API_KEY')) ??
+            process.env.ELEVENLABS_API_KEY ??
+            null;
+        if (!resolved) {
+            throw new MoxxyError({
+                code: 'AUTH_NO_CREDENTIALS',
+                message: 'No ElevenLabs API key for text-to-speech.',
+                hint: 'Run `moxxy init` (stores it in the vault) or set ELEVENLABS_API_KEY.',
+                context: { provider: ELEVENLABS_TTS_PROVIDER_ID },
+            });
+        }
+        this.key = resolved;
+        return resolved;
+    }
+}
+/**
+ * Cap `text` to ElevenLabs' input limit. When over, truncate at the last
+ * sentence boundary (`. `, `! `, `? `, newline) inside the budget — as long as
+ * that keeps most of the text — else hard-slice, and append a single ellipsis so
+ * the result is always ≤ {@link MAX_INPUT_CHARS} characters.
+ */
+export function capInput(text) {
+    if (text.length <= MAX_INPUT_CHARS)
+        return text;
+    const budget = MAX_INPUT_CHARS - 1; // leave room for the ellipsis
+    const slice = text.slice(0, budget);
+    const boundary = Math.max(slice.lastIndexOf('. '), slice.lastIndexOf('! '), slice.lastIndexOf('? '), slice.lastIndexOf('\n'));
+    // Only honor a boundary that doesn't discard more than half the budget,
+    // otherwise a single very long sentence would be cut to almost nothing.
+    const cut = boundary > budget * 0.5 ? boundary + 1 : budget;
+    return `${slice.slice(0, cut).trimEnd()}…`;
+}
+export function createElevenLabsSynthesizer(opts = {}) {
+    return new ElevenLabsSynthesizer(opts);
+}
+//# sourceMappingURL=elevenlabs-tts.js.map

package/dist/elevenlabs-tts.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { type Plugin } from '@moxxy/sdk';
+import { type ElevenLabsSynthesizerOptions } from './elevenlabs-tts.js';
+export { ElevenLabsSynthesizer, createElevenLabsSynthesizer, capInput, type ElevenLabsSynthesizerOptions, type ElevenLabsTtsFormat, type FetchLike, } from './elevenlabs-tts.js';
+/** The single registered synthesizer name — surfaces show this in `set_voice`. */
+export declare const ELEVENLABS_TTS_SYNTHESIZER_NAME = "elevenlabs";
+export interface BuildElevenLabsTtsPluginOptions {
+    /**
+     * Build-time defaults baked into the synthesizer def. Per-activation config
+     * (`session.synthesizers.setActive(name, config)`) still overrides `model` /
+     * `voiceId` / `format`. Mainly a seam for tests to inject `fetchImpl` / `apiKey`.
+     */
+    readonly defaults?: Omit<ElevenLabsSynthesizerOptions, 'getSecret'>;
+}
+/**
+ * Build the @moxxy/plugin-tts-elevenlabs plugin. Registers exactly one
+ * synthesizer, `elevenlabs`, backed by ElevenLabs' `POST /v1/text-to-speech`.
+ *
+ * The plugin is intentionally side-effect free — it never calls `setActive`.
+ * The `SynthesizerRegistry` is `autoAdoptFirst`, so the first synthesizer
+ * registered becomes active on read without any activation step here; the agent
+ * switches voices via the `set_voice` tool.
+ */
+export declare function buildElevenLabsTtsPlugin(opts?: BuildElevenLabsTtsPluginOptions): Plugin;
+declare const _default: Plugin;
+export default _default;
+//# 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,EAAmC,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAEL,KAAK,4BAA4B,EAElC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,QAAQ,EACR,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,kFAAkF;AAClF,eAAO,MAAM,+BAA+B,eAAe,CAAC;AAE5D,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,4BAA4B,EAAE,WAAW,CAAC,CAAC;CACrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,GAAE,+BAAoC,GAAG,MAAM,CAoB3F;;AAiCD,wBAA0C"}

package/dist/index.js

@@ -0,0 +1,67 @@
+import { definePlugin, defineSynthesizer } from '@moxxy/sdk';
+import { ElevenLabsSynthesizer, } from './elevenlabs-tts.js';
+export { ElevenLabsSynthesizer, createElevenLabsSynthesizer, capInput, } from './elevenlabs-tts.js';
+/** The single registered synthesizer name — surfaces show this in `set_voice`. */
+export const ELEVENLABS_TTS_SYNTHESIZER_NAME = 'elevenlabs';
+/**
+ * Build the @moxxy/plugin-tts-elevenlabs plugin. Registers exactly one
+ * synthesizer, `elevenlabs`, backed by ElevenLabs' `POST /v1/text-to-speech`.
+ *
+ * The plugin is intentionally side-effect free — it never calls `setActive`.
+ * The `SynthesizerRegistry` is `autoAdoptFirst`, so the first synthesizer
+ * registered becomes active on read without any activation step here; the agent
+ * switches voices via the `set_voice` tool.
+ */
+export function buildElevenLabsTtsPlugin(opts = {}) {
+    const defaults = opts.defaults ?? {};
+    return definePlugin({
+        name: '@moxxy/plugin-tts-elevenlabs',
+        version: '0.0.0',
+        synthesizers: [
+            defineSynthesizer({
+                name: ELEVENLABS_TTS_SYNTHESIZER_NAME,
+                displayName: 'ElevenLabs',
+                // `create` runs lazily and may re-run (buildOnRead) — keep it cheap and
+                // side-effect free; the key is resolved inside `synthesize`.
+                create: (ctx) => new ElevenLabsSynthesizer({
+                    ...defaults,
+                    ...configToOptions(ctx.config),
+                    ...(ctx.getSecret ? { getSecret: ctx.getSecret } : {}),
+                }),
+            }),
+        ],
+    });
+}
+/** Narrow the untrusted per-activation config record into typed options. Only
+ *  string `model` / `voiceId` / `baseURL` / `apiKey` and a known `format` are
+ *  honored; anything else is ignored so a malformed config can't break create. */
+function configToOptions(config) {
+    const out = {};
+    if (typeof config.model === 'string' && config.model)
+        out.model = config.model;
+    if (typeof config.voiceId === 'string' && config.voiceId)
+        out.voiceId = config.voiceId;
+    if (typeof config.baseURL === 'string' && config.baseURL)
+        out.baseURL = config.baseURL;
+    if (typeof config.apiKey === 'string' && config.apiKey)
+        out.apiKey = config.apiKey;
+    const format = normalizeFormat(config.format);
+    if (format)
+        out.format = format;
+    return out;
+}
+const KNOWN_FORMATS = [
+    'mp3_44100_128',
+    'mp3_44100_64',
+    'mp3_22050_32',
+];
+/** Accept only the exact supported format strings (guards against inherited
+ *  keys like `constructor` slipping through an `in` check). */
+function normalizeFormat(value) {
+    return typeof value === 'string' && KNOWN_FORMATS.includes(value)
+        ? value
+        : undefined;
+}
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default buildElevenLabsTtsPlugin();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAe,MAAM,YAAY,CAAC;AAC1E,OAAO,EACL,qBAAqB,GAGtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,QAAQ,GAIT,MAAM,qBAAqB,CAAC;AAE7B,kFAAkF;AAClF,MAAM,CAAC,MAAM,+BAA+B,GAAG,YAAY,CAAC;AAW5D;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAwC,EAAE;IACjF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACrC,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,8BAA8B;QACpC,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE;YACZ,iBAAiB,CAAC;gBAChB,IAAI,EAAE,+BAA+B;gBACrC,WAAW,EAAE,YAAY;gBACzB,wEAAwE;gBACxE,6DAA6D;gBAC7D,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CACd,IAAI,qBAAqB,CAAC;oBACxB,GAAG,QAAQ;oBACX,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC;oBAC9B,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACvD,CAAC;aACL,CAAC;SACH;KACF,CAAC,CAAC;AACL,CAAC;AAED;;kFAEkF;AAClF,SAAS,eAAe,CAAC,MAA+B;IACtD,MAAM,GAAG,GAEL,EAAE,CAAC;IACP,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK;QAAE,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC/E,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IACvF,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IACvF,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM;QAAE,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IACnF,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,MAAM;QAAE,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,aAAa,GAAuC;IACxD,eAAe;IACf,cAAc;IACd,cAAc;CACf,CAAC;AAEF;+DAC+D;AAC/D,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,aAAuC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC1F,CAAC,CAAE,KAA6B;QAChC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,0EAA0E;AAC1E,eAAe,wBAAwB,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@moxxy/plugin-tts-elevenlabs",
+  "version": "0.28.0",
+  "description": "ElevenLabs text-to-speech Synthesizer for moxxy. Text → spoken audio bytes via POST /v1/text-to-speech/{voiceId}. Plugs into the session's SynthesizerRegistry; read-aloud surfaces (desktop 'Read aloud', a voice channel) consume it transparently. The higher-quality Synthesizer backend alongside OpenAI TTS.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "tts",
+    "text-to-speech",
+    "elevenlabs",
+    "synthesizer"
+  ],
+  "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-tts-elevenlabs"
+  },
+  "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": "synthesizer"
+    },
+    "setup": {
+      "title": "ElevenLabs text-to-speech",
+      "description": "Read-aloud through ElevenLabs' /v1/text-to-speech. Needs an ElevenLabs API key — the plugin does nothing without one, so skipping this leaves the package disabled.",
+      "fields": [
+        {
+          "key": "apiKey",
+          "label": "ElevenLabs API key",
+          "kind": "secret",
+          "vaultKey": "ELEVENLABS_API_KEY",
+          "required": true,
+          "placeholder": "sk_…",
+          "description": "Your ElevenLabs API key, from https://elevenlabs.io → Profile → API Keys. Stored in the vault as ELEVENLABS_API_KEY; the model never sees it."
+        }
+      ]
+    }
+  },
+  "dependencies": {
+    "@moxxy/sdk": "0.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/elevenlabs-tts.test.ts

@@ -0,0 +1,276 @@
+import { describe, expect, it } from 'vitest';
+import { ElevenLabsSynthesizer, capInput, type FetchLike } from './elevenlabs-tts.js';
+import { buildElevenLabsTtsPlugin, ELEVENLABS_TTS_SYNTHESIZER_NAME } from './index.js';
+
+interface Captured {
+  url: string;
+  init: RequestInit;
+}
+
+const RACHEL = '21m00Tcm4TlvDq8ikWAM';
+
+/** A stub `fetch` that records the request and returns fixed audio bytes. */
+function okFetch(
+  bytes: Uint8Array = new Uint8Array([1, 2, 3, 4]),
+  status = 200,
+): { fetchImpl: FetchLike; calls: Captured[] } {
+  const calls: Captured[] = [];
+  const fetchImpl: FetchLike = async (url, init) => {
+    calls.push({ url, init });
+    return new Response(bytes, { status });
+  };
+  return { fetchImpl, calls };
+}
+
+/** A stub `fetch` that returns an error status with a body. */
+function statusFetch(status: number, body = 'boom'): FetchLike {
+  return async () => new Response(body, { status });
+}
+
+/** A `fetch` that never resolves and only rejects when its signal aborts —
+ *  checking `aborted` synchronously (as real fetch does) so it works even when
+ *  the signal fired before the request was issued. Drives abort + timeout. */
+const abortAwareFetch: FetchLike = (_url, init) =>
+  new Promise((_resolve, reject) => {
+    const signal = init.signal;
+    const fail = (): void => reject(new DOMException('Aborted', 'AbortError'));
+    if (signal?.aborted) fail();
+    else signal?.addEventListener('abort', fail, { once: true });
+  });
+
+/** Parse the JSON body a captured request carried. */
+function bodyOf(calls: Captured[]): Record<string, unknown> {
+  return JSON.parse(calls[0]!.init.body as string) as Record<string, unknown>;
+}
+
+describe('ElevenLabsSynthesizer.synthesize', () => {
+  it('returns audio bytes and the mp3 mimeType by default', async () => {
+    const { fetchImpl, calls } = okFetch(new Uint8Array([9, 8, 7]));
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    const out = await synth.synthesize('hello world');
+
+    expect(Array.from(out.audio)).toEqual([9, 8, 7]);
+    expect(out.mimeType).toBe('audio/mpeg');
+    expect(calls[0]!.url).toBe(
+      `https://api.elevenlabs.io/v1/text-to-speech/${RACHEL}?output_format=mp3_44100_128`,
+    );
+    expect(calls[0]!.init.method).toBe('POST');
+    const headers = calls[0]!.init.headers as Record<string, string>;
+    expect(headers['xi-api-key']).toBe('sk-test');
+    expect(headers['content-type']).toBe('application/json');
+    const body = bodyOf(calls);
+    expect(body.text).toBe('hello world');
+    expect(body.model_id).toBe('eleven_multilingual_v2');
+    // No speaking-rate/voice_settings field is ever sent (see `rate` below).
+    expect(Object.keys(body).sort()).toEqual(['model_id', 'text']);
+  });
+
+  it.each([
+    ['mp3_44100_128', 'audio/mpeg'],
+    ['mp3_44100_64', 'audio/mpeg'],
+    ['mp3_22050_32', 'audio/mpeg'],
+  ] as const)('maps format %s to mimeType %s (as an output_format query)', async (format, mimeType) => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl, format });
+    const out = await synth.synthesize('hi');
+    expect(out.mimeType).toBe(mimeType);
+    expect(calls[0]!.url).toContain(`output_format=${format}`);
+  });
+
+  it('lets opts.voice override the configured voiceId (in the URL path)', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl, voiceId: RACHEL });
+    await synth.synthesize('hi', { voice: 'AZnzlk1XvdvUeBnXmlld' });
+    expect(calls[0]!.url).toBe(
+      'https://api.elevenlabs.io/v1/text-to-speech/AZnzlk1XvdvUeBnXmlld?output_format=mp3_44100_128',
+    );
+  });
+
+  it('ignores opts.rate (no speaking-rate parameter is sent)', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    await synth.synthesize('hi', { rate: 1.5 });
+    const body = bodyOf(calls);
+    expect(body.speed).toBeUndefined();
+    expect(body.voice_settings).toBeUndefined();
+    expect(Object.keys(body).sort()).toEqual(['model_id', 'text']);
+  });
+
+  it('truncates input over 2500 chars at a sentence boundary with an ellipsis', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    // 'a'*2400 + '. ' then more — the sentence boundary at index 2400 is the
+    // last one inside the 2499-char budget.
+    const long = `${'a'.repeat(2400)}. ${'b'.repeat(200)}. ${'c'.repeat(200)}`;
+    await synth.synthesize(long);
+    const input = bodyOf(calls).text as string;
+    expect(input.length).toBeLessThanOrEqual(2500);
+    expect(input.length).toBeLessThan(long.length);
+    expect(input.endsWith('…')).toBe(true);
+    // Cut fell right after the sentence-ending period, not mid-word.
+    expect(input.endsWith('.…')).toBe(true);
+  });
+
+  it('leaves short input untouched (no ellipsis)', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    await synth.synthesize('a short reply.');
+    expect(bodyOf(calls).text).toBe('a short reply.');
+  });
+
+  it('throws AUTH_NO_CREDENTIALS when no key is available anywhere', async () => {
+    const prev = process.env.ELEVENLABS_API_KEY;
+    delete process.env.ELEVENLABS_API_KEY;
+    try {
+      const { fetchImpl } = okFetch();
+      const synth = new ElevenLabsSynthesizer({ getSecret: async () => null, fetchImpl });
+      await expect(synth.synthesize('hi')).rejects.toMatchObject({
+        code: 'AUTH_NO_CREDENTIALS',
+      });
+    } finally {
+      if (prev !== undefined) process.env.ELEVENLABS_API_KEY = prev;
+    }
+  });
+
+  it('reads the key from getSecret (ELEVENLABS_API_KEY) when no explicit key', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new ElevenLabsSynthesizer({
+      getSecret: async (name) => (name === 'ELEVENLABS_API_KEY' ? 'sk-vault' : null),
+      fetchImpl,
+    });
+    await synth.synthesize('hi');
+    const headers = calls[0]!.init.headers as Record<string, string>;
+    expect(headers['xi-api-key']).toBe('sk-vault');
+  });
+
+  it.each([
+    [401, 'AUTH_INVALID'],
+    [403, 'AUTH_DENIED'],
+    [429, 'PROVIDER_RATE_LIMITED'],
+    [500, 'PROVIDER_SERVER_ERROR'],
+    [503, 'PROVIDER_SERVER_ERROR'],
+  ])('maps HTTP %s to %s', async (status, code) => {
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl: statusFetch(status) });
+    await expect(synth.synthesize('hi')).rejects.toMatchObject({ code });
+  });
+
+  it('falls back to PROVIDER_BAD_REQUEST for an unmapped status', async () => {
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl: statusFetch(418) });
+    await expect(synth.synthesize('hi')).rejects.toMatchObject({
+      code: 'PROVIDER_BAD_REQUEST',
+      context: { status: 418 },
+    });
+  });
+
+  it('classifies a network failure', async () => {
+    const fetchImpl: FetchLike = async () => {
+      throw new Error('fetch failed');
+    };
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    await expect(synth.synthesize('hi')).rejects.toMatchObject({
+      code: 'NETWORK_UNREACHABLE',
+    });
+  });
+
+  it('honors an already-aborted signal, propagating its reason', async () => {
+    const { fetchImpl } = okFetch();
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    const ac = new AbortController();
+    const reason = new Error('user stopped');
+    ac.abort(reason);
+    await expect(synth.synthesize('hi', { signal: ac.signal })).rejects.toBe(reason);
+  });
+
+  it('honors an in-flight abort, propagating the caller reason', async () => {
+    const synth = new ElevenLabsSynthesizer({ apiKey: 'sk-test', fetchImpl: abortAwareFetch });
+    const ac = new AbortController();
+    const reason = new Error('cancelled mid-flight');
+    const p = synth.synthesize('hi', { signal: ac.signal });
+    ac.abort(reason);
+    await expect(p).rejects.toBe(reason);
+  });
+
+  it('times out a hung request as NETWORK_TIMEOUT', async () => {
+    const synth = new ElevenLabsSynthesizer({
+      apiKey: 'sk-test',
+      fetchImpl: abortAwareFetch,
+      timeoutMs: 10,
+    });
+    await expect(synth.synthesize('hi')).rejects.toMatchObject({ code: 'NETWORK_TIMEOUT' });
+  });
+});
+
+describe('capInput helper', () => {
+  it('passes through under the limit', () => {
+    expect(capInput('short')).toBe('short');
+    expect(capInput('a'.repeat(2500))).toBe('a'.repeat(2500));
+  });
+
+  it('hard-slices a single boundary-less sentence', () => {
+    const out = capInput('x'.repeat(4000));
+    expect(out.length).toBe(2500); // 2499 chars + the ellipsis
+    expect(out.endsWith('…')).toBe(true);
+  });
+});
+
+describe('buildElevenLabsTtsPlugin', () => {
+  it('registers exactly one synthesizer named elevenlabs', () => {
+    const plugin = buildElevenLabsTtsPlugin();
+    expect(plugin.synthesizers).toHaveLength(1);
+    const def = plugin.synthesizers![0]!;
+    expect(def.name).toBe(ELEVENLABS_TTS_SYNTHESIZER_NAME);
+    expect(def.displayName).toBe('ElevenLabs');
+  });
+
+  it('create() yields a synthesizer whose config voiceId/format flow through', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const plugin = buildElevenLabsTtsPlugin({ defaults: { fetchImpl, apiKey: 'sk-test' } });
+    const def = plugin.synthesizers![0]!;
+    const inst = def.create({ config: { voiceId: 'AZnzlk1XvdvUeBnXmlld', format: 'mp3_22050_32' } });
+    expect(inst.name).toBe('elevenlabs');
+    const out = await inst.synthesize('hi');
+    expect(out.mimeType).toBe('audio/mpeg');
+    expect(calls[0]!.url).toBe(
+      'https://api.elevenlabs.io/v1/text-to-speech/AZnzlk1XvdvUeBnXmlld?output_format=mp3_22050_32',
+    );
+  });
+
+  it('create() wires ctx.getSecret through for key resolution', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const plugin = buildElevenLabsTtsPlugin({ defaults: { fetchImpl } });
+    const def = plugin.synthesizers![0]!;
+    const inst = def.create({
+      config: {},
+      getSecret: async (name) => (name === 'ELEVENLABS_API_KEY' ? 'sk-ctx' : null),
+    });
+    await inst.synthesize('hi');
+    const headers = calls[0]!.init.headers as Record<string, string>;
+    expect(headers['xi-api-key']).toBe('sk-ctx');
+  });
+
+  it('create() ignores an unknown config format', async () => {
+    const { fetchImpl } = okFetch();
+    const plugin = buildElevenLabsTtsPlugin({ defaults: { fetchImpl, apiKey: 'sk-test' } });
+    const inst = plugin.synthesizers![0]!.create({ config: { format: 'pcm_24000' } });
+    const out = await inst.synthesize('hi');
+    // Unknown/unsupported format ignored → default mp3_44100_128.
+    expect(out.mimeType).toBe('audio/mpeg');
+  });
+
+  it('default export registers and builds a synthesizer with a fake getSecret', async () => {
+    // Registry-level smoke: the default export is what `createPluginLoader`
+    // discovers. It must register exactly one synthesizer whose `create`, given a
+    // vault-backed `getSecret`, builds a ready instance without touching the
+    // network or a live key.
+    const { default: plugin } = await import('./index.js');
+    expect(plugin.name).toBe('@moxxy/plugin-tts-elevenlabs');
+    expect(plugin.synthesizers).toHaveLength(1);
+    const def = plugin.synthesizers![0]!;
+    const inst = def.create({
+      config: {},
+      getSecret: async (name) => (name === 'ELEVENLABS_API_KEY' ? 'sk-smoke' : null),
+    });
+    expect(inst.name).toBe('elevenlabs');
+    expect(inst.mimeType).toBe('audio/mpeg');
+  });
+});

package/src/elevenlabs-tts.ts

@@ -0,0 +1,239 @@
+import {
+  classifyHttpStatus,
+  classifyNetworkError,
+  MoxxyError,
+  type Synthesizer,
+  type SynthesizeOptions,
+  type SynthesisResult,
+} from '@moxxy/sdk';
+
+/** Provider tag attached to classified errors for logs/debug context. */
+const ELEVENLABS_TTS_PROVIDER_ID = 'elevenlabs';
+
+/** ElevenLabs `output_format` query values we expose, mapped to the MIME type
+ *  the desktop/channels play the returned bytes as. Deliberately a small closed
+ *  map of only the mp3 variants — every one is a self-contained, playable
+ *  container that maps cleanly to `audio/mpeg`. `mp3_44100_128` is the default
+ *  (44.1 kHz / 128 kbps).
+ *
+ *  Formats intentionally NOT surfaced, and why:
+ *   - `pcm_*` (raw 16-bit LE PCM): headerless — there is no container, so the
+ *     honest options are to WAV-wrap the bytes or omit them. We omit rather than
+ *     hand a caller unplayable bytes under a bogus `audio/wav`/`audio/pcm` label.
+ *   - `ulaw_8000` / `alaw_8000`: telephony codecs, likewise headerless.
+ *   - opus: some newer API versions document an `opus_48000_*` family, but we
+ *     are not confident of the exact stable token on this endpoint, and inventing
+ *     a query value would 4xx the request — so it is left out rather than guessed. */
+const MIME_BY_FORMAT = {
+  mp3_44100_128: 'audio/mpeg',
+  mp3_44100_64: 'audio/mpeg',
+  mp3_22050_32: 'audio/mpeg',
+} as const;
+
+export type ElevenLabsTtsFormat = keyof typeof MIME_BY_FORMAT;
+
+/** Rachel — a stock ElevenLabs voice present on every account. */
+const DEFAULT_VOICE_ID = '21m00Tcm4TlvDq8ikWAM';
+
+/** ElevenLabs' input length caps vary by plan/model (roughly 2500–5000 chars).
+ *  We truncate at the conservative 2500 so a long channel reply never 4xx's the
+ *  whole read-aloud regardless of the caller's plan; the cut lands on a sentence
+ *  boundary, same mechanism as the OpenAI sibling. */
+const MAX_INPUT_CHARS = 2500;
+
+/** Default per-request deadline. Read-aloud is cancellable, but a hung socket
+ *  should still free itself so callers can fall back to the OS voice. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/** Injectable `fetch` — the default is the global; tests pass a stub. Widened
+ *  from the global signature so a plain `(url, init) => Response` stub fits. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+export interface ElevenLabsSynthesizerOptions {
+  /** Explicit API key. Normally omitted — the key is read via `getSecret`. */
+  readonly apiKey?: string;
+  /** Vault-backed secret resolver handed in by `SynthesizerCreateContext`. */
+  readonly getSecret?: (name: string) => Promise<string | null>;
+  /** API base, default `https://api.elevenlabs.io/v1`. Trailing slashes trimmed. */
+  readonly baseURL?: string;
+  /** TTS model, default `eleven_multilingual_v2`. */
+  readonly model?: string;
+  /** Default voice id, default Rachel (`21m00Tcm4TlvDq8ikWAM`). Overridden
+   *  per-call by `opts.voice`. */
+  readonly voiceId?: string;
+  /** Output container, default `mp3_44100_128`. Determines the returned `mimeType`. */
+  readonly format?: ElevenLabsTtsFormat;
+  /** Injected `fetch` (tests). Defaults to the global. */
+  readonly fetchImpl?: FetchLike;
+  /** Per-request timeout in ms. Default 60000. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * `Synthesizer` backed by ElevenLabs' `POST /v1/text-to-speech/{voiceId}`
+ * endpoint — one JSON POST returning raw audio bytes, so there's no need for a
+ * vendor SDK. The API key rides the vault (`ctx.getSecret('ELEVENLABS_API_KEY')`)
+ * with a `process.env.ELEVENLABS_API_KEY` fallback, resolved lazily on the first
+ * `synthesize` and cached so `create()` stays cheap. This is the "quality"
+ * Synthesizer option alongside the OpenAI backend.
+ */
+export class ElevenLabsSynthesizer implements Synthesizer {
+  readonly name = 'elevenlabs';
+  /** MIME type of the bytes this instance returns (derived from `format`). */
+  readonly mimeType: string;
+
+  private readonly explicitKey: string | undefined;
+  private readonly getSecret: ((name: string) => Promise<string | null>) | undefined;
+  private readonly baseURL: string;
+  private readonly model: string;
+  private readonly voiceId: string;
+  private readonly format: ElevenLabsTtsFormat;
+  private readonly fetchImpl: FetchLike;
+  private readonly timeoutMs: number;
+  private key: string | null = null;
+
+  constructor(opts: ElevenLabsSynthesizerOptions = {}) {
+    this.explicitKey = opts.apiKey;
+    this.getSecret = opts.getSecret;
+    this.baseURL = (opts.baseURL ?? 'https://api.elevenlabs.io/v1').replace(/\/+$/, '');
+    this.model = opts.model ?? 'eleven_multilingual_v2';
+    this.voiceId = opts.voiceId ?? DEFAULT_VOICE_ID;
+    this.format = opts.format ?? 'mp3_44100_128';
+    this.mimeType = MIME_BY_FORMAT[this.format];
+    this.fetchImpl = opts.fetchImpl ?? (globalThis.fetch as FetchLike);
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  async synthesize(text: string, opts: SynthesizeOptions = {}): Promise<SynthesisResult> {
+    // Fast-path a caller who cancelled before we started — propagate their reason.
+    opts.signal?.throwIfAborted();
+
+    const key = await this.resolveKey();
+    const input = capInput(text);
+    const voiceId = opts.voice ?? this.voiceId;
+    // `opts.rate` is intentionally ignored: ElevenLabs has no reliable, model-
+    // agnostic speaking-rate parameter (`voice_settings` covers stability /
+    // similarity / style, not speed), so mapping it would be guesswork. We omit
+    // `voice_settings` entirely and let the model use its own defaults.
+    const body = {
+      text: input,
+      model_id: this.model,
+    };
+    // `output_format` is a QUERY parameter on this endpoint, not a body field.
+    const url = `${this.baseURL}/text-to-speech/${encodeURIComponent(voiceId)}?output_format=${this.format}`;
+
+    // Chain the caller's abort signal with our own timeout onto one controller
+    // passed to fetch, so either cancels the request and frees the socket.
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.timeoutMs);
+    const forward = (): void => controller.abort();
+    if (opts.signal) {
+      // The signal may have fired during key resolution above; a listener added
+      // to an already-aborted signal is never called, so abort directly here.
+      if (opts.signal.aborted) controller.abort();
+      else opts.signal.addEventListener('abort', forward, { once: true });
+    }
+
+    let res: Response;
+    try {
+      res = await this.fetchImpl(url, {
+        method: 'POST',
+        headers: { 'xi-api-key': key, 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      // Caller-initiated cancellation: re-throw their reason unchanged so a
+      // stopped read-aloud isn't masked as a provider/network error.
+      if (opts.signal?.aborted && !timedOut) throw opts.signal.reason ?? err;
+      if (timedOut) {
+        throw new MoxxyError({
+          code: 'NETWORK_TIMEOUT',
+          message: `ElevenLabs text-to-speech request timed out after ${this.timeoutMs} ms.`,
+          hint: 'Retry, or shorten the text being read aloud.',
+          context: { provider: ELEVENLABS_TTS_PROVIDER_ID, url },
+        });
+      }
+      const network = classifyNetworkError(err, { provider: ELEVENLABS_TTS_PROVIDER_ID, url });
+      if (network) throw network;
+      throw err;
+    } finally {
+      clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', forward);
+    }
+
+    if (!res.ok) {
+      const classified = classifyHttpStatus(res.status, {
+        provider: ELEVENLABS_TTS_PROVIDER_ID,
+        url,
+        body: await res.text().catch(() => ''),
+      });
+      if (classified) throw classified;
+      throw new MoxxyError({
+        code: 'PROVIDER_BAD_REQUEST',
+        message: `ElevenLabs text-to-speech returned HTTP ${res.status}.`,
+        context: { provider: ELEVENLABS_TTS_PROVIDER_ID, url, status: res.status },
+      });
+    }
+
+    const audio = new Uint8Array(await res.arrayBuffer());
+    return { audio, mimeType: this.mimeType };
+  }
+
+  /**
+   * Resolve the API key lazily: explicit option → vault (`ELEVENLABS_API_KEY`) →
+   * `process.env.ELEVENLABS_API_KEY`. Cache only a successful resolution so a key
+   * added after a first failed attempt is still picked up on retry. A missing
+   * key becomes a classified, actionable `MoxxyError`.
+   */
+  private async resolveKey(): Promise<string> {
+    if (this.key) return this.key;
+    const resolved =
+      this.explicitKey ??
+      (await this.getSecret?.('ELEVENLABS_API_KEY')) ??
+      process.env.ELEVENLABS_API_KEY ??
+      null;
+    if (!resolved) {
+      throw new MoxxyError({
+        code: 'AUTH_NO_CREDENTIALS',
+        message: 'No ElevenLabs API key for text-to-speech.',
+        hint: 'Run `moxxy init` (stores it in the vault) or set ELEVENLABS_API_KEY.',
+        context: { provider: ELEVENLABS_TTS_PROVIDER_ID },
+      });
+    }
+    this.key = resolved;
+    return resolved;
+  }
+}
+
+/**
+ * Cap `text` to ElevenLabs' input limit. When over, truncate at the last
+ * sentence boundary (`. `, `! `, `? `, newline) inside the budget — as long as
+ * that keeps most of the text — else hard-slice, and append a single ellipsis so
+ * the result is always ≤ {@link MAX_INPUT_CHARS} characters.
+ */
+export function capInput(text: string): string {
+  if (text.length <= MAX_INPUT_CHARS) return text;
+  const budget = MAX_INPUT_CHARS - 1; // leave room for the ellipsis
+  const slice = text.slice(0, budget);
+  const boundary = Math.max(
+    slice.lastIndexOf('. '),
+    slice.lastIndexOf('! '),
+    slice.lastIndexOf('? '),
+    slice.lastIndexOf('\n'),
+  );
+  // Only honor a boundary that doesn't discard more than half the budget,
+  // otherwise a single very long sentence would be cut to almost nothing.
+  const cut = boundary > budget * 0.5 ? boundary + 1 : budget;
+  return `${slice.slice(0, cut).trimEnd()}…`;
+}
+
+export function createElevenLabsSynthesizer(
+  opts: ElevenLabsSynthesizerOptions = {},
+): ElevenLabsSynthesizer {
+  return new ElevenLabsSynthesizer(opts);
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+import { definePlugin, defineSynthesizer, type Plugin } from '@moxxy/sdk';
+import {
+  ElevenLabsSynthesizer,
+  type ElevenLabsSynthesizerOptions,
+  type ElevenLabsTtsFormat,
+} from './elevenlabs-tts.js';
+
+export {
+  ElevenLabsSynthesizer,
+  createElevenLabsSynthesizer,
+  capInput,
+  type ElevenLabsSynthesizerOptions,
+  type ElevenLabsTtsFormat,
+  type FetchLike,
+} from './elevenlabs-tts.js';
+
+/** The single registered synthesizer name — surfaces show this in `set_voice`. */
+export const ELEVENLABS_TTS_SYNTHESIZER_NAME = 'elevenlabs';
+
+export interface BuildElevenLabsTtsPluginOptions {
+  /**
+   * Build-time defaults baked into the synthesizer def. Per-activation config
+   * (`session.synthesizers.setActive(name, config)`) still overrides `model` /
+   * `voiceId` / `format`. Mainly a seam for tests to inject `fetchImpl` / `apiKey`.
+   */
+  readonly defaults?: Omit<ElevenLabsSynthesizerOptions, 'getSecret'>;
+}
+
+/**
+ * Build the @moxxy/plugin-tts-elevenlabs plugin. Registers exactly one
+ * synthesizer, `elevenlabs`, backed by ElevenLabs' `POST /v1/text-to-speech`.
+ *
+ * The plugin is intentionally side-effect free — it never calls `setActive`.
+ * The `SynthesizerRegistry` is `autoAdoptFirst`, so the first synthesizer
+ * registered becomes active on read without any activation step here; the agent
+ * switches voices via the `set_voice` tool.
+ */
+export function buildElevenLabsTtsPlugin(opts: BuildElevenLabsTtsPluginOptions = {}): Plugin {
+  const defaults = opts.defaults ?? {};
+  return definePlugin({
+    name: '@moxxy/plugin-tts-elevenlabs',
+    version: '0.0.0',
+    synthesizers: [
+      defineSynthesizer({
+        name: ELEVENLABS_TTS_SYNTHESIZER_NAME,
+        displayName: 'ElevenLabs',
+        // `create` runs lazily and may re-run (buildOnRead) — keep it cheap and
+        // side-effect free; the key is resolved inside `synthesize`.
+        create: (ctx) =>
+          new ElevenLabsSynthesizer({
+            ...defaults,
+            ...configToOptions(ctx.config),
+            ...(ctx.getSecret ? { getSecret: ctx.getSecret } : {}),
+          }),
+      }),
+    ],
+  });
+}
+
+/** Narrow the untrusted per-activation config record into typed options. Only
+ *  string `model` / `voiceId` / `baseURL` / `apiKey` and a known `format` are
+ *  honored; anything else is ignored so a malformed config can't break create. */
+function configToOptions(config: Record<string, unknown>): Partial<ElevenLabsSynthesizerOptions> {
+  const out: {
+    -readonly [K in keyof ElevenLabsSynthesizerOptions]?: ElevenLabsSynthesizerOptions[K];
+  } = {};
+  if (typeof config.model === 'string' && config.model) out.model = config.model;
+  if (typeof config.voiceId === 'string' && config.voiceId) out.voiceId = config.voiceId;
+  if (typeof config.baseURL === 'string' && config.baseURL) out.baseURL = config.baseURL;
+  if (typeof config.apiKey === 'string' && config.apiKey) out.apiKey = config.apiKey;
+  const format = normalizeFormat(config.format);
+  if (format) out.format = format;
+  return out;
+}
+
+const KNOWN_FORMATS: ReadonlyArray<ElevenLabsTtsFormat> = [
+  'mp3_44100_128',
+  'mp3_44100_64',
+  'mp3_22050_32',
+];
+
+/** Accept only the exact supported format strings (guards against inherited
+ *  keys like `constructor` slipping through an `in` check). */
+function normalizeFormat(value: unknown): ElevenLabsTtsFormat | undefined {
+  return typeof value === 'string' && (KNOWN_FORMATS as ReadonlyArray<string>).includes(value)
+    ? (value as ElevenLabsTtsFormat)
+    : undefined;
+}
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default buildElevenLabsTtsPlugin();