pi-voicekit 0.2.0 → 0.2.2

package/README.md

@@ -381,12 +381,28 @@ One measured behaviour is worth knowing: a model that thinks before it answers m
 spoken operator into its symbol — `select star` comes back as `select *`. The information is
 unchanged, there is no setting for it, and `/voice-polish off` is the way to keep the words verbatim.
 
+A reasoning model used to spend its whole token budget thinking about a long dictation, so the
+answer was truncated and the pass kept the raw transcript — which looked like polish quietly
+doing nothing past roughly half a minute of speech. Dictations longer than 200 characters now
+turn thinking off (the same 309-character input went from 10.2 s to 1.2 s with the same
+punctuation), while shorter ones keep it, because there it costs almost nothing and corrects
+terms and self-corrections better. The field only reaches OpenAI-compatible providers; one that
+ignores it behaves exactly as before.
+
 Assistant text can contain anything the conversation contained — file paths,
 identifiers, values the agent echoed. The character limits bound how much is sent,
 not how sensitive it is. With the local backend, nothing else leaves your machine,
 and audio never does: recognition runs on this machine with no API key. Turn the
 feature off with `/voice-polish off` or the Polish tab's Enabled row.
 
+Every dictation also writes one `voice-polish` entry into the session file: the raw
+transcript, what reached the editor and why the pass decided that. The model never sees
+these entries — they are not part of the conversation context — so they are there for
+analysis, and they do keep the raw text on disk for as long as the session file exists.
+Each entry also records how the pass was configured: the transcript length on its own
+(separate from any text already in the editor), whether thinking was turned off for it,
+and the output-token cap it carried.
+
 | Setting                   | Scope              | Default     | Notes                                                   |
 | ------------------------- | ------------------ | ----------- | ------------------------------------------------------- |
 | `postProcessEnabled`      | global only        | `true`      | Master switch. A project `voice` block cannot flip it.  |

package/extensions/voice/post-process-prompt.ts

@@ -69,7 +69,10 @@ If nothing in <TRANSCRIPT> can be cleaned, return it unchanged.
  */
 export function polishMaxTokens(rawChars: number): number {
 	const bounded = Number.isFinite(rawChars) ? Math.max(1, Math.floor(rawChars)) : 1;
-	return Math.min(4096, Math.max(1024, Math.ceil(bounded * 2) + 512));
+	// The floor is 2048 because thinking is not bounded by the input length: a 76-character
+	// dictation spent about 1,200 reasoning tokens, so the earlier 1024 floor truncated it and
+	// dropped the pass back to the raw transcript after a 7.6 s wait.
+	return Math.min(4096, Math.max(2048, Math.ceil(bounded * 2) + 512));
 }
 
 function renderContext(context: AssembledContext): string {

package/extensions/voice/post-process.ts

@@ -217,3 +217,108 @@ export async function polishTranscript(input: PolishInput): Promise<PolishResult
 		if (timer) clearTimeout(timer);
 	}
 }
