osdy-pi 1.11.17 → 1.11.18

package/README.md

@@ -8,7 +8,7 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 
 **Audio notifications share a bundled 180 ms default sound on macOS and Windows**, with a persistent master mute in `/osdyConfig` → **Sounds**. Custom paths take precedence: startup flag → saved global path → bundled default. Muting preserves those paths and visual alerts; explicit **Test effective** still plays while muted. See [Audio notifications](#audio-notifications).
 
-**Local response narration is opt-in on macOS**: `/osdyConfig` → **Speech** offers a one-line installed-voice selector and explicit previews without saving or enabling narration. Stop from chat with **Ctrl+Option+S** or `/osdy-pi speech stop`. Speech stays independent of notification sounds and their mute. See [Response speech](#response-speech).
+**Local response narration is opt-in on macOS**: `/osdyConfig` → **Speech** offers a one-line selector for installed macOS voices and optional local Kokoro voices, with explicit previews without saving or enabling narration. Stop from chat with **Ctrl+Option+S** or `/osdy-pi speech stop`. Speech stays independent of notification sounds and their mute. See [Response speech](#response-speech).
 
 **The Control Center consolidates Osdy controls in `/osdyConfig`**: eleven categories cover appearance, Git, sounds, accounts, usage, TODO/Agents provider settings, and opt-in response speech. Account quota previews query a selected stored Codex profile without switching it. The header shows the installed Osdy package version when it fits; constrained layouts show only the centered mascot. See [Control Center in Pi](#control-center-in-pi) for confirmation and persistence boundaries.
 
@@ -19,7 +19,7 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 | Area | What ships |
 | --- | --- |
 | Control Center | **Ctrl+Option+O** or `/osdyConfig` opens eleven categories, including confirmed TODO/Agents provider selection, explicit per-profile Codex quota previews, and Speech. |
-| Speech | Default-off local macOS narration, one saved installed voice, explicit draft previews, and chat-accessible Stop. |
+| Speech | Default-off local macOS narration, optional Spanish Kokoro voices, one saved voice, explicit draft previews, and chat-accessible Stop. |
 | Audio | Shared bundled default, per-event custom paths, and persistent automatic-audio mute; [explicit tests remain available](#audio-notifications). |
 | Local analytics (1.10.0) | `/osdy-usage` opens Summary, Profiles, Models, and History pages for recorded tokens and estimated cost—not billing or subscription quota. |
 | Themes introduced in 1.11.0 | Spider-Man Classic, Miles Morales, and Spider-Verse add three distinct dark palettes. |
@@ -590,13 +590,31 @@ From chat, press **Ctrl+Option+S** on macOS (**Ctrl+Alt+S** elsewhere) for the s
 
 Open **`/osdyConfig` → Speech** (the last category) to enable/disable narration, read the last response, stop playback, or select a voice:
 
-1. Use **↑/↓** to reach the single **Voice: ‹ … ›** row. **←/→** browses installed voices, wrapping at both ends. The row marks the draft **saved** or **unsaved**; the summary always identifies the saved voice. Browsing never saves or plays audio.
-2. Select **Preview voice** and press **Enter** to hear a fixed short English sample in the draft voice, independent of the last response. Preview does **not** save the draft or enable narration, and works while narration is disabled. It may replace current playback. Leaving Speech or closing the panel cancels only its preview, not unrelated narration.
+1. Use **↑/↓** to reach the single **Voice: ‹ … ›** row. **←/→** browses installed macOS voices and **Kokoro Dora / Kokoro Alex / Kokoro Santa**, wrapping at both ends. The row marks the draft **saved** or **unsaved**; the summary always identifies the saved voice. Browsing never saves or plays audio.
+2. Select **Preview voice** and press **Enter** to hear a fixed Spanish sample for Kokoro or the existing fixed English sample for native voices, independent of the last response. Preview does **not** save the draft or enable narration, and works while narration is disabled. It may replace current playback. Leaving Speech or closing the panel cancels only its preview, not unrelated narration.
 3. Return to **Voice** and press **Enter** to save the draft for subsequent narration. Preview, other controls, and failed saves preserve the draft. **Read last response** uses the saved voice, not an unsaved draft. Saving never plays audio, enables narration, or changes already-playing audio.
 
 Opening Speech starts at the playback controls; **Home** returns there, **Tab** returns to categories, and arrows outside the Voice row retain normal pane focus behavior. The feminine Paulina voice remains the default until you save another voice.
 
-The panel shows enabled/saved-voice/rate state and offers supported voices already installed on the Pi host; it does not download voices. Empty/unavailable voice lists leave narration controls accessible. Rate tuning is not exposed. Selection saves globally in the independent `<agent-dir>/extensions/osdy-pi/speech.json` store and survives reload/restart; **Sounds mute and event notifications are unchanged and independent**.
+The panel shows enabled/saved-voice/rate state. Native speech uses supported voices already installed on the Pi host and needs no server or model download. Optional **Kokoro** needs a separately started local MLX-Audio server and an explicitly downloaded model; listing or saving a voice does not download anything. See [local Kokoro setup](docs/kokoro.md) for prerequisites and validation status. The extension never installs dependencies or starts the server automatically. Empty/unavailable voice lists leave narration controls accessible. Rate tuning is not exposed; the existing wpm display maps to Kokoro speed as **rate / 180**, not a guarantee of identical spoken wpm. Selection saves globally in the independent `<agent-dir>/extensions/osdy-pi/speech.json` store and survives reload/restart; **Sounds mute and event notifications are unchanged and independent**.
+
+### Optional Kokoro voices
+
+On Apple Silicon Macs, the same selector includes three local Spanish voices:
+
+| Voice | Preset |
+| --- | --- |
+| **Kokoro Dora** | Feminine, `ef_dora` |
+| **Kokoro Alex** | Masculine, `em_alex` |
+| **Kokoro Santa** | Masculine, `em_santa` |
+
+Follow [the Kokoro setup and startup guide](docs/kokoro.md) to prepare the isolated Python environment, explicitly download the free model, and start MLX-Audio on **`http://127.0.0.1:8000`**. Keep that service running while using Kokoro: the extension does **not** start it automatically. A preview reporting **`Kokoro synthesis failed`** can mean the server is stopped; check the service and the optional `OSDY_PI_KOKORO_URL` loopback origin before reinstalling anything. Native voices do not need this service.
+
+After starting it, browse to a Kokoro voice and use **Preview voice** to listen without changing your saved voice or enabling narration. Save only when you want subsequent narration to use that voice. Generation is local, but the complete WAV is produced before playback; this is not streamed narration. Initial model loading is slower than warm requests.
+
+**Known limit:** long Spanish responses may be truncated by the current upstream phonemizer. Osdy normalizes newlines, so adding line breaks is not a workaround in this integration. Prefer an installed native voice for long responses until chunking/completeness is evaluated. The [guide](docs/kokoro.md#observed-local-synthesis) records tested versions and short-sample measurements; these are not quality or latency guarantees.
+
+### Narration lifecycle and compatibility
 
 Automatic narration waits for final settlement, including retries, compaction, and queued continuations—not every message or intermediate agent end. Only successful final text is read, omitting fenced code, tools, thinking, and Markdown noise. Cancelled, failed, empty, and tool-only newest responses never fall back to older text automatically. Explicit replay retains the last successful response only in memory for this session; switching sessions, reload, and shutdown clear it. New input/runs stop narration, and queued follow-ups remain eligible once their final response settles. Explicit **Stop** also cancels pending starts and suppresses automatic narration for the rest of that run; explicit replay remains available when idle. Cancelling post-run compaction discards that run's pending response. Speech launch never waits for the full spoken playback in an agent lifecycle handler.
 

package/docs/kokoro.md

@@ -0,0 +1,91 @@
+# Optional local Spanish speech with Kokoro
+
+Kokoro adds **Kokoro Dora**, **Kokoro Alex**, and **Kokoro Santa** to the existing Speech selector. Native macOS speech remains the default: **Paulina**, narration **off**, **180 wpm**. Native voices never need a server. Kokoro uses a free local model, not cloud speech or voice cloning; initial playback support is macOS only.
+
+## Quick path
+
+1. On an Apple Silicon Mac, explicitly prepare the isolated Python environment below and start the local MLX-Audio service in a separate terminal.
+2. In Pi, open **`/osdyConfig` → Speech → Voice**, browse with **←/→**, then choose **Preview voice**. Kokoro previews use a fixed Spanish sample; native voices retain their fixed English sample. Preview uses the unsaved draft without saving it or enabling narration.
+3. Return to **Voice** and press **Enter** to save the draft. **Read last response** uses the saved voice even while narration is disabled. Enable automatic narration only if wanted.
+4. Use **Stop**, **Ctrl+Option+S** from chat, or **`/osdy-pi speech stop`** to cancel pending synthesis or playback. If the terminal cannot deliver the shortcut, use the command. Leaving Speech or closing its panel stops only its preview, not unrelated narration.
+
+## Explicit environment setup
+
+Prerequisites: an **Apple Silicon Mac** and **uv**. The example explicitly downloads a managed Python 3.11 interpreter inside the project rather than installing Python packages globally. No npm runtime dependency is added.
+
+The isolated environment was prepared successfully on an **M3 Pro / 18 GiB RAM** with **Python 3.11.15**, **MLX-Audio 0.5.9**, **Misaki 0.9.4**, and **espeakng-loader 0.2.4**. A Spanish `EspeakG2P(language="es")` probe returned phonemes successfully. `espeakng-loader` supplies the native library used by Misaki in this setup; no separate global Homebrew install was needed. All three Spanish voices also produced valid 24 kHz mono WAV through the local HTTP server. Audible playback and subjective listening quality were not evaluated.
+
+Run from the project root. These environment variables must also be set in every terminal that runs setup, model download, or the server:
+
+```bash
+export KOKORO_HOME="$PWD/.pi-dev/kokoro"
+export UV_CACHE_DIR="$KOKORO_HOME/cache/uv"
+export UV_PYTHON_INSTALL_DIR="$KOKORO_HOME/python"
+export HF_HOME="$KOKORO_HOME/cache/huggingface"
+export HF_HUB_CACHE="$HF_HOME/hub"
+export HUGGINGFACE_HUB_CACHE="$HF_HUB_CACHE"
+export XDG_CACHE_HOME="$KOKORO_HOME/cache/xdg"
+export PIP_CACHE_DIR="$KOKORO_HOME/cache/pip"
+export TORCH_HOME="$KOKORO_HOME/cache/torch"
+export NUMBA_CACHE_DIR="$KOKORO_HOME/cache/numba"
+export MPLCONFIGDIR="$KOKORO_HOME/cache/matplotlib"
+export PYTHONPYCACHEPREFIX="$KOKORO_HOME/cache/pycache"
+export HF_HUB_DISABLE_TELEMETRY=1
+mkdir -p "$KOKORO_HOME"
+uv --no-config venv --managed-python --python 3.11 "$KOKORO_HOME/venv"
+uv --no-config pip install --python "$KOKORO_HOME/venv/bin/python" \
+  'mlx-audio[server,tts]==0.5.9' 'misaki[en]==0.9.4' \
+  'espeakng-loader==0.2.4' soundfile
+# Explicitly download before playback: a first download can exceed the request timeout.
+"$KOKORO_HOME/venv/bin/python" -c \
+  'from huggingface_hub import snapshot_download; snapshot_download("mlx-community/Kokoro-82M-bf16")'
+```
+
+The managed interpreter, virtualenv, package caches, and model cache are explicitly project-contained. If you prefer an existing Python 3.10+ interpreter, omit `--managed-python` and supply its path to `--python`. Do not silently fall back to a global package environment. Keep any additional dependency caches project-local too.
+
+### Start the server separately
+
+With the same environment variables, start the server. These bind flags were exercised successfully with MLX-Audio 0.5.9; inspect `--help` when changing versions:
+
+```bash
+"$KOKORO_HOME/venv/bin/python" -m mlx_audio.server --help
+"$KOKORO_HOME/venv/bin/python" -m mlx_audio.server --host 127.0.0.1 --port 8000
+```
+
+Bind only to **127.0.0.1:8000**, never `0.0.0.0` or a LAN address. Leave the process running to keep the model warm. Model files are downloaded only during explicit model setup or the first explicit Kokoro request, not by catalog browsing, selection, or native speech. The extension never installs Python packages, downloads models on startup, or launches the server automatically. Dependency/model setup can require internet access; synthesis sends response text only to the local service. Use a trusted local service that does not forward or log sensitive text.
+
+## Integration contract
+
+| Setting | Fixed behavior |
+| --- | --- |
+| Default origin | `http://127.0.0.1:8000` |
+| Optional override | `OSDY_PI_KOKORO_URL`, set in Pi's launch environment |
+| Allowed origins | HTTP with literal `127.0.0.1` or `[::1]` only; optional port, no path beyond `/`, credentials, query, or fragment. Hostnames including `localhost` are not accepted. Redirects are never followed. |
+| Model | `mlx-community/Kokoro-82M-bf16` |
+| Voices | `Kokoro Dora` → `ef_dora`; `Kokoro Alex` → `em_alex`; `Kokoro Santa` → `em_santa` |
+| Language / format | Spanish `lang_code: "e"`; complete WAV generated before playback |
+| Rate | Existing wpm setting mapped to bounded Kokoro `speed = rate / 180`; 180 maps to 1.0, not a measured words-per-minute promise |
+| Settings | Existing v1 voice-name setting; no new engine selector, command grammar, or migration |
+
+This is **not audio streaming**. Automatic speech waits for the successful settled final assistant response; it does not speak unfinished responses, thinking, tools, or fenced code. The first cold request may include model download/loading and be much slower than warm synthesis. Long responses also wait for the full WAV before playback; no latency or quality target is established here.
+
+## Failures and verification
+
+An unavailable server, missing Spanish dependency, rejected origin, synthesis failure, or playback failure is an error—not permission to silently substitute a native voice. Explicit playback reports failure; automatic speech failures do not interrupt the agent. Choose an installed native voice explicitly if you want to continue without Kokoro. Speech remains independent of Sounds mute.
+
+### Observed local synthesis
+
+An isolated MLX-Audio 0.5.9 server on an M3 Pro / 18 GiB generated the same short Spanish sample through `/v1/audio/speech` with the fixed model/language/WAV contract:
+
+| Request | Complete WAV generation | Audio duration |
+| --- | --- | --- |
+| Dora, first inference after download | 5.664 s | 4.350 s |
+| Dora, same sample with warm model | 0.268 s | 4.350 s |
+| Alex | 1.176 s | 4.325 s |
+| Santa | 1.123 s | 4.325 s |
+
+The one-time model download took about 291 seconds. These are short-sample measurements, not general latency guarantees or time-to-first-stream benchmarks. Generated WAVs were validated without playing sound; no subjective naturalness or accent ranking is established. Automated tests and independent public-interface probes passed for request cancellation, native independence, selector drafts and settings preservation. The independent check also exercised a real filesystem and a harmless child process: private directory/file modes were 0700/0600, Stop terminated the process, and WAV cleanup waited for child close. No audible player was invoked.
+
+**Long Spanish responses are not yet validated.** MLX-Audio's Spanish phonemizer warns: `Chunking logic not yet implemented, so long texts may be truncated unless you split them with '\n'.` Osdy currently normalizes newlines before synthesis, so adding newlines to a response is not an app-level workaround. Prefer a native voice for long responses until Kokoro chunking/completeness is evaluated. Listening quality, audible-device playback, physical shortcut delivery, clean-machine installation and installed-package execution remain unverified.
+
+Primary references: [MLX-Audio server and TTS guidance](https://github.com/Blaizzy/mlx-audio) and [Kokoro-82M model/language documentation](https://huggingface.co/hexgrad/Kokoro-82M).

package/extensions/osdy-pi/control-center-speech.test.ts

@@ -52,6 +52,28 @@ void test("Speech displays enabled/voice/rate and routes only Enable/Disable, Re
 	assert.deepEqual(actions, ["on", "off", "last", "stop"]);
 	panel.dispose();
 });
+void test("Speech explains native and optional Kokoro previews without adding controls", async () => {
+ const previews: string[] = [];
+ const speech = createControlCenterSpeech({
+  settings: () => Promise.resolve({ version: 1, enabled: false, voice: "Paulina", rate: 180 }),
+  voices: () => Promise.resolve(["Paulina", "Kokoro Dora"]),
+  selectVoice: () => { throw new Error("must not save while browsing or previewing"); },
+  previewVoice: voice => { previews.push(voice); return Promise.resolve({ failed: false, message: "Preview started" }); },
+  stopPreview: () => {}, command: () => { throw new Error("must not enable narration"); },
+ }, {} as ExtensionContext);
+ const initial = await speech.read();
+ assert.match(initial.note, /installed macOS voices/);
+ assert.match(initial.note, /optional Kokoro.*local server/i);
+ assert.equal(initial.rows.length, 5);
+ const draft = speech.moveVoice(1)!;
+ assert.match(draft.summary, /disabled.*Paulina.*180 wpm/);
+ assert.deepEqual(draft.rows[3]?.action, { kind: "speech-voice", voice: "Kokoro Dora" });
+ assert.deepEqual(draft.rows[4]?.action, { kind: "speech-preview", voice: "Kokoro Dora" });
+ assert.match(draft.rows[4]?.details?.join(" ") ?? "", /Spanish.*Kokoro.*English.*native/);
+ await speech.apply({ kind: "speech-preview", voice: "Kokoro Dora" });
+ assert.deepEqual(previews, ["Kokoro Dora"]);
+ assert.match((await speech.read()).rows[3]!.label, /Kokoro Dora.*unsaved/);
+});
 void test("Stale Control Center speech actions cannot launch in a replaced session", async () => {
 	let calls = 0;
 	const speech = createControlCenterSpeech({

package/extensions/osdy-pi/control-center-speech.ts

@@ -22,12 +22,12 @@ export function createControlCenterSpeech(speech: ResponseSpeech, ctx: Extension
 	let voices: readonly string[] = [];
 	let savedVoice: string | undefined;
 	let draft: string | undefined;
-	let voiceNote = "No installed voices available.";
+	let voiceNote = "No voices available.";
 	const project = (): ControlCenterDetail => {
 		if (!settings) return { summary: "Speech unavailable", note: voiceNote, rows: [] };
 		return {
 			summary: `Speech: ${settings.enabled ? "enabled" : "disabled"} · Saved voice: ${settings.voice} · Rate: ${settings.rate} wpm`,
-			note: `Local macOS speech; independent of Sounds mute. Read last response uses the saved voice while disabled. ${voiceNote}`,
+			note: `Local speech: installed macOS voices or optional Kokoro (requires a separately started local server). Independent of Sounds mute. Read last response uses the saved voice while disabled. ${voiceNote}`,
 			rows: [
 				{ label: settings.enabled ? "Disable" : "Enable", current: false, action: { kind: "speech-enabled", value: !settings.enabled } },
 				{ label: "Read last response", current: false, action: { kind: "speech-last" } },
@@ -37,7 +37,7 @@ export function createControlCenterSpeech(speech: ResponseSpeech, ctx: Extension
 						action: { kind: "speech-voice" as const, voice: draft }, speechSelector: true,
 						details: ["←/→ browse draft (wraps); Enter saves. Browsing and saving never play audio.", `Saved voice: ${settings.voice}. Preview voice explicitly plays the draft without saving.`] },
 					{ label: "Preview voice", current: false, action: { kind: "speech-preview" as const, voice: draft },
-						details: ["Play a fixed short English sample of the draft voice; does not save or enable narration."] },
+						details: ["Play a fixed sample: Spanish for Kokoro, English for native voices; does not save or enable narration."] },
 				]),
 			],
 		};
@@ -46,7 +46,7 @@ export function createControlCenterSpeech(speech: ResponseSpeech, ctx: Extension
 		async read() {
 			const nextSettings = await speech.settings();
 			let nextVoices: readonly string[] = [];
-			voiceNote = "No installed voices available.";
+			voiceNote = "No voices available.";
 			try {
 				nextVoices = await speech.voices(ctx);
 				if (nextVoices.length) voiceNote = "←/→ on Voice browses; Enter saves; Preview voice plays an explicit sample. Tab returns to categories.";

package/extensions/osdy-pi/kokoro-audio-player.test.ts

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import test from "node:test";
+// @ts-expect-error Native Node tests import TypeScript sources.
+import { createKokoroAudioPlayer } from "./kokoro-audio-player.ts";
+
+export function wav(): Uint8Array {
+ const bytes = Buffer.alloc(46);
+ bytes.write("RIFF"); bytes.writeUInt32LE(38, 4); bytes.write("WAVEfmt ", 8);
+ bytes.writeUInt32LE(16, 16); bytes.writeUInt16LE(1, 20); bytes.writeUInt16LE(1, 22);
+ bytes.writeUInt32LE(24000, 24); bytes.writeUInt32LE(48000, 28);
+ bytes.writeUInt16LE(2, 32); bytes.writeUInt16LE(16, 34);
+ bytes.write("data", 36); bytes.writeUInt32LE(2, 40);
+ return bytes;
+}
+class Child extends EventEmitter {
+ kills: string[] = [];
+ kill(signal: string): boolean { this.kills.push(signal); return true; }
+}
+function fixture() {
+ const child = new Child();
+ const calls: unknown[] = [];
+ let create = (): Promise<string> => Promise.resolve("/private/test");
+ let write = (): Promise<void> => Promise.resolve();
+ let remove = (): Promise<void> => Promise.resolve();
+ let spawnHook = (): void => {};
+ const player = createKokoroAudioPlayer({
+  fs: {
+   createDirectory: () => { calls.push("create"); return create(); },
+   write: (path, audio) => { calls.push(["write", path, audio.byteLength]); return write(); },
+   remove: (directory) => { calls.push(["remove", directory]); return remove(); },
+  },
+  spawn: (command, args) => { calls.push([command, args]); spawnHook(); return child; },
+ });
+ return { player, child, calls, setSpawn: (fn: typeof spawnHook) => { spawnHook = fn; }, setCreate: (fn: typeof create) => { create = fn; },
+  setWrite: (fn: typeof write) => { write = fn; }, setRemove: (fn: typeof remove) => { remove = fn; } };
+}
+async function tick(): Promise<void> { await new Promise<void>((resolve) => setImmediate(resolve)); }
+void test("player separates launch from completion and cleans only after termination", async () => {
+ const f = fixture(); let launched = false;
+ const pending = f.player.play(wav(), new AbortController().signal).then((value) => { launched = true; return value; });
+ await tick(); assert.equal(launched, false);
+ assert.deepEqual(f.calls, ["create", ["write", "/private/test/speech.wav", 46], ["/usr/bin/afplay", ["/private/test/speech.wav"]]]);
+ f.child.emit("spawn"); const playback = await pending;
+ assert.equal(f.calls.length, 3);
+ f.child.emit("close", 0); await playback.done;
+ assert.deepEqual(f.calls[3], ["remove", "/private/test"]);
+});
+void test("malformed/empty/oversized WAV never creates or spawns", async () => {
+ for (const audio of [new Uint8Array(), new Uint8Array(44), new Uint8Array(25 * 1024 * 1024 + 1), wav().slice(0, 45)]) {
+  const f = fixture(); await assert.rejects(f.player.play(audio, new AbortController().signal), /WAV/i);
+  assert.deepEqual(f.calls, []);
+ }
+});
+void test("RIFF metadata and chunk boundaries are validated before any filesystem call", async () => {
+ for (const mutate of [
+  (audio: Buffer) => audio.writeUInt32LE(999, 4),
+  (audio: Buffer) => audio.writeUInt32LE(999, 16),
+  (audio: Buffer) => audio.writeUInt16LE(99, 20),
+  (audio: Buffer) => audio.writeUInt16LE(0, 22),
+  (audio: Buffer) => audio.writeUInt32LE(0, 24),
+  (audio: Buffer) => audio.writeUInt32LE(0, 28),
+  (audio: Buffer) => audio.writeUInt16LE(0, 32),
+  (audio: Buffer) => audio.writeUInt16LE(0, 34),
+  (audio: Buffer) => audio.writeUInt32LE(0, 40),
+ ]) {
+  const f = fixture(); const audio = Buffer.from(wav()); mutate(audio);
+  await assert.rejects(f.player.play(audio, new AbortController().signal), /WAV/); assert.deepEqual(f.calls, []);
+ }
+});
+void test("non-ASCII lookalike RIFF bytes must not pass envelope validation", async () => {
+ const f = fixture(); const audio = Buffer.from(wav()); audio[0] = 0xd2;
+ f.setSpawn(() => { queueMicrotask(() => { f.child.emit("spawn"); f.child.emit("close", 0); }); });
+ await assert.rejects(f.player.play(audio, new AbortController().signal), /WAV/);
+ assert.deepEqual(f.calls, []);
+});
+void test("pre-abort has no effects; synchronous spawn failure and abort inside spawn clean safely", async () => {
+ const pre = fixture(); const controller = new AbortController(); controller.abort();
+ await assert.rejects(pre.player.play(wav(), controller.signal), /cancel/i); assert.deepEqual(pre.calls, []);
+ const failed = fixture(); failed.setSpawn(() => { throw new Error("private prose"); });
+ await assert.rejects(failed.player.play(wav(), new AbortController().signal), /Audio playback failed/);
+ assert.deepEqual(failed.calls.at(-1), ["remove", "/private/test"]);
+ const f = fixture(); const during = new AbortController(); f.setSpawn(() => { during.abort(); });
+ const pending = f.player.play(wav(), during.signal); const rejection = assert.rejects(pending, /cancel/i);
+ await tick(); assert.deepEqual(f.child.kills, ["SIGKILL"]); assert.equal(f.calls.length, 3);
+ f.child.emit("close", null); await rejection; assert.equal(f.calls.length, 4);
+});
+void test("abort while creating or writing prevents spawn and still cleans", async () => {
+ for (const stage of ["create", "write"]) {
+  const f = fixture(); const controller = new AbortController();
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  if (stage === "create") f.setCreate(async () => { await gate; return "/private/test"; });
+  else f.setWrite(() => gate);
+  const pending = f.player.play(wav(), controller.signal); await tick();
+  controller.abort(); controller.abort(); release();
+  await assert.rejects(pending, /cancel/i);
+  assert.equal(f.calls.some((call) => Array.isArray(call) && call[0] === "/usr/bin/afplay"), false);
+  assert.deepEqual(f.calls.at(-1), ["remove", "/private/test"]);
+ }
+});
+void test("abort before spawn and during playback kills once, waits for close, then cleans", async () => {
+ for (const active of [false, true]) {
+  const f = fixture(); const controller = new AbortController();
+  const pending = f.player.play(wav(), controller.signal); await tick();
+  let done: Promise<unknown> = pending;
+  if (active) { f.child.emit("spawn"); done = (await pending).done; }
+  const rejection = assert.rejects(done, /cancel/i);
+  controller.abort(); controller.abort(); await tick();
+  assert.deepEqual(f.child.kills, ["SIGKILL"]); assert.equal(f.calls.length, 3);
+  f.child.emit("spawn"); f.child.emit("close", null); await rejection;
+  assert.deepEqual(f.calls.at(-1), ["remove", "/private/test"]);
+  f.child.emit("error", new Error("late secret"));
+ }
+});
+void test("process and filesystem failures stay private and clean artifacts", async () => {
+ const f = fixture(); const pending = f.player.play(wav(), new AbortController().signal); await tick();
+ const rejection = assert.rejects(pending, /Audio playback failed/);
+ f.child.emit("error", new Error("private response prose"));
+ assert.equal(f.calls.length, 3); f.child.emit("close", -1); await rejection;
+ assert.equal(f.calls.length, 4);
+ const failed = fixture(); failed.setWrite(() => Promise.reject(new Error("private path")));
+ await assert.rejects(failed.player.play(wav(), new AbortController().signal), /Audio playback failed/);
+ assert.deepEqual(failed.calls.at(-1), ["remove", "/private/test"]);
+});
+void test("abort during cleanup rejects completion and cleanup failure is observable", async () => {
+ const f = fixture(); const controller = new AbortController(); let release!: () => void;
+ f.setRemove(() => new Promise<void>((resolve) => { release = resolve; }));
+ const pending = f.player.play(wav(), controller.signal); await tick(); f.child.emit("spawn");
+ const playback = await pending; f.child.emit("close", 0); await tick(); controller.abort(); release();
+ await assert.rejects(playback.done, /cancel/i);
+ const failed = fixture(); failed.setRemove(() => Promise.reject(new Error("secret path")));
+ const next = failed.player.play(wav(), new AbortController().signal); await tick(); failed.child.emit("spawn");
+ const handle = await next; failed.child.emit("close", 1);
+ await assert.rejects(handle.done, /Audio cleanup failed/);
+});

package/extensions/osdy-pi/kokoro-audio-player.ts

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { SpeechPlayback } from "./speech-adapter.js";
+
+export const MAX_KOKORO_WAV_BYTES = 25 * 1024 * 1024;
+export interface KokoroAudioPlayer {
+ play(audio: Uint8Array, signal: AbortSignal): Promise<SpeechPlayback>;
+}
+export interface KokoroAudioProcess {
+ on(event: "spawn", listener: () => void): this;
+ on(event: "error", listener: (error: Error) => void): this;
+ on(event: "close", listener: (code: number | null) => void): this;
+ kill(signal: "SIGKILL"): boolean;
+}
+export interface KokoroAudioFileSystem {
+ createDirectory(): Promise<string>;
+ write(path: string, audio: Uint8Array): Promise<void>;
+ remove(directory: string): Promise<void>;
+}
+export interface KokoroAudioPlayerOptions {
+ fs?: KokoroAudioFileSystem;
+ spawn?: (command: string, args: readonly string[]) => KokoroAudioProcess;
+}
+
+/** Require a complete, nonempty PCM/IEEE-float RIFF WAVE, not a MIME claim. */
+export function validateKokoroWav(audio: Uint8Array): void {
+ const invalid = (): never => { throw new Error("Invalid or oversized Kokoro WAV audio"); };
+ if (audio.byteLength < 44 || audio.byteLength > MAX_KOKORO_WAV_BYTES) invalid();
+ const bytes = Buffer.from(audio.buffer, audio.byteOffset, audio.byteLength);
+ if (bytes.toString("latin1", 0, 4) !== "RIFF" || bytes.toString("latin1", 8, 12) !== "WAVE" ||
+  bytes.readUInt32LE(4) !== bytes.length - 8) invalid();
+ let format = false;
+ let dataSize = 0;
+ let alignment = 0;
+ let offset = 12;
+ while (offset + 8 <= bytes.length) {
+  const id = bytes.toString("latin1", offset, offset + 4);
+  const size = bytes.readUInt32LE(offset + 4);
+  const start = offset + 8;
+  const end = start + size;
+  if (end > bytes.length) invalid();
+  if (id === "fmt ") {
+   if (format || size < 16) invalid();
+   const encoding = bytes.readUInt16LE(start);
+   const channels = bytes.readUInt16LE(start + 2);
+   const sampleRate = bytes.readUInt32LE(start + 4);
+   const byteRate = bytes.readUInt32LE(start + 8);
+   alignment = bytes.readUInt16LE(start + 12);
+   const bits = bytes.readUInt16LE(start + 14);
+   if (![1, 3].includes(encoding) || channels < 1 || channels > 2 || sampleRate < 8000 || sampleRate > 192000 ||
+    !(encoding === 3 ? [32, 64] : [8, 16, 24, 32]).includes(bits) ||
+    alignment !== channels * bits / 8 || byteRate !== sampleRate * alignment) invalid();
+   format = true;
+  }
+  if (id === "data") {
+   if (!format || dataSize !== 0 || size === 0 || size % alignment !== 0) invalid();
+   dataSize = size;
+  }
+  offset = end + size % 2;
+ }
+ if (!format || dataSize === 0 || offset !== bytes.length) invalid();
+}
+
+function cancelled(): Error { return new Error("Speech cancelled"); }
+function checkAbort(signal: AbortSignal): void { if (signal.aborted) throw cancelled(); }
+
+const privateFileSystem: KokoroAudioFileSystem = {
+ createDirectory: () => mkdtemp(join(tmpdir(), "osdy-kokoro-")),
+ write: (path, audio) => writeFile(path, audio, {mode: 0o600, flag: "wx"}),
+ remove: (directory) => rm(directory, {recursive: true, force: true}),
+};
+
+export function createKokoroAudioPlayer(options: KokoroAudioPlayerOptions = {}): KokoroAudioPlayer {
+ const fs = options.fs ?? privateFileSystem;
+ const spawnProcess = options.spawn ?? ((command, args) => spawn(command, [...args], {shell: false, stdio: "ignore"}));
+ return {
+  async play(audio, signal) {
+   checkAbort(signal);
+   validateKokoroWav(audio);
+   let directory: string | undefined;
+   const cleanup = async (): Promise<void> => {
+    if (directory === undefined) return;
+    try { await fs.remove(directory); }
+    catch { throw new Error("Audio cleanup failed"); }
+   };
+   let child: KokoroAudioProcess;
+   try {
+    directory = await fs.createDirectory();
+    checkAbort(signal);
+    const file = join(directory, "speech.wav");
+    await fs.write(file, audio);
+    checkAbort(signal);
+    child = spawnProcess("/usr/bin/afplay", [file]);
+   } catch {
+    await cleanup();
+    throw signal.aborted ? cancelled() : new Error("Audio playback failed");
+   }
+
+   let resolveLaunch!: () => void;
+   let rejectLaunch!: (error: Error) => void;
+   let resolveExit!: () => void;
+   let rejectExit!: (error: Error) => void;
+   let failure: Error | undefined;
+   let closed = false;
+   let killed = false;
+   const launched = new Promise<void>((resolve, reject) => { resolveLaunch = resolve; rejectLaunch = reject; });
+   const exited = new Promise<void>((resolve, reject) => { resolveExit = resolve; rejectExit = reject; });
+   void launched.catch(() => {});
+   const abort = (): void => {
+    if (closed || failure) return;
+    failure = cancelled();
+    rejectLaunch(failure);
+    if (!killed) { killed = true; child.kill("SIGKILL"); }
+   };
+   child.on("spawn", () => {
+    if (!failure && !signal.aborted) resolveLaunch();
+   });
+   child.on("error", () => {
+    if (closed || failure) return;
+    failure = new Error("Audio playback failed");
+    rejectLaunch(failure);
+    if (!killed) { killed = true; child.kill("SIGKILL"); }
+   });
+   child.on("close", (code) => {
+    if (closed) return;
+    closed = true;
+    const error = signal.aborted ? cancelled() : failure ?? (code === 0 ? undefined : new Error("Audio playback failed"));
+    if (error) { rejectLaunch(error); rejectExit(error); }
+    else { resolveLaunch(); resolveExit(); }
+   });
+   signal.addEventListener("abort", abort, {once: true});
+   if (signal.aborted) abort();
+   // Cleanup is owned by completion, never by the launch event or kill request.
+   const done = (async (): Promise<void> => {
+    try { await exited; }
+    finally {
+     try { await cleanup(); }
+     finally { signal.removeEventListener("abort", abort); }
+    }
+    checkAbort(signal);
+   })();
+   void done.catch(() => {});
+   try { await launched; }
+   catch (error) { await done.catch(() => {}); throw error; }
+   return {done};
+  },
+ };
+}

package/extensions/osdy-pi/kokoro-speech-adapter.test.ts

@@ -0,0 +1,128 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+// @ts-expect-error Native Node tests import TypeScript sources.
+import { createKokoroSpeechAdapter, createLocalSpeechAdapter } from "./kokoro-speech-adapter.ts";
+import type { SpeechAdapter } from "./speech-adapter.js";
+
+function wav(): Uint8Array<ArrayBuffer> {
+ const bytes = Buffer.alloc(46);
+ bytes.write("RIFF"); bytes.writeUInt32LE(38, 4); bytes.write("WAVEfmt ", 8);
+ bytes.writeUInt32LE(16, 16); bytes.writeUInt16LE(1, 20); bytes.writeUInt16LE(1, 22);
+ bytes.writeUInt32LE(24000, 24); bytes.writeUInt32LE(48000, 28);
+ bytes.writeUInt16LE(2, 32); bytes.writeUInt16LE(16, 34);
+ bytes.write("data", 36); bytes.writeUInt32LE(2, 40); return new Uint8Array(bytes);
+}
+function fixture(url: unknown = "http://127.0.0.1:8000", platform = "darwin") {
+ const requests: Array<{ url: string; init: RequestInit }> = [];
+ const plays: Uint8Array[] = [];
+ let respond: (init: RequestInit) => Promise<Response> = () => Promise.resolve(new Response(wav()));
+ const adapter = createKokoroSpeechAdapter({ platform, url,
+  fetch: (url, init) => { requests.push({url, init}); return respond(init); },
+  player: { play: (audio) => { plays.push(audio); return Promise.resolve({ done: Promise.resolve() }); } },
+ });
+ return { adapter, requests, plays, setResponse: (fn: typeof respond) => { respond = fn; } };
+}
+void test("construction and listing never fetch; fixed Spanish voices and full prose payload", async () => {
+ const f = fixture(); const signal = new AbortController().signal;
+ assert.equal(f.adapter.available(), true); assert.deepEqual(f.requests, []);
+ assert.deepEqual(await f.adapter.voices(signal), ["Kokoro Dora", "Kokoro Alex", "Kokoro Santa"]);
+ assert.deepEqual(f.requests, []);
+ for (const [voice, id] of [["Kokoro Dora", "ef_dora"], ["Kokoro Alex", "em_alex"], ["Kokoro Santa", "em_santa"]]) {
+  const text = "Buenos días. ".repeat(2000);
+  await (await f.adapter.speak(text, voice!, 270, signal)).done;
+  const request: {url: string; init: RequestInit} = f.requests.at(-1)!;
+  assert.equal(request.url, "http://127.0.0.1:8000/v1/audio/speech");
+  assert.equal(request.init.redirect, "error"); assert.equal(request.init.method, "POST");
+  assert.ok(typeof request.init.body === "string");
+  assert.deepEqual(JSON.parse(request.init.body), { model: "mlx-community/Kokoro-82M-bf16", input: text,
+   voice: id, lang_code: "e", response_format: "wav", stream: false, speed: 1.5 });
+ }
+ assert.equal(f.plays.length, 3);
+});
+void test("only explicit literal loopback HTTP origins are accepted", async () => {
+ for (const url of ["http://127.0.0.1", "http://[::1]:8000/"]) {
+  const f = fixture(url); await f.adapter.speak("hola", "Kokoro Dora", 180, new AbortController().signal);
+  assert.equal(f.requests.length, 1);
+ }
+ for (const url of ["https://127.0.0.1", "http://localhost", "http://example.com", "http://127.1", "http://2130706433",
+  "http://127.0.0.1/path", "http://127.0.0.1?x", "http://127.0.0.1#x", "http://user@127.0.0.1", "http://127.0.0.1:99999", {}, null, ""]) {
+  const f = fixture(url);
+  await assert.rejects(f.adapter.speak("private", "Kokoro Dora", 180, new AbortController().signal), /loopback/i);
+  assert.deepEqual(f.requests, []); assert.deepEqual(f.plays, []);
+ }
+});
+void test("invalid voices/rates and unsupported platforms never fetch or play", async () => {
+ for (const [voice, rate] of [["Paulina", 180], ["Kokoro Dora", 79], ["Kokoro Dora", 351], ["Kokoro Dora", NaN], ["Kokoro Dora", 180.5]] as const) {
+  const f = fixture(); await assert.rejects(f.adapter.speak("hola", voice, rate, new AbortController().signal));
+  assert.deepEqual(f.requests, []); assert.deepEqual(f.plays, []);
+ }
+ const f = fixture(undefined, "linux"); assert.equal(f.adapter.available(), false);
+ assert.deepEqual(await f.adapter.voices(new AbortController().signal), []);
+ await assert.rejects(f.adapter.speak("hola", "Kokoro Dora", 180, new AbortController().signal), /macOS/);
+ assert.deepEqual(f.requests, []);
+ for (const rate of [80, 350]) {
+  const mac = fixture(); await mac.adapter.speak("hola", "Kokoro Dora", rate, new AbortController().signal);
+  const body = mac.requests[0]!.init.body;
+  assert.ok(typeof body === "string");
+  const payload: unknown = JSON.parse(body);
+  assert.ok(typeof payload === "object" && payload !== null && "speed" in payload);
+  assert.equal(payload.speed, rate / 180);
+ }
+});
+void test("HTTP, redirect, unavailable server and invalid audio errors disclose no response text", async () => {
+ for (const response of [new Response("secret prose", {status: 500}), new Response("secret prose", {status: 302, headers: {location: "https://example.com"}}),
+  new Response("secret prose", {headers: {"content-type": "audio/wav"}}), new Response(new Uint8Array()),
+  new Response(wav(), {headers: {"content-length": String(25 * 1024 * 1024 + 1)}}), new Response(new Uint8Array(25 * 1024 * 1024 + 1))]) {
+  const f = fixture(); f.setResponse(() => Promise.resolve(response));
+  await assert.rejects(f.adapter.speak("private", "Kokoro Dora", 180, new AbortController().signal),
+   (error: unknown) => error instanceof Error && !error.message.includes("secret prose"));
+  assert.deepEqual(f.plays, []);
+ }
+ const f = fixture(); f.setResponse(() => Promise.reject(new Error("secret prose")));
+ await assert.rejects(f.adapter.speak("private", "Kokoro Dora", 180, new AbortController().signal), /local.*MLX-Audio/i);
+});
+void test("pending synthesis cancellation settles even if transport ignores abort and prevents late play", async () => {
+ const f = fixture(); let release!: (response: Response) => void;
+ f.setResponse(() => new Promise<Response>((resolve) => { release = resolve; }));
+ const controller = new AbortController(); const pending = f.adapter.speak("hola", "Kokoro Dora", 180, controller.signal);
+ controller.abort(); controller.abort(); await assert.rejects(pending, /cancel/i);
+ assert.equal(f.requests[0]!.init.signal?.aborted, true);
+ release(new Response(wav())); await new Promise<void>((resolve) => setImmediate(resolve)); assert.deepEqual(f.plays, []);
+ const pre = new AbortController(); pre.abort();
+ await assert.rejects(f.adapter.speak("hola", "Kokoro Dora", 180, pre.signal), /cancel/i);
+ assert.equal(f.requests.length, 1);
+});
+void test("synthesis timeout is bounded even when transport ignores its signal", async (context) => {
+ context.mock.timers.enable({apis: ["setTimeout"]});
+ const f = fixture(); f.setResponse(() => new Promise<Response>(() => {}));
+ const pending = f.adapter.speak("hola", "Kokoro Dora", 180, new AbortController().signal);
+ const rejection = assert.rejects(pending, /timed out.*120 seconds/);
+ context.mock.timers.tick(120_000); await rejection;
+ assert.equal(f.requests[0]!.init.signal?.aborted, true); assert.deepEqual(f.plays, []);
+});
+void test("abort during response download cancels reader and prevents playback", async () => {
+ const f = fixture(); let cancelled = false;
+ const body = new ReadableStream<Uint8Array>({
+  start(controller) { controller.enqueue(wav().slice(0, 20)); },
+  cancel() { cancelled = true; },
+ });
+ f.setResponse(() => Promise.resolve(new Response(body)));
+ const controller = new AbortController(); const pending = f.adapter.speak("hola", "Kokoro Dora", 180, controller.signal);
+ await new Promise<void>((resolve) => setImmediate(resolve)); controller.abort();
+ await assert.rejects(pending, /cancel/i); assert.equal(cancelled, true); assert.deepEqual(f.plays, []);
+});
+void test("combined adapter retains native availability/catalog/errors and native speech never fetches", async () => {
+ let network = 0; const nativeCalls: unknown[] = []; const failure = new Error("native discovery failure");
+ const native: SpeechAdapter = { available: () => true, voices: () => Promise.resolve(["Paulina"]),
+  speak: (...args) => { nativeCalls.push(args); return Promise.resolve({done: Promise.resolve()}); } };
+ const combined = createLocalSpeechAdapter({ platform: "darwin", native, url: "https://unsafe.example",
+  fetch: () => { network++; return Promise.reject(new Error("must not fetch")); } });
+ const signal = new AbortController().signal;
+ assert.equal(combined.available(), true);
+ assert.deepEqual(await combined.voices(signal), ["Paulina", "Kokoro Dora", "Kokoro Alex", "Kokoro Santa"]);
+ await combined.speak("hola", "Paulina", 180, signal); assert.equal(nativeCalls.length, 1); assert.equal(network, 0);
+ await assert.rejects(combined.speak("hola", "Kokoro Dora", 180, signal), /loopback/i); assert.equal(network, 0);
+ native.voices = () => Promise.reject(failure); await assert.rejects(combined.voices(signal), (error: unknown) => error === failure);
+ const unsupported = createLocalSpeechAdapter({platform: "linux", native});
+ native.voices = () => Promise.resolve(["Paulina"]); assert.deepEqual(await unsupported.voices(signal), ["Paulina"]);
+});

package/extensions/osdy-pi/kokoro-speech-adapter.ts

@@ -0,0 +1,146 @@
+import type { SpeechAdapter } from "./speech-adapter.js";
+// @ts-expect-error Native Node tests import TypeScript sources.
+import { createNativeSpeechAdapter } from "./speech-adapter.ts";
+// @ts-expect-error Native Node tests import TypeScript sources.
+import { validateSpeechSettings } from "./speech-settings.ts";
+// @ts-expect-error Native Node tests import TypeScript sources.
+import { createKokoroAudioPlayer, MAX_KOKORO_WAV_BYTES, validateKokoroWav } from "./kokoro-audio-player.ts";
+import type { KokoroAudioPlayer } from "./kokoro-audio-player.js";
+
+const VOICES = new Map([
+ ["Kokoro Dora", "ef_dora"],
+ ["Kokoro Alex", "em_alex"],
+ ["Kokoro Santa", "em_santa"],
+]);
+const SYNTHESIS_TIMEOUT_MS = 120_000;
+export interface KokoroSpeechAdapterOptions {
+ platform?: string;
+ /** Base origin only. Unknown configuration is validated before sending prose. */
+ url?: unknown;
+ fetch?: (url: string, init: RequestInit) => Promise<Response>;
+ player?: KokoroAudioPlayer;
+}
+export interface LocalSpeechAdapterOptions extends KokoroSpeechAdapterOptions {
+ native?: SpeechAdapter;
+}
+
+function endpoint(value: unknown): string {
+ const invalid = (): never => { throw new Error("Kokoro URL must be a literal HTTP loopback origin (127.0.0.1 or [::1])"); };
+ if (typeof value !== "string" || !/^http:\/\/(?:127\.0\.0\.1|\[::1\])(?::[0-9]+)?\/?$/u.test(value)) return invalid();
+ let url: URL;
+ try { url = new URL(value); } catch { return invalid(); }
+ if (url.port === "0") return invalid();
+ return `${url.origin}/v1/audio/speech`;
+}
+function cancelled(): Error { return new Error("Speech cancelled"); }
+function setupError(): Error {
+ return new Error("Kokoro synthesis failed. Start the local MLX-Audio server with mlx-community/Kokoro-82M-bf16; check local Kokoro setup and OSDY_PI_KOKORO_URL.");
+}
+
+async function readWav(response: Response, signal: AbortSignal): Promise<Uint8Array> {
+ if (!response.ok || response.redirected || !response.body) {
+  await response.body?.cancel();
+  throw setupError();
+ }
+ const declared = response.headers.get("content-length");
+ if (declared !== null && (!/^\d+$/u.test(declared) || Number(declared) > MAX_KOKORO_WAV_BYTES)) {
+  await response.body.cancel();
+  throw new Error("Invalid or oversized Kokoro WAV audio");
+ }
+ const reader = response.body.getReader();
+ const chunks: Uint8Array[] = [];
+ let size = 0;
+ const abort = (): void => { void reader.cancel().catch(() => {}); };
+ signal.addEventListener("abort", abort, {once: true});
+ try {
+  if (signal.aborted) throw cancelled();
+  while (true) {
+   const chunk = await reader.read();
+   if (signal.aborted) throw cancelled();
+   if (chunk.done) break;
+   size += chunk.value.byteLength;
+   if (size > MAX_KOKORO_WAV_BYTES) throw new Error("Invalid or oversized Kokoro WAV audio");
+   chunks.push(chunk.value);
+  }
+  const audio = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) { audio.set(chunk, offset); offset += chunk.byteLength; }
+  validateKokoroWav(audio);
+  return audio;
+ } finally {
+  signal.removeEventListener("abort", abort);
+  void reader.cancel().catch(() => {});
+ }
+}
+
+export function createKokoroSpeechAdapter(options: KokoroSpeechAdapterOptions = {}): SpeechAdapter {
+ const platform = options.platform ?? process.platform;
+ const transport = options.fetch ?? fetch;
+ const player = options.player ?? createKokoroAudioPlayer();
+ // Reading configuration is inert: invalid Kokoro configuration cannot disable native speech.
+ const baseUrl: unknown = options.url !== undefined ? options.url : process.env.OSDY_PI_KOKORO_URL ?? "http://127.0.0.1:8000";
+ return {
+  available: () => platform === "darwin",
+  voices: (signal) => signal.aborted ? Promise.reject(cancelled()) : Promise.resolve(platform === "darwin" ? [...VOICES.keys()] : []),
+  async speak(text, voice, rate, signal) {
+   if (signal.aborted) throw cancelled();
+   if (platform !== "darwin") throw new Error("Kokoro playback is only available on macOS");
+   validateSpeechSettings({version: 1, enabled: false, voice, rate});
+   const mapped = VOICES.get(voice);
+   if (!mapped) throw new Error("Unknown Kokoro voice");
+   const url = endpoint(baseUrl);
+   const controller = new AbortController();
+   let rejectCancelled!: (error: Error) => void;
+   const interrupted = new Promise<never>((_, reject) => { rejectCancelled = reject; });
+   const abort = (): void => { controller.abort(); rejectCancelled(cancelled()); };
+   signal.addEventListener("abort", abort, {once: true});
+   const timeout = setTimeout(() => {
+    controller.abort();
+    rejectCancelled(new Error("Kokoro synthesis timed out after 120 seconds. Check the local MLX-Audio setup."));
+   }, SYNTHESIS_TIMEOUT_MS);
+   let audio: Uint8Array;
+   try {
+    if (signal.aborted) abort();
+    const synthesis = (async (): Promise<Uint8Array> => {
+     if (controller.signal.aborted) throw cancelled();
+     const response = await transport(url, {
+      method: "POST", redirect: "error", signal: controller.signal,
+      headers: {"Content-Type": "application/json"},
+      body: JSON.stringify({model: "mlx-community/Kokoro-82M-bf16", input: text,
+       voice: mapped, lang_code: "e", response_format: "wav", stream: false,
+       // Existing validated 80–350 wpm maps to explicit speed bounds 4/9–35/18.
+       speed: rate / 180}),
+     });
+     if (controller.signal.aborted) { void response.body?.cancel().catch(() => {}); throw cancelled(); }
+     return readWav(response, controller.signal);
+    })();
+    audio = await Promise.race([synthesis, interrupted]);
+   } catch {
+    if (signal.aborted) throw cancelled();
+    if (controller.signal.aborted) throw new Error("Kokoro synthesis timed out after 120 seconds. Check the local MLX-Audio setup.");
+    throw setupError();
+   } finally {
+    clearTimeout(timeout);
+    signal.removeEventListener("abort", abort);
+   }
+   if (signal.aborted) throw cancelled();
+   return player.play(audio, signal);
+  },
+ };
+}
+
+/** Native speech remains independent: no probing, fallback, settings or lifecycle ownership. */
+export function createLocalSpeechAdapter(options: LocalSpeechAdapterOptions = {}): SpeechAdapter {
+ const native = options.native ?? createNativeSpeechAdapter(options);
+ const kokoro = createKokoroSpeechAdapter(options);
+ return {
+  available: () => native.available() || kokoro.available(),
+  async voices(signal) {
+   const voices = await native.voices(signal);
+   return [...voices, ...await kokoro.voices(signal)];
+  },
+  speak: (text, voice, rate, signal) => VOICES.has(voice)
+   ? kokoro.speak(text, voice, rate, signal)
+   : native.speak(text, voice, rate, signal),
+ };
+}

package/extensions/osdy-pi/speech-service.test.ts

@@ -26,6 +26,18 @@ function fixture() {
  const service = createSpeechService({ adapter, store, onError: (error) => { errors.push(error); } });
  return { service, adapter, store, calls, errors, done, stored: () => stored, saves: () => saves };
 }
+void test("production macOS catalog retains native voices and adds optional Kokoro without reading settings", { skip: process.platform !== "darwin" }, async () => {
+ let storeCalls = 0;
+ const service = createSpeechService({ store: {
+  load: () => { storeCalls++; return Promise.reject(new Error("Discovery must not read settings")); },
+  save: () => { storeCalls++; return Promise.reject(new Error("Discovery must not save settings")); },
+ } });
+ const voices = await service.voices();
+ for (const voice of ["Kokoro Dora", "Kokoro Alex", "Kokoro Santa"]) assert.ok(voices.includes(voice), voice);
+ assert.ok(voices.some(voice => !voice.startsWith("Kokoro ")));
+ assert.equal(storeCalls, 0);
+ service.stop();
+});
 void test("off by default; manual uses installed Paulina and returns before playback ends", async () => {
  const f = fixture();
  assert.equal(f.service.available(), true);
@@ -168,6 +180,25 @@ void test("preview uses the explicit installed voice and fixed sample at persist
  assert.deepEqual(await f.service.settings(), before); assert.equal(f.saves(), saves);
  f.service.stop(); f.done.resolve();
 });
+void test("only the three fixed Kokoro labels preview Spanish without saving or enabling", async () => {
+ const f = fixture();
+ const kokoro = ["Kokoro Dora", "Kokoro Alex", "Kokoro Santa"];
+ const native = ["Kokoro Dora (Enhanced)", "Kokoro Native", "Jorge"];
+ f.adapter.voices = () => Promise.resolve([...kokoro, ...native]);
+ const before = await f.service.settings();
+ for (const voice of [...kokoro, ...native]) {
+  assert.deepEqual(await f.service.preview(voice), {kind: "started"});
+  assert.equal(f.calls.at(-1)?.text, kokoro.includes(voice)
+   ? "¡Hola! Esta es una muestra de mi voz en Osdy Pi. Puedo leer tus respuestas en español, con claridad y naturalidad."
+   : "Hello! This is a preview of my voice in Osdy Pi.");
+  assert.equal(f.calls.at(-1)?.voice, voice);
+  assert.equal(f.calls.at(-1)?.rate, 180);
+  assert.deepEqual(await f.service.settings(), before);
+  assert.equal(f.saves(), 0);
+ }
+ assert.equal((await f.service.speak("still disabled", {automatic: true})).kind, "disabled");
+ f.service.stop(); f.done.resolve();
+});
 void test("preview rejects invalid or uninstalled exact choices without fallback or settings writes", async () => {
  const f = fixture(); const before = await f.service.settings();
  for (const voice of ["", "bad\nvoice", "[[rate 999]]", "Missing", "Paulina"]) {

package/extensions/osdy-pi/speech-service.ts

@@ -2,7 +2,7 @@ import type { SpeechResult, SpeechService, SpeechSettings } from "./speech-types
 import type { SpeechAdapter } from "./speech-adapter.js";
 import type { SpeechSettingsStore } from "./speech-settings.js";
 // @ts-expect-error Native Node tests import TypeScript sources.
-import { createNativeSpeechAdapter } from "./speech-adapter.ts";
+import { createLocalSpeechAdapter } from "./kokoro-speech-adapter.ts";
 // @ts-expect-error Native Node tests import TypeScript sources.
 import { createSpeechSettingsStore, defaultSpeechSettings, validateSpeechSettings } from "./speech-settings.ts";
 // @ts-expect-error Native Node tests import TypeScript sources.
@@ -25,7 +25,7 @@ function resolveVoice(installed: readonly string[], requested: string): string |
 }
 
 export function createSpeechService(options: SpeechServiceOptions = {}): SpeechService {
- const adapter = options.adapter ?? createNativeSpeechAdapter();
+ const adapter = options.adapter ?? createLocalSpeechAdapter();
  const store = options.store ?? createSpeechSettingsStore(options.agentDir);
  let generation = 0;
  let active: AbortController | undefined;
@@ -114,7 +114,9 @@ export function createSpeechService(options: SpeechServiceOptions = {}): SpeechS
    configureQueue = update.then(() => {}, () => {});
    return update;
   },
-  preview: voice => launch("Hello! This is a preview of my voice in Osdy Pi.", { voice }),
+  preview: voice => launch(["Kokoro Dora", "Kokoro Alex", "Kokoro Santa"].includes(voice)
+   ? "¡Hola! Esta es una muestra de mi voz en Osdy Pi. Puedo leer tus respuestas en español, con claridad y naturalidad."
+   : "Hello! This is a preview of my voice in Osdy Pi.", { voice }),
   stopPreview() {
    if (activeKind !== "preview") return;
    generation++;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "osdy-pi",
-	"version": "1.11.17",
+	"version": "1.11.18",
 	"description": "Osdy Pi package: themes, header, and custom editor for Pi.",
 	"license": "MIT",
 	"type": "module",
@@ -22,6 +22,7 @@
 	},
 	"files": [
 		"README.md",
+		"docs/kokoro.md",
 		"LICENSE",
 		"bin",
 		"scripts/osdy-pi-account-profiles.mjs",
@@ -83,7 +84,7 @@
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.46.3"
 	},
-	"releaseSource": "6eda9d1e331bc6af461f03272e5bb0962c682c2e",
+	"releaseSource": "1a36c12e766b5a18613c1d893af4c2f095b040f4",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/OsdyOrtiz/Osdy-Pi.git"