@moxxy/plugin-tts-openai 0.27.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,26 @@
+import { type Plugin } from '@moxxy/sdk';
+import { type OpenAiSynthesizerOptions } from './openai-tts.js';
+export { OpenAiSynthesizer, createOpenAiSynthesizer, capInput, clampSpeed, type OpenAiSynthesizerOptions, type OpenAiTtsFormat, type FetchLike, } from './openai-tts.js';
+/** The single registered synthesizer name — surfaces show this in `set_voice`. */
+export declare const OPENAI_TTS_SYNTHESIZER_NAME = "openai-tts";
+export interface BuildOpenAiTtsPluginOptions {
+    /**
+     * Build-time defaults baked into the synthesizer def. Per-activation config
+     * (`session.synthesizers.setActive(name, config)`) still overrides `model` /
+     * `voice` / `format`. Mainly a seam for tests to inject `fetchImpl` / `apiKey`.
+     */
+    readonly defaults?: Omit<OpenAiSynthesizerOptions, 'getSecret'>;
+}
+/**
+ * Build the @moxxy/plugin-tts-openai plugin. Registers exactly one synthesizer,
+ * `openai-tts`, backed by OpenAI's `/v1/audio/speech`.
+ *
+ * The plugin is intentionally side-effect free — it never calls `setActive`.
+ * The `SynthesizerRegistry` is `autoAdoptFirst`, so the first synthesizer
+ * registered (this one, on a fresh install) becomes active on read without any
+ * activation step here; the agent switches voices via the `set_voice` tool.
+ */
+export declare function buildOpenAiTtsPlugin(opts?: BuildOpenAiTtsPluginOptions): 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,wBAAwB,EAE9B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,QAAQ,EACR,UAAU,EACV,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAC;AAEzB,kFAAkF;AAClF,eAAO,MAAM,2BAA2B,eAAe,CAAC;AAExD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,WAAW,CAAC,CAAC;CACjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,2BAAgC,GAAG,MAAM,CAoBnF;;AA2BD,wBAAsC"}

package/dist/index.js

