@oh-my-pi/pi-coding-agent 15.12.3 → 15.13.0

package/src/tools/read.ts

@@ -9,7 +9,7 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { getRemoteDir, logger, prompt, readImageMetadata, untilAborted } from "@oh-my-pi/pi-utils";
 import { LRUCache } from "lru-cache/raw";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import {
 	canonicalSnapshotKey,
 	getFileSnapshotStore,
@@ -38,7 +38,12 @@ import { fileHyperlink, renderCodeCell, renderMarkdownCell, renderStatusLine, tr
 import { CachedOutputBlock, markFramedBlockComponent } from "../tui/output-block";
 import { buildLineEntriesWithBlockContext, type LineEntry, lineEntriesToPlainText } from "../utils/block-context";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
-import { ImageInputTooLargeError, loadImageInput, MAX_IMAGE_INPUT_BYTES } from "../utils/image-loading";
+import {
+	ImageInputTooLargeError,
+	loadImageInput,
+	MAX_IMAGE_INPUT_BYTES,
+	webpExclusionForModel,
+} from "../utils/image-loading";
 import { convertFileWithMarkit } from "../utils/markit";
 import { buildDirectoryTree, type DirectoryTree } from "../workspace-tree";
 import { type ArchiveReader, formatArchiveEntryLines, openArchive, parseArchivePathCandidates } from "./archive-reader";
@@ -1974,6 +1979,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						maxBytes: MAX_IMAGE_SIZE,
 						resolvedPath: absolutePath,
 						detectedMimeType: mimeType,
+						excludeWebP: webpExclusionForModel(this.session.getActiveModel?.()),
 					});
 					if (!imageInput) {
 						throw new ToolError(`Read image file [${mimeType}] failed: unsupported image format.`);

package/src/tools/render-mermaid.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { type MermaidAsciiRenderOptions, prompt, renderMermaidAscii } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import renderMermaidDescription from "../prompts/tools/render-mermaid.md" with { type: "text" };
 import type { ToolSession } from "./index";
 

package/src/tools/renderers.ts

@@ -44,18 +44,14 @@ export type ToolRenderer = {
 	/** Render without background box, inline in the response flow */
 	inline?: boolean;
 	/**
-	 * Collapsed pending preview is provisional — a tail-window or otherwise
-	 * re-anchored view the result render replaces wholesale (an edit's
-	 * streamed-diff tail, bash/ssh command caps, eval cells whose outputs
-	 * interleave under each cell). Its rows must never commit to native
-	 * scrollback mid-run; see
-	 * `ToolExecutionComponent.isTranscriptBlockCommitStable`. Absent = the
-	 * pending preview streams top-anchored append-shaped rows the result
-	 * render preserves (task context/assignment, write content), which stay
-	 * commit-eligible so a call taller than the viewport scrolls into history
-	 * instead of reading as cut off.
+	 * Whether pending-call rows are provisional: useful on screen while a tool is
+	 * streaming, but not durable transcript history. `true` means every pending
+	 * shape is provisional. `"collapsed"` means only the collapsed pending shape
+	 * is provisional; expanded rendering is top-anchored/append-shaped enough to
+	 * let the transcript commit its settled prefix. Absent = the pending preview
+	 * streams rows the result render preserves.
 	 */
-	provisionalPendingPreview?: boolean;
+	provisionalPendingPreview?: boolean | "collapsed";
 };
 
 export const toolRenderers: Record<string, ToolRenderer> = {

package/src/tools/report-tool-issue.ts

@@ -24,7 +24,7 @@ import path from "node:path";
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import type { FetchImpl } from "@oh-my-pi/pi-ai";
 import { $env, $flag, getAgentDir, getInstallId, logger, VERSION } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { Settings } from "..";
 import type { ToolSession } from "./index";
 
@@ -206,10 +206,11 @@ export function openAutoQaDb(): Database | null {
 	if (cachedDb) return cachedDb;
 	try {
 		const db = new Database(getAutoQaDbPath());
+		// Install the busy handler BEFORE any lock-taking statement. See #2421.
+		db.run("PRAGMA busy_timeout = 5000");
 		db.run(`
 			PRAGMA journal_mode=WAL;
 			PRAGMA synchronous=NORMAL;
-			PRAGMA busy_timeout=5000;
 			CREATE TABLE IF NOT EXISTS grievances (
 				id INTEGER PRIMARY KEY AUTOINCREMENT,
 				model TEXT NOT NULL,

package/src/tools/resolve.ts

@@ -2,7 +2,7 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import resolveDescription from "../prompts/tools/resolve.md" with { type: "text" };

package/src/tools/review.ts

@@ -12,7 +12,7 @@ import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Container, Text } from "@oh-my-pi/pi-tui";
 import { isRecord } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { Theme, ThemeColor } from "../modes/theme/theme";
 import { subprocessToolRegistry } from "../task/subprocess-tool-registry";
 import type { ReviewFinding } from "../task/types";

package/src/tools/search-tool-bm25.ts

@@ -2,7 +2,7 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { prompt } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import searchToolBm25Description from "../prompts/tools/search-tool-bm25.md" with { type: "text" };

package/src/tools/search.ts

@@ -7,7 +7,7 @@ import { type GrepMatch, GrepOutputMode, type GrepResult, grep } from "@oh-my-pi
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { recordFileSnapshot } from "../edit/file-snapshot-store";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { LocalProtocolOptions } from "../internal-urls/local-protocol";

package/src/tools/ssh.ts

@@ -1,7 +1,7 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { prompt } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { SSHHost } from "../capability/ssh";
 import { sshCapability } from "../capability/ssh";
 import { loadCapability } from "../discovery";
@@ -346,7 +346,8 @@ export const sshToolRenderer = {
 		});
 	},
 	mergeCallAndResult: true,
-	// Pending preview caps the command to a viewport-sized tail window that
-	// shifts while args stream; keep it out of native scrollback mid-run.
-	provisionalPendingPreview: true,
+	// Collapsed pending preview caps the command to a viewport-sized tail window
+	// that shifts while args stream. Expanded output is top-anchored enough for
+	// the transcript to commit its settled prefix.
+	provisionalPendingPreview: "collapsed",
 };

package/src/tools/todo.ts

@@ -3,12 +3,12 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { prompt } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import todoDescription from "../prompts/tools/todo.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 import { framedBlock, renderStatusLine, renderTreeList } from "../tui";
 import { formatErrorDetail, PREVIEW_LIMITS } from "./render-utils";
 

package/src/tools/tts.ts

@@ -1,10 +1,17 @@
 // Ported from NousResearch/hermes-agent (MIT) — tools/tts_tool.py L167-171, L896-959.
+// The xAI Grok Voice path below is preserved intact; a local on-device neural TTS
+// backend (Kokoro-82M via kokoro-js on the shared ONNX worker) is layered on behind
+// the `providers.tts` switch.
 
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { type ApiKey, ProviderHttpError, withAuth } from "@oh-my-pi/pi-ai";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
+import { settings } from "../config/settings";
 import type { CustomTool, CustomToolContext } from "../extensibility/custom-tools/types";
 import { ohMyPiXAIUserAgent, resolveXAIHttpCredentials } from "../lib/xai-http";
+import { DEFAULT_TTS_LOCAL_MODEL_KEY, DEFAULT_TTS_VOICE, isTtsLocalModelKey, KOKORO_VOICES } from "../tts/models";
+import { ttsClient } from "../tts/tts-client";
+import { encodeWav } from "../tts/wav";
 import { formatPathRelativeToCwd, resolveToCwd } from "./path-utils";
 
 // Hermes tts_tool.py L167-171
@@ -22,6 +29,7 @@ const formatVoiceList = (): string =>
 	XAI_BUILTIN_VOICES.map(v => (v === DEFAULT_XAI_VOICE_ID ? `${v} (default)` : v)).join(", ");
 
 type TtsCodec = "mp3" | "wav";
+type TtsBackend = "local" | "xai";
 
 const ttsSchema = z.object({
 	text: z.string().min(1).max(XAI_MAX_TEXT_LENGTH),
@@ -36,16 +44,200 @@ interface TtsToolDetails {
 	bytes: number;
 	voiceId: string;
 	codec: TtsCodec;
+	backend: TtsBackend;
+}
+
+/**
+ * Pick the synthesis backend. Pure for testability.
+ *
+ * - `xai` / `local` are honored verbatim (the xAI path still surfaces its own
+ *   "no credentials" error when creds are missing).
+ * - `auto` prefers the local on-device backend, except when the caller asked for
+ *   an `.mp3` and xAI credentials exist — only the cloud path can emit MP3, so we
+ *   route there to satisfy the requested container rather than substituting WAV.
+ */
+export function resolveTtsBackend(opts: { preference: string; wantsMp3: boolean; hasXaiCreds: boolean }): TtsBackend {
+	if (opts.preference === "xai") return "xai";
+	if (opts.preference === "local") return "local";
+	if (opts.wantsMp3 && opts.hasXaiCreds) return "xai";
+	return "local";
+}
+
+/**
+ * Resolve the on-disk path for local synthesis. Local output is always WAV (no
+ * MP3 encoder is bundled), so an `.mp3` (or any non-`.wav`) request is rewritten
+ * to a sibling `.wav` and flagged so the tool result can note the substitution.
+ */
+export function resolveLocalWavPath(outputPath: string): { wavPath: string; substituted: boolean } {
+	const lower = outputPath.toLowerCase();
+	if (lower.endsWith(".wav")) return { wavPath: outputPath, substituted: false };
+	const slash = Math.max(outputPath.lastIndexOf("/"), outputPath.lastIndexOf("\\"));
+	const dot = outputPath.lastIndexOf(".");
+	const base = dot > slash ? outputPath.slice(0, dot) : outputPath;
+	return { wavPath: `${base}.wav`, substituted: true };
+}
+
+function readStringSetting(key: "providers.tts" | "tts.localModel" | "tts.localVoice"): string | undefined {
+	try {
+		const value = settings.get(key);
+		return typeof value === "string" ? value : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+async function synthesizeXai(
+	params: z.infer<typeof ttsSchema>,
+	ctx: CustomToolContext,
+	outputPath: string,
+	displayPath: string,
+	codec: TtsCodec,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<TtsToolDetails, typeof ttsSchema>> {
+	const creds = await resolveXAIHttpCredentials(ctx.modelRegistry);
+	if (!creds) {
+		return {
+			isError: true,
+			content: [
+				{
+					type: "text",
+					text: "No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok Subscription) or set XAI_API_KEY.",
+				},
+			],
+		};
+	}
+
+	const voiceId = params.voice_id;
+	const language = params.language;
+	const sampleRate = params.sample_rate ?? DEFAULT_XAI_SAMPLE_RATE;
+	const bitRate = params.bit_rate ?? DEFAULT_XAI_BIT_RATE;
+
+	const payload: Record<string, unknown> = {
+		text: params.text,
+		voice_id: voiceId,
+		language,
+	};
+	// Hermes tts_tool.py L926-940 — only send output_format when caller overrides a default.
+	const codecOverridden = codec !== "mp3";
+	const sampleRateOverridden = sampleRate !== DEFAULT_XAI_SAMPLE_RATE;
+	const bitRateOverridden = codec === "mp3" && bitRate !== DEFAULT_XAI_BIT_RATE;
+	if (codecOverridden || sampleRateOverridden || bitRateOverridden) {
+		const fmt: Record<string, unknown> = { codec };
+		if (sampleRate) fmt.sample_rate = sampleRate;
+		if (codec === "mp3" && bitRate) fmt.bit_rate = bitRate;
+		payload.output_format = fmt;
+	}
+
+	// Compose the caller signal with a 60 s timeout fence.
+	const timeoutSignal = AbortSignal.timeout(60_000);
+	const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+
+	const sessionId = ctx.sessionManager.getSessionId();
+	const apiKey: ApiKey = ctx.modelRegistry.resolver(creds.provider, {
+		sessionId,
+		baseUrl: creds.baseURL,
+	});
+
+	let response: Response;
+	try {
+		response = await withAuth(
+			apiKey,
+			async key => {
+				const resp = await fetch(`${creds.baseURL}/tts`, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${key}`,
+						"Content-Type": "application/json",
+						"User-Agent": ohMyPiXAIUserAgent(),
+					},
+					body: JSON.stringify(payload),
+					signal: combinedSignal,
+				});
+				if (!resp.ok) {
+					const detail = await resp.text();
+					throw new ProviderHttpError(`xAI TTS failed (${resp.status}): ${detail.slice(0, 300)}`, resp.status, {
+						headers: resp.headers,
+					});
+				}
+				return resp;
+			},
+			{ signal: combinedSignal },
+		);
+	} catch (error) {
+		const status = (error as { status?: unknown }).status;
+		if (error instanceof Error && typeof status === "number") {
+			return {
+				isError: true,
+				content: [{ type: "text", text: error.message }],
+			};
+		}
+		throw error;
+	}
+	const bytes = new Uint8Array(await response.arrayBuffer());
+	await Bun.write(outputPath, bytes);
+	return {
+		content: [
+			{
+				type: "text",
+				text: `Saved ${bytes.length} bytes to ${displayPath} (voice=${voiceId}, codec=${codec}, backend=xai).`,
+			},
+		],
+		details: { bytes: bytes.length, voiceId, codec, backend: "xai" },
+	};
+}
+
+async function synthesizeLocal(
+	params: z.infer<typeof ttsSchema>,
+	cwd: string,
+	outputPath: string,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<TtsToolDetails, typeof ttsSchema>> {
+	const modelSetting = readStringSetting("tts.localModel");
+	const modelKey = modelSetting && isTtsLocalModelKey(modelSetting) ? modelSetting : DEFAULT_TTS_LOCAL_MODEL_KEY;
+	const voice = readStringSetting("tts.localVoice") || DEFAULT_TTS_VOICE;
+
+	const audio = await ttsClient.synthesize(modelKey, params.text, { voice, signal });
+	if (!audio) {
+		return {
+			isError: true,
+			content: [
+				{
+					type: "text",
+					text: `Local TTS synthesis failed (model=${modelKey}). The on-device worker may be unavailable or the model download was interrupted.`,
+				},
+			],
+		};
+	}
+
+	const { wavPath, substituted } = resolveLocalWavPath(outputPath);
+	const wav = encodeWav(audio.pcm, audio.sampleRate);
+	await Bun.write(wavPath, wav);
+	const displayPath = formatPathRelativeToCwd(wavPath, cwd);
+	const note = substituted
+		? ` No local MP3 encoder is bundled, so WAV (PCM16) was written instead of the requested container.`
+		: "";
+	return {
+		content: [
+			{
+				type: "text",
+				text: `Saved ${wav.length} bytes to ${displayPath} (voice=${modelKey}/${voice}, codec=wav, backend=local, ${audio.sampleRate} Hz).${note}`,
+			},
+		],
+		details: { bytes: wav.length, voiceId: `${modelKey}/${voice}`, codec: "wav", backend: "local" },
+	};
 }
 
 export const ttsTool: CustomTool<typeof ttsSchema, TtsToolDetails> = {
 	name: "tts",
-	label: "TextToSpeech",
+	label: "Speech Generation",
 	strict: false,
 	approval: "write",
 	description:
-		`Synthesize speech from text using xAI Grok Voice. Built-in voices: ${formatVoiceList()}. ` +
-		"Custom voice IDs also accepted. Output codec inferred from output_path suffix (.wav → wav, else mp3). " +
+		"Generate a speech audio file from text and write it to output_path. Two backends, selected by the providers.tts setting (auto|local|xai): " +
+		`local = on-device neural TTS (Kokoro-82M via the bundled ONNX runtime, no network, output is always WAV/PCM16; voice set by the tts.localVoice setting — ${KOKORO_VOICES.map(v => (v.id === DEFAULT_TTS_VOICE ? `${v.id} (default)` : v.id)).join(", ")}); ` +
+		`xai = xAI Grok Voice cloud (built-in voices: ${formatVoiceList()}; custom voice IDs accepted; MP3 or WAV). ` +
+		"auto prefers local, but routes an .mp3 request to xAI when credentials exist (only the cloud path emits MP3); " +
+		"otherwise an .mp3 path is written as a sibling .wav. xAI codec is inferred from the output_path suffix. " +
 		`Max ${XAI_MAX_TEXT_LENGTH.toLocaleString("en-US")} characters.`,
 	parameters: ttsSchema,
 	async execute(
@@ -55,99 +247,18 @@ export const ttsTool: CustomTool<typeof ttsSchema, TtsToolDetails> = {
 		ctx: CustomToolContext,
 		signal?: AbortSignal,
 	): Promise<AgentToolResult<TtsToolDetails, typeof ttsSchema>> {
-		const creds = await resolveXAIHttpCredentials(ctx.modelRegistry);
-		if (!creds) {
-			return {
-				isError: true,
-				content: [
-					{
-						type: "text",
-						text: "No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok Subscription) or set XAI_API_KEY.",
-					},
-				],
-			};
-		}
-
 		const cwd = ctx.sessionManager.getCwd();
 		const outputPath = resolveToCwd(params.output_path, cwd);
 		const displayPath = formatPathRelativeToCwd(outputPath, cwd);
 		const codec: TtsCodec = outputPath.toLowerCase().endsWith(".wav") ? "wav" : "mp3";
-		const voiceId = params.voice_id;
-		const language = params.language;
-		const sampleRate = params.sample_rate ?? DEFAULT_XAI_SAMPLE_RATE;
-		const bitRate = params.bit_rate ?? DEFAULT_XAI_BIT_RATE;
-
-		const payload: Record<string, unknown> = {
-			text: params.text,
-			voice_id: voiceId,
-			language,
-		};
-		// Hermes tts_tool.py L926-940 — only send output_format when caller overrides a default.
-		const codecOverridden = codec !== "mp3";
-		const sampleRateOverridden = sampleRate !== DEFAULT_XAI_SAMPLE_RATE;
-		const bitRateOverridden = codec === "mp3" && bitRate !== DEFAULT_XAI_BIT_RATE;
-		if (codecOverridden || sampleRateOverridden || bitRateOverridden) {
-			const fmt: Record<string, unknown> = { codec };
-			if (sampleRate) fmt.sample_rate = sampleRate;
-			if (codec === "mp3" && bitRate) fmt.bit_rate = bitRate;
-			payload.output_format = fmt;
-		}
 
-		// Compose the caller signal with a 60 s timeout fence.
-		const timeoutSignal = AbortSignal.timeout(60_000);
-		const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
-
-		const sessionId = ctx.sessionManager.getSessionId();
-		const apiKey: ApiKey = ctx.modelRegistry.resolver(creds.provider, {
-			sessionId,
-			baseUrl: creds.baseURL,
-		});
-
-		let response: Response;
-		try {
-			response = await withAuth(
-				apiKey,
-				async key => {
-					const resp = await fetch(`${creds.baseURL}/tts`, {
-						method: "POST",
-						headers: {
-							Authorization: `Bearer ${key}`,
-							"Content-Type": "application/json",
-							"User-Agent": ohMyPiXAIUserAgent(),
-						},
-						body: JSON.stringify(payload),
-						signal: combinedSignal,
-					});
-					if (!resp.ok) {
-						const detail = await resp.text();
-						throw new ProviderHttpError(`xAI TTS failed (${resp.status}): ${detail.slice(0, 300)}`, resp.status, {
-							headers: resp.headers,
-						});
-					}
-					return resp;
-				},
-				{ signal: combinedSignal },
-			);
-		} catch (error) {
-			const status = (error as { status?: unknown }).status;
-			if (error instanceof Error && typeof status === "number") {
-				return {
-					isError: true,
-					content: [{ type: "text", text: error.message }],
-				};
-			}
-			throw error;
-		}
-		const bytes = new Uint8Array(await response.arrayBuffer());
-		await Bun.write(outputPath, bytes);
-		return {
-			content: [
-				{
-					type: "text",
-					text: `Saved ${bytes.length} bytes to ${displayPath} (voice=${voiceId}, codec=${codec}).`,
-				},
-			],
-			details: { bytes: bytes.length, voiceId, codec },
-		};
+		const preference = readStringSetting("providers.tts") ?? "auto";
+		// Only resolve xAI creds when they can affect routing (skip for an explicit local preference).
+		const hasXaiCreds =
+			preference === "local" ? false : (await resolveXAIHttpCredentials(ctx.modelRegistry)) !== null;
+		const backend = resolveTtsBackend({ preference, wantsMp3: codec === "mp3", hasXaiCreds });
+
+		if (backend === "local") return synthesizeLocal(params, cwd, outputPath, signal);
+		return synthesizeXai(params, ctx, outputPath, displayPath, codec, signal);
 	},
 };

package/src/tools/write.ts

@@ -6,7 +6,7 @@ import { formatHashlineHeader, stripHashlinePrefixes } from "@oh-my-pi/hashline"
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { isEnoent, isRecord, prompt, untilAborted } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 
 import { canonicalSnapshotKey, getFileSnapshotStore } from "../edit/file-snapshot-store";
 import { normalizeToLF } from "../edit/normalize";
@@ -35,7 +35,7 @@ import {
 import { invalidateFsScanAfterWrite } from "./fs-cache-invalidation";
 import { type OutputMeta, outputMeta } from "./output-meta";
 import { formatPathRelativeToCwd, isInternalUrlPath } from "./path-utils";
-import { enforcePlanModeWrite, resolvePlanPath } from "./plan-mode-guard";
+import { enforcePlanModeWrite, resolvePlanPath, unwrapHashlineHeaderPath } from "./plan-mode-guard";
 import {
 	cachedRenderedString,
 	createRenderedStringCache,
@@ -63,6 +63,7 @@ import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 
 const LOOSE_HASHLINE_HEADER_RE = /^\s*\[[^#\r\n]+#[^ \t\r\n]*\]\s*$/;
+const EXECUTABLE_NOTICE = "[Notice: Made executable via chmod +x]";
 
 let fflateModulePromise: Promise<typeof import("fflate")> | undefined;
 async function loadFflate(): Promise<typeof import("fflate")> {
@@ -818,11 +819,20 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 	}
 	async execute(
 		_toolCallId: string,
-		{ path, content }: WriteParams,
+		{ path: rawPath, content }: WriteParams,
 		signal?: AbortSignal,
 		_onUpdate?: AgentToolUpdateCallback<WriteToolDetails>,
 		context?: AgentToolContext,
 	): Promise<AgentToolResult<WriteToolDetails>> {
+		// Strip a hashline `[path#TAG]` wrapper up front so every downstream
+		// decision (scheme routing, internal-URL handler dispatch, plan-mode
+		// guard, plan path resolution, ACP bridge routing) sees the same
+		// filesystem target. Without this, a model that pastes a `read`
+		// header as the `path` arg would slip past `isInternalUrlPath`
+		// (which fails on a leading `[`) and the bridge router would send a
+		// `[local://scratch.md#ABCD]` write to the editor instead of the
+		// session-local sandbox.
+		const path = unwrapHashlineHeaderPath(rawPath);
 		return untilAborted(signal, async () => {
 			// Strip hashline display prefixes ([PATH#HASH] + LINE:) if the model copied them from read output
 			const { text: cleanContent, stripped } = stripWriteContent(this.session, content);
@@ -932,6 +942,9 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				if (stripped) {
 					resultText += `\nNote: auto-stripped hashline display prefixes from content before writing.`;
 				}
+				if (madeExecutable) {
+					resultText += `\n${EXECUTABLE_NOTICE}`;
+				}
 				return {
 					content: [{ type: "text", text: resultText }],
 					details: { resolvedPath: absolutePath, madeExecutable: madeExecutable || undefined },
@@ -950,6 +963,9 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			if (stripped) {
 				resultText += `\nNote: auto-stripped hashline display prefixes from content before writing.`;
 			}
+			if (madeExecutable) {
+				resultText += `\n${EXECUTABLE_NOTICE}`;
+			}
 			if (!diagnostics) {
 				return {
 					content: [{ type: "text", text: resultText }],

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";