pi-say 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matifema
+
+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/README.md

@@ -0,0 +1,105 @@
+# pi-say
+
+Spoken output for [pi](https://pi.dev/): a `say` tool that turns short sentences into speech.
+
+Give pi a voice. The model calls `say` for acks before slow work and for the final result:
+
+> "Checking the logs now." … "Found three failed requests."
+
+Google Cloud TTS is used when credentials are available, with local fallback
+(Kokoro/Piper server, macOS `say`, or `espeak-ng`) so speech keeps working offline.
+
+## Install
+
+```bash
+pi install npm:pi-say
+# or from git
+pi install git:github.com/matifema/pi-say
+# or try without installing
+pi -e npm:pi-say
+```
+
+Restart pi (or start a new session) after installing.
+
+## Google Cloud TTS
+
+Provide credentials in one of these ways:
+
+- **API key:** set `PI_SAY_GOOGLE_API_KEY` (or `VOICECTL_GOOGLE_API_KEY`, or `GOOGLE_API_KEY`)
+- **Service account JSON:** set `GOOGLE_APPLICATION_CREDENTIALS`, or drop the file at
+  `~/.config/pi-say/google-sa.json` (voicectl's `~/.config/voicectl/google-sa.json` is also picked up)
+
+The Cloud Text-to-Speech API must be enabled on the project. Without
+credentials, pi-say silently falls back to the local engines below.
+
+## Voice
+
+Change the voice from pi in two ways:
+
+- Ask pi in plain language — the model calls `say_voice` for you
+- Type `/voice <name>` in the pi prompt (`/voice` shows the current settings, `/voice list` lists Google voices)
+
+Examples:
+
+```
+/voice en-US-Chirp3-HD-Aoede
+/voice en-US-Journey-O
+/voice local
+/voice speed 1.15
+```
+
+Settings persist in `~/.config/pi-say/config.json`:
+
+```json
+{
+  "engine": "auto",
+  "voice": "en-US-Chirp3-HD-Charon",
+  "speed": 1.0
+}
+```
+
+`engine` is one of `auto` (Google, then local, then espeak), `google`,
+`local`, or `espeak`.
+
+## Local fallback
+
+`auto` mode tries these in order:
+
+1. **Google Cloud TTS** — when credentials are configured
+2. **Local HTTP TTS** — any server exposing `POST /tts` with `{ text, voice, speed }`
+   returning audio (Kokoro, Piper, voicectl, …); default `http://127.0.0.1:8181`
+3. **macOS `say`** — built in
+4. **`espeak-ng` / `espeak`** — install with your package manager
+
+Playback uses a voicectl-style HUD unix socket when present, otherwise
+`pw-play`, `paplay`, `aplay`, or `ffplay` (`afplay` on macOS).
+
+## Environment variables
+
+Everything is optional; values in `~/.config/pi-say/config.json` (written by
+`/voice` and `say_voice`) take precedence. `VOICECTL_*` aliases remain
+supported for compatibility with [voicectl](https://github.com/matifema/voicectl).
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `PI_SAY_GOOGLE_API_KEY` | — | Google Cloud TTS API key. |
+| `PI_SAY_GOOGLE_SA` / `GOOGLE_APPLICATION_CREDENTIALS` | auto-discovered | Service account JSON path. |
+| `PI_SAY_ENGINE` | `auto` | `auto`, `google`, `local`, or `espeak`. |
+| `PI_SAY_VOICE` | `en-US-Chirp3-HD-Charon` | Voice name. |
+| `PI_SAY_SPEED` | `1.0` | Speaking rate. |
+| `PI_SAY_TTS_URL` | `http://127.0.0.1:8181` | Local TTS server. Set to `off` to skip it. |
+| `PI_SAY_HUD_SOCKET` | `$XDG_RUNTIME_DIR/voicectl.sock` | HUD socket that accepts `{"cmd":"speak","file":…,"interrupt":…}`. |
+| `PI_SAY_PLAYER` | auto | Force a player command, e.g. `aplay`. |
+| `PI_SAY_TIMING_LOG` | `$XDG_RUNTIME_DIR/pi-say-timing.jsonl` | JSONL latency log; failures are silent. |
+
+## How it works
+
+1. Text is clipped to twelve words.
+2. Synthesis: Google Cloud TTS → local HTTP TTS → macOS `say` → `espeak-ng`.
+3. Playback: HUD socket → `pw-play` / `paplay` / `aplay` / `ffplay` (`afplay` on macOS).
+
+Generated WAVs are cached under `~/.cache/pi-say/`.
+
+## License
+
+MIT

package/extensions/say.ts

@@ -0,0 +1,642 @@
+/**
+ * say — spoken output for pi.
+ *
+ * Synthesis: Google Cloud TTS (API key or service account JSON)
+ *            -> local HTTP TTS server (Kokoro/Piper/voicectl, default :8181)
+ *            -> macOS built-in `say`
+ *            -> espeak-ng / espeak
+ * Playback:  HUD unix socket (if present)
+ *            -> pw-play / paplay / aplay / ffplay (afplay on macOS)
+ *
+ * Voice, speed and engine live in ~/.config/pi-say/config.json and can be
+ * changed from pi with the `say_voice` tool or the `/voice` command.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { spawn } from "node:child_process";
+import { createSign, randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { homedir, platform, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+const firstEnv = (...names: string[]): string | undefined => {
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+};
+
+const IS_MAC = platform() === "darwin";
+const RUNTIME_DIR = process.env.XDG_RUNTIME_DIR ?? tmpdir();
+const CONFIG_PATH = join(
+    process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
+    "pi-say",
+    "config.json",
+);
+const TIMING = firstEnv("PI_SAY_TIMING_LOG") ?? join(RUNTIME_DIR, "pi-say-timing.jsonl");
+const DEFAULT_VOICE = "en-US-Chirp3-HD-Charon";
+const ENGINES = ["auto", "google", "local", "espeak"];
+
+const COMMON_VOICES = [
+    "en-US-Chirp3-HD-Charon",
+    "en-US-Chirp3-HD-Aoede",
+    "en-US-Chirp3-HD-Kore",
+    "en-US-Chirp3-HD-Leda",
+    "en-US-Chirp3-HD-Orus",
+    "en-US-Chirp3-HD-Puck",
+    "en-US-Chirp3-HD-Fenrir",
+    "en-US-Chirp3-HD-Zephyr",
+    "en-US-Journey-D",
+    "en-US-Journey-F",
+    "en-US-Journey-O",
+    "en-US-Studio-O",
+    "en-US-Studio-Q",
+];
+
+type SayConfig = {
+    engine?: string;
+    voice?: string;
+    speed?: number;
+    localTtsUrl?: string;
+    hudSocket?: string;
+    googleApiKey?: string;
+    googleSaPath?: string;
+};
+
+function loadConfig(): SayConfig {
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as SayConfig;
+    } catch {
+        return {};
+    }
+}
+
+function saveConfig(patch: SayConfig): SayConfig {
+    const next = { ...loadConfig(), ...patch };
+    for (const [key, value] of Object.entries(next)) {
+        if (value === undefined || value === "")
+            delete next[key as keyof SayConfig];
+    }
+    try {
+        mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+        writeFileSync(CONFIG_PATH, `${JSON.stringify(next, null, 2)}\n`);
+    } catch {
+        /* read-only home; env vars still work */
+    }
+    return next;
+}
+
+function currentEngine(): string {
+    const engine = (loadConfig().engine ?? firstEnv("PI_SAY_ENGINE") ?? "auto").toLowerCase();
+    return ENGINES.includes(engine) ? engine : "auto";
+}
+
+function currentVoice(override?: string): string {
+    return (
+        override?.trim() ||
+        loadConfig().voice ||
+        firstEnv("PI_SAY_VOICE", "VOICECTL_TTS_VOICE", "VOICECTL_VOICE") ||
+        DEFAULT_VOICE
+    );
+}
+
+function currentSpeed(): number {
+    const raw = loadConfig().speed ?? Number(firstEnv("PI_SAY_SPEED", "VOICECTL_SPEED") ?? "1.0");
+    return Number.isFinite(raw) && raw > 0 ? raw : 1;
+}
+
+function localTtsUrl(): string {
+    return (
+        loadConfig().localTtsUrl ??
+        firstEnv("PI_SAY_TTS_URL", "VOICECTL_TTS_URL") ??
+        "http://127.0.0.1:8181"
+    );
+}
+
+function hudSocket(): string {
+    return (
+        loadConfig().hudSocket ??
+        firstEnv("PI_SAY_HUD_SOCKET", "VOICECTL_SOCKET") ??
+        (process.env.XDG_RUNTIME_DIR
+            ? join(process.env.XDG_RUNTIME_DIR, "voicectl.sock")
+            : join(homedir(), ".voicectl.sock"))
+    );
+}
+
+function googleApiKey(): string | undefined {
+    return (
+        loadConfig().googleApiKey ??
+        firstEnv("PI_SAY_GOOGLE_API_KEY", "VOICECTL_GOOGLE_API_KEY", "GOOGLE_API_KEY")
+    );
+}
+
+function googleSaPath(): string | undefined {
+    const configured = loadConfig().googleSaPath ?? firstEnv("PI_SAY_GOOGLE_SA", "GOOGLE_APPLICATION_CREDENTIALS");
+    if (configured)
+        return existsSync(configured) ? configured : undefined;
+    for (const candidate of [
+        join(homedir(), ".config/pi-say/google-sa.json"),
+        join(homedir(), ".config/voicectl/google-sa.json"),
+    ]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+
+function hasGoogleCreds(): boolean {
+    return Boolean(googleApiKey() ?? googleSaPath());
+}
+
+function tlog(phase: string, extra: Record<string, unknown> = {}): void {
+    const rec = { ts: Date.now() / 1000, src: "say", phase, ...extra };
+    try {
+        appendFileSync(TIMING, `${JSON.stringify(rec)}\n`);
+    } catch {
+        /* diagnostics only */
+    }
+}
+
+async function sendHud(payload: unknown): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+        const sock = createConnection(hudSocket());
+        let buf = "";
+        let settled = false;
+        const done = (err?: Error) => {
+            if (settled)
+                return;
+            settled = true;
+            sock.destroy();
+            if (err)
+                reject(err);
+            else
+                resolve();
+        };
+        sock.setTimeout(3000);
+        sock.on("connect", () => {
+            sock.write(`${JSON.stringify(payload)}\n`);
+        });
+        sock.on("data", (chunk) => {
+            buf += String(chunk);
+            if (!buf.includes("\n"))
+                return;
+            try {
+                const reply = JSON.parse(buf.split("\n", 1)[0] || "{}");
+                if (reply.ok === false)
+                    done(new Error(String(reply.error ?? "hud speak failed")));
+                else
+                    done();
+            } catch (err) {
+                done(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        sock.on("timeout", () => done(new Error("voicectl socket timeout")));
+        sock.on("error", (err) => done(err));
+        sock.on("close", () => {
+            if (!settled)
+                done(new Error("voicectl socket closed before reply"));
+        });
+    });
+}
+
+function clipSpoken(text: string): string {
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    if (words.length <= 12)
+        return words.join(" ");
+    return words.slice(0, 12).join(" ");
+}
+
+function isDaemonMissing(err: unknown): boolean {
+    const msg = String(err);
+    return msg.includes("voicectl socket") || msg.includes("ECONNREFUSED") || msg.includes("ENOENT");
+}
+
+function run(cmd: string, args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => {
+            stdout += String(d);
+        });
+        child.stderr.on("data", (d) => {
+            stderr += String(d);
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+}
+
+function languageOfVoice(name: string): string {
+    const match = /^([a-z]{2,3}-[A-Z]{2})/.exec(name);
+    return match ? match[1] : "en-US";
+}
+
+function isWav(buf: Buffer): boolean {
+    return (
+        buf.length >= 12 &&
+        buf.subarray(0, 4).toString("ascii") === "RIFF" &&
+        buf.subarray(8, 12).toString("ascii") === "WAVE"
+    );
+}
+
+function pcmToWav(pcm: Buffer, sampleRate: number): Buffer {
+    const header = Buffer.alloc(44);
+    header.write("RIFF", 0);
+    header.writeUInt32LE(36 + pcm.length, 4);
+    header.write("WAVE", 8);
+    header.write("fmt ", 12);
+    header.writeUInt32LE(16, 16);
+    header.writeUInt16LE(1, 20);
+    header.writeUInt16LE(1, 22);
+    header.writeUInt32LE(sampleRate, 24);
+    header.writeUInt32LE(sampleRate * 2, 28);
+    header.writeUInt16LE(2, 32);
+    header.writeUInt16LE(16, 34);
+    header.write("data", 36);
+    header.writeUInt32LE(pcm.length, 40);
+    return Buffer.concat([header, pcm]);
+}
+
+let googleToken: { token: string; exp: number } | null = null;
+
+async function googleAccessToken(saPath: string): Promise<string> {
+    if (googleToken && Date.now() < googleToken.exp)
+        return googleToken.token;
+    const sa = JSON.parse(readFileSync(saPath, "utf8")) as { client_email?: string; private_key?: string };
+    if (!sa.client_email || !sa.private_key)
+        throw new Error("service account JSON missing client_email/private_key");
+    const now = Math.floor(Date.now() / 1000);
+    const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url");
+    const claim = Buffer.from(
+        JSON.stringify({
+            iss: sa.client_email,
+            scope: "https://www.googleapis.com/auth/cloud-platform",
+            aud: "https://oauth2.googleapis.com/token",
+            iat: now,
+            exp: now + 3600,
+        }),
+    ).toString("base64url");
+    const signer = createSign("RSA-SHA256");
+    signer.update(`${header}.${claim}`);
+    const jwt = `${header}.${claim}.${signer.sign(sa.private_key, "base64url")}`;
+    const res = await fetch("https://oauth2.googleapis.com/token", {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: `grant_type=${encodeURIComponent("urn:ietf:params:oauth:grant-type:jwt-bearer")}&assertion=${jwt}`,
+    });
+    const data = (await res.json()) as { access_token?: string; error_description?: string; error?: string };
+    if (!data.access_token)
+        throw new Error(data.error_description ?? data.error ?? `token request failed (${res.status})`);
+    googleToken = { token: data.access_token, exp: Date.now() + 50 * 60 * 1000 };
+    return data.access_token;
+}
+
+async function googleAuth(): Promise<{ headers: Record<string, string>; query: string }> {
+    const key = googleApiKey();
+    if (key)
+        return { headers: { "content-type": "application/json" }, query: `?key=${encodeURIComponent(key)}` };
+    const saPath = googleSaPath();
+    if (!saPath)
+        throw new Error("no Google credentials");
+    return {
+        headers: { "content-type": "application/json", authorization: `Bearer ${await googleAccessToken(saPath)}` },
+        query: "",
+    };
+}
+
+async function synthGoogle(
+    text: string,
+    voice: string,
+    speed: number,
+    outPath: string,
+    signal?: AbortSignal,
+): Promise<void> {
+    const { headers, query } = await googleAuth();
+    const body = {
+        input: { text },
+        voice: { languageCode: languageOfVoice(voice), name: voice },
+        audioConfig: { audioEncoding: "LINEAR16", sampleRateHertz: 24000, speakingRate: speed },
+    };
+    const res = await fetch(`https://texttospeech.googleapis.com/v1/text:synthesize${query}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal,
+    });
+    const data = (await res.json().catch(() => ({}))) as {
+        audioContent?: string;
+        error?: { message?: string };
+    };
+    if (!res.ok || !data.audioContent)
+        throw new Error(`Google TTS ${res.status}: ${data.error?.message ?? res.statusText}`);
+    const buf = Buffer.from(data.audioContent, "base64");
+    await writeFile(outPath, isWav(buf) ? buf : pcmToWav(buf, 24000));
+}
+
+async function synthHttp(
+    url: string,
+    text: string,
+    voice: string,
+    speed: number,
+    outPath: string,
+    signal?: AbortSignal,
+): Promise<void> {
+    const res = await fetch(`${url}/tts`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ text, voice, speed }),
+        signal,
+    });
+    if (!res.ok) {
+        const err = await res.text().catch(() => res.statusText);
+        throw new Error(`TTS ${res.status}: ${err}`);
+    }
+    await writeFile(outPath, Buffer.from(await res.arrayBuffer()));
+}
+
+async function synthEspeak(text: string, outPath: string): Promise<string> {
+    for (const bin of ["espeak-ng", "espeak"]) {
+        try {
+            const r = await run(bin, ["-w", outPath, "--", text]);
+            if (r.code === 0)
+                return bin;
+        } catch {
+            /* try next binary */
+        }
+    }
+    throw new Error("espeak-ng/espeak not installed");
+}
+
+async function synthMacSay(text: string, outPath: string): Promise<void> {
+    const r = await run("say", ["-o", outPath, "--data-format=LEI16@22050", text]);
+    if (r.code !== 0)
+        throw new Error(`say failed: ${r.stderr.trim() || `exit ${r.code}`}`);
+}
+
+async function playFile(file: string): Promise<string> {
+    const override = firstEnv("PI_SAY_PLAYER");
+    const candidates: Array<[string, string[]]> = override
+        ? [[override, [file]]]
+        : IS_MAC
+          ? [["afplay", [file]]]
+          : [
+                ["pw-play", [file]],
+                ["paplay", [file]],
+                ["aplay", ["-q", file]],
+                ["ffplay", ["-nodisp", "-autoexit", "-loglevel", "quiet", file]],
+            ];
+    const errors: string[] = [];
+    for (const [bin, args] of candidates) {
+        try {
+            const r = await run(bin, args);
+            if (r.code === 0)
+                return bin;
+            errors.push(`${bin}: ${r.stderr.trim() || `exit ${r.code}`}`);
+        } catch (err) {
+            errors.push(`${bin}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    throw new Error(`no audio player available (${errors.join("; ")})`);
+}
+
+async function googleVoices(language: string): Promise<string[]> {
+    const { headers, query } = await googleAuth();
+    const sep = query ? "&" : "?";
+    const res = await fetch(
+        `https://texttospeech.googleapis.com/v1/voices${query}${sep}languageCode=${encodeURIComponent(language)}`,
+        { headers },
+    );
+    const data = (await res.json().catch(() => ({}))) as {
+        voices?: Array<{ name?: string }>;
+        error?: { message?: string };
+    };
+    if (!res.ok)
+        throw new Error(`Google voices ${res.status}: ${data.error?.message ?? res.statusText}`);
+    return (data.voices ?? []).map((v) => v.name ?? "").filter(Boolean).sort();
+}
+
+function describeSettings(): string {
+    const voice = currentVoice();
+    const parts = [`voice ${voice}`, `engine ${currentEngine()}`, `speed ${currentSpeed()}`];
+    if (hasGoogleCreds())
+        parts.push("Google credentials ready");
+    else
+        parts.push("no Google credentials, local fallback only");
+    return parts.join(", ");
+}
+
+export default function (pi: ExtensionAPI) {
+    pi.registerTool({
+        name: "say",
+        label: "Say",
+        description:
+            "Speak one short sentence aloud (under twelve words). Use it as an ack before slow work and once at the end with the result. Never speak lists, code, paths, diffs, or secrets. Use say_voice to change voice, speed, or engine.",
+        promptSnippet: "One short spoken sentence; ack before slow work; silent after visible desktop changes",
+        promptGuidelines: [
+            "Before updates, installs, search, or long bash: say a 3-6 word ack first, then tools in the same turn.",
+            "After: one sentence. No package lists or tool output.",
+            "Do not say after a successful tile, focus, or keybind.",
+            "If the user asks to change the spoken voice, use say_voice instead of editing files.",
+        ],
+        parameters: Type.Object({
+            text: Type.String({ description: "One short sentence, under twelve words" }),
+            interrupt: Type.Optional(Type.Boolean({ description: "Stop current speech first" })),
+            voice: Type.Optional(Type.String({ description: "One-off voice override for this sentence" })),
+        }),
+        async execute(_id, params, signal) {
+            const t0 = Date.now();
+            const text = clipSpoken(params.text);
+            if (!text)
+                return { content: [{ type: "text", text: "empty say ignored" }], details: {} };
+
+            const engine = currentEngine();
+            const voice = currentVoice(params.voice);
+            const speed = currentSpeed();
+            tlog("say_start", { chars: text.length, engine });
+
+            const dir = join(homedir(), ".cache/pi-say");
+            await mkdir(dir, { recursive: true });
+            const outPath = join(dir, `${Date.now()}-${randomBytes(4).toString("hex")}.wav`);
+
+            let used: string | undefined;
+            const failures: string[] = [];
+
+            if (engine !== "local" && engine !== "espeak" && hasGoogleCreds()) {
+                try {
+                    await synthGoogle(text, voice, speed, outPath, signal);
+                    used = "google";
+                } catch (err) {
+                    failures.push(`google: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            const url = localTtsUrl();
+            if (!used && engine !== "espeak" && !/^(off|none|-)$/i.test(url)) {
+                try {
+                    await synthHttp(url, text, voice, speed, outPath, signal);
+                    used = "local";
+                } catch (err) {
+                    failures.push(`local: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (!used && engine !== "espeak" && IS_MAC) {
+                try {
+                    await synthMacSay(text, outPath);
+                    used = "say";
+                } catch (err) {
+                    failures.push(`say: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (!used) {
+                try {
+                    used = await synthEspeak(text, outPath);
+                } catch (err) {
+                    failures.push(`espeak: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (!used)
+                throw new Error(`could not synthesize speech (${failures.join("; ")})`);
+
+            tlog("say_tts_done", { ms: Date.now() - t0, engine: used, voice });
+
+            try {
+                await sendHud({ cmd: "speak", file: outPath, interrupt: Boolean(params.interrupt) });
+                tlog("say_hud_acked", { ms: Date.now() - t0 });
+                return {
+                    content: [{ type: "text", text: `spoke: ${text}` }],
+                    details: { engine: used, voice, file: outPath },
+                };
+            } catch (err) {
+                if (!isDaemonMissing(err))
+                    throw err;
+            }
+
+            const player = await playFile(outPath);
+            tlog("say_player_played", { ms: Date.now() - t0, player });
+            return {
+                content: [{ type: "text", text: `spoke (${player}): ${text}` }],
+                details: { engine: used, voice, player, file: outPath },
+            };
+        },
+    });
+
+    pi.registerTool({
+        name: "say_voice",
+        label: "Say Voice",
+        description:
+            "Change or inspect the voice, speed, and engine used by the say tool. Use when the user asks to change how they are spoken to. Persists in ~/.config/pi-say/config.json.",
+        promptSnippet: "Change the spoken voice/speed/engine for say",
+        parameters: Type.Object({
+            voice: Type.Optional(Type.String({ description: "Google voice name, e.g. en-US-Chirp3-HD-Aoede" })),
+            speed: Type.Optional(Type.Number({ description: "Speaking rate, e.g. 1.0" })),
+            engine: Type.Optional(Type.String({ description: "auto, google, local, or espeak" })),
+            list: Type.Optional(Type.Boolean({ description: "List available Google voices" })),
+            language: Type.Optional(Type.String({ description: "Language code for list, default from current voice" })),
+        }),
+        async execute(_id, params) {
+            if (params.list) {
+                const language = params.language?.trim() || languageOfVoice(currentVoice());
+                try {
+                    const names = await googleVoices(language);
+                    const shown = names.slice(0, 60).join(", ");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `${names.length} ${language} voices: ${shown}${names.length > 60 ? ", …" : ""}`,
+                            },
+                        ],
+                        details: { voices: names },
+                    };
+                } catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `could not list Google voices: ${err instanceof Error ? err.message : String(err)}`,
+                            },
+                        ],
+                        details: {},
+                    };
+                }
+            }
+
+            const patch: SayConfig = {};
+            if (params.voice?.trim())
+                patch.voice = params.voice.trim();
+            if (typeof params.speed === "number" && Number.isFinite(params.speed) && params.speed > 0)
+                patch.speed = params.speed;
+            if (params.engine) {
+                const engine = params.engine.trim().toLowerCase();
+                if (!ENGINES.includes(engine))
+                    return {
+                        content: [{ type: "text", text: `unknown engine ${engine}; use one of ${ENGINES.join(", ")}` }],
+                        details: {},
+                    };
+                patch.engine = engine;
+            }
+
+            if (Object.keys(patch).length > 0)
+                saveConfig(patch);
+            return {
+                content: [{ type: "text", text: describeSettings() }],
+                details: { config: { ...loadConfig() } },
+            };
+        },
+    });
+
+    pi.registerCommand("voice", {
+        description: "Show or change the say voice (/voice <name>, /voice list, /voice google|local|espeak)",
+        getArgumentCompletions: (prefix: string) => {
+            const items = [...ENGINES, "list", "speed", ...COMMON_VOICES, currentVoice()];
+            const seen = new Set<string>();
+            const matches = items
+                .filter((item) => {
+                    if (seen.has(item))
+                        return false;
+                    seen.add(item);
+                    return item.startsWith(prefix);
+                })
+                .map((item) => ({ value: item, label: item }));
+            return matches.length > 0 ? matches : null;
+        },
+        handler: async (args, ctx) => {
+            const arg = args.trim();
+            if (!arg) {
+                ctx.ui.notify(describeSettings(), "info");
+                return;
+            }
+            if (arg === "list") {
+                try {
+                    const names = await googleVoices(languageOfVoice(currentVoice()));
+                    ctx.ui.notify(`${names.length} voices: ${names.slice(0, 40).join(", ")}`, "info");
+                } catch (err) {
+                    ctx.ui.notify(`could not list voices: ${err instanceof Error ? err.message : String(err)}`, "error");
+                }
+                return;
+            }
+            if (ENGINES.includes(arg.toLowerCase())) {
+                saveConfig({ engine: arg.toLowerCase() });
+                ctx.ui.notify(describeSettings(), "info");
+                return;
+            }
+            const speedMatch = /^speed\s+([0-9]*\.?[0-9]+)$/i.exec(arg);
+            if (speedMatch) {
+                const speed = Number(speedMatch[1]);
+                if (Number.isFinite(speed) && speed > 0) {
+                    saveConfig({ speed });
+                    ctx.ui.notify(describeSettings(), "info");
+                } else {
+                    ctx.ui.notify("speed must be a positive number", "error");
+                }
+                return;
+            }
+            saveConfig({ voice: arg });
+            ctx.ui.notify(describeSettings(), "info");
+        },
+    });
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "pi-say",
+  "version": "1.1.0",
+  "description": "Spoken output for pi: a say tool that speaks short sentences through local TTS (Kokoro/Piper HTTP server, macOS say, or espeak-ng).",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "tts",
+    "text-to-speech",
+    "speech",
+    "voice",
+    "accessibility"
+  ],
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}