@@ -0,0 +1,63 @@
+import { definePlugin, defineSynthesizer } from '@moxxy/sdk';
+import { OpenAiSynthesizer, } from './openai-tts.js';
+export { OpenAiSynthesizer, createOpenAiSynthesizer, capInput, clampSpeed, } from './openai-tts.js';
+/** The single registered synthesizer name — surfaces show this in `set_voice`. */
+export const OPENAI_TTS_SYNTHESIZER_NAME = 'openai-tts';
+/**
+ * Build the @moxxy/plugin-tts-openai plugin. Registers exactly one synthesizer,
+ * `openai-tts`, backed by OpenAI's `/v1/audio/speech`.
+ *
+ * The plugin is intentionally side-effect free — it never calls `setActive`.
+ * The `SynthesizerRegistry` is `autoAdoptFirst`, so the first synthesizer
+ * registered (this one, on a fresh install) becomes active on read without any
+ * activation step here; the agent switches voices via the `set_voice` tool.
+ */
+export function buildOpenAiTtsPlugin(opts = {}) {
+    const defaults = opts.defaults ?? {};
+    return definePlugin({
+        name: '@moxxy/plugin-tts-openai',
+        version: '0.0.0',
+        synthesizers: [
+            defineSynthesizer({
+                name: OPENAI_TTS_SYNTHESIZER_NAME,
+                displayName: 'OpenAI TTS',
+                // `create` runs lazily and may re-run (buildOnRead) — keep it cheap and
+                // side-effect free; the key is resolved inside `synthesize`.
+                create: (ctx) => new OpenAiSynthesizer({
+                    ...defaults,
+                    ...configToOptions(ctx.config),
+                    ...(ctx.getSecret ? { getSecret: ctx.getSecret } : {}),
+                }),
+            }),
+        ],
+    });
+}
+/** Narrow the untrusted per-activation config record into typed options. Only
+ *  string `model` / `voice` / `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.voice === 'string' && config.voice)
+        out.voice = config.voice;
+    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', 'opus', 'wav', 'aac'];
+/** 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 buildOpenAiTtsPlugin();
+//# 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,iBAAiB,GAGlB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,QAAQ,EACR,UAAU,GAIX,MAAM,iBAAiB,CAAC;AAEzB,kFAAkF;AAClF,MAAM,CAAC,MAAM,2BAA2B,GAAG,YAAY,CAAC;AAWxD;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAoC,EAAE;IACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IACrC,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,0BAA0B;QAChC,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE;YACZ,iBAAiB,CAAC;gBAChB,IAAI,EAAE,2BAA2B;gBACjC,WAAW,EAAE,YAAY;gBACzB,wEAAwE;gBACxE,6DAA6D;gBAC7D,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CACd,IAAI,iBAAiB,CAAC;oBACpB,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,GAAsF,EAAE,CAAC;IAClG,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,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,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,GAAmC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEpF;+DAC+D;AAC/D,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,aAAuC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC1F,CAAC,CAAE,KAAyB;QAC5B,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,0EAA0E;AAC1E,eAAe,oBAAoB,EAAE,CAAC"}

package/dist/openai-tts.d.ts

@@ -0,0 +1,76 @@
+import { type Synthesizer, type SynthesizeOptions, type SynthesisResult } from '@moxxy/sdk';
+/** OpenAI `/v1/audio/speech` response formats we expose, mapped to the MIME
+ *  type the desktop/channels play the returned bytes as. Kept a small closed
+ *  map (OpenAI also serves flac/pcm — not surfaced here). */
+declare const MIME_BY_FORMAT: {
+    readonly mp3: "audio/mpeg";
+    readonly opus: "audio/ogg";
+    readonly wav: "audio/wav";
+    readonly aac: "audio/aac";
+};
+export type OpenAiTtsFormat = 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 OpenAiSynthesizerOptions {
+    /** 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.openai.com/v1`. Trailing slashes trimmed. */
+    readonly baseURL?: string;
+    /** TTS model, default `gpt-4o-mini-tts`. */
+    readonly model?: string;
+    /** Default voice, default `alloy`. Overridden per-call by `opts.voice`. */
+    readonly voice?: string;
+    /** Output container, default `mp3`. Determines the returned `mimeType`. */
+    readonly format?: OpenAiTtsFormat;
+    /** Injected `fetch` (tests). Defaults to the global. */
+    readonly fetchImpl?: FetchLike;
+    /** Per-request timeout in ms. Default 60000. */
+    readonly timeoutMs?: number;
+}
+/**
+ * `Synthesizer` backed by OpenAI's `POST /v1/audio/speech` endpoint — one JSON
+ * POST returning raw audio bytes, so there's no need for the `openai` SDK. The
+ * API key rides the vault (`ctx.getSecret('OPENAI_API_KEY')`, the same key the
+ * OpenAI provider uses) with a `process.env.OPENAI_API_KEY` fallback, resolved
+ * lazily on the first `synthesize` and cached so `create()` stays cheap.
+ */
+export declare class OpenAiSynthesizer implements Synthesizer {
+    readonly name = "openai-tts";
+    /** 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 voice;
+    private readonly format;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private key;
+    constructor(opts?: OpenAiSynthesizerOptions);
+    synthesize(text: string, opts?: SynthesizeOptions): Promise<SynthesisResult>;
+    /**
+     * Resolve the API key lazily: explicit option → vault (`OPENAI_API_KEY`) →
+     * `process.env.OPENAI_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;
+}
+/** Map a `SynthesizeOptions.rate` multiplier onto OpenAI's `speed`, clamped to
+ *  the accepted 0.25–4.0 range. Non-finite / absent rates yield `undefined` so
+ *  the field is omitted and OpenAI uses its default. */
+export declare function clampSpeed(rate: number | undefined): number | undefined;
+/**
+ * Cap `text` to OpenAI's 4096-char `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 ≤ 4096 characters.
+ */
+export declare function capInput(text: string): string;
+export declare function createOpenAiSynthesizer(opts?: OpenAiSynthesizerOptions): OpenAiSynthesizer;
+export {};
+//# sourceMappingURL=openai-tts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openai-tts.d.ts","sourceRoot":"","sources":["../src/openai-tts.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAKpB;;6DAE6D;AAC7D,QAAA,MAAM,cAAc;;;;;CAKV,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,cAAc,CAAC;AAe1D;gFACgF;AAChF,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhF,MAAM,WAAW,wBAAwB;IACvC,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,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IACnD,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,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,GAAG,CAAuB;gBAEtB,IAAI,GAAE,wBAA6B;IAYzC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;IA+EtF;;;;;OAKG;YACW,UAAU;CAmBzB;AAED;;wDAEwD;AACxD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGvE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc7C;AAED,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,wBAA6B,GAAG,iBAAiB,CAE9F"}

package/dist/openai-tts.js

@@ -0,0 +1,187 @@
+import { classifyHttpStatus, classifyNetworkError, MoxxyError, } from '@moxxy/sdk';
+/** Provider tag attached to classified errors for logs/debug context. */
+const OPENAI_TTS_PROVIDER_ID = 'openai';
+/** OpenAI `/v1/audio/speech` response formats we expose, mapped to the MIME
+ *  type the desktop/channels play the returned bytes as. Kept a small closed
+ *  map (OpenAI also serves flac/pcm — not surfaced here). */
+const MIME_BY_FORMAT = {
+    mp3: 'audio/mpeg',
+    opus: 'audio/ogg',
+    wav: 'audio/wav',
+    aac: 'audio/aac',
+};
+/** OpenAI rejects `input` longer than 4096 characters. Channels routinely send
+ *  long replies, so we truncate at a sentence boundary rather than let the API
+ *  400 the whole read-aloud. */
+const MAX_INPUT_CHARS = 4096;
+/** OpenAI clamps `speed` to this inclusive range; anything outside 400s. */
+const MIN_SPEED = 0.25;
+const MAX_SPEED = 4.0;
+/** 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 OpenAI's `POST /v1/audio/speech` endpoint — one JSON
+ * POST returning raw audio bytes, so there's no need for the `openai` SDK. The
+ * API key rides the vault (`ctx.getSecret('OPENAI_API_KEY')`, the same key the
+ * OpenAI provider uses) with a `process.env.OPENAI_API_KEY` fallback, resolved
+ * lazily on the first `synthesize` and cached so `create()` stays cheap.
+ */
+export class OpenAiSynthesizer {
+    name = 'openai-tts';
+    /** MIME type of the bytes this instance returns (derived from `format`). */
+    mimeType;
+    explicitKey;
+    getSecret;
+    baseURL;
+    model;
+    voice;
+    format;
+    fetchImpl;
+    timeoutMs;
+    key = null;
+    constructor(opts = {}) {
+        this.explicitKey = opts.apiKey;
+        this.getSecret = opts.getSecret;
+        this.baseURL = (opts.baseURL ?? 'https://api.openai.com/v1').replace(/\/+$/, '');
+        this.model = opts.model ?? 'gpt-4o-mini-tts';
+        this.voice = opts.voice ?? 'alloy';
+        this.format = opts.format ?? 'mp3';
+        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 voice = opts.voice ?? this.voice;
+        const speed = clampSpeed(opts.rate);
+        const body = {
+            model: this.model,
+            voice,
+            input,
+            response_format: this.format,
+            ...(speed !== undefined ? { speed } : {}),
+        };
+        const url = `${this.baseURL}/audio/speech`;
+        // 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: { authorization: `Bearer ${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: `OpenAI text-to-speech request timed out after ${this.timeoutMs} ms.`,
+                    hint: 'Retry, or shorten the text being read aloud.',
+                    context: { provider: OPENAI_TTS_PROVIDER_ID, url },
+                });
+            }
+            const network = classifyNetworkError(err, { provider: OPENAI_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: OPENAI_TTS_PROVIDER_ID,
+                url,
+                body: await res.text().catch(() => ''),
+            });
+            if (classified)
+                throw classified;
+            throw new MoxxyError({
+                code: 'PROVIDER_BAD_REQUEST',
+                message: `OpenAI text-to-speech returned HTTP ${res.status}.`,
+                context: { provider: OPENAI_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 (`OPENAI_API_KEY`) →
+     * `process.env.OPENAI_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?.('OPENAI_API_KEY')) ??
+            process.env.OPENAI_API_KEY ??
+            null;
+        if (!resolved) {
+            throw new MoxxyError({
+                code: 'AUTH_NO_CREDENTIALS',
+                message: 'No OpenAI API key for text-to-speech. It rides the same OPENAI_API_KEY as the OpenAI provider.',
+                hint: 'Run `moxxy init` (stores it in the vault) or set OPENAI_API_KEY.',
+                context: { provider: OPENAI_TTS_PROVIDER_ID },
+            });
+        }
+        this.key = resolved;
+        return resolved;
+    }
+}
+/** Map a `SynthesizeOptions.rate` multiplier onto OpenAI's `speed`, clamped to
+ *  the accepted 0.25–4.0 range. Non-finite / absent rates yield `undefined` so
+ *  the field is omitted and OpenAI uses its default. */
+export function clampSpeed(rate) {
+    if (rate === undefined || !Number.isFinite(rate))
+        return undefined;
+    return Math.min(MAX_SPEED, Math.max(MIN_SPEED, rate));
+}
+/**
+ * Cap `text` to OpenAI's 4096-char `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 ≤ 4096 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 createOpenAiSynthesizer(opts = {}) {
+    return new OpenAiSynthesizer(opts);
+}
+//# sourceMappingURL=openai-tts.js.map

package/dist/openai-tts.js.map

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

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@moxxy/plugin-tts-openai",
+  "version": "0.27.0",
+  "description": "OpenAI text-to-speech Synthesizer for moxxy. Text → spoken audio bytes via POST /v1/audio/speech. Plugs into the session's SynthesizerRegistry; read-aloud surfaces (desktop 'Read aloud', a voice channel) consume it transparently. The first shipped Synthesizer backend.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "tts",
+    "text-to-speech",
+    "openai",
+    "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-openai"
+  },
+  "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": "OpenAI text-to-speech",
+      "description": "Read-aloud through OpenAI's /v1/audio/speech. Uses the same OPENAI_API_KEY as the OpenAI provider — if you already added that (via `moxxy init` or the OpenAI provider), you can skip this; leave it blank to reuse the existing key.",
+      "fields": [
+        {
+          "key": "apiKey",
+          "label": "OpenAI API key",
+          "kind": "secret",
+          "vaultKey": "OPENAI_API_KEY",
+          "required": false,
+          "placeholder": "sk-…",
+          "description": "Reuses the OpenAI provider key. Only needed if you haven't already stored OPENAI_API_KEY."
+        }
+      ]
+    }
+  },
+  "dependencies": {
+    "@moxxy/sdk": "0.27.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/index.ts

@@ -0,0 +1,86 @@
+import { definePlugin, defineSynthesizer, type Plugin } from '@moxxy/sdk';
+import {
+  OpenAiSynthesizer,
+  type OpenAiSynthesizerOptions,
+  type OpenAiTtsFormat,
+} from './openai-tts.js';
+
+export {
+  OpenAiSynthesizer,
+  createOpenAiSynthesizer,
+  capInput,
+  clampSpeed,
+  type OpenAiSynthesizerOptions,
+  type OpenAiTtsFormat,
+  type FetchLike,
+} from './openai-tts.js';
+
+/** The single registered synthesizer name — surfaces show this in `set_voice`. */
+export const OPENAI_TTS_SYNTHESIZER_NAME = 'openai-tts';
+
+export interface BuildOpenAiTtsPluginOptions {
+  /**
+   * Build-time defaults baked into the synthesizer def. Per-activation config
+   * (`session.synthesizers.setActive(name, config)`) still overrides `model` /
+   * `voice` / `format`. Mainly a seam for tests to inject `fetchImpl` / `apiKey`.
+   */
+  readonly defaults?: Omit<OpenAiSynthesizerOptions, 'getSecret'>;
+}
+
+/**
+ * Build the @moxxy/plugin-tts-openai plugin. Registers exactly one synthesizer,
+ * `openai-tts`, backed by OpenAI's `/v1/audio/speech`.
+ *
+ * The plugin is intentionally side-effect free — it never calls `setActive`.
+ * The `SynthesizerRegistry` is `autoAdoptFirst`, so the first synthesizer
+ * registered (this one, on a fresh install) becomes active on read without any
+ * activation step here; the agent switches voices via the `set_voice` tool.
+ */
+export function buildOpenAiTtsPlugin(opts: BuildOpenAiTtsPluginOptions = {}): Plugin {
+  const defaults = opts.defaults ?? {};
+  return definePlugin({
+    name: '@moxxy/plugin-tts-openai',
+    version: '0.0.0',
+    synthesizers: [
+      defineSynthesizer({
+        name: OPENAI_TTS_SYNTHESIZER_NAME,
+        displayName: 'OpenAI TTS',
+        // `create` runs lazily and may re-run (buildOnRead) — keep it cheap and
+        // side-effect free; the key is resolved inside `synthesize`.
+        create: (ctx) =>
+          new OpenAiSynthesizer({
+            ...defaults,
+            ...configToOptions(ctx.config),
+            ...(ctx.getSecret ? { getSecret: ctx.getSecret } : {}),
+          }),
+      }),
+    ],
+  });
+}
+
+/** Narrow the untrusted per-activation config record into typed options. Only
+ *  string `model` / `voice` / `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<OpenAiSynthesizerOptions> {
+  const out: { -readonly [K in keyof OpenAiSynthesizerOptions]?: OpenAiSynthesizerOptions[K] } = {};
+  if (typeof config.model === 'string' && config.model) out.model = config.model;
+  if (typeof config.voice === 'string' && config.voice) out.voice = config.voice;
+  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<OpenAiTtsFormat> = ['mp3', 'opus', 'wav', 'aac'];
+
+/** Accept only the exact supported format strings (guards against inherited
+ *  keys like `constructor` slipping through an `in` check). */
+function normalizeFormat(value: unknown): OpenAiTtsFormat | undefined {
+  return typeof value === 'string' && (KNOWN_FORMATS as ReadonlyArray<string>).includes(value)
+    ? (value as OpenAiTtsFormat)
+    : undefined;
+}
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default buildOpenAiTtsPlugin();

package/src/openai-tts.test.ts

@@ -0,0 +1,269 @@
+import { describe, expect, it } from 'vitest';
+import { OpenAiSynthesizer, capInput, clampSpeed, type FetchLike } from './openai-tts.js';
+import { buildOpenAiTtsPlugin, OPENAI_TTS_SYNTHESIZER_NAME } from './index.js';
+
+interface Captured {
+  url: string;
+  init: RequestInit;
+}
+
+/** 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('OpenAiSynthesizer.synthesize', () => {
+  it('returns audio bytes and the mp3 mimeType by default', async () => {
+    const { fetchImpl, calls } = okFetch(new Uint8Array([9, 8, 7]));
+    const synth = new OpenAiSynthesizer({ 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.openai.com/v1/audio/speech');
+    expect(calls[0]!.init.method).toBe('POST');
+    const headers = calls[0]!.init.headers as Record<string, string>;
+    expect(headers.authorization).toBe('Bearer sk-test');
+    expect(headers['content-type']).toBe('application/json');
+    const body = bodyOf(calls);
+    expect(body.model).toBe('gpt-4o-mini-tts');
+    expect(body.voice).toBe('alloy');
+    expect(body.input).toBe('hello world');
+    expect(body.response_format).toBe('mp3');
+    expect(body.speed).toBeUndefined();
+  });
+
+  it.each([
+    ['mp3', 'audio/mpeg'],
+    ['opus', 'audio/ogg'],
+    ['wav', 'audio/wav'],
+    ['aac', 'audio/aac'],
+  ] as const)('maps format %s to mimeType %s', async (format, mimeType) => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new OpenAiSynthesizer({ apiKey: 'sk-test', fetchImpl, format });
+    const out = await synth.synthesize('hi');
+    expect(out.mimeType).toBe(mimeType);
+    expect(bodyOf(calls).response_format).toBe(format);
+  });
+
+  it('lets opts.voice override the configured voice', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new OpenAiSynthesizer({ apiKey: 'sk-test', fetchImpl, voice: 'alloy' });
+    await synth.synthesize('hi', { voice: 'nova' });
+    expect(bodyOf(calls).voice).toBe('nova');
+  });
+
+  it('maps rate to speed', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new OpenAiSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    await synth.synthesize('hi', { rate: 1.5 });
+    expect(bodyOf(calls).speed).toBe(1.5);
+  });
+
+  it.each([
+    [10, 4.0],
+    [0.01, 0.25],
+    [Number.NaN, undefined],
+  ])('clamps rate %s to speed %s', async (rate, expected) => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new OpenAiSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    await synth.synthesize('hi', { rate });
+    expect(bodyOf(calls).speed).toBe(expected);
+  });
+
+  it('truncates input over 4096 chars at a sentence boundary with an ellipsis', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new OpenAiSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    // 'a'*4000 + '. ' then more — the sentence boundary at index 4000 is the
+    // last one inside the 4095-char budget.
+    const long = `${'a'.repeat(4000)}. ${'b'.repeat(200)}. ${'c'.repeat(200)}`;
+    await synth.synthesize(long);
+    const input = bodyOf(calls).input as string;
+    expect(input.length).toBeLessThanOrEqual(4096);
+    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 OpenAiSynthesizer({ apiKey: 'sk-test', fetchImpl });
+    await synth.synthesize('a short reply.');
+    expect(bodyOf(calls).input).toBe('a short reply.');
+  });
+
+  it('throws AUTH_NO_CREDENTIALS when no key is available anywhere', async () => {
+    const prev = process.env.OPENAI_API_KEY;
+    delete process.env.OPENAI_API_KEY;
+    try {
+      const { fetchImpl } = okFetch();
+      const synth = new OpenAiSynthesizer({ getSecret: async () => null, fetchImpl });
+      await expect(synth.synthesize('hi')).rejects.toMatchObject({
+        code: 'AUTH_NO_CREDENTIALS',
+      });
+    } finally {
+      if (prev !== undefined) process.env.OPENAI_API_KEY = prev;
+    }
+  });
+
+  it('reads the key from getSecret (OPENAI_API_KEY) when no explicit key', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const synth = new OpenAiSynthesizer({
+      getSecret: async (name) => (name === 'OPENAI_API_KEY' ? 'sk-vault' : null),
+      fetchImpl,
+    });
+    await synth.synthesize('hi');
+    const headers = calls[0]!.init.headers as Record<string, string>;
+    expect(headers.authorization).toBe('Bearer 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 OpenAiSynthesizer({ 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 OpenAiSynthesizer({ 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 OpenAiSynthesizer({ 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 OpenAiSynthesizer({ 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 OpenAiSynthesizer({ 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 OpenAiSynthesizer({
+      apiKey: 'sk-test',
+      fetchImpl: abortAwareFetch,
+      timeoutMs: 10,
+    });
+    await expect(synth.synthesize('hi')).rejects.toMatchObject({ code: 'NETWORK_TIMEOUT' });
+  });
+});
+
+describe('capInput / clampSpeed helpers', () => {
+  it('capInput passes through under the limit', () => {
+    expect(capInput('short')).toBe('short');
+    expect(capInput('a'.repeat(4096))).toBe('a'.repeat(4096));
+  });
+
+  it('capInput hard-slices a single boundary-less sentence', () => {
+    const out = capInput('x'.repeat(5000));
+    expect(out.length).toBe(4096); // 4095 chars + the ellipsis
+    expect(out.endsWith('…')).toBe(true);
+  });
+
+  it('clampSpeed clamps and drops non-finite', () => {
+    expect(clampSpeed(undefined)).toBeUndefined();
+    expect(clampSpeed(Number.POSITIVE_INFINITY)).toBeUndefined();
+    expect(clampSpeed(1)).toBe(1);
+    expect(clampSpeed(9)).toBe(4);
+    expect(clampSpeed(0)).toBe(0.25);
+  });
+});
+
+describe('buildOpenAiTtsPlugin', () => {
+  it('registers exactly one synthesizer named openai-tts', () => {
+    const plugin = buildOpenAiTtsPlugin();
+    expect(plugin.synthesizers).toHaveLength(1);
+    const def = plugin.synthesizers![0]!;
+    expect(def.name).toBe(OPENAI_TTS_SYNTHESIZER_NAME);
+    expect(def.displayName).toBe('OpenAI TTS');
+  });
+
+  it('create() yields a synthesizer whose config voice/format flow through', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const plugin = buildOpenAiTtsPlugin({ defaults: { fetchImpl, apiKey: 'sk-test' } });
+    const def = plugin.synthesizers![0]!;
+    const inst = def.create({ config: { voice: 'nova', format: 'opus' } });
+    expect(inst.name).toBe('openai-tts');
+    const out = await inst.synthesize('hi');
+    expect(out.mimeType).toBe('audio/ogg');
+    expect(bodyOf(calls).voice).toBe('nova');
+  });
+
+  it('create() wires ctx.getSecret through for key resolution', async () => {
+    const { fetchImpl, calls } = okFetch();
+    const plugin = buildOpenAiTtsPlugin({ defaults: { fetchImpl } });
+    const def = plugin.synthesizers![0]!;
+    const inst = def.create({
+      config: {},
+      getSecret: async (name) => (name === 'OPENAI_API_KEY' ? 'sk-ctx' : null),
+    });
+    await inst.synthesize('hi');
+    const headers = calls[0]!.init.headers as Record<string, string>;
+    expect(headers.authorization).toBe('Bearer sk-ctx');
+  });
+
+  it('create() ignores an unknown config format', async () => {
+    const { fetchImpl } = okFetch();
+    const plugin = buildOpenAiTtsPlugin({ defaults: { fetchImpl, apiKey: 'sk-test' } });
+    const inst = plugin.synthesizers![0]!.create({ config: { format: 'flac' } });
+    const out = await inst.synthesize('hi');
+    // Unknown format ignored → default mp3.
+    expect(out.mimeType).toBe('audio/mpeg');
+  });
+});

package/src/openai-tts.ts

@@ -0,0 +1,233 @@
+import {
+  classifyHttpStatus,
+  classifyNetworkError,
+  MoxxyError,
+  type Synthesizer,
+  type SynthesizeOptions,
+  type SynthesisResult,
+} from '@moxxy/sdk';
+
+/** Provider tag attached to classified errors for logs/debug context. */
+const OPENAI_TTS_PROVIDER_ID = 'openai';
+
+/** OpenAI `/v1/audio/speech` response formats we expose, mapped to the MIME
+ *  type the desktop/channels play the returned bytes as. Kept a small closed
+ *  map (OpenAI also serves flac/pcm — not surfaced here). */
+const MIME_BY_FORMAT = {
+  mp3: 'audio/mpeg',
+  opus: 'audio/ogg',
+  wav: 'audio/wav',
+  aac: 'audio/aac',
+} as const;
+
+export type OpenAiTtsFormat = keyof typeof MIME_BY_FORMAT;
+
+/** OpenAI rejects `input` longer than 4096 characters. Channels routinely send
+ *  long replies, so we truncate at a sentence boundary rather than let the API
+ *  400 the whole read-aloud. */
+const MAX_INPUT_CHARS = 4096;
+
+/** OpenAI clamps `speed` to this inclusive range; anything outside 400s. */
+const MIN_SPEED = 0.25;
+const MAX_SPEED = 4.0;
+
+/** 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 OpenAiSynthesizerOptions {
+  /** 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.openai.com/v1`. Trailing slashes trimmed. */
+  readonly baseURL?: string;
+  /** TTS model, default `gpt-4o-mini-tts`. */
+  readonly model?: string;
+  /** Default voice, default `alloy`. Overridden per-call by `opts.voice`. */
+  readonly voice?: string;
+  /** Output container, default `mp3`. Determines the returned `mimeType`. */
+  readonly format?: OpenAiTtsFormat;
+  /** Injected `fetch` (tests). Defaults to the global. */
+  readonly fetchImpl?: FetchLike;
+  /** Per-request timeout in ms. Default 60000. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * `Synthesizer` backed by OpenAI's `POST /v1/audio/speech` endpoint — one JSON
+ * POST returning raw audio bytes, so there's no need for the `openai` SDK. The
+ * API key rides the vault (`ctx.getSecret('OPENAI_API_KEY')`, the same key the
+ * OpenAI provider uses) with a `process.env.OPENAI_API_KEY` fallback, resolved
+ * lazily on the first `synthesize` and cached so `create()` stays cheap.
+ */
+export class OpenAiSynthesizer implements Synthesizer {
+  readonly name = 'openai-tts';
+  /** 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 voice: string;
+  private readonly format: OpenAiTtsFormat;
+  private readonly fetchImpl: FetchLike;
+  private readonly timeoutMs: number;
+  private key: string | null = null;
+
+  constructor(opts: OpenAiSynthesizerOptions = {}) {
+    this.explicitKey = opts.apiKey;
+    this.getSecret = opts.getSecret;
+    this.baseURL = (opts.baseURL ?? 'https://api.openai.com/v1').replace(/\/+$/, '');
+    this.model = opts.model ?? 'gpt-4o-mini-tts';
+    this.voice = opts.voice ?? 'alloy';
+    this.format = opts.format ?? 'mp3';
+    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 voice = opts.voice ?? this.voice;
+    const speed = clampSpeed(opts.rate);
+    const body = {
+      model: this.model,
+      voice,
+      input,
+      response_format: this.format,
+      ...(speed !== undefined ? { speed } : {}),
+    };
+    const url = `${this.baseURL}/audio/speech`;
+
+    // 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: { authorization: `Bearer ${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: `OpenAI text-to-speech request timed out after ${this.timeoutMs} ms.`,
+          hint: 'Retry, or shorten the text being read aloud.',
+          context: { provider: OPENAI_TTS_PROVIDER_ID, url },
+        });
+      }
+      const network = classifyNetworkError(err, { provider: OPENAI_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: OPENAI_TTS_PROVIDER_ID,
+        url,
+        body: await res.text().catch(() => ''),
+      });
+      if (classified) throw classified;
+      throw new MoxxyError({
+        code: 'PROVIDER_BAD_REQUEST',
+        message: `OpenAI text-to-speech returned HTTP ${res.status}.`,
+        context: { provider: OPENAI_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 (`OPENAI_API_KEY`) →
+   * `process.env.OPENAI_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?.('OPENAI_API_KEY')) ??
+      process.env.OPENAI_API_KEY ??
+      null;
+    if (!resolved) {
+      throw new MoxxyError({
+        code: 'AUTH_NO_CREDENTIALS',
+        message:
+          'No OpenAI API key for text-to-speech. It rides the same OPENAI_API_KEY as the OpenAI provider.',
+        hint: 'Run `moxxy init` (stores it in the vault) or set OPENAI_API_KEY.',
+        context: { provider: OPENAI_TTS_PROVIDER_ID },
+      });
+    }
+    this.key = resolved;
+    return resolved;
+  }
+}
+
+/** Map a `SynthesizeOptions.rate` multiplier onto OpenAI's `speed`, clamped to
+ *  the accepted 0.25–4.0 range. Non-finite / absent rates yield `undefined` so
+ *  the field is omitted and OpenAI uses its default. */
+export function clampSpeed(rate: number | undefined): number | undefined {
+  if (rate === undefined || !Number.isFinite(rate)) return undefined;
+  return Math.min(MAX_SPEED, Math.max(MIN_SPEED, rate));
+}
+
+/**
+ * Cap `text` to OpenAI's 4096-char `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 ≤ 4096 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 createOpenAiSynthesizer(opts: OpenAiSynthesizerOptions = {}): OpenAiSynthesizer {
+  return new OpenAiSynthesizer(opts);
+}