@oh-my-pi/pi-coding-agent 17.1.0 → 17.1.2

package/src/tools/xdev.ts

@@ -30,10 +30,11 @@ import { parseStreamingJson } from "@oh-my-pi/pi-utils";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { XD_URL_PREFIX } from "../internal-urls/xd-protocol";
 import type { Theme } from "../modes/theme/theme";
+import { renderDefaultToolExecution } from "./default-renderer";
 import type { Tool } from "./index";
 import { replaceTabs } from "./render-utils";
 import type { ToolRenderer } from "./renderers";
-import { ToolError } from "./tool-errors";
+import { renderError, ToolAbortError, ToolError } from "./tool-errors";
 
 /**
  * Discoverable built-ins that must stay top-level even when xdev mounting is
@@ -389,28 +390,45 @@ export class XdevRegistry {
 		onUpdate?: AgentToolUpdateCallback,
 		context?: AgentToolContext,
 	): Promise<{ result: AgentToolResult<unknown>; xdev: XdevDispatch }> {
-		const inst = this.#resolve(name);
+		let xdev: XdevDispatch = { tool: name, mode: "execute" };
+		try {
+			const inst = this.#resolve(name);
+
+			if (HELP_CONTENT_RE.test(content)) {
+				return {
+					result: { content: [{ type: "text", text: renderDocs(inst) }] },
+					xdev: { tool: name, mode: "help" },
+				};
+			}
 
-		if (HELP_CONTENT_RE.test(content)) {
+			const validated = parseDeviceArgs(inst as AiTool, content, toolCallId, () => renderDocs(inst));
+			xdev = { ...xdev, args: validated };
+			const innerOnUpdate: AgentToolUpdateCallback | undefined = onUpdate
+				? partial =>
+						onUpdate({
+							content: partial.content,
+							details: { xdev: { ...xdev, inner: partial.details } },
+							isError: partial.isError,
+						})
+				: undefined;
+			const result = await inst.execute(toolCallId, validated as never, signal, innerOnUpdate, context);
+			return { result, xdev: { ...xdev, inner: result.details } };
+		} catch (error) {
+			if (
+				error instanceof ToolAbortError ||
+				signal?.aborted ||
+				(error instanceof Error && error.name === "AbortError")
+			) {
+				throw error;
+			}
 			return {
-				result: { content: [{ type: "text", text: renderDocs(inst) }] },
-				xdev: { tool: name, mode: "help" },
+				result: {
+					content: [{ type: "text", text: renderError(error) }],
+					isError: true,
+				},
+				xdev,
 			};
 		}
-
-		const validated = parseDeviceArgs(inst as AiTool, content, toolCallId, () => renderDocs(inst));
-
-		const xdevBase: XdevDispatch = { tool: name, mode: "execute", args: validated };
-		const innerOnUpdate: AgentToolUpdateCallback | undefined = onUpdate
-			? partial =>
-					onUpdate({
-						content: partial.content,
-						details: { xdev: { ...xdevBase, inner: partial.details } },
-						isError: partial.isError,
-					})
-			: undefined;
-		const result = await inst.execute(toolCallId, validated as never, signal, innerOnUpdate, context);
-		return { result, xdev: { ...xdevBase, inner: result.details } };
 	}
 }
 
@@ -423,9 +441,8 @@ export class XdevRegistry {
  *  map keyed by name. */
 function resolveDeviceRenderer(
 	name: string,
-	resolveMounted: ((name: string) => Tool | undefined) | undefined,
+	mounted: Tool | undefined,
 ): Pick<ToolRenderer, "renderCall" | "renderResult" | "mergeCallAndResult"> | undefined {
-	const mounted = resolveMounted?.(name);
 	if (mounted && (mounted.renderCall || mounted.renderResult)) {
 		// A mounted AgentTool exposes the same renderCall/renderResult/mergeCallAndResult
 		// surface as a static ToolRenderer; only the parameter generics differ, so unify
@@ -447,11 +464,13 @@ export function renderXdevCall(
 	theme: Theme,
 	resolveMounted?: (name: string) => Tool | undefined,
 ): Component | undefined {
-	const renderer = resolveDeviceRenderer(name, resolveMounted);
+	const mounted = resolveMounted?.(name);
+	const renderer = resolveDeviceRenderer(name, mounted);
+	const args = decodeInnerArgs(content);
 	if (renderer?.renderCall) {
-		return renderer.renderCall(decodeInnerArgs(content), options, theme);
+		return renderer.renderCall(args, options, theme);
 	}
-	return new Text(theme.fg("toolTitle", theme.bold(`${XD_URL_PREFIX}${name}`)), 0, 0);
+	return renderDefaultToolExecution({ label: mounted?.label ?? name, args, options }, theme);
 }
 
 /** Forward an `xd://` dispatch result to the mounted tool's renderer. */
@@ -469,7 +488,8 @@ export function renderXdevResult(
 	if (dispatch.mode === "help") {
 		return text ? new Text(theme.fg("toolOutput", replaceTabs(text)), 0, 0) : undefined;
 	}
-	const renderer = resolveDeviceRenderer(dispatch.tool, resolveMounted);
+	const mounted = resolveMounted?.(dispatch.tool);
+	const renderer = resolveDeviceRenderer(dispatch.tool, mounted);
 	const innerResult = { content: result.content, details: dispatch.inner, isError: result.isError };
 	if (renderer?.renderResult) {
 		const parts: Component[] = [];
@@ -488,5 +508,13 @@ export function renderXdevResult(
 			return box;
 		}
 	}
-	return text ? new Text(theme.fg("toolOutput", replaceTabs(text)), 0, 0) : undefined;
+	return renderDefaultToolExecution(
+		{
+			label: mounted?.label ?? dispatch.tool,
+			args: dispatch.args ?? {},
+			result: { output: text, isError: result.isError },
+			options,
+		},
+		theme,
+	);
 }

package/src/tts/streaming-player.ts

@@ -1,379 +1,120 @@
-/**
- * Gapless streaming audio output for assistant speech.
- *
- * Replaces the spawn-`afplay`-per-sentence approach (a fresh process per chunk
- * meant audible gaps, per-spawn latency, and no way to interrupt a clip mid-play)
- * with a single persistent player process fed raw 32-bit-float mono PCM over
- * stdin. Chunks are queued and drained by one writer so segments play back to
- * back; writes are paced to stay only {@link LEAD_SECONDS} ahead of realtime so
- * ducking and stop take effect promptly instead of after seconds of buffered
- * audio. {@link StreamingAudioPlayer.stop} kills the process for instant silence.
- *
- * Where no streaming backend exists (Windows, or a host without ffmpeg/sox), it
- * degrades to the per-file {@link playAudioFile} path so speech still works —
- * just without gapless playback or mid-clip interruption. A backend that spawns
- * but dies early (e.g. an ffmpeg built without its platform audio device) is
- * detected via its exit and the session downgrades to per-file playback without
- * dropping the chunk being played.
- */
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import { $which, logger, Snowflake } from "@oh-my-pi/pi-utils";
-import type { FileSink, Subprocess } from "bun";
-import { getToolPath } from "../utils/tools-manager";
-import { type PlayerCommand, playAudioFile } from "./player";
-import { encodeWav } from "./wav";
+import { AudioPlayback } from "@oh-my-pi/pi-natives";
 
-/** Kokoro emits 24 kHz mono; used when a chunk does not declare a rate. */
+/** Kokoro emits 24 kHz mono PCM when a chunk does not declare a rate. */
 const DEFAULT_SAMPLE_RATE = 24_000;
-/** Cap how far ahead of realtime we buffer into the player so duck/stop are responsive. */
-const LEAD_SECONDS = 0.6;
-/** Output gain applied while ducked (the user is speaking over the assistant). */
-export const DUCK_GAIN = 0.25;
-/**
- * Cap on streamed PCM retained for the nonzero-exit replay. Past this the
- * buffer is dropped: the failure being recovered is a short clip that fits the
- * OS pipe buffer before a broken backend dies, while a backend that consumed
- * minutes of realtime-paced audio was playing it — replaying a whole long
- * utterance would duplicate audio, and unbounded retention (~5.8 MB/min at
- * 24 kHz mono f32) would defeat streaming for long input.
- */
-const REPLAY_RETENTION_SECONDS = 60;
-
-/** Injection seam for {@link streamingPlayerCommandsFor} — defaults to real PATH/tools lookups. */
-export interface StreamingPlayerLookup {
-	which?: (bin: string) => string | null;
-	ffmpeg?: () => string | null;
-}
-
-/**
- * Ordered candidate commands for a persistent raw-PCM player on `platform`: each
- * reads 32-bit-float little-endian mono PCM at `sampleRate` from stdin (`pipe:0`)
- * and plays it to the default output device. An empty list means no streaming
- * backend is available and the caller should fall back to per-file playback.
- *
- * - darwin: `ffmpeg` (AudioToolbox output device) → sox's `play` (coreaudio).
- * - linux/other POSIX: `ffmpeg` (`-f pulse` then `-f alsa`) → `paplay`/`aplay`
- *   raw fallbacks.
- * - win32: none (PowerShell `SoundPlayer` is file-only).
- */
-export function streamingPlayerCommandsFor(
-	platform: NodeJS.Platform,
-	sampleRate: number,
-	lookup: StreamingPlayerLookup = {},
-): PlayerCommand[] {
-	const which = lookup.which ?? $which;
-	const ffmpeg = lookup.ffmpeg ?? ((): string | null => getToolPath("ffmpeg"));
-	const rate = String(sampleRate > 0 ? sampleRate : DEFAULT_SAMPLE_RATE);
-	const input = ["-loglevel", "error", "-nostdin", "-f", "f32le", "-ar", rate, "-ac", "1", "-i", "pipe:0"];
-
-	if (platform === "darwin") {
-		const commands: PlayerCommand[] = [];
-		const ffmpegBin = ffmpeg();
-		if (ffmpegBin) commands.push({ cmd: ffmpegBin, args: [...input, "-f", "audiotoolbox", "default"] });
-		const play = which("play");
-		if (play) {
-			commands.push({
-				cmd: play,
-				args: ["-q", "-t", "raw", "-e", "floating-point", "-b", "32", "-r", rate, "-c", "1", "-"],
-			});
-		}
-		return commands;
-	}
-	if (platform === "win32") {
-		return [];
-	}
 
-	const commands: PlayerCommand[] = [];
-	const ffmpegBin = ffmpeg();
-	if (ffmpegBin) {
-		commands.push({ cmd: ffmpegBin, args: [...input, "-f", "pulse", "default"] });
-		commands.push({ cmd: ffmpegBin, args: [...input, "-f", "alsa", "default"] });
-	}
-	const paplay = which("paplay");
-	if (paplay) commands.push({ cmd: paplay, args: ["--raw", `--rate=${rate}`, "--format=float32le", "--channels=1"] });
-	const aplay = which("aplay");
-	if (aplay) commands.push({ cmd: aplay, args: ["-q", "-f", "FLOAT_LE", "-r", rate, "-c", "1", "-"] });
-	return commands;
-}
+/** Output gain applied while the user speaks over assistant audio. */
+export const DUCK_GAIN = 0.25;
 
-/**
- * Test seams for {@link StreamingAudioPlayer}: override backend discovery and
- * the per-file fallback so playback logic can be exercised without a real audio
- * device. Both default to the platform lookup and {@link playAudioFile}.
- */
-export interface StreamingPlayerOptions {
-	/** Ordered backend commands for a sample rate; defaults to {@link streamingPlayerCommandsFor}. */
-	commandsFor?: (sampleRate: number) => PlayerCommand[];
-	/** Per-file fallback playback; defaults to {@link playAudioFile}. */
-	playAudio?: (wavPath: string, signal: AbortSignal) => Promise<void>;
-	/** Max seconds of streamed PCM retained for the nonzero-exit replay; defaults to {@link REPLAY_RETENTION_SECONDS}. */
-	replayRetentionSeconds?: number;
+function errorFrom(cause: unknown): Error {
+	return cause instanceof Error ? cause : new Error(String(cause));
 }
 
 /**
- * Single-session gapless player. Lifecycle: {@link start} once, {@link write}
- * chunks in order, then {@link end} to drain or {@link stop} to abort. Not
- * reusable after stop/end — create a new instance per utterance.
+ * One native gapless playback session. Call {@link start}, enqueue mono `f32`
+ * chunks with {@link write}, then {@link end} to drain or {@link stop} to abort.
  */
 export class StreamingAudioPlayer {
-	#queue: Float32Array[] = [];
+	#native: AudioPlayback | null = null;
 	#sampleRate = DEFAULT_SAMPLE_RATE;
 	#gain = 1;
-	#mode: "stream" | "file" = "file";
-	#proc: Subprocess<"pipe", "ignore", "ignore"> | null = null;
-	#sink: FileSink | null = null;
-	/** Streaming backends not yet tried; consumed head-first by {@link #spawnStream}. */
-	#candidates: PlayerCommand[] | null = null;
-	#writtenSec = 0;
-	#startedAt = 0;
-	#started = false;
+	#error: Error | null = null;
+	#ending: Promise<void> | null = null;
 	#inputClosed = false;
 	#stopped = false;
-	#abortController = new AbortController();
-	#wake: (() => void) | null = null;
-	#drain: Promise<void> = Promise.resolve();
-	readonly #commandsFor: (sampleRate: number) => PlayerCommand[];
-	readonly #playAudio: (wavPath: string, signal: AbortSignal) => Promise<void>;
-	readonly #replayRetentionSec: number;
-	/** Streamed PCM retained for this utterance so a failed backend can be replayed via file playback. */
-	#played: Float32Array[] = [];
-	#playedSec = 0;
-
-	constructor(options: StreamingPlayerOptions = {}) {
-		this.#commandsFor = options.commandsFor ?? (rate => streamingPlayerCommandsFor(process.platform, rate));
-		this.#playAudio = options.playAudio ?? ((wavPath, signal) => playAudioFile(wavPath, { signal }));
-		this.#replayRetentionSec = options.replayRetentionSeconds ?? REPLAY_RETENTION_SECONDS;
+	#failNative(native: AudioPlayback, cause: unknown): void {
+		this.#error = errorFrom(cause);
+		if (this.#native === native) this.#native = null;
+		try {
+			native.stop();
+		} catch {
+			// Preserve the original playback failure.
+		}
 	}
 
-	/** Pick a backend and begin draining. Idempotent; the first call's rate wins. */
-	start(sampleRate: number): void {
-		if (this.#started || this.#stopped) return;
-		this.#started = true;
+	/** Opens the default speaker at the stream's logical sample rate. */
+	start(sampleRate = DEFAULT_SAMPLE_RATE): void {
+		if (this.#native || this.#error || this.#inputClosed || this.#stopped) return;
 		this.#sampleRate = sampleRate > 0 ? sampleRate : DEFAULT_SAMPLE_RATE;
-		this.#mode = this.#spawnStream() ? "stream" : "file";
-		this.#startedAt = performance.now();
-		this.#drain = this.#drainLoop();
+		let native: AudioPlayback | undefined;
+		try {
+			native = new AudioPlayback(this.#sampleRate);
+			native.setGain(this.#gain);
+			this.#native = native;
+		} catch (cause) {
+			if (native) this.#failNative(native, cause);
+			else this.#error = errorFrom(cause);
+		}
 	}
 
-	/** Queue a mono float32 PCM chunk for playback in arrival order. */
+	/** Queues one mono `f32` PCM chunk without copying it in TypeScript. */
 	write(pcm: Float32Array): void {
-		if (this.#stopped) return;
-		this.#queue.push(pcm);
-		this.#signal();
-	}
-
-	/** Scale subsequent output (1 = normal, <1 = ducked). Applies within {@link LEAD_SECONDS}. */
-	setGain(gain: number): void {
-		this.#gain = gain < 0 ? 0 : gain;
-	}
-
-	/** Close the input; resolves once all queued audio has finished playing. */
-	async end(): Promise<void> {
-		this.#inputClosed = true;
-		this.#signal();
-		await this.#drain;
-	}
-
-	/** Stop immediately: kill the player, drop everything still queued. */
-	stop(): void {
-		if (this.#stopped) return;
-		this.#stopped = true;
-		this.#queue.length = 0;
-		this.#played.length = 0;
-		this.#abortController.abort();
-		this.#signal();
+		if (this.#inputClosed || this.#stopped || pcm.length === 0) return;
+		if (!this.#native && !this.#error) this.start(this.#sampleRate);
+		const native = this.#native;
+		if (!native) return;
 		try {
-			// end() flushes asynchronously; the SIGKILL below races it, so a broken
-			// pipe here is expected — swallow the rejection (it otherwise surfaces
-			// as an unhandled EPIPE right as speech ends).
-			void Promise.resolve(this.#sink?.end()).catch(() => {});
-		} catch {}
-		try {
-			this.#proc?.kill("SIGKILL");
-		} catch {}
-	}
-
-	/**
-	 * Spawn the next untried streaming backend; false once the list is
-	 * exhausted. A backend that spawns but dies early (e.g. an ffmpeg built
-	 * without this platform's audio output device) would otherwise swallow PCM
-	 * into a dead pipe, so its exit advances to the next candidate — or to
-	 * per-file playback — and #writeStream's failure path replays the
-	 * in-flight chunk.
-	 */
-	#spawnStream(): boolean {
-		this.#candidates ??= this.#commandsFor(this.#sampleRate);
-		for (let command = this.#candidates.shift(); command; command = this.#candidates.shift()) {
-			const { cmd, args } = command;
-			try {
-				const proc = Bun.spawn([cmd, ...args], {
-					stdin: "pipe",
-					stdout: "ignore",
-					stderr: "ignore",
-				});
-				this.#proc = proc;
-				this.#sink = proc.stdin;
-				void proc.exited.then(code => {
-					if (this.#proc !== proc || this.#stopped || this.#inputClosed) return;
-					logger.debug("tts: streaming backend exited early; trying next backend", { cmd, code });
-					this.#proc = null;
-					this.#sink = null;
-					this.#mode = this.#spawnStream() ? "stream" : "file";
-				});
-				return true;
-			} catch (error) {
-				logger.debug("tts: streaming player spawn failed", {
-					cmd,
-					error: error instanceof Error ? error.message : String(error),
-				});
-			}
+			native.write(pcm);
+		} catch (cause) {
+			this.#failNative(native, cause);
 		}
-		return false;
 	}
 
-	#signal(): void {
-		const wake = this.#wake;
-		this.#wake = null;
-		wake?.();
-	}
-
-	async #drainLoop(): Promise<void> {
+	/** Applies gain at render time, including to samples already queued natively. */
+	setGain(gain: number): void {
+		if (!Number.isFinite(gain) || gain < 0) throw new RangeError("Audio gain must be a finite non-negative number");
+		this.#gain = gain;
+		const native = this.#native;
+		if (!native) return;
 		try {
-			while (!this.#stopped) {
-				const chunk = this.#queue.shift();
-				if (!chunk) {
-					if (this.#inputClosed) break;
-					await this.#waitForWork();
-					continue;
-				}
-				if (this.#mode === "stream") {
-					if (this.#playedSec <= this.#replayRetentionSec) {
-						this.#played.push(chunk);
-						this.#playedSec += chunk.length / this.#sampleRate;
-						// Over the cap: drop retention for the rest of the utterance.
-						if (this.#playedSec > this.#replayRetentionSec) this.#played.length = 0;
-					}
-					// Pace writes so the player buffers ~LEAD_SECONDS, no more, keeping
-					// ducking and stop responsive instead of locked behind buffered audio.
-					const ahead = this.#writtenSec - (performance.now() - this.#startedAt) / 1000;
-					if (ahead > LEAD_SECONDS) {
-						await Bun.sleep((ahead - LEAD_SECONDS) * 1000);
-						if (this.#stopped) return;
-					}
-					if (await this.#writeStream(chunk)) {
-						this.#writtenSec += chunk.length / this.#sampleRate;
-						continue;
-					}
-					// Backend died mid-write: move to the next streaming candidate
-					// (or the file path) and replay this exact chunk so nothing is
-					// dropped.
-					this.#mode = this.#spawnStream() ? "stream" : "file";
-					if (this.#mode === "stream" && (await this.#writeStream(chunk))) {
-						this.#writtenSec += chunk.length / this.#sampleRate;
-					} else {
-						this.#mode = "file";
-						await this.#playFile(chunk);
-					}
-				} else {
-					await this.#playFile(chunk);
-				}
-			}
-			if (!this.#stopped && this.#mode === "stream") {
-				try {
-					await this.#sink?.end();
-				} catch {}
-				const proc = this.#proc;
-				let exitCode: number | null = null;
-				if (proc) {
-					try {
-						exitCode = await proc.exited;
-					} catch {}
-				}
-				// A streaming backend that exits nonzero never opened its audio
-				// device (e.g. the bundled ffmpeg built without pulse/alsa output).
-				// For a short single-segment clip the pipe write succeeds before
-				// that death and #inputClosed is already set, so neither the
-				// broken-pipe replay nor the early-exit handler advances backends.
-				// Replay the buffered utterance through per-file playback so it
-				// still reaches the speakers.
-				if (!this.#stopped && proc && exitCode !== 0) {
-					this.#mode = "file";
-					for (const chunk of this.#played) {
-						if (this.#stopped) break;
-						await this.#playFile(chunk);
-					}
-				}
-			}
-		} catch (error) {
-			logger.debug("tts: streaming player drain failed", {
-				error: error instanceof Error ? error.message : String(error),
-			});
+			native.setGain(gain);
+		} catch (cause) {
+			this.#failNative(native, cause);
 		}
 	}
 
-	/** Block until a chunk is queued, the input closes, or stop is called. */
-	#waitForWork(): Promise<void> {
-		const { promise, resolve } = Promise.withResolvers<void>();
-		this.#wake = resolve;
-		// Re-check after arming to close the gap between the empty shift and here.
-		if (this.#queue.length > 0 || this.#inputClosed || this.#stopped) {
-			this.#wake = null;
-			resolve();
+	/** Closes input and resolves after every queued sample reaches the speaker. */
+	end(): Promise<void> {
+		if (this.#ending) return this.#ending;
+		if (this.#stopped) return Promise.resolve();
+		this.#inputClosed = true;
+		if (this.#error) {
+			this.#stopped = true;
+			return Promise.reject(this.#error);
 		}
-		return promise;
-	}
-
-	/**
-	 * Write one chunk into the backend's stdin and await the flush — a broken
-	 * pipe rejects here (not as an unhandled rejection later), so the caller
-	 * can replay the exact chunk on the next backend.
-	 */
-	async #writeStream(pcm: Float32Array): Promise<boolean> {
-		const sink = this.#sink;
-		if (!sink) return false;
-		try {
-			sink.write(this.#bytes(pcm));
-			await sink.flush();
-			return true;
-		} catch (error) {
-			logger.debug("tts: streaming write failed", {
-				error: error instanceof Error ? error.message : String(error),
-			});
-			return false;
+		const native = this.#native;
+		if (!native) {
+			this.#stopped = true;
+			return Promise.resolve();
 		}
+		this.#ending = native
+			.end()
+			.catch(cause => {
+				throw errorFrom(cause);
+			})
+			.finally(() => {
+				if (this.#native === native) this.#native = null;
+				this.#stopped = true;
+			});
+		return this.#ending;
 	}
 
-	async #playFile(pcm: Float32Array): Promise<void> {
-		const wavPath = path.join(os.tmpdir(), `omp-speech-${Snowflake.next()}.wav`);
+	/** Stops immediately and discards queued audio. Safe to call repeatedly. */
+	stop(): void {
+		this.#inputClosed = true;
+		this.#stopped = true;
+		const native = this.#native;
+		this.#native = null;
+		if (!native) return;
 		try {
-			await fs.writeFile(wavPath, encodeWav(this.#scaled(pcm), this.#sampleRate));
-			if (!this.#stopped) await this.#playAudio(wavPath, this.#abortController.signal);
-		} catch (error) {
-			logger.debug("tts: file playback failed", {
-				error: error instanceof Error ? error.message : String(error),
-			});
-		} finally {
-			await fs.unlink(wavPath).catch(() => {});
+			native.stop();
+		} catch {
+			// Best-effort abort during session teardown.
 		}
 	}
-
-	/** Raw f32le bytes for the stream sink, applying gain only when ducked (avoids a copy at unity). */
-	#bytes(pcm: Float32Array): Uint8Array {
-		if (this.#gain === 1) return new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength);
-		return new Uint8Array(this.#scaled(pcm).buffer);
-	}
-
-	#scaled(pcm: Float32Array): Float32Array {
-		if (this.#gain === 1) return pcm;
-		const out = new Float32Array(pcm.length);
-		for (let i = 0; i < pcm.length; i++) out[i] = (pcm[i] ?? 0) * this.#gain;
-		return out;
-	}
 }
 
-/** Factory the vocalizer calls; a function so tests can stub it without spawning a player. */
+/** Creates the single-use player used by the speech vocalizer. */
 export function createStreamingPlayer(): StreamingAudioPlayer {
 	return new StreamingAudioPlayer();
 }

package/src/utils/clipboard.ts

@@ -1,6 +1,7 @@
 import type { ClipboardImage } from "@oh-my-pi/pi-natives";
 import * as native from "@oh-my-pi/pi-natives";
 import { logger } from "@oh-my-pi/pi-utils";
+import MAC_FILE_URL_SCRIPT from "./mac-file-urls.applescript" with { type: "text" };
 
 /**
  * Run a subprocess and capture its stdout without blocking the event loop.
@@ -52,36 +53,6 @@ function isWsl(): boolean {
 	return process.platform === "linux" && Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
 }
 
-// AppleScript that returns the POSIX paths of every file URL currently on the
-// macOS pasteboard, one path per line. `pbpaste(1)` only surfaces plain text,
-// EPS, or RTF, so a Finder `Cmd+C` (which puts only a `public.file-url`
-// representation on the pasteboard) makes `pbpaste` empty. AppleScript's
-// `«class furl»` coercion reaches the file-URL representation directly and
-// works for both single-file and multi-file selections. The `try` blocks
-// suppress the `-1700` "can't make … into type" error AppleScript raises when
-// the clipboard holds no file URLs, so the script's exit status only reflects
-// `osascript` itself.
-const MAC_FILE_URL_SCRIPT = [
-	"on run",
-	'\tset output to ""',
-	"\ttry",
-	"\t\tset theClip to the clipboard as «class furl»",
-	"\t\tif class of theClip is list then",
-	"\t\t\trepeat with anItem in theClip",
-	"\t\t\t\ttry",
-	"\t\t\t\t\tset output to output & POSIX path of anItem & linefeed",
-	"\t\t\t\tend try",
-	"\t\t\tend repeat",
-	"\t\telse",
-	"\t\t\ttry",
-	"\t\t\t\tset output to POSIX path of theClip & linefeed",
-	"\t\t\tend try",
-	"\t\tend if",
-	"\tend try",
-	"\treturn output",
-	"end run",
-].join("\n");
-
 /**
  * Read file paths from the macOS pasteboard's `public.file-url` representation.
  *

package/src/utils/mac-file-urls.applescript

@@ -0,0 +1,37 @@
+-- Returns the POSIX paths of every file URL currently on the macOS
+-- pasteboard, one path per line. `pbpaste(1)` only surfaces plain text,
+-- EPS, or RTF, so a Finder Cmd+C (which puts only a `public.file-url`
+-- representation on the pasteboard) makes `pbpaste` empty. The
+-- `«class furl»` coercion reaches the file-URL representation directly and
+-- works for both single-file and multi-file selections.
+--
+-- The coercion is guarded by `clipboard info for «class furl»`: AppleScript
+-- happily coerces plain *text* into a file URL by treating it as an HFS
+-- path, so an unguarded cast turns a copied `https://i.can.ac/x.png` string
+-- into the mangled `/https/::i.can.ac:x.png` (HFS `:`↔`/` swap) and the
+-- paste dead-ends with "Image not found" instead of falling back to pasting
+-- the text. `clipboard info for` inspects the actual pasteboard types, so
+-- it is `{}` unless a real `public.file-url` representation is present.
+--
+-- The `try` blocks suppress the `-1700` "can't make … into type" error
+-- AppleScript raises when the clipboard holds no file URLs, so the script's
+-- exit status only reflects `osascript` itself.
+on run
+	set output to ""
+	try
+		if (clipboard info for «class furl») is {} then return output
+		set theClip to the clipboard as «class furl»
+		if class of theClip is list then
+			repeat with anItem in theClip
+				try
+					set output to output & POSIX path of anItem & linefeed
+				end try
+			end repeat
+		else
+			try
+				set output to POSIX path of theClip & linefeed
+			end try
+		end if
+	end try
+	return output
+end run