+
+/**
+ * One durable record of what a pass did, written into the session file by the caller.
+ *
+ * `pi.appendEntry` stores it as a CustomEntry, which never enters the model's context, so
+ * this records the raw text, what actually reached the editor and why a pass fell back
+ * without changing anything the model sees. The shape is versioned so that a later analysis
+ * can tell which fields mean what.
+ */
+export interface PolishAudit {
+	version: 1;
+	rawText: string;
+	writtenText?: string;
+	/** True when a rewrite reached the editor; false for a fallback, a discard or no write. */
+	applied: boolean;
+	status?: string;
+	disposition?: string;
+	reason?: string;
+	model?: string;
+	configured?: string;
+	latencyMs?: number;
+	contextChars?: number;
+	truncated?: boolean;
+	/** Characters of the dictation itself, excluding text already in the editor. */
+	transcriptChars?: number;
+	/** Characters of the editor prefix, which is not part of the transcript. */
+	editorPrefixChars?: number;
+	/** True when the pass asked the model not to think. */
+	thinkingOff?: boolean;
+	/** The output-token cap the request carried, a cap and not a spend. */
+	maxTokens?: number;
+}
+
+export function buildPolishAudit(input: {
+	raw: string;
+	written?: string;
+	status?: string;
+	disposition?: string;
+	reason?: string;
+	transcriptChars?: number;
+	editorPrefixChars?: number;
+	thinkingOff?: boolean;
+	maxTokens?: number;
+	telemetry?: {
+		model?: string;
+		configured?: string;
+		ms?: number;
+		contextChars?: number;
+		truncated?: boolean;
+	};
+}): PolishAudit {
+	const audit: PolishAudit = {
+		version: 1,
+		rawText: input.raw,
+		// A write that equals the raw text is still a write, but it did not change anything.
+		applied: input.written !== undefined && input.written !== input.raw,
+	};
+	if (input.written !== undefined) audit.writtenText = input.written;
+	if (input.status !== undefined) audit.status = input.status;
+	if (input.disposition !== undefined) audit.disposition = input.disposition;
+	if (input.reason !== undefined) audit.reason = input.reason;
+	if (input.transcriptChars !== undefined) audit.transcriptChars = input.transcriptChars;
+	if (input.editorPrefixChars !== undefined) audit.editorPrefixChars = input.editorPrefixChars;
+	if (input.thinkingOff !== undefined) audit.thinkingOff = input.thinkingOff;
+	if (input.maxTokens !== undefined) audit.maxTokens = input.maxTokens;
+	const telemetry = input.telemetry;
+	if (telemetry) {
+		if (telemetry.model !== undefined) audit.model = telemetry.model;
+		if (telemetry.configured !== undefined) audit.configured = telemetry.configured;
+		if (telemetry.ms !== undefined) audit.latencyMs = telemetry.ms;
+		if (telemetry.contextChars !== undefined) audit.contextChars = telemetry.contextChars;
+		if (telemetry.truncated !== undefined) audit.truncated = telemetry.truncated;
+	}
+	return audit;
+}
+
+/**
+ * Extra request fields for the polish call, or nothing when the model has no thinking to turn
+ * off.
+ *
+ * Short transcripts keep thinking on: it is cheap there and the wording comes out better.
+ * Measured 2026-09-26 on the acceptance corpus, thinking on won exactly the samples this pass
+ * exists for — a self-correction merged for +1.71 CER with it on against 0 with it off, and two
+ * zh-en term samples +0.08/+0.10 against 0 — while a 161-character transcript spent only 66
+ * reasoning tokens in 0.47 s.
+ *
+ * Long transcripts turn it off: there thinking grows far past the token budget (309 characters
+ * needed ~1700 reasoning tokens, 471 characters ~2800-4400, against a budget of 1130-1454), so the
+ * answer was truncated and the pass fell back to the raw transcript — intermittently, which is
+ * what made a long dictation look unpolished. With thinking off the same input finished in ~1.2 s
+ * and spent no reasoning tokens at all.
+ *
+ * `samplingParams` is applied by OpenAI-compatible adapters only, and the `reasoning` gate keeps
+ * the field away from models with no thinking at all.
+ */
+export const THINKING_MAX_CHARS = 200;
+
+export function polishSamplingOptions(
+	model: { reasoning?: boolean } | undefined | null,
+	rawLength: number
+): { samplingParams?: { reasoning_effort: string } } {
+	if (!model || model.reasoning !== true) return {};
+	if (Number.isFinite(rawLength) && rawLength <= THINKING_MAX_CHARS) return {};
+	return { samplingParams: { reasoning_effort: "none" } };
+}

package/extensions/voice.ts

