oma-coding-agent 1.1.4

package/src/tools/yield.ts

@@ -0,0 +1,269 @@
+/**
+ * Submit result tool for structured subagent output.
+ *
+ * Subagents must call this tool to finish and return structured JSON output.
+ */
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { TSchema } from "@oh-my-pi/pi-ai/types";
+import {
+	dereferenceJsonSchema,
+	isValidJsonSchema,
+	type JsonSchemaValidationResult,
+	sanitizeSchemaForStrictMode,
+	tryEnforceStrictSchema,
+} from "@oh-my-pi/pi-ai/utils/schema";
+import { subprocessToolRegistry } from "../task/subprocess-tool-registry";
+import type { ToolSession } from ".";
+import { buildOutputValidator, formatAllValidationIssues } from "./output-schema-validator";
+
+export interface YieldDetails {
+	data: unknown;
+	status: "success" | "aborted";
+	error?: string;
+	/**
+	 * Set when the yield tool exhausted its in-tool schema-retry budget
+	 * (MAX_SCHEMA_RETRIES) and accepted the data anyway. Surfaced so the
+	 * executor's post-mortem finalizer can honor the override instead of
+	 * re-rejecting the same payload with `schema_violation` — keeping the
+	 * subagent's acceptance and the parent's view of the result in lockstep.
+	 */
+	schemaOverridden?: boolean;
+}
+
+function formatSchema(schema: unknown): string {
+	if (schema === undefined) return "No schema provided.";
+	if (typeof schema === "string") return schema;
+	try {
+		return JSON.stringify(schema, null, 2);
+	} catch {
+		return "[unserializable schema]";
+	}
+}
+
+function looseRecordSchema(description: string): Record<string, unknown> {
+	return {
+		type: "object",
+		additionalProperties: true,
+		description,
+	};
+}
+
+function hasUnresolvedRefs(schema: unknown): boolean {
+	if (schema == null) return false;
+	if (Array.isArray(schema)) {
+		for (const item of schema) {
+			if (hasUnresolvedRefs(item)) return true;
+		}
+		return false;
+	}
+	if (typeof schema !== "object") return false;
+	const record = schema as Record<string, unknown>;
+	if (typeof record.$ref === "string") return true;
+	for (const key in record) {
+		if (key === "const" || key === "default" || key === "enum" || key === "examples") continue;
+		if (hasUnresolvedRefs(record[key])) return true;
+	}
+	return false;
+}
+
+function wrapYieldParameters(dataSchema: Record<string, unknown>): Record<string, unknown> {
+	return {
+		type: "object",
+		additionalProperties: false,
+		description: "submit data or error",
+		properties: {
+			result: {
+				anyOf: [
+					{
+						type: "object",
+						additionalProperties: false,
+						description: "task succeeded",
+						properties: { data: dataSchema },
+						required: ["data"],
+					},
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							error: { type: "string", description: "error message" },
+						},
+						required: ["error"],
+					},
+				],
+			},
+		},
+		required: ["result"],
+	};
+}
+
+/**
+ * Max consecutive schema-validation failures before the yield tool overrides validation
+ * and lets non-conforming data through. The override is a safety net for schemas the
+ * JTD→JSON-Schema converter cannot fully express; it should not be reached during normal
+ * model retries. Three matches the existing "3 reminders" pattern elsewhere in the agent
+ * runtime.
+ */
+const MAX_SCHEMA_RETRIES = 3;
+
+export class YieldTool implements AgentTool<TSchema, YieldDetails> {
+	readonly name = "yield";
+	readonly approval = "read" as const;
+	readonly label = "Submit Result";
+	readonly description =
+		"Finish the task with structured JSON output. Call exactly once at the end of the task.\n\n" +
+		'Pass `result: { data: <your output> }` for success, or `result: { error: "message" }` for failure.\n' +
+		"The `data`/`error` wrapper is required — do not put your output directly in `result`.";
+	readonly parameters: TSchema;
+	strict = true;
+	readonly intent = "omit" as const;
+	lenientArgValidation = true;
+
+	readonly #validate?: (value: unknown) => JsonSchemaValidationResult;
+	#schemaValidationFailures = 0;
+
+	constructor(session: ToolSession) {
+		let validate: ((value: unknown) => JsonSchemaValidationResult) | undefined;
+		let parameters: TSchema;
+
+		try {
+			const {
+				validator,
+				jsonSchema: normalizedSchema,
+				normalized,
+				error: schemaError,
+			} = buildOutputValidator(session.outputSchema);
+			if (validator) {
+				validate = value => validator.validate(value);
+			}
+
+			const schemaHint = formatSchema(normalizedSchema ?? session.outputSchema);
+			const schemaDescription = schemaError
+				? `Structured JSON output (output schema invalid; accepting unconstrained object): ${schemaError}`
+				: `Structured output matching the schema:\n${schemaHint}`;
+			let sanitizedSchema: Record<string, unknown> | undefined;
+			if (!schemaError && normalizedSchema !== undefined) {
+				const strictProbe = tryEnforceStrictSchema(normalizedSchema);
+				if (strictProbe.strict) {
+					sanitizedSchema = sanitizeSchemaForStrictMode(normalizedSchema);
+				} else {
+					sanitizedSchema = normalizedSchema;
+					this.strict = false;
+				}
+			} else if (!schemaError && normalized === true) {
+				sanitizedSchema = {};
+				this.strict = false;
+			}
+
+			let dataSchema: Record<string, unknown>;
+			if (sanitizedSchema !== undefined) {
+				const resolved = dereferenceJsonSchema({
+					...sanitizedSchema,
+					description: schemaDescription,
+				}) as Record<string, unknown>;
+				if (hasUnresolvedRefs(resolved)) {
+					throw new Error("schema contains unresolved $ref after dereferencing");
+				}
+				dataSchema = resolved;
+			} else {
+				this.strict = false;
+				dataSchema = looseRecordSchema(
+					schemaError ? schemaDescription : "Structured JSON output (no schema specified)",
+				);
+			}
+			parameters = wrapYieldParameters(dataSchema);
+			JSON.stringify(parameters);
+			if (!isValidJsonSchema(parameters)) throw new Error("yield parameters schema is invalid");
+		} catch (err) {
+			const errorMsg = err instanceof Error ? err.message : String(err);
+			parameters = wrapYieldParameters(
+				looseRecordSchema(`Structured JSON output (schema processing failed: ${errorMsg})`),
+			);
+			validate = undefined;
+			this.strict = false;
+		}
+
+		this.#validate = validate;
+		this.parameters = parameters;
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: unknown,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<YieldDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<YieldDetails>> {
+		const raw = params as Record<string, unknown>;
+		const rawResult = raw.result;
+		if (!rawResult || typeof rawResult !== "object" || Array.isArray(rawResult)) {
+			throw new Error("result must be an object containing either data or error");
+		}
+
+		const resultRecord = rawResult as Record<string, unknown>;
+		const errorMessage = typeof resultRecord.error === "string" ? resultRecord.error : undefined;
+		const data = resultRecord.data;
+
+		if (errorMessage !== undefined && data !== undefined) {
+			throw new Error("result cannot contain both data and error");
+		}
+		if (errorMessage === undefined && data === undefined) {
+			throw new Error(
+				'result must contain either `data` or `error`. Use `{result: {data: <your output>}}` for success or `{result: {error: "message"}}` for failure.',
+			);
+		}
+
+		const status = errorMessage !== undefined ? "aborted" : "success";
+		let schemaValidationOverridden = false;
+		if (status === "success") {
+			if (data === undefined || data === null) {
+				throw new Error("data is required when yield indicates success");
+			}
+			if (this.#validate) {
+				const parsed = this.#validate(data);
+				if (!parsed.success) {
+					this.#schemaValidationFailures++;
+					if (this.#schemaValidationFailures <= MAX_SCHEMA_RETRIES) {
+						const remaining = MAX_SCHEMA_RETRIES - this.#schemaValidationFailures;
+						const retryHint =
+							remaining > 0
+								? ` Call yield again with the corrected shape — ${remaining} retry attempt(s) remain before the schema constraint is dropped.`
+								: " Call yield again with the corrected shape — this is the final retry before the schema constraint is dropped.";
+						throw new Error(
+							`Output does not match schema: ${formatAllValidationIssues(parsed.issues)}.${retryHint}`,
+						);
+					}
+					schemaValidationOverridden = true;
+				}
+			}
+		}
+
+		const responseText =
+			status === "aborted"
+				? `Task aborted: ${errorMessage}`
+				: schemaValidationOverridden
+					? `Result submitted (schema validation overridden after ${this.#schemaValidationFailures} failed attempt(s)).`
+					: "Result submitted.";
+		return {
+			content: [{ type: "text", text: responseText }],
+			details: { data, status, error: errorMessage, schemaOverridden: schemaValidationOverridden || undefined },
+		};
+	}
+}
+
+// Register subprocess tool handler for extraction + termination.
+subprocessToolRegistry.register<YieldDetails>("yield", {
+	extractData: event => {
+		const details = event.result?.details;
+		if (!details || typeof details !== "object") return undefined;
+		const record = details as Record<string, unknown>;
+		const status = record.status;
+		if (status !== "success" && status !== "aborted") return undefined;
+		return {
+			data: record.data,
+			status,
+			error: typeof record.error === "string" ? record.error : undefined,
+			schemaOverridden: record.schemaOverridden === true ? true : undefined,
+		};
+	},
+	shouldTerminate: event => !event.isError,
+});

package/src/tts/downloader.ts

@@ -0,0 +1,64 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getTinyModelsCacheDir } from "@oh-my-pi/pi-utils";
+import { getTtsLocalModelSpec } from "./models";
+import { isTtsRuntimeCached } from "./runtime";
+import { ttsClient } from "./tts-client";
+
+export interface TtsDownloadProgress {
+	stage: string;
+	/** Integer 0–100 download percent when known. */
+	percent?: number;
+}
+
+/**
+ * Whether the selected local TTS model and the side Kokoro runtime are already
+ * present. transformers.js stores `main`-revision files at
+ * `<cacheDir>/<repo>/...`, so any `.onnx` weight under the repo dir means the
+ * model weights can load without a network fetch; the Kokoro package runtime is
+ * version-keyed separately and must also exist before setup can report ready.
+ */
+export async function isTtsModelCached(modelKey: string): Promise<boolean> {
+	const spec = getTtsLocalModelSpec(modelKey);
+	if (!spec) return false;
+	const repoDir = path.join(getTinyModelsCacheDir(), ...spec.repo.split("/"));
+	try {
+		const entries = await fs.readdir(repoDir, { recursive: true });
+		const hasWeights = entries.some(entry => typeof entry === "string" && entry.endsWith(".onnx"));
+		return hasWeights && (await isTtsRuntimeCached());
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Ensure the selected local TTS model is downloaded into the transformers.js
+ * cache (and warm in the worker), streaming integer-percent Hub progress. The
+ * worker resolves the request once every model file is cached. Returns `false`
+ * if the worker is unavailable or the download failed.
+ */
+export async function downloadTtsModel(
+	modelKey: string,
+	onProgress?: (progress: TtsDownloadProgress) => void,
+	signal?: AbortSignal,
+): Promise<boolean> {
+	const spec = getTtsLocalModelSpec(modelKey);
+	if (!spec) return false;
+	onProgress?.({ stage: `Preparing ${spec.label}...` });
+	return ttsClient.downloadModel(spec.key, {
+		signal,
+		onProgress: event => {
+			if (event.status === "ready" || event.status === "done") {
+				onProgress?.({ stage: `${spec.label} ready`, percent: 100 });
+				return;
+			}
+			const percent =
+				typeof event.total === "number" && event.total > 0 && typeof event.loaded === "number"
+					? Math.round((event.loaded / event.total) * 100)
+					: typeof event.progress === "number"
+						? Math.round(event.progress)
+						: undefined;
+			onProgress?.({ stage: `Downloading ${spec.label}`, percent });
+		},
+	});
+}

package/src/tts/index.ts

@@ -0,0 +1,8 @@
+export * from "./downloader";
+export * from "./models";
+export * from "./runtime";
+export * from "./tts-client";
+export * from "./tts-protocol";
+export * from "./tts-worker";
+export * from "./vocalizer";
+export * from "./wav";

package/src/tts/models.ts

@@ -0,0 +1,137 @@
+import type { TinyModelDtype } from "../tiny/dtype";
+
+/**
+ * Voice exposed by a local TTS model. Kokoro ships a fixed catalog of named
+ * voices; a voice is just a stable id (e.g. `af_heart`) plus a display label.
+ * Selection is purely on-device — generating with a different voice needs no
+ * extra network fetch once the model weights are cached.
+ */
+export interface TtsLocalVoiceSpec {
+	id: string;
+	label: string;
+}
+
+/**
+ * A local (on-device, ONNX) text-to-speech model the worker can load. `repo` is
+ * the Hugging Face model id loaded through `kokoro-js`
+ * (`KokoroTTS.from_pretrained`), which runs on the same `@huggingface/transformers`
+ * + `onnxruntime` runtime as the rest of the tiny-model stack and bundles the
+ * misaki/espeak phonemizer Kokoro needs. `dtype` is the default ONNX precision
+ * (overridable via `providers.tinyModelDtype`/`PI_TINY_DTYPE`).
+ */
+export interface TtsLocalModelSpec {
+	key: string;
+	repo: string;
+	dtype: TinyModelDtype;
+	/** PCM sample rate the model emits; fallback only — the worker uses the value RawAudio reports. */
+	sampleRate: number;
+	label: string;
+	description: string;
+	/** First entry is the model's default voice. */
+	voices: readonly TtsLocalVoiceSpec[];
+}
+
+/**
+ * Curated Kokoro-82M voice catalog. Kokoro ships ~28 voices; we surface the
+ * higher-graded ones across American/British × female/male so the picker stays
+ * useful without listing every D/F-grade sample. `af_heart` (grade A) leads and
+ * is the default voice. Grades are Kokoro's own `overallGrade` ratings.
+ */
+export const KOKORO_VOICES: readonly TtsLocalVoiceSpec[] = [
+	{ id: "af_heart", label: "Heart (American female)" },
+	{ id: "af_bella", label: "Bella (American female)" },
+	{ id: "af_nicole", label: "Nicole (American female)" },
+	{ id: "af_aoede", label: "Aoede (American female)" },
+	{ id: "af_kore", label: "Kore (American female)" },
+	{ id: "af_sarah", label: "Sarah (American female)" },
+	{ id: "am_michael", label: "Michael (American male)" },
+	{ id: "am_fenrir", label: "Fenrir (American male)" },
+	{ id: "am_puck", label: "Puck (American male)" },
+	{ id: "bf_emma", label: "Emma (British female)" },
+	{ id: "bm_george", label: "George (British male)" },
+	{ id: "bm_fable", label: "Fable (British male)" },
+] as const;
+
+/** Default voice within the default model — Kokoro's flagship grade-A voice. */
+export const DEFAULT_TTS_VOICE = "af_heart";
+
+/** Default local TTS model used when `tts.localModel` is unset. */
+export const DEFAULT_TTS_LOCAL_MODEL_KEY = "kokoro";
+
+/**
+ * Local TTS model registry. Kokoro-82M is the on-device SoTA tiny TTS (tops the
+ * TTS Arena leaderboard); the `onnx-community` ONNX export runs through
+ * `kokoro-js` on the shared transformers.js/onnxruntime worker. q8 keeps the
+ * weights ~100 MB and CPU inference fast while preserving quality. One model
+ * spans every voice/accent — language selection is a voice choice, not a
+ * separate download.
+ */
+export const TTS_LOCAL_MODELS = [
+	{
+		key: "kokoro",
+		repo: "onnx-community/Kokoro-82M-v1.0-ONNX",
+		dtype: "q8",
+		sampleRate: 24_000,
+		label: "Kokoro-82M",
+		description: "Kokoro-82M neural TTS — SoTA on-device quality, multi-voice, fully local",
+		voices: KOKORO_VOICES,
+	},
+] as const satisfies readonly TtsLocalModelSpec[];
+
+export type TtsLocalModelKey = (typeof TTS_LOCAL_MODELS)[number]["key"];
+
+export const TTS_LOCAL_MODEL_VALUES = ["kokoro"] as const;
+
+type MissingTtsModelValue = Exclude<TtsLocalModelKey, (typeof TTS_LOCAL_MODEL_VALUES)[number]>;
+type ExtraTtsModelValue = Exclude<(typeof TTS_LOCAL_MODEL_VALUES)[number], TtsLocalModelKey>;
+const TTS_LOCAL_MODEL_VALUES_MATCH_REGISTRY: MissingTtsModelValue extends never
+	? ExtraTtsModelValue extends never
+		? true
+		: never
+	: never = true;
+void TTS_LOCAL_MODEL_VALUES_MATCH_REGISTRY;
+
+export const TTS_LOCAL_MODEL_OPTIONS = [
+	{
+		value: "kokoro",
+		label: "Kokoro-82M",
+		description: "Kokoro-82M neural TTS — SoTA on-device quality, multi-voice, fully local",
+	},
+] as const satisfies ReadonlyArray<{ value: TtsLocalModelKey; label: string; description: string }>;
+
+/** Voice options for the `tts.localVoice` setting picker (default model's catalog). */
+export const TTS_LOCAL_VOICE_OPTIONS = KOKORO_VOICES.map(voice => ({
+	value: voice.id,
+	label: voice.label,
+})) as ReadonlyArray<{ value: string; label: string }>;
+
+/** Accepted `tts.localVoice` values (default model's catalog) for schema validation. */
+export const TTS_LOCAL_VOICE_VALUES = KOKORO_VOICES.map(voice => voice.id) as readonly string[];
+
+export function getTtsLocalModelSpec(key: string): TtsLocalModelSpec | undefined {
+	return TTS_LOCAL_MODELS.find(model => model.key === key);
+}
+
+export function isTtsLocalModelKey(value: string): value is TtsLocalModelKey {
+	return getTtsLocalModelSpec(value) !== undefined;
+}
+
+/** Resolve a model key (or the default) to its Hugging Face repo id. */
+export function resolveTtsRepo(modelKey: string | undefined): string {
+	const spec = (modelKey && getTtsLocalModelSpec(modelKey)) || getTtsLocalModelSpec(DEFAULT_TTS_LOCAL_MODEL_KEY);
+	if (!spec) throw new Error(`No local TTS model registered for key: ${modelKey ?? DEFAULT_TTS_LOCAL_MODEL_KEY}`);
+	return spec.repo;
+}
+
+/**
+ * Resolve a requested voice id to a concrete voice the model supports, falling
+ * back to the model's default voice (first entry) when the id is unknown or the
+ * legacy `"default"` sentinel. The returned id is always a valid Kokoro voice.
+ */
+export function resolveTtsVoice(modelKey: string | undefined, voice: string | undefined): string {
+	const spec = (modelKey && getTtsLocalModelSpec(modelKey)) || getTtsLocalModelSpec(DEFAULT_TTS_LOCAL_MODEL_KEY);
+	const fallback = spec?.voices[0]?.id ?? DEFAULT_TTS_VOICE;
+	if (!spec || !voice) return fallback;
+	const match = spec.voices.find(v => v.id === voice);
+	return match ? match.id : fallback;
+}

package/src/tts/player.ts

@@ -0,0 +1,137 @@
+/**
+ * Cross-platform audio-file playback via the system's built-in players.
+ *
+ * The selection logic is split into a pure, injectable builder
+ * ({@link playerCommandsFor}) so it can be unit-tested without spawning a
+ * process or touching PATH, and a thin runtime wrapper ({@link playAudioFile})
+ * that walks the resulting fallback chain.
+ */
+import * as fs from "node:fs/promises";
+import { $which } from "@oh-my-pi/pi-utils";
+import { getToolPath } from "../utils/tools-manager";
+
+export interface PlayerCommand {
+	cmd: string;
+	args: string[];
+}
+
+/** Injection seam for {@link playerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface PlayerLookup {
+	which?: (bin: string) => string | null;
+	ffmpeg?: () => string | null;
+}
+
+/**
+ * Build the ordered list of playback commands to try for `filePath` on the
+ * given platform. Pure + injectable so the selection logic is testable without
+ * spawning anything.
+ *
+ * - darwin: `afplay` (always present on macOS).
+ * - win32: PowerShell `Media.SoundPlayer.PlaySync()` (no extra deps).
+ * - linux/other POSIX: `paplay` (PulseAudio) → `aplay` (ALSA) → the bundled
+ *   static `ffmpeg` (`-f pulse` then `-f alsa`). Empty result means nothing is
+ *   available and the caller should surface an install hint.
+ */
+export function playerCommandsFor(
+	platform: NodeJS.Platform,
+	filePath: string,
+	lookup: PlayerLookup = {},
+): PlayerCommand[] {
+	const which = lookup.which ?? $which;
+	const ffmpeg = lookup.ffmpeg ?? ((): string | null => getToolPath("ffmpeg"));
+
+	if (platform === "darwin") {
+		return [{ cmd: "afplay", args: [filePath] }];
+	}
+	if (platform === "win32") {
+		return [
+			{
+				cmd: "powershell",
+				args: ["-NoProfile", "-Command", `(New-Object Media.SoundPlayer '${filePath}').PlaySync()`],
+			},
+		];
+	}
+
+	// Linux and other POSIX desktops share the PulseAudio/ALSA fallback chain.
+	const commands: PlayerCommand[] = [];
+	const paplay = which("paplay");
+	if (paplay) commands.push({ cmd: paplay, args: [filePath] });
+	const aplay = which("aplay");
+	if (aplay) commands.push({ cmd: aplay, args: [filePath] });
+	const ffmpegBin = ffmpeg();
+	if (ffmpegBin) {
+		commands.push({
+			cmd: ffmpegBin,
+			args: ["-loglevel", "error", "-nostdin", "-i", filePath, "-f", "pulse", "default"],
+		});
+		commands.push({
+			cmd: ffmpegBin,
+			args: ["-loglevel", "error", "-nostdin", "-i", filePath, "-f", "alsa", "default"],
+		});
+	}
+	return commands;
+}
+
+export interface PlayAudioOptions {
+	signal?: AbortSignal;
+}
+
+function playbackAbortError(signal: AbortSignal): Error {
+	const reason = signal.reason;
+	return reason instanceof Error ? reason : new DOMException("Audio playback aborted", "AbortError");
+}
+
+/**
+ * Play `filePath` through the speakers, trying each candidate command in order
+ * and returning on the first clean exit. Throws an actionable Error if no
+ * player exists or every candidate fails (with the collected stderr).
+ */
+export async function playAudioFile(filePath: string, options: PlayAudioOptions = {}): Promise<void> {
+	const { signal } = options;
+	if (signal?.aborted) throw playbackAbortError(signal);
+	const commands = playerCommandsFor(process.platform, filePath);
+	if (commands.length === 0) {
+		throw new Error(
+			"No audio player available. Install PulseAudio (paplay) or ALSA (aplay), " +
+				"or run `omp setup speech` to download a bundled ffmpeg.",
+		);
+	}
+
+	const failures: string[] = [];
+	for (const command of commands) {
+		if (signal?.aborted) throw playbackAbortError(signal);
+		try {
+			const proc = Bun.spawn([command.cmd, ...command.args], { stdout: "ignore", stderr: "pipe" });
+			let killTimer: NodeJS.Timeout | undefined;
+			const abort = (): void => {
+				proc.kill("SIGTERM");
+				killTimer = setTimeout(() => proc.kill("SIGKILL"), 500);
+				killTimer.unref?.();
+			};
+			signal?.addEventListener("abort", abort, { once: true });
+			try {
+				const code = await proc.exited;
+				if (signal?.aborted) throw playbackAbortError(signal);
+				if (code === 0) return;
+				let stderr = "";
+				if (proc.stderr && typeof proc.stderr !== "number") {
+					stderr = await new Response(proc.stderr as ReadableStream).text();
+				}
+				failures.push(`${command.cmd} exited ${code}${stderr.trim() ? `: ${stderr.trim()}` : ""}`);
+			} finally {
+				signal?.removeEventListener("abort", abort);
+				if (killTimer) clearTimeout(killTimer);
+			}
+		} catch (err) {
+			if (signal?.aborted) throw playbackAbortError(signal);
+			failures.push(`${command.cmd}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+
+	throw new Error(`Audio playback failed:\n${failures.join("\n")}`);
+}
+
+/** Best-effort temp-file cleanup used by callers after playback. */
+export async function removeTempFile(filePath: string): Promise<void> {
+	await fs.unlink(filePath).catch(() => {});
+}

package/src/tts/runtime.ts

@@ -0,0 +1,21 @@
+import * as path from "node:path";
+import { getTinyModelsCacheDir } from "@oh-my-pi/pi-utils";
+
+export const KOKORO_PACKAGE = "kokoro-js";
+export const KOKORO_VERSION = "1.2.1";
+export const ONNXRUNTIME_NODE_PACKAGE = "onnxruntime-node";
+export const ONNXRUNTIME_NODE_VERSION = "1.26.0";
+
+export function getTtsRuntimeDir(): string {
+	const runtimeKey = KOKORO_VERSION.replace(/[^A-Za-z0-9._-]/g, "_");
+	return path.join(path.dirname(getTinyModelsCacheDir()), "tts-runtime", `kokoro-${runtimeKey}`);
+}
+
+export async function isTtsRuntimeCached(): Promise<boolean> {
+	try {
+		const pkg = await Bun.file(path.join(getTtsRuntimeDir(), "node_modules", KOKORO_PACKAGE, "package.json")).json();
+		return typeof pkg === "object" && pkg !== null && "version" in pkg && pkg.version === KOKORO_VERSION;
+	} catch {
+		return false;
+	}
+}