pi-voicekit 0.2.0 → 0.2.1

package/README.md

@@ -381,12 +381,25 @@ 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.
+
 | Setting                   | Scope              | Default     | Notes                                                   |
 | ------------------------- | ------------------ | ----------- | ------------------------------------------------------- |
 | `postProcessEnabled`      | global only        | `true`      | Master switch. A project `voice` block cannot flip it.  |

package/extensions/voice/post-process.ts

@@ -217,3 +217,92 @@ 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;
+}
+
+export function buildPolishAudit(input: {
+	raw: string;
+	written?: string;
+	status?: string;
+	disposition?: string;
+	reason?: string;
+	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;
+	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,
@@ -971,7 +973,14 @@ 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),
 			});
@@ -1787,17 +1796,38 @@ 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,
+									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.1",
   "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": [