pi-voicekit 0.1.4 → 0.2.1

package/README.md

@@ -21,7 +21,7 @@ speaks the agent's replies (Kitten, Kokoro, Piper, or Deepgram Aura).
 > `PULSE_SERVER` is set (SSH audio tunnel / remote PulseAudio), so remote
 > microphones record reliably. Voice in **and** voice out: 21 offline STT models,
 > 20 local TTS voices plus Deepgram Aura, driven by one `/voice-settings` panel
-> with 5 tabs. The 0.1.x line is documented in the [changelog](CHANGELOG.md).
+> with 6 tabs. The 0.1.x line is documented in the [changelog](CHANGELOG.md).
 
 ---
 
@@ -50,14 +50,14 @@ pi install npm:pi-voicekit
 
 pi-voicekit supports two transcription backends:
 
-|                  | Deepgram (cloud)                                         | Local models (offline)                              |
+|                  | Deepgram (cloud)                                         | Local models (offline recognition)                  |
 | ---------------- | -------------------------------------------------------- | --------------------------------------------------- |
 | **How it works** | Live streaming — text appears as you speak               | Batch mode — transcribes after you finish recording |
 | **Setup**        | API key required                                         | No API key, models auto-download on first use       |
-| **Internet**     | Required                                                 | Not required after model download                   |
+| **Internet**     | Required                                                 | Not required after model download for recognition; the polish step may use the network |
 | **Latency**      | Real-time interim results                                | 2–10 seconds after recording stops                  |
 | **Languages**    | 56+ with live streaming                                  | Depends on model (1–57 languages)                   |
-| **Cost**         | $200 free credit (lasts 6–12 months for most developers) | Free forever                                        |
+| **Cost**         | $200 free credit (lasts 6–12 months for most developers) | Recognition is free; the polish step may cost money |
 
 Run `/voice-settings` inside Pi to choose your backend and configure everything from one panel.
 
@@ -69,7 +69,7 @@ Sign up at [dpgr.am/pi-voice](https://dpgr.am/pi-voice) — $200 free credit, no
 export DEEPGRAM_API_KEY="your-key-here"    # add to ~/.zshrc or ~/.bashrc
 ```
 
-#### Option B: Local models (fully offline)
+#### Option B: Local models (offline recognition)
 
 No setup needed — run `/voice-settings`, switch backend to Local, and select a model. It downloads automatically.
 
@@ -100,7 +100,7 @@ pi-voicekit auto-detects your audio tool. No manual install needed if you alread
 
 ## Settings Panel
 
-All configuration lives in one place: `/voice-settings`. Five tabs cover everything you need.
+All configuration lives in one place: `/voice-settings`. Six tabs cover everything you need.
 
 ### General — backend, language, scope
 
@@ -132,6 +132,18 @@ agent replies is toggled here.
 
 See your hardware profile (RAM, CPU, GPU), dependency status (sherpa-onnx runtime), available disk space, and total downloaded models. Model recommendations are based on this profile.
 
+### Polish — transcript cleanup
+
+Optional post-ASR cleanup, on by default. Toggle it, pick the model, set how many
+recent conversation turns accompany the transcript (0–10), and cap how long one
+pass may take (`1000`–`30000` ms). The last row shows the most recent polished
+dictation as a `RAW` / `POLISHED` pair. `/voice-polish last` prints the newest
+dictation a pass ran on — including one whose result was discarded — with its
+`STATUS`, `RAW`, and `WRITTEN` text, or says that nothing was written.
+
+`/voice-polish` takes `on`, `off`, `model`, `turns <0-10>`, `last` and `restore`;
+run it with no argument for the current status.
+
 ---
 
 ## Usage
@@ -165,6 +177,7 @@ See your hardware profile (RAM, CPU, GPU), dependency status (sherpa-onnx runtim
 | `/voice-stream`          | Toggle Deepgram streaming TTS (cloud)                     |
 | `/voice-speak-stop`      | Stop in-flight TTS playback                               |
 | `/voice-autosubmit`      | Toggle: STT text auto-sent to the agent (`on`/`off`)      |
+| `/voice-polish [sub]`    | Transcript polish: on, off, model, turns, last, restore   |
 | `/voice-hold-delay`      | Set hold-to-talk delay (200-3000 ms, default 700)         |
 | `/voice-speak-models`    | Browse / install TTS voice models                         |
 | `/voice-speak-info`      | Diagnose TTS state                                        |
@@ -261,6 +274,7 @@ Models from [Handy](https://github.com/cjpais/handy) (`~/Library/Application Sup
 | **Pre-recording**                | Audio capture starts during warmup — you never miss the first word                       |
 | **Tail recording**               | Keeps recording 1.5s after release so your last word isn't clipped                       |
 | **Live streaming**               | Deepgram Nova 3 WebSocket (Nova 2 for Chinese locales) — live interim transcripts        |
+| **Transcript polish**            | Optional post-ASR cleanup — every dictation makes one extra model call; the last N conversation turns (default 2) are sent with it, and no conversation context at all when the turn count is zero. Disable with `/voice-polish off` |
 | **56+ languages**                | Deepgram: 56+ with live streaming. Local: up to 57 depending on model.                   |
 | **Continuous dictation**         | `/voice dictate` for long-form input without holding keys                                |
 | **Typing cooldown**              | Space holds within 400ms of typing are ignored                                           |
@@ -288,6 +302,11 @@ extensions/voice/sherpa-loader.ts           Lazy native module loading
 extensions/voice/model-download.ts          Download manager — resume, progress, verification, Handy import
 extensions/voice/device.ts                  Device profiling — RAM, GPU, CPU, container detection
 
+# transcript post-processing
+extensions/voice/post-process.ts            Polish pass — fail-open guardrails, model resolution, bounded call
+extensions/voice/post-process-context.ts    Context assembly — recent turns and character caps
+extensions/voice/post-process-prompt.ts     Fixed polish prompt and request shape
+
 # text-to-speech
 extensions/voice/speak.ts                   Speak entry point, auto-speak wiring
 extensions/voice/tts-engine.ts              sherpa-onnx TTS synthesis
@@ -301,7 +320,7 @@ extensions/voice/tts-install-progress.ts    Model install progress widget
 extensions/voice/tts-playback-indicator.ts  Speaking indicator widget
 
 # settings and UI
-extensions/voice/settings-panel.ts          Settings panel — overlay, 5 tabs
+extensions/voice/settings-panel.ts          Settings panel — overlay, 6 tabs
 extensions/voice/ui-picker.ts               Generic list picker
 extensions/voice/ui-help-overlay.ts         Keyboard and command reference
 extensions/voice/ui-aura.ts                 Visual primitives (Liquid Braille, Aurora)
@@ -329,13 +348,13 @@ Settings stored in Pi's settings files under the `voice` key:
 ```json
 {
 	"voice": {
-		"version": 2,
+		"version": 3,
 		"enabled": true,
 		"language": "en",
 		"backend": "local",
 		"localModel": "parakeet-v3",
 		"scope": "global",
-		"onboarding": { "completed": true, "schemaVersion": 2 }
+		"onboarding": { "completed": true, "schemaVersion": 3 }
 	}
 }
 ```
@@ -346,6 +365,56 @@ an explicit save and it still goes to `~/.env.secrets` or `~/.zshrc`.
 
 Hold-to-talk delay defaults to **700 ms** (`/voice-hold-delay` accepts 200–3000 ms).
 
+### Transcript polish
+
+Transcript polish is on by default: every dictation runs one extra model call. When
+the selected model is a cloud provider, the text that leaves your machine is:
+
+- the transcript of the dictation;
+- the last N conversation turns of user and assistant text, where N is
+  `postProcessContextTurns` (default `2`; `0` sends no conversation context);
+- nothing else. The compaction summary is deliberately not sent: it is a digest built from
+  earlier messages, so it can carry residues of thinking and tool output, and it measured no
+  gain over the turns alone.
+
+One measured behaviour is worth knowing: a model that thinks before it answers may normalise a
+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.  |
+| `postProcessModel`        | global only        | `"session"` | Reuses the session model, or `provider/modelId`.        |
+| `postProcessContextTurns` | global and project | `2`         | Conversation turns sent with the transcript, `0`–`10`.  |
+| `postProcessTimeoutMs`    | global and project | `12000`     | Per-pass timeout in milliseconds, `1000`–`30000`.       |
+
+The global-only fields resolve from `~/.pi/agent/settings.json` even when a
+repository provides its own `voice` block, so a cloned repo can neither turn the
+feature on nor redirect where dictated text goes. The model is chosen from a
+picker (`/voice-polish model`), never typed: a hand-typed reference is refused,
+and an unavailable or malformed model keeps the raw transcript instead of
+switching provider. `postProcessNoticeShown` is machine-local bookkeeping for the
+one-time notice, not a user setting.
+
 ---
 
 ## Troubleshooting

package/extensions/voice/config.ts

@@ -7,7 +7,7 @@ function getAgentDir(): string {
 }
 
 export const SETTINGS_KEY = "voice";
-export const VOICE_CONFIG_VERSION = 2;
+export const VOICE_CONFIG_VERSION = 3;
 
 export type VoiceSettingsScope = "global" | "project";
 export type VoiceConfigSource = VoiceSettingsScope | "default";
@@ -40,6 +40,27 @@ export interface VoiceConfig {
 	/** Global-only shortcut used to toggle recording without hold-to-talk */
 	toggleShortcut?: string;
 
+	// ─── Post-processing (optional transcript polish) — new in v3 ─────
+
+	/**
+	 * Master switch for the post-ASR polish pass. Global-only — the
+	 * enablement decides whether dictated text makes an extra model call,
+	 * so a project file must not be able to flip it.
+	 */
+	postProcessEnabled?: boolean;
+	/**
+	 * Model used by the polish pass — "session" reuses the active session
+	 * model, or "<provider>/<modelId>". Global-only: the value decides
+	 * where dictated text is sent.
+	 */
+	postProcessModel?: string;
+	/** How many recent conversation turns accompany the transcript. Honoured in both scopes; clamped to [0, 10]. */
+	postProcessContextTurns?: number;
+	/** Upper bound in milliseconds for one polish pass. Honoured in both scopes; clamped to [1000, 30000]. */
+	postProcessTimeoutMs?: number;
+	/** Set once the one-time default-on notice has been shown. Global-only — it describes this machine, not the repository. */
+	postProcessNoticeShown?: boolean;
+
 	// ─── TTS (text-to-speech) ─────────────────────────────────────────
 	// All TTS fields are opt-in (default: TTS disabled). New in v6.0.0.
 
@@ -125,6 +146,12 @@ export const DEFAULT_CONFIG: VoiceConfig = {
 	localModel: undefined,
 	localEndpoint: undefined,
 	toggleShortcut: "ctrl+shift+v",
+	// Post-processing defaults — on by default (D5), reusing the session model
+	postProcessEnabled: true,
+	postProcessModel: "session",
+	postProcessContextTurns: 2,
+	postProcessTimeoutMs: 12000,
+	postProcessNoticeShown: false,
 	// TTS defaults — all opt-in
 	ttsEnabled: false,
 	ttsBackend: "local",
@@ -176,11 +203,46 @@ function normalizeOnboarding(input: any, fallbackCompleted: boolean): VoiceOnboa
 	};
 }
 
-function migrateConfig(rawVoice: any, source: VoiceConfigSource): VoiceConfig {
+/** Clamp an integer config value; non-numeric or non-finite input takes the default. */
+function clampInt(value: unknown, min: number, max: number, fallback: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) return fallback;
+	return Math.max(min, Math.min(max, value));
+}
+
+function migrateConfig(rawVoice: any, source: VoiceConfigSource, globalVoice?: unknown): VoiceConfig {
 	if (!rawVoice || typeof rawVoice !== "object") {
 		return structuredClone(DEFAULT_CONFIG);
 	}
 
+	// D7: model selection, enablement and the notice flag are global-only, and a
+	// project file must not be able to inject an API key or point audio at a
+	// non-loopback host. These fields resolve from the global block in BOTH scopes —
+	// falling back to DEFAULT_CONFIG would let a cloned repository re-enable a
+	// feature the maintainer turned off globally (spec §4.2).
+	const projectScoped = source === "project";
+	const globalRaw: Record<string, unknown> =
+		globalVoice && typeof globalVoice === "object" ? (globalVoice as Record<string, unknown>) : {};
+	const globalOnly = (key: string): unknown => (projectScoped ? globalRaw[key] : rawVoice[key]);
+	const asString = (value: unknown): string | undefined => (typeof value === "string" && value ? value : undefined);
+	const asBoolean = (value: unknown, fallbackValue: boolean): boolean =>
+		typeof value === "boolean" ? value : fallbackValue;
+
+	for (const key of ["postProcessEnabled", "postProcessModel", "deepgramApiKey", "localEndpoint"]) {
+		if (!projectScoped || rawVoice[key] === undefined) continue;
+		// A loopback project endpoint is honoured, not ignored — reporting it would
+		// cry wolf on the safe case and weaken the signal for the discarded ones.
+		if (
+			key === "localEndpoint" &&
+			typeof rawVoice.localEndpoint === "string" &&
+			isLoopbackEndpoint(rawVoice.localEndpoint)
+		) {
+			continue;
+		}
+		// Never print a key, even one that is being ignored.
+		const shown = key === "deepgramApiKey" ? "<redacted>" : JSON.stringify(rawVoice[key]);
+		process.stderr.write(`[pi-voicekit] Ignoring project-scoped voice.${key} (${shown}); using the global value\n`);
+	}
+
 	// Legacy configs may have backend+model — treat that as completed onboarding
 	const hasMeaningfulLegacySetup =
 		(typeof rawVoice.backend === "string" && typeof rawVoice.model === "string") ||
@@ -192,14 +254,26 @@ function migrateConfig(rawVoice: any, source: VoiceConfigSource): VoiceConfig {
 		enabled: typeof rawVoice.enabled === "boolean" ? rawVoice.enabled : DEFAULT_CONFIG.enabled,
 		language: typeof rawVoice.language === "string" ? rawVoice.language : DEFAULT_CONFIG.language,
 		scope: (rawVoice.scope as VoiceSettingsScope | undefined) ?? (source === "project" ? "project" : "global"),
-		deepgramApiKey: typeof rawVoice.deepgramApiKey === "string" ? rawVoice.deepgramApiKey : undefined,
+		deepgramApiKey: asString(globalOnly("deepgramApiKey")),
 		backend: rawVoice.backend === "local" ? "local" : undefined,
 		localModel: typeof rawVoice.localModel === "string" ? rawVoice.localModel : undefined,
-		localEndpoint: typeof rawVoice.localEndpoint === "string" ? rawVoice.localEndpoint : undefined,
+		localEndpoint: projectScoped
+			? typeof rawVoice.localEndpoint === "string" && isLoopbackEndpoint(rawVoice.localEndpoint)
+				? rawVoice.localEndpoint
+				: asString(globalRaw.localEndpoint)
+			: asString(rawVoice.localEndpoint),
 		toggleShortcut:
 			source !== "project" && typeof rawVoice.toggleShortcut === "string"
 				? rawVoice.toggleShortcut
 				: DEFAULT_CONFIG.toggleShortcut,
+		// Post-processing fields (v3). Model selection, enablement and the
+		// notice flag resolve through `globalOnly`; the two numeric knobs are
+		// honoured in both scopes.
+		postProcessEnabled: asBoolean(globalOnly("postProcessEnabled"), DEFAULT_CONFIG.postProcessEnabled ?? true),
+		postProcessModel: asString(globalOnly("postProcessModel")) ?? DEFAULT_CONFIG.postProcessModel,
+		postProcessContextTurns: clampInt(rawVoice.postProcessContextTurns, 0, 10, DEFAULT_CONFIG.postProcessContextTurns!),
+		postProcessTimeoutMs: clampInt(rawVoice.postProcessTimeoutMs, 1000, 30000, DEFAULT_CONFIG.postProcessTimeoutMs!),
+		postProcessNoticeShown: asBoolean(globalOnly("postProcessNoticeShown"), false),
 		// TTS fields — type-validated; mismatched persisted values fall
 		// back to safe defaults so a hand-edited config can't poison the
 		// engine. Notably: ttsLocalVoiceId rejects strings (would crash
@@ -251,7 +325,7 @@ export function loadConfigWithSource(cwd: string, options: ConfigPathOptions = {
 
 	if (projectVoice && typeof projectVoice === "object") {
 		return {
-			config: migrateConfig(projectVoice, "project"),
+			config: migrateConfig(projectVoice, "project", globalVoice),
 			source: "project",
 			globalSettingsPath,
 			projectSettingsPath,
@@ -353,6 +427,11 @@ function serializeConfig(config: VoiceConfig, scope: VoiceSettingsScope): VoiceC
 			scope === "project" && config.localEndpoint && !isLoopbackEndpoint(config.localEndpoint)
 				? undefined
 				: config.localEndpoint,
+		// D7: model selection and enablement are global-only, and the notice flag
+		// describes this machine, not this repository.
+		postProcessEnabled: scope === "project" ? undefined : config.postProcessEnabled,
+		postProcessModel: scope === "project" ? undefined : config.postProcessModel,
+		postProcessNoticeShown: scope === "project" ? undefined : config.postProcessNoticeShown,
 		// Shortcut registration is static at extension load time — project-scoped overrides cannot apply
 		toggleShortcut: scope === "project" ? undefined : config.toggleShortcut,
 		onboarding: {
@@ -362,6 +441,23 @@ function serializeConfig(config: VoiceConfig, scope: VoiceSettingsScope): VoiceC
 	};
 }
 
+/**
+ * Atomic settings write: temp file + rename prevents corruption from partial
+ * writes. Shared by every writer in this module so the path cannot diverge.
+ */
+function writeSettingsFile(settingsPath: string, settings: Record<string, unknown>): void {
+	fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+	const tmpPath = `${settingsPath}.${process.pid}.tmp`;
+	try {
+		fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + "\n");
+		fs.renameSync(tmpPath, settingsPath);
+	} finally {
+		try {
+			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
+		} catch {}
+	}
+}
+
 export function saveConfig(
 	config: VoiceConfig,
 	scope: VoiceSettingsScope,
@@ -371,17 +467,62 @@ export function saveConfig(
 	const settingsPath = scope === "project" ? getProjectSettingsPath(cwd) : getGlobalSettingsPath(options);
 	const settings = readJsonFile(settingsPath);
 	settings[SETTINGS_KEY] = serializeConfig(config, scope);
-	fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
-	// Atomic write: temp file + rename prevents corruption from partial writes
-	const tmpPath = `${settingsPath}.${process.pid}.tmp`;
-	try {
-		fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + "\n");
-		fs.renameSync(tmpPath, settingsPath);
-	} finally {
+	writeSettingsFile(settingsPath, settings);
+	return settingsPath;
+}
+
+/**
+ * The global-only keys `saveGlobalVoiceFields` accepts. A project block cannot
+ * carry them — `serializeConfig` strips them and the loader ignores them — so
+ * they always belong in the global file.
+ */
+type GlobalVoiceFieldKey = "postProcessEnabled" | "postProcessModel" | "postProcessNoticeShown";
+
+/**
+ * Field-level writer for the global-only voice settings (R26).
+ *
+ * `saveConfig(config, "global", …)` renders the WHOLE in-memory config, and in a
+ * project-scoped session that object also carries project and default values —
+ * writing it globally silently resets every unrelated machine-global setting
+ * (TTS speed, auto-submit, hold threshold, …). This writer instead reads the
+ * existing global file and merges only the named keys into its `voice` block:
+ *
+ * - an existing `version` is preserved; a block created here gets the current
+ *   schema version,
+ * - no other key is created, changed or removed,
+ * - a missing file or `voice` block is created,
+ * - a file that exists but cannot be parsed is refused, not overwritten,
+ * - the write is atomic (temp file + rename), like `saveConfig`.
+ */
+export function saveGlobalVoiceFields(
+	fields: Partial<Pick<VoiceConfig, GlobalVoiceFieldKey>>,
+	options: ConfigPathOptions = {}
+): string {
+	const settingsPath = getGlobalSettingsPath(options);
+	// The shared reader reports a file it cannot parse exactly like a missing one, so this
+	// writer has to tell them apart itself: merging into `{}` would replace a damaged
+	// settings file with a fresh object and lose every other key. An existing file that
+	// cannot be read is logged and left untouched; throwing hands the failure to the
+	// caller's guard instead of silently reporting a write that never happened.
+	let settings: Record<string, unknown> = {};
+	if (fs.existsSync(settingsPath)) {
 		try {
-			if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
-		} catch {}
+			settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[pi-voicekit] Warning: not writing ${settingsPath}: ${reason}\n`);
+			throw new Error(`Refusing to overwrite an unreadable settings file: ${settingsPath}`);
+		}
+	}
+	const existing = settings[SETTINGS_KEY];
+	const voice: Record<string, unknown> =
+		existing && typeof existing === "object" ? { ...(existing as Record<string, unknown>) } : {};
+	if (typeof voice.version !== "number") voice.version = VOICE_CONFIG_VERSION;
+	for (const [key, value] of Object.entries(fields)) {
+		if (value !== undefined) voice[key] = value;
 	}
+	settings[SETTINGS_KEY] = voice;
+	writeSettingsFile(settingsPath, settings);
 	return settingsPath;
 }
 

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

@@ -0,0 +1,185 @@
+/**
+ * Transcript post-processing: conversation-context assembly.
+ *
+ * Pure functions only — no Pi API, no I/O — so the whole module is testable
+ * offline. The caller passes the compaction-aware projection returned by
+ * `ctx.sessionManager.buildContextEntries()`, which is why `EntryLike` is
+ * structural rather than imported: this package does not depend on pi-ai.
+ *
+ * Spec: docs/superpowers/specs/2026-09-26-stt-post-processing-design.md §4.3
+ * (a local design record, not part of the published package)
+ */
+
+export interface EntryLike {
+	type?: string;
+	message?: { role?: string; content?: unknown };
+	summary?: string;
+}
+
+export interface ContextLimits {
+	/** User turns to keep, counted from the newest. 0 disables context entirely. */
+	turns: number;
+	/** Per-entry character cap on the text as returned, elision marker included. */
+	perEntryChars: number;
+	/** Total character cap across the turns that are kept. */
+	totalChars: number;
+}
+
+export interface ContextTurn {
+	role: "user" | "assistant";
+	text: string;
+}
+
+export interface AssembledContext {
+	turns: ContextTurn[];
+	/** Characters of the text as returned, elision markers included; never above totalChars. */
+	characters: number;
+	/** True when a cap dropped or shortened something. */
+	truncated: boolean;
+}
+
+export const DEFAULT_CONTEXT_LIMITS: ContextLimits = { turns: 2, perEntryChars: 500, totalChars: 4000 };
+
+const ELLIPSIS = "…";
+
+/** Extract only the text this feature is allowed to see from one entry's content. */
+function extractText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const part of content) {
+		if (!part || typeof part !== "object") continue;
+		const block = part as { type?: string; text?: string };
+		if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+	}
+	return parts.join("\n");
+}
+
+/** Keep the head of a long entry: terms are usually introduced early. */
+function truncateHead(text: string, limit: number): { text: string; truncated: boolean } {
+	const trimmed = text.trim();
+	const cap = Math.floor(limit);
+	if (cap <= 0) return { text: "", truncated: trimmed.length > 0 };
+	if (trimmed.length <= cap) return { text: trimmed, truncated: false };
+	// R11: the elision marker is part of the cap, so cut one code unit short of it.
+	let cut = cap - 1;
+	// R12: never end the kept text on a high surrogate — a split pair reaches the
+	// prompt as U+FFFD once the text is encoded to UTF-8.
+	if (cut > 0 && isHighSurrogate(trimmed.charCodeAt(cut - 1))) cut -= 1;
+	return { text: trimmed.slice(0, cut) + ELLIPSIS, truncated: true };
+}
+
+function isHighSurrogate(code: number): boolean {
+	return code >= 0xd800 && code <= 0xdbff;
+}
+
+/**
+ * R10: floor and clamp the turn limit locally. A non-integer value would produce
+ * a fractional slice index, and `slice(undefined)` means `slice(0)` — the limit
+ * would silently vanish and the whole history would be kept. Non-finite input is
+ * malformed and fails closed to no context.
+ */
+function resolveTurns(turns: number): number {
+	return Number.isFinite(turns) ? Math.max(0, Math.floor(turns)) : 0;
+}
+
+function toUnits(entries: readonly EntryLike[]): ContextTurn[] {
+	const units: ContextTurn[] = [];
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		if (entry.type === "compaction") {
+			// A compaction entry is skipped outright: the digest it carries can hold residues
+			// of thinking and tool output, and it measured no gain over the turns alone.
+			continue;
+		}
+		if (entry.type !== "message" || !entry.message) continue;
+		const role = entry.message.role;
+		if (role !== "user" && role !== "assistant") continue;
+		const text = extractText(entry.message.content).trim();
+		// Item 7: a user message always opens a turn — an image-only one consumes a turn
+		// even though it contributes no text. Assistant text with nothing in it
+		// contributes nothing at all.
+		if (role === "user" || text) units.push({ role, text });
+	}
+	return units;
+}
+
+/** A turn is one user entry plus every following non-user entry (spec §4.3 item 3). */
+function groupTurns(units: readonly ContextTurn[]): ContextTurn[][] {
+	const turns: ContextTurn[][] = [];
+	for (const unit of units) {
+		if (unit.role === "user" || turns.length === 0) turns.push([]);
+		turns[turns.length - 1]!.push(unit);
+	}
+	return turns;
+}
+
+function turnSize(turn: readonly ContextTurn[]): number {
+	return turn.reduce((sum, entry) => sum + entry.text.length, 0);
+}
+
+/**
+ * R9: the newest turn is never dropped. When it alone exceeds the budget, keep
+ * its head — entries in order, the first one (the user entry) included — and
+ * elide the tail so the total still fits.
+ */
+function fitTurnToBudget(turn: readonly ContextTurn[], budget: number): ContextTurn[] {
+	const fitted: ContextTurn[] = [];
+	let remaining = budget;
+	for (const entry of turn) {
+		// Under one character left, nothing usable fits — an empty entry is not kept.
+		if (remaining < 1) break;
+		const capped = truncateHead(entry.text, remaining);
+		fitted.push({ role: entry.role, text: capped.text });
+		remaining -= capped.text.length;
+		if (capped.truncated) break;
+	}
+	return fitted;
+}
+
+export function assembleContext(entries: readonly EntryLike[], limits: ContextLimits): AssembledContext {
+	const units = toUnits(entries);
+	// R10: resolve the turn limit once, locally — see resolveTurns.
+	const turns = resolveTurns(limits.turns);
+	let truncated = false;
+
+	let start = units.length;
+	if (turns > 0) {
+		const userIndexes = units.map((unit, index) => (unit.role === "user" ? index : -1)).filter((index) => index >= 0);
+		start = userIndexes.length > turns ? userIndexes[userIndexes.length - turns]! : 0;
+	}
+
+	const selected = units.slice(start).map((unit) => {
+		const capped = truncateHead(unit.text, limits.perEntryChars);
+		truncated = truncated || capped.truncated;
+		return { role: unit.role, text: capped.text };
+	});
+
+	// R8 + R9: one shared budget, spent on whole turns from the oldest first.
+	// Dropping single entries could keep an assistant reply whose user entry is
+	// gone, which is not a turn (spec §4.3 item 3). Item 7: grouping is also what
+	// counts the turns, so it happens before the empty entries are dropped — inside
+	// a turn only the sendable text reaches the prompt.
+	const groups = groupTurns(selected).map((turn) => turn.filter((unit) => unit.text));
+	const sizes = groups.map(turnSize);
+	let first = 0;
+	let characters = sizes.reduce((sum, size) => sum + size, 0);
+	while (groups.length - first > 1 && characters > limits.totalChars) {
+		characters -= sizes[first]!;
+		first += 1;
+		truncated = true;
+	}
+	let keptTurns = groups.slice(first);
+	if (keptTurns.length === 1 && characters > limits.totalChars) {
+		keptTurns = [fitTurnToBudget(keptTurns[0]!, limits.totalChars)];
+		characters = turnSize(keptTurns[0]!);
+		truncated = true;
+	}
+	const kept = keptTurns.flat();
+
+	return {
+		turns: kept,
+		characters,
+		truncated,
+	};
+}