pi-push-to-talk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sqwxl
+
+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

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# pi-push-to-talk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hold space in pi's prompt to dictate. Your words appear where the cursor is, and speech recognition runs on your machine.
+
+```
+hold space  →  speak  →  release
+```
+
+No overlay, no separate window, no API key. The transcript is ordinary text in the editor, so you can keep typing, move the cursor, and dictate again wherever you are.
+
+## Install
+
+```bash
+pi install npm:pi-push-to-talk
+```
+
+Remove any other voice extension first. Several of them also bind space or replace the editor, and two handlers on one key produce dropped spaces.
+
+## Use
+
+| Action | Result |
+|---|---|
+| Hold space (> 350 ms) | Recording starts; text appears at the cursor every second and updates in place |
+| Release | That phrase is transcribed and committed |
+| Pause 2.5 s while holding | The open phrase is committed and dictation continues |
+| Tap space | An ordinary space, as usual |
+
+While you speak, the open phrase is drawn dim; committed text is normal.
+
+## First run
+
+Whisper base is downloaded once, about 198 MB, into `~/.pi/models/whisper-base/`. Only the int8 files are kept. After that, dictation is fully offline.
+
+Extraction uses the system `tar` with bzip2 support, which is present on macOS, Linux, and Windows 10+.
+
+## How it works
+
+- Capture: `decibri` reads the microphone in process, resampling to 16 kHz mono.
+- Recognition: `sherpa-onnx-node` runs Whisper base int8 on the CPU, four threads.
+- Segmentation: a phrase closes after 2.5 s of silence or 12 s of unbroken speech; the cut lands in the quietest part of the last 800 ms, not mid-syllable.
+- Editor: the extension owns the prompt editor, but only to write text. Keys are handled on the raw terminal path and only while the main editor has focus, so dialogs and nested editors keep working.
+
+## Requirements
+
+- pi with extension support
+- A microphone the terminal may use
+- macOS, Linux, or Windows, x64 or arm64
+
+## Known limits
+
+- Undo history records each preview rewrite; `Ctrl+Z` after a dictation steps back through them. The editor API offers no way to write without an undo entry.
+- English only.
+- A true sentence end followed by a pause longer than 2.5 s loses its full stop, because a mid-session commit drops Whisper's trailing period.
+- Brackets are stripped from transcripts, since Whisper emits them as sound captions. Dictating code with brackets is not supported.
+- The cursor is restored with simulated left-arrow presses, capped at 4,000 characters. Inserting near the start of a very long prompt can leave the cursor short of the dictation point.
+- Nested editors (dialogs) do not accept dictation, only normal typing.
+
+## Diagnostics
+
+Both are off unless the environment variable is set; both write only to `/tmp`.
+
+| Variable | File | Content |
+|---|---|---|
+| `PI_DICTATION_DEBUG=1` | `/tmp/pi-dictation.log` | Space events, phrase decodes, recognizer errors |
+| `PI_DICTATION_PROBE=1` | `/tmp/pi-dictation-probe.log` | Every terminal key sequence, for diagnosing key encoding. Dictation is disabled in this mode. |
+
+## Uninstall
+
+```bash
+pi remove npm:pi-push-to-talk
+rm -rf ~/.pi/models/whisper-base   # optional, frees 154 MB
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,73 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DictationEditor } from "./src/editor.ts";
+import { SpaceHold } from "./src/hold.ts";
+import { ProbeEditor } from "./src/probe.ts";
+import { Stt } from "./src/stt.ts";
+
+type Ui = {
+	notify: (message: string, level: "info" | "warning" | "error") => void;
+	setStatus: (key: string, text: string | undefined) => void;
+	onTerminalInput: (handler: (data: string) => { consume?: boolean } | undefined) => () => void;
+};
+
+export default function dictationExtension(pi: ExtensionAPI): void {
+	let ui: Ui | undefined;
+	let editor: DictationEditor | undefined;
+	let sttPromise: Promise<Stt> | undefined;
+	let unsubscribe: (() => void) | undefined;
+
+	const getStt = (): Promise<Stt> => {
+		if (!sttPromise) {
+			sttPromise = Stt.create(undefined, (message) => ui?.setStatus("dictation", message)).then(
+				(stt) => {
+					ui?.setStatus("dictation", undefined);
+					return stt;
+				},
+				(error: unknown) => {
+					// Do not cache a failure: the next hold retries.
+					sttPromise = undefined;
+					ui?.setStatus("dictation", undefined);
+					throw error;
+				},
+			);
+		}
+		return sttPromise;
+	};
+
+	const hold = new SpaceHold({
+		getEditor: () => editor,
+		getStt,
+		notify: (message, level) => ui?.notify(message, level),
+		status: (text) => ui?.setStatus("dictation", text),
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		if (!ctx.hasUI) return;
+		ui = ctx.ui;
+
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+			if (process.env.PI_DICTATION_PROBE) return new ProbeEditor(tui, theme, keybindings);
+			editor = new DictationEditor(tui, theme, keybindings);
+			return editor;
+		});
+
+		unsubscribe?.();
+		// Probe mode replaces the editor purely to log keys; it must not consume
+		// space or start sessions.
+		unsubscribe = process.env.PI_DICTATION_PROBE
+			? undefined
+			: ctx.ui.onTerminalInput((data) => (hold.handle(data) ? { consume: true } : undefined));
+	});
+
+	// A submitted prompt clears the editor; an open session must not refill it
+	// with a transcript written against the old buffer.
+	pi.on("input", () => {
+		hold.cancel();
+	});
+
+	pi.on("session_shutdown", () => {
+		hold.cancel();
+		unsubscribe?.();
+		unsubscribe = undefined;
+	});
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "pi-push-to-talk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Hold space to dictate into pi's prompt, transcribed locally with Whisper.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "dictation",
+    "push-to-talk",
+    "speech-to-text",
+    "whisper",
+    "local"
+  ],
+  "license": "MIT",
+  "author": "sqwxl",
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "files": ["index.ts", "src/**/*.ts", "!src/**/*.test.ts", "README.md", "LICENSE"],
+  "dependencies": {
+    "decibri": "^3.4.2",
+    "sherpa-onnx-node": "^1.13.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": { "optional": true }
+  }
+}

package/src/capture.ts

@@ -0,0 +1,92 @@
+/**
+ * Microphone capture.
+ *
+ * Asks the device for 16 kHz mono directly; falls back to a native rate with a
+ * linear resampler when the device refuses, which is what built-in mics do on
+ * some Linux setups.
+ */
+import { createRequire } from "node:module";
+import { SAMPLE_RATE, msToSamples } from "./config.ts";
+
+const require = createRequire(import.meta.url);
+
+export interface Microphone {
+	stop(): void;
+}
+
+const FALLBACK_RATES = [SAMPLE_RATE, 48000, 44100];
+
+function toFloat32(chunk: Buffer): Float32Array {
+	const count = Math.floor(chunk.length / 2);
+	const out = new Float32Array(count);
+	for (let i = 0; i < count; i++) out[i] = chunk.readInt16LE(i * 2) / 32768;
+	return out;
+}
+
+/** Linear resampler with phase carried across chunks. */
+function makeResampler(fromRate: number): (input: Float32Array) => Float32Array {
+	if (fromRate === SAMPLE_RATE) return (input) => input;
+	const step = fromRate / SAMPLE_RATE;
+	let position = 0;
+	let last = 0;
+
+	return (input) => {
+		const out: number[] = [];
+		for (;;) {
+			const index = Math.floor(position);
+			if (index + 1 >= input.length) break;
+			const frac = position - index;
+			const a = index < 0 ? last : (input[index] ?? 0);
+			const b = input[index + 1] ?? 0;
+			out.push(a + (b - a) * frac);
+			position += step;
+		}
+		position -= input.length;
+		last = input[input.length - 1] ?? last;
+		return Float32Array.from(out);
+	};
+}
+
+export async function openMicrophone(
+	onSamples: (samples: Float32Array) => void,
+	onError: (error: Error) => void,
+): Promise<Microphone> {
+	const Decibri = require("decibri");
+	let failure: Error = new Error("no capture device");
+
+	for (const rate of FALLBACK_RATES) {
+		try {
+			const mic = new Decibri({
+				sampleRate: rate,
+				channels: 1,
+				framesPerBuffer: Math.round((msToSamples(100) * rate) / SAMPLE_RATE),
+				format: "int16",
+			});
+			const resample = makeResampler(rate);
+			let stopped = false;
+			mic.on("data", (chunk: Buffer) => {
+				const samples = resample(toFloat32(chunk));
+				if (samples.length > 0) onSamples(samples);
+			});
+			mic.on("error", (error: Error) => {
+				if (!stopped) onError(error);
+			});
+			// A device that disappears mid-recording must not leave a silent session.
+			for (const event of ["end", "close"] as const) {
+				mic.once(event, () => {
+					if (!stopped) onError(new Error("microphone stream ended"));
+				});
+			}
+			return {
+				stop: () => {
+					stopped = true;
+					mic.stop();
+				},
+			};
+		} catch (error) {
+			failure = error instanceof Error ? error : new Error(String(error));
+		}
+	}
+
+	throw failure;
+}

package/src/config.ts

@@ -0,0 +1,41 @@
+import os from "node:os";
+import path from "node:path";
+
+export const SAMPLE_RATE = 16000;
+
+/** How often the still-open phrase is re-decoded for the live preview. */
+export const PARTIAL_INTERVAL_MS = 1000;
+
+/**
+ * Silence that closes a phrase.
+ *
+ * Long on purpose: a pause mid-sentence is the speaker thinking, not the end of
+ * a thought. Cutting there splits words across two decodes, which is where lost
+ * and reordered words come from. The 12 s cap still bounds a non-stop stretch.
+ */
+export const SILENCE_COMMIT_MS = 2500;
+
+/** Trailing silence kept with a phrase so its last word is not clipped. */
+export const TAIL_PAD_MS = 300;
+
+/** Shorter buffers are not worth a decode. */
+export const MIN_PHRASE_MS = 400;
+
+/** Longest phrase sent to the recognizer in one piece. */
+export const MAX_PHRASE_MS = 12000;
+
+/** Window scanned for the quietest point when the cap fires. */
+export const CAP_CUT_SCAN_MS = 800;
+
+/** Mean level below which a buffer counts as silence, not speech. */
+export const MIN_PHRASE_RMS = 0.005;
+
+/** SPACE held this long starts dictating. */
+export const HOLD_MS = 350;
+
+/** A space this soon after typing stays a space (pi-voicekit's value). */
+export const TYPING_COOLDOWN_MS = 400;
+
+export const MODEL_DIR = path.join(os.homedir(), ".pi", "models", "whisper-base");
+
+export const msToSamples = (ms: number): number => Math.round((SAMPLE_RATE * ms) / 1000);

package/src/debug.ts

@@ -0,0 +1,20 @@
+/**
+ * Opt-in trace for the space state machine. `PI_DICTATION_DEBUG=1 pi` writes
+ * one line per space event to /tmp/pi-dictation.log — the only way to tell a
+ * missing release from an unmatched one.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const ENABLED = !!process.env.PI_DICTATION_DEBUG;
+export const LOG_FILE = path.join(os.tmpdir(), "pi-dictation.log");
+
+export function trace(message: string): void {
+	if (!ENABLED) return;
+	try {
+		fs.appendFileSync(LOG_FILE, `${new Date().toISOString()} ${message}\n`);
+	} catch {
+		// Diagnostics must never break input handling.
+	}
+}

package/src/dim.ts

@@ -0,0 +1,85 @@
+/**
+ * Dim the uncommitted transcript: the N characters just before the cursor.
+ *
+ * The editor renders the cursor as zero-width APC markers around one character,
+ * so the end of the open text is unambiguous. Everything else here is ANSI
+ * bookkeeping: escape sequences are zero-width, so they must not be counted.
+ */
+const FAKE_CURSOR_START = "\x1b_pi:fc\x07";
+const ANSI = /\x1b(?:\[[0-9;?]*[A-Za-z]|_pi:[^\x07]*\x07)/y;
+
+const DIM_ON = "\x1b[2m";
+const DIM_OFF = "\x1b[22m";
+
+/** Visible characters of a line, with the string index where each starts. */
+function visibleChars(line: string): Array<{ text: string; at: number }> {
+	const out: Array<{ text: string; at: number }> = [];
+	let at = 0;
+	while (at < line.length) {
+		ANSI.lastIndex = at;
+		const escape = ANSI.exec(line);
+		if (escape) {
+			at += escape[0].length;
+			continue;
+		}
+		const char = String.fromCodePoint(line.codePointAt(at) ?? 0);
+		out.push({ text: char, at });
+		at += char.length;
+	}
+	return out;
+}
+
+/**
+ * Wrap the `count` visible characters before the cursor in dim, per line.
+ * Returns the input untouched when the cursor cannot be found or `count` is 0.
+ */
+export function dimBeforeCursor(lines: readonly string[], count: number): string[] {
+	if (count <= 0) return lines as string[];
+
+	const cursorLine = lines.findIndex((line) => line.includes(FAKE_CURSOR_START));
+	if (cursorLine === -1) return lines as string[];
+
+	// Characters before the cursor, walking back from the cursor line.
+	const targets: Array<{ line: number; at: number; length: number }> = [];
+	let remaining = count;
+
+	for (let lineIndex = cursorLine; lineIndex >= 0 && remaining > 0; lineIndex--) {
+		const chars = visibleChars(lines[lineIndex] ?? "");
+		let limit = chars.length;
+		if (lineIndex === cursorLine) {
+			const markerAt = (lines[lineIndex] ?? "").indexOf(FAKE_CURSOR_START);
+			limit = chars.filter((char) => char.at < markerAt).length;
+		}
+		for (let i = limit - 1; i >= 0 && remaining > 0; i--) {
+			const char = chars[i];
+			if (!char) continue;
+			targets.push({ line: lineIndex, at: char.at, length: char.text.length });
+			remaining--;
+		}
+	}
+	if (targets.length === 0) return [...lines];
+
+	const first = targets[targets.length - 1];
+	const last = targets[0];
+	if (!first || !last) return [...lines];
+
+	const byLine = new Map<number, Array<{ at: number; text: string }>>();
+	const push = (line: number, at: number, text: string) => {
+		const list = byLine.get(line) ?? [];
+		list.push({ at, text });
+		byLine.set(line, list);
+	};
+	push(first.line, first.at, DIM_ON);
+	push(last.line, last.at + last.length, DIM_OFF);
+
+	const out = [...lines];
+	for (const [lineIndex, insertions] of byLine) {
+		let line = out[lineIndex] ?? "";
+		// Right to left so earlier indices stay valid.
+		for (const insertion of [...insertions].sort((a, b) => b.at - a.at)) {
+			line = line.slice(0, insertion.at) + insertion.text + line.slice(insertion.at);
+		}
+		out[lineIndex] = line;
+	}
+	return out;
+}

package/src/editor.ts

@@ -0,0 +1,65 @@
+/**
+ * The prompt editor, extended with cursor-preserving writes and dim rendering
+ * of the uncommitted transcript.
+ *
+ * Key handling lives in SpaceHold, which sits on the raw terminal input path.
+ * Nothing here can swallow a keystroke.
+ */
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { dimBeforeCursor } from "./dim.ts";
+
+/** Guard against pathological cursor rewinds on very long buffers. */
+const MAX_CURSOR_REWIND = 4000;
+
+export class DictationEditor extends CustomEditor {
+	/** Characters before the cursor that are not committed yet. */
+	private partialLength = 0;
+	/** Last buffer state written, so identical rewrites are skipped. */
+	private lastWrite = "";
+
+	override render(width: number): string[] {
+		const lines = super.render(width);
+		return dimBeforeCursor(lines, this.partialLength);
+	}
+
+	/** Absolute offset of the cursor in the buffer. */
+	insertionOffset(): number {
+		const { line, col } = this.getCursor();
+		const lines = this.getLines();
+		let offset = 0;
+		for (let i = 0; i < line && i < lines.length; i++) offset += (lines[i] ?? "").length + 1;
+		return offset + col;
+	}
+
+	/** Replace the buffer, keep the cursor at `cursorOffset`, dim `partialLength` before it. */
+	writeAtCursor(text: string, cursorOffset: number, partialLength: number): void {
+		const state = `${cursorOffset}:${partialLength}:${text}`;
+		if (state === this.lastWrite) return;
+		this.lastWrite = state;
+
+		this.setText(text);
+		let rewind = Math.min(MAX_CURSOR_REWIND, Math.max(0, text.length - cursorOffset));
+		while (rewind > 0) {
+			super.handleInput("\x1b[D");
+			rewind--;
+		}
+		// UTF-16 length; identical to the visible count for the scripts this is
+		// used with, and an off-by-one only trims one cell from the dim span.
+		this.partialLength = Math.max(0, partialLength);
+		// setText does not repaint on its own, so timer-driven writes would stay
+		// invisible until the next keystroke.
+		this.tui.requestRender(true);
+	}
+
+	/** Insert a literal space at the cursor. */
+	typeSpace(): void {
+		super.handleInput(" ");
+		this.tui.requestRender(true);
+	}
+
+	/** Remove one character before the cursor (the space typed by the key press). */
+	deleteBackward(): void {
+		super.handleInput("\x7f");
+		this.tui.requestRender(true);
+	}
+}

package/src/hold.ts

@@ -0,0 +1,174 @@
+/**
+ * Hold SPACE to dictate.
+ *
+ * Hooks `ctx.ui.onTerminalInput`, the raw terminal path, because that is where
+ * kitty key releases arrive. The press is left to the editor, so typing a space
+ * never depends on this state machine: if the key stays down past HOLD_MS the
+ * space the editor just typed is taken back and dictation starts.
+ */
+import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
+import { HOLD_MS, TYPING_COOLDOWN_MS } from "./config.ts";
+import { trace } from "./debug.ts";
+import type { DictationEditor } from "./editor.ts";
+import { createRegion } from "./region.ts";
+import { DictationSession, type SessionUi } from "./session.ts";
+import type { Stt } from "./stt.ts";
+
+export type HoldDeps = {
+	getEditor: () => DictationEditor | undefined;
+	getStt: () => Promise<Stt>;
+	notify: (message: string, level: "info" | "warning" | "error") => void;
+	status: (text: string | undefined) => void;
+	/** Test seam; production uses DictationSession. */
+	createSession?: (stt: Stt, ui: SessionUi) => DictationSession;
+};
+
+/** A hold with no release event for this long is treated as stale. */
+const STALE_HOLD_MS = 5000;
+
+export class SpaceHold {
+	private readonly deps: HoldDeps;
+	private session: DictationSession | undefined;
+	private holdTimer: ReturnType<typeof setTimeout> | undefined;
+	private holding = false;
+	private holdingSince = 0;
+	private lastTypingAt = 0;
+	private starting = false;
+	/** Resolves when the previous session finished its final decode. */
+	private stopping: Promise<unknown> = Promise.resolve();
+
+	constructor(deps: HoldDeps) {
+		this.deps = deps;
+	}
+
+	/** Returns true when the event belongs to dictation and must be consumed. */
+	handle(data: string): boolean {
+		const editor = this.deps.getEditor();
+
+		// Raw terminal input is global: dialogs and nested editors receive it too.
+		// Without this guard a space typed into a permission prompt would start
+		// dictation instead of reaching that editor.
+		if (editor && editor.focused === false) {
+			if (this.session?.isActive()) this.cancel();
+			return false;
+		}
+
+		if (matchesKey(data, "space")) return this.handleSpace(isKeyRelease(data), isKeyRepeat(data));
+
+		if (!isKeyRelease(data) && !isKeyRepeat(data) && data.length === 1 && data.charCodeAt(0) >= 32) {
+			this.lastTypingAt = Date.now();
+		}
+		return false;
+	}
+
+	/** Abandon any open session without committing, e.g. when the prompt is submitted. */
+	cancel(): void {
+		this.holding = false;
+		this.clearHoldTimer();
+		this.session?.cancel();
+		this.session = undefined;
+	}
+
+	private handleSpace(released: boolean, repeated: boolean): boolean {
+		trace(
+			`space release=${String(released)} repeat=${String(repeated)} holding=${String(this.holding)} active=${String(this.session?.isActive())}`,
+		);
+
+		if (this.session?.isActive()) {
+			if (released) this.finish();
+			return true; // space events are meaningless while dictating
+		}
+
+		if (released) {
+			this.holding = false;
+			this.clearHoldTimer();
+			return false; // the space the editor typed stays
+		}
+
+		// Repeats of a held key must not type more spaces; the first one is the
+		// space we take back when the hold threshold is reached.
+		if (this.holding) {
+			if (Date.now() - this.holdingSince > STALE_HOLD_MS) {
+				this.holding = false; // release was lost; recover typing
+				return false;
+			}
+			return true;
+		}
+
+		if (repeated) return false;
+		if (Date.now() - this.lastTypingAt < TYPING_COOLDOWN_MS) return false;
+
+		this.holding = true;
+		this.holdingSince = Date.now();
+		this.holdTimer = setTimeout(() => {
+			this.holdTimer = undefined;
+			void this.begin();
+		}, HOLD_MS);
+		return false;
+	}
+
+	private finish(): void {
+		this.holding = false;
+		this.clearHoldTimer();
+		if (this.session) this.stopping = this.session.stop();
+		void this.stopping;
+	}
+
+	private async begin(): Promise<void> {
+		if (this.starting) return;
+		this.starting = true;
+		try {
+			const editor = this.deps.getEditor();
+			if (!editor) return;
+
+			// Take back the space the editor typed when the key went down.
+			editor.deleteBackward();
+
+			// A previous stop may still be decoding its tail; its write would land
+			// on top of the text this session is about to produce.
+			await this.stopping;
+
+			// Released before capture began: the tap must not vanish.
+			if (!this.holding) {
+				editor.typeSpace();
+				return;
+			}
+
+			const stt = await this.deps.getStt();
+			if (!this.holding) {
+				editor.typeSpace();
+				return;
+			}
+
+			const ui: SessionUi = {
+				write: (text, cursorOffset, partialLength) => editor.writeAtCursor(text, cursorOffset, partialLength),
+				status: (text) => this.deps.status(text),
+				notify: (message, level) => this.deps.notify(message, level),
+			};
+			const create = this.deps.createSession ?? ((engine, sessionUi) => new DictationSession(engine, sessionUi));
+			const session = create(stt, ui);
+			this.session = session;
+			await session.start(createRegion(editor.getText(), editor.insertionOffset()));
+
+			// Released while the capture device was opening: close it, and give the
+			// space back if nothing was transcribed.
+			if (!this.holding) {
+				const committed = await session.stop();
+				if (!committed) editor.typeSpace();
+			}
+		} catch (error) {
+			this.deps.notify(`Dictation: ${String(error)}`, "error");
+			// Nothing was transcribed, so the deleted space comes back.
+			if (!this.session?.isActive()) this.deps.getEditor()?.typeSpace();
+		} finally {
+			this.starting = false;
+		}
+	}
+
+	private clearHoldTimer(): void {
+		if (this.holdTimer) {
+			clearTimeout(this.holdTimer);
+			this.holdTimer = undefined;
+		}
+	}
+}

package/src/model.ts

@@ -0,0 +1,84 @@
+/**
+ * Model bootstrap.
+ *
+ * The recognizer needs whisper-base int8 on disk. Fetching it is part of first
+ * use, not an install step, so a fresh `pi install` works without instructions.
+ * System `tar` does the extraction because the archive is bzip2.
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { promisify } from "node:util";
+import { MODEL_DIR } from "./config.ts";
+
+const execFileAsync = promisify(execFile);
+
+const ARCHIVE_URL =
+	"https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-whisper-base.tar.bz2";
+
+/** Files the recognizer loads, all int8. */
+export const REQUIRED_FILES = ["base-encoder.int8.onnx", "base-decoder.int8.onnx", "base-tokens.txt"] as const;
+
+/** Full-precision duplicates in the archive; not used on CPU. */
+const FP32_FILES = ["base-encoder.onnx", "base-decoder.onnx"];
+
+export type Progress = (message: string) => void;
+
+export function modelReady(dir: string = MODEL_DIR): boolean {
+	return REQUIRED_FILES.every((file) => fs.existsSync(path.join(dir, file)));
+}
+
+async function download(url: string, destination: string, onProgress?: Progress): Promise<void> {
+	const response = await fetch(url, { redirect: "follow" });
+	if (!response.ok || !response.body) {
+		throw new Error(`model download failed: HTTP ${response.status}`);
+	}
+
+	const total = Number(response.headers.get("content-length") ?? 0);
+	let received = 0;
+	let reported = -1;
+
+	const source = Readable.fromWeb(response.body as Parameters<typeof Readable.fromWeb>[0]);
+	source.on("data", (chunk: Buffer) => {
+		received += chunk.length;
+		if (!onProgress || total === 0) return;
+		const percent = Math.floor((received / total) * 100);
+		if (percent >= reported + 10) {
+			reported = percent;
+			onProgress(`Downloading Whisper base ${percent}%`);
+		}
+	});
+
+	await pipeline(source, fs.createWriteStream(destination));
+}
+
+/** Ensure the model directory holds every required file; download it once if not. */
+export async function ensureModel(dir: string = MODEL_DIR, onProgress?: Progress): Promise<string> {
+	if (modelReady(dir)) return dir;
+
+	fs.mkdirSync(dir, { recursive: true });
+	const archive = path.join(os.tmpdir(), `pi-dictation-${process.pid}.tar.bz2`);
+
+	try {
+		onProgress?.("Downloading Whisper base (198 MB, once)");
+		await download(ARCHIVE_URL, archive, onProgress);
+
+		onProgress?.("Extracting model files");
+		// --strip-components drops the archive's wrapper directory.
+		await execFileAsync("tar", ["-xjf", archive, "--strip-components=1", "-C", dir]);
+
+		for (const file of FP32_FILES) fs.rmSync(path.join(dir, file), { force: true });
+		// Sample clips from the archive; not used by the recognizer.
+		fs.rmSync(path.join(dir, "test_wavs"), { recursive: true, force: true });
+	} finally {
+		fs.rmSync(archive, { force: true });
+	}
+
+	if (!modelReady(dir)) {
+		throw new Error(`model files missing after extraction in ${dir}`);
+	}
+	return dir;
+}

package/src/probe.ts

@@ -0,0 +1,26 @@
+/**
+ * Temporary key probe.
+ *
+ * Hold-to-talk needs a key whose press *and* release both reach the app. This
+ * editor logs every sequence the terminal sends, so the binding can be chosen
+ * from evidence instead of guessed. Enabled with PI_DICTATION_PROBE=1.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+
+export const PROBE_LOG = path.join(os.tmpdir(), "pi-dictation-probe.log");
+
+export class ProbeEditor extends CustomEditor {
+	override handleInput(data: string): void {
+		try {
+			const hex = Buffer.from(data, "utf8").toString("hex");
+			const printable = /^[\x20-\x7e]+$/.test(data) ? JSON.stringify(data) : "-";
+			fs.appendFileSync(PROBE_LOG, `${new Date().toISOString()} hex=${hex} text=${printable}\n`);
+		} catch {
+			// A diagnostic must never break typing.
+		}
+		super.handleInput(data);
+	}
+}

package/src/region.ts

@@ -0,0 +1,47 @@
+/**
+ * The text region the current dictation owns.
+ *
+ * `before` and `after` are frozen when the key is pressed, so the rest of the
+ * buffer is never rewritten. Only `committed` + `partial` change while the key
+ * is held.
+ */
+export type Region = {
+	before: string;
+	committed: string;
+	partial: string;
+	after: string;
+};
+
+/** True when two pieces would glue together without a space. */
+const needsSpace = (left: string, right: string): boolean =>
+	left.length > 0 && right.length > 0 && !/\s$/.test(left) && !/^\s/.test(right);
+
+/** Join two pieces with a space unless the seam is already whitespace. */
+export function joinText(left: string, right: string): string {
+	return needsSpace(left, right) ? `${left} ${right}` : left + right;
+}
+
+export function createRegion(text: string, offset: number): Region {
+	const at = Math.max(0, Math.min(offset, text.length));
+	return { before: text.slice(0, at), committed: "", partial: "", after: text.slice(at) };
+}
+
+export function withPartial(region: Region, partial: string): Region {
+	return { ...region, partial };
+}
+
+export function commitPartial(region: Region): Region {
+	if (region.partial.trim().length === 0) return { ...region, partial: "" };
+	return { ...region, committed: joinText(region.committed, region.partial.trim()), partial: "" };
+}
+
+const renderHead = (region: Region): string => joinText(joinText(region.before, region.committed), region.partial);
+
+export function renderRegion(region: Region): string {
+	return joinText(renderHead(region), region.after);
+}
+
+/** Where the cursor belongs: right after the text this session owns. */
+export function regionCursorOffset(region: Region): number {
+	return renderHead(region).length;
+}

package/src/segmenter.ts

@@ -0,0 +1,137 @@
+/**
+ * Phrase boundaries.
+ *
+ * A phrase closes on SILENCE_COMMIT_MS of quiet, or at MAX_PHRASE_MS. The cap
+ * cuts at the quietest point of the trailing CAP_CUT_SCAN_MS so it lands in a
+ * breath rather than mid-syllable; the tail carries into the next phrase.
+ */
+import {
+	CAP_CUT_SCAN_MS,
+	MAX_PHRASE_MS,
+	MIN_PHRASE_RMS,
+	SILENCE_COMMIT_MS,
+	TAIL_PAD_MS,
+	msToSamples,
+} from "./config.ts";
+
+export type ClosedPhrase = {
+	samples: Float32Array;
+	reason: "silence" | "cap";
+};
+
+/**
+ * Level of a buffer, with its mean removed.
+ *
+ * Centring matters: a capture stream with a constant offset reads as loud even
+ * in silence, which would defeat the silence gate entirely.
+ */
+export function rmsOf(samples: Float32Array): number {
+	if (samples.length === 0) return 0;
+	let sum = 0;
+	for (let i = 0; i < samples.length; i++) sum += samples[i] ?? 0;
+	const mean = sum / samples.length;
+
+	let energy = 0;
+	for (let i = 0; i < samples.length; i++) {
+		const centred = (samples[i] ?? 0) - mean;
+		energy += centred * centred;
+	}
+	return Math.sqrt(energy / samples.length);
+}
+
+function concat(chunks: readonly Float32Array[]): Float32Array {
+	const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+	const out = new Float32Array(total);
+	let at = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, at);
+		at += chunk.length;
+	}
+	return out;
+}
+
+export class Segmenter {
+	private chunks: Float32Array[] = [];
+	private total = 0;
+	private silent = 0;
+	private hasSpeech = false;
+
+	/** Feed captured audio; returns a phrase when one closes. */
+	add(samples: Float32Array): ClosedPhrase | undefined {
+		if (samples.length === 0) return undefined;
+		this.chunks.push(samples);
+		this.total += samples.length;
+
+		const quiet = rmsOf(samples) < MIN_PHRASE_RMS;
+		if (quiet) {
+			this.silent += samples.length;
+		} else {
+			this.silent = 0;
+			this.hasSpeech = true;
+		}
+
+		const silenceLimit = msToSamples(SILENCE_COMMIT_MS);
+		if (this.silent >= silenceLimit) {
+			// Nothing was ever said: drop the buffer instead of closing on it,
+			// otherwise every quiet stretch would ask the recognizer to caption
+			// silence.
+			if (!this.hasSpeech) {
+				this.reset();
+				return undefined;
+			}
+			return this.closeAt(Math.min(this.total, Math.max(0, this.total - this.silent + msToSamples(TAIL_PAD_MS))), "silence");
+		}
+
+		if (this.total >= msToSamples(MAX_PHRASE_MS)) {
+			return this.closeAt(this.quietestCut(), "cap");
+		}
+
+		return undefined;
+	}
+
+	/** The still-open buffer, for the live preview decode. */
+	open(): Float32Array {
+		return concat(this.chunks);
+	}
+
+	/** Drop everything buffered, e.g. on cancel. */
+	reset(): void {
+		this.chunks = [];
+		this.total = 0;
+		this.silent = 0;
+		this.hasSpeech = false;
+	}
+
+	private closeAt(cut: number, reason: ClosedPhrase["reason"]): ClosedPhrase {
+		const all = concat(this.chunks);
+		const head = all.slice(0, cut);
+		// Silence that closed a phrase is not carried into the next one; only a
+		// cap cut keeps its tail, because that tail is still speech.
+		const tail = reason === "cap" ? all.slice(cut) : new Float32Array(0);
+		this.chunks = tail.length > 0 ? [tail] : [];
+		this.total = tail.length;
+		this.silent = 0;
+		// A cap cut keeps speech in the tail; a tail of pure silence must not
+		// look like speech, or the next phrase would decode silence.
+		this.hasSpeech = tail.length > 0 && rmsOf(tail) >= MIN_PHRASE_RMS;
+		return { samples: head, reason };
+	}
+
+	/** Start of the quietest 10 ms window in the trailing scan range. */
+	private quietestCut(): number {
+		const all = concat(this.chunks);
+		const scan = Math.min(all.length, msToSamples(CAP_CUT_SCAN_MS));
+		const step = msToSamples(10);
+		const from = Math.max(0, all.length - scan);
+		let bestAt = from;
+		let bestRms = Number.POSITIVE_INFINITY;
+		for (let at = from; at < all.length; at += step) {
+			const rms = rmsOf(all.subarray(at, Math.min(at + step, all.length)));
+			if (rms < bestRms) {
+				bestRms = rms;
+				bestAt = at;
+			}
+		}
+		return bestAt;
+	}
+}

package/src/session.ts

@@ -0,0 +1,190 @@
+/**
+ * One dictation stretch: mic -> segmenter -> recognizer -> editor region.
+ *
+ * The region is created on key press and frozen on release. Nothing outside it
+ * is ever rewritten, so the rest of the buffer stays the user's.
+ */
+import { openMicrophone, type Microphone } from "./capture.ts";
+import { MIN_PHRASE_MS, MIN_PHRASE_RMS, PARTIAL_INTERVAL_MS, msToSamples } from "./config.ts";
+import { trace } from "./debug.ts";
+import { commitPartial, joinText, regionCursorOffset, renderRegion, withPartial, type Region } from "./region.ts";
+import { Segmenter, rmsOf } from "./segmenter.ts";
+import type { Stt } from "./stt.ts";
+import { cleanTranscript } from "./transcript.ts";
+
+export type SessionUi = {
+	/** Replace the editor text, place the cursor at `cursorOffset`, dim `partialLength` before it. */
+	write(text: string, cursorOffset: number, partialLength: number): void;
+	status(text: string | undefined): void;
+	notify(message: string, level: "info" | "warning" | "error"): void;
+};
+
+const MIN_PHRASE_SAMPLES = msToSamples(MIN_PHRASE_MS);
+
+/** Whisper ends a decode with a full stop; mid-session that is not the sentence end. */
+const TRAILING_PERIOD = /\.\s*$/;
+
+export class DictationSession {
+	private readonly stt: Stt;
+	private readonly ui: SessionUi;
+	private readonly openMic: typeof openMicrophone;
+	private region: Region | undefined;
+	private mic: Microphone | undefined;
+	private segmenter = new Segmenter();
+	private timer: ReturnType<typeof setInterval> | undefined;
+	private pending = 0;
+	private stopped = true;
+	/** Characters committed during this session, to tell a real result from silence. */
+	private committedChars = 0;
+
+	constructor(stt: Stt, ui: SessionUi, openMic: typeof openMicrophone = openMicrophone) {
+		this.stt = stt;
+		this.ui = ui;
+		this.openMic = openMic;
+	}
+
+	async start(region: Region): Promise<void> {
+		if (!this.stopped) return;
+		this.stopped = false;
+		this.region = region;
+		this.segmenter = new Segmenter();
+		this.committedChars = 0;
+		this.ui.status("MIC listening");
+
+		try {
+			this.mic = await this.openMic(
+				(samples) => this.onSamples(samples),
+				(error) => this.fail(error),
+			);
+		} catch (error) {
+			this.stopped = true;
+			this.ui.status(undefined);
+			this.ui.notify(`Dictation: microphone unavailable (${String(error)})`, "error");
+			return;
+		}
+
+		// Released while the device was still opening.
+		if (this.stopped) {
+			this.mic.stop();
+			this.mic = undefined;
+			return;
+		}
+
+		this.timer = setInterval(() => void this.preview(), PARTIAL_INTERVAL_MS);
+	}
+
+	isActive(): boolean {
+		return !this.stopped;
+	}
+
+	/** Decode what is still open, commit it, and close the session. Returns whether anything was transcribed. */
+	async stop(): Promise<boolean> {
+		if (this.stopped) return false;
+		this.stopped = true;
+		this.clearTimer();
+		this.mic?.stop();
+		this.mic = undefined;
+
+		const tail = this.segmenter.open();
+		this.segmenter.reset();
+		if (tail.length >= MIN_PHRASE_SAMPLES && rmsOf(tail) >= MIN_PHRASE_RMS) {
+			await this.decodePhrase(tail, true);
+		}
+
+		// A preview of audio that was never committed must not stay in the buffer.
+		if (this.region && this.region.partial.length > 0) {
+			this.region = { ...this.region, partial: "" };
+			this.write();
+		}
+
+		const committed = this.committedChars > 0;
+		this.ui.status(undefined);
+		this.region = undefined;
+		return committed;
+	}
+
+	/** Abandon the session and remove whatever it wrote. */
+	cancel(): void {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.clearTimer();
+		this.mic?.stop();
+		this.mic = undefined;
+		this.segmenter.reset();
+
+		if (this.region && (this.region.committed.length > 0 || this.region.partial.length > 0)) {
+			const cleaned = joinText(this.region.before, this.region.after);
+			this.ui.write(cleaned, this.region.before.length, 0);
+		}
+		this.ui.status(undefined);
+		this.region = undefined;
+	}
+
+	private onSamples(samples: Float32Array): void {
+		if (this.stopped) return;
+		const closed = this.segmenter.add(samples);
+		if (!closed) return;
+		if (rmsOf(closed.samples) < MIN_PHRASE_RMS) return;
+		// A phrase closing while the session is open is not the end of the thought:
+		// its trailing full stop is Whisper's, not the speaker's.
+		void this.decodePhrase(closed.samples, false);
+	}
+
+	private async decodePhrase(samples: Float32Array, final: boolean): Promise<void> {
+		this.pending++;
+		try {
+			const raw = await this.stt.recognize(samples);
+			trace(`phrase ${samples.length} samples final=${String(final)} -> ${JSON.stringify(raw)}`);
+			const text = cleanTranscript(raw);
+			this.commitText(final ? text : text.replace(TRAILING_PERIOD, ""));
+		} catch (error) {
+			this.fail(error instanceof Error ? error : new Error(String(error)));
+		} finally {
+			this.pending--;
+		}
+	}
+
+	private async preview(): Promise<void> {
+		// Let queued phrases land first so the preview never rewrites newer text.
+		if (this.pending > 0 || this.stopped || !this.region) return;
+		const open = this.segmenter.open();
+		if (open.length < MIN_PHRASE_SAMPLES || rmsOf(open) < MIN_PHRASE_RMS) return;
+
+		this.pending++;
+		try {
+			const text = cleanTranscript(await this.stt.recognize(open));
+			if (this.stopped || !this.region) return;
+			this.region = withPartial(this.region, text);
+			this.write();
+		} catch (error) {
+			this.fail(error instanceof Error ? error : new Error(String(error)));
+		} finally {
+			this.pending--;
+		}
+	}
+
+	private commitText(text: string): void {
+		const clean = text.trim();
+		if (!this.region || clean.length === 0) return;
+		this.region = commitPartial(withPartial(this.region, clean));
+		this.committedChars += clean.length;
+		this.write();
+	}
+
+	private write(): void {
+		if (!this.region) return;
+		this.ui.write(renderRegion(this.region), regionCursorOffset(this.region), this.region.partial.length);
+	}
+
+	private fail(error: Error): void {
+		this.ui.notify(`Dictation: ${error.message}`, "error");
+		this.cancel();
+	}
+
+	private clearTimer(): void {
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = undefined;
+		}
+	}
+}

package/src/stt.ts

@@ -0,0 +1,98 @@
+/**
+ * whisper-base int8 through sherpa-onnx-node.
+ *
+ * Decodes are FIFO-queued: the native handle tolerates one decode at a time and
+ * the preview can overlap a phrase commit.
+ */
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { MODEL_DIR, SAMPLE_RATE } from "./config.ts";
+import { trace } from "./debug.ts";
+import { ensureModel } from "./model.ts";
+
+const require = createRequire(import.meta.url);
+
+type Recognizer = {
+	createStream(): unknown;
+	getResult(stream: unknown): { text?: string } | undefined;
+	decodeAsync?(stream: unknown): Promise<void>;
+	decode?(stream: unknown): void;
+};
+
+type RecognizerCtor = {
+	new (config: unknown): Recognizer;
+	createAsync?(config: unknown): Promise<Recognizer>;
+};
+
+/** Four threads is the sweet spot for these int8 models; do not starve the app. */
+const THREADS = Math.max(1, Math.min(4, os.cpus().length - 1));
+
+function recognizerConfig(modelDir: string): unknown {
+	return {
+		featConfig: { sampleRate: SAMPLE_RATE, featureDim: 80 },
+		modelConfig: {
+			whisper: {
+				encoder: path.join(modelDir, "base-encoder.int8.onnx"),
+				decoder: path.join(modelDir, "base-decoder.int8.onnx"),
+				language: "en",
+				task: "transcribe",
+				// Trailing padding keeps Whisper from missing EOS and inventing a
+				// closing phrase on short buffers (sherpa-onnx#2787).
+				tailPaddings: 1000,
+			},
+			tokens: path.join(modelDir, "base-tokens.txt"),
+			numThreads: THREADS,
+			provider: "cpu",
+		},
+	};
+}
+
+export class Stt {
+	private readonly recognizer: Recognizer;
+	private queue: Promise<unknown> = Promise.resolve();
+
+	private constructor(recognizer: Recognizer) {
+		this.recognizer = recognizer;
+	}
+
+	/** Async so loading the model does not block the UI on first dictation. */
+	static async create(modelDir: string = MODEL_DIR, onProgress?: (message: string) => void): Promise<Stt> {
+		await ensureModel(modelDir, onProgress);
+		const sherpa = require("sherpa-onnx-node");
+		const RecognizerClass = sherpa.OfflineRecognizer as RecognizerCtor;
+		const config = recognizerConfig(modelDir);
+		const recognizer =
+			typeof RecognizerClass.createAsync === "function"
+				? await RecognizerClass.createAsync(config)
+				: new RecognizerClass(config);
+		return new Stt(recognizer);
+	}
+
+	/** Transcribe 16 kHz mono samples. Never rejects; returns "" on failure. */
+	recognize(samples: Float32Array): Promise<string> {
+		const run = this.queue
+			.then(() => this.decode(samples))
+			.catch((error: unknown) => {
+				trace(`recognize failed: ${String(error)}`);
+				return "";
+			});
+		this.queue = run;
+		return run;
+	}
+
+	private async decode(samples: Float32Array): Promise<string> {
+		if (samples.length === 0) return "";
+		const stream = this.recognizer.createStream();
+		(stream as { acceptWaveform(input: { sampleRate: number; samples: Float32Array }): void }).acceptWaveform({
+			sampleRate: SAMPLE_RATE,
+			samples,
+		});
+		if (typeof this.recognizer.decodeAsync === "function") {
+			await this.recognizer.decodeAsync(stream);
+		} else if (typeof this.recognizer.decode === "function") {
+			this.recognizer.decode(stream);
+		}
+		return String(this.recognizer.getResult(stream)?.text ?? "").trim();
+	}
+}

package/src/transcript.ts

@@ -0,0 +1,24 @@
+/**
+ * Transcript cleanup.
+ *
+ * Whisper captions non-speech instead of returning nothing: `[Music]`,
+ * `(footsteps)`, `♪`. Those come from near-silent audio, which the level gate
+ * is supposed to reject — it cannot on a stream with a DC offset, so the
+ * artifacts are removed after decoding as well.
+ */
+
+/** Bracketed annotations, musical notes, and repeated punctuation. */
+const CAPTION = /[\[(][^\])]*[\])]/g;
+const MUSIC = /[♪♫♬♩]/g;
+/** Stray brackets left behind by a caption or by decoded noise. */
+const STRAY_BRACKET = /[\[\]]/g;
+
+export function cleanTranscript(text: string): string {
+	return text
+		.replace(CAPTION, " ")
+		.replace(MUSIC, " ")
+		.replace(STRAY_BRACKET, " ")
+		.replace(/\s+/g, " ")
+		.replace(/\s+([,.!?;:])/g, "$1")
+		.trim();
+}