@@ -103,6 +103,8 @@ import { shouldArmReleaseDetectOnRepeat, decideRecordingStartTimer } from "./voi
 import { GapTimer, type TimerPort } from "./voice/release-controller";
 import { audioToolOrder, type AudioToolName } from "./voice/audio-tool";
 import {
+	buildPolishAudit,
+	polishSamplingOptions,
 	decideApply,
 	finalizePolishDisposition,
 	EDITOR_READ_FAILED,
@@ -112,6 +114,7 @@ import {
 	resolveModelChoice,
 } from "./voice/post-process";
 import { DEFAULT_CONTEXT_LIMITS } from "./voice/post-process-context";
+import { polishMaxTokens } from "./voice/post-process-prompt";
 
 /** Adapter for the real event loop — lets GapTimer run under the real setTimeout. */
 const realTimerPort: TimerPort = {
@@ -881,6 +884,9 @@ export default function (pi: ExtensionAPI) {
 		ms: number;
 		contextChars?: number;
 		truncated?: boolean;
+		/** Recorded so a slow or truncated pass can be diagnosed without reading code. */
+		thinkingOff?: boolean;
+		maxTokens?: number;
 		reason?: string;
 		error?: string;
 	};
@@ -971,13 +977,24 @@ export default function (pi: ExtensionAPI) {
 					ctx!.modelRegistry.complete(
 						model as never,
 						{ systemPrompt: request.systemPrompt, messages: request.messages as never },
-						{ signal, maxTokens: request.maxTokens }
+						{
+							signal,
+							maxTokens: request.maxTokens,
+							// Measured 2026-09-26: without this a reasoning model spends the whole budget thinking
+							// about a long dictation and the pass falls back to the raw text — see
+							// polishSamplingOptions.
+							...polishSamplingOptions(model as { reasoning?: boolean }, raw.length),
+						}
 					),
 				debug: (reason, data) => voiceDebug(`polish ${reason}`, data),
 			});
 			const telemetry = {
 				model: polishModelLabel(choice),
 				configured: choice.ref,
+				// Pure and cheap, so computing it twice (here and in the call options) is fine, and it
+				// keeps the audit entry honest about what the pass decided.
+				thinkingOff: Boolean(polishSamplingOptions(model as { reasoning?: boolean }, raw.length).samplingParams),
+				maxTokens: polishMaxTokens(raw.length),
 				status: result.status,
 				ms: Date.now() - started,
 				contextChars: result.contextChars,
@@ -1787,17 +1804,42 @@ export default function (pi: ExtensionAPI) {
 					if (polishOutcome !== undefined) {
 						const final = finalizePolishDisposition(polishOutcome, wroteEditor, editorWriteFailed);
 						polishOutcome = final.status;
+						// One reason string for the debug log and the audit entry.
+						const reason = editorWriteFailed
+							? "editor-write-failed"
+							: !wroteEditor && !skipWrite
+								? "editor-write-skipped"
+								: polishTelemetry?.reason;
 						if (polishTelemetry) {
 							voiceDebug("polish result", {
 								...polishTelemetry,
 								disposition: final.disposition,
-								reason: editorWriteFailed
-									? "editor-write-failed"
-									: !wroteEditor && !skipWrite
-										? "editor-write-skipped"
-										: polishTelemetry.reason,
+								reason,
 							});
 						}
+						// Durable audit record: one CustomEntry per dictation, carrying the raw text, what
+						// actually reached the editor and why the pass did what it did. A CustomEntry never
+						// enters the model's context, so the pass stays analysable after the session ends
+						// without changing what the model sees. A failure here must not affect the dictation.
+						try {
+							pi.appendEntry(
+								"voice-polish",
+								buildPolishAudit({
+									raw: prefix + fullText,
+									transcriptChars: fullText.length,
+									editorPrefixChars: prefix.length,
+									thinkingOff: polishTelemetry?.thinkingOff,
+									maxTokens: polishTelemetry?.maxTokens,
+									written: wroteEditor ? finalText : undefined,
+									status: final.status,
+									disposition: final.disposition,
+									reason,
+									telemetry: polishTelemetry,
+								})
+							);
+						} catch (err) {
+							voiceDebug("polish audit entry failed", { error: String(err) });
+						}
 					}
 
 					// v7.1.1 — auto-submit on STT (config.autoSubmitOnSpeak).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-voicekit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Voice in + voice out for Pi CLI — hold-to-talk STT (Deepgram streaming or 21 offline models) plus TTS (Kitten Nano, Piper, Kokoro, or Deepgram Aura)",
   "type": "module",
   "keywords": [