@oh-my-pi/pi-coding-agent 16.1.13 → 16.1.14

package/src/jsonrpc/message-framing.ts

@@ -0,0 +1,142 @@
+/**
+ * Shared Content-Length message framing for the JSON byte streams spoken by the
+ * LSP and DAP stdio clients. Both protocols use the same base-protocol framing:
+ * each message is a `Content-Length: <n>\r\n\r\n` header block followed by `<n>`
+ * bytes of UTF-8 JSON. This module owns the incremental decode so the two
+ * clients don't each reimplement chunk accumulation, header scanning, and the
+ * mid-message remainder handoff.
+ */
+
+// Reused for all full (non-streaming) decodes; each decode() resets state, so a
+// single instance is safe and avoids per-message TextDecoder allocation.
+const MESSAGE_DECODER = new TextDecoder("utf-8");
+
+/**
+ * Locate the `\r\n\r\n` header terminator across the pending chunk list.
+ * Returns the absolute byte index of the first `\r`, or -1 when not present.
+ * Equivalent to scanning the contiguous concatenation of the chunks.
+ */
+function findHeaderEndInChunks(chunks: Buffer[]): number {
+	let global = 0;
+	let b0 = -1;
+	let b1 = -1;
+	let b2 = -1;
+	for (const chunk of chunks) {
+		for (let i = 0; i < chunk.length; i++) {
+			const b3 = chunk[i];
+			if (b0 === 13 && b1 === 10 && b2 === 13 && b3 === 10) {
+				return global - 3;
+			}
+			b0 = b1;
+			b1 = b2;
+			b2 = b3;
+			global++;
+		}
+	}
+	return -1;
+}
+
+/** Copy the byte range [from, to) out of the pending chunk list into one Buffer. */
+function copyChunkRange(chunks: Buffer[], from: number, to: number): Buffer {
+	const out = Buffer.allocUnsafe(to - from);
+	let global = 0;
+	let written = 0;
+	for (const chunk of chunks) {
+		const chunkEnd = global + chunk.length;
+		if (chunkEnd > from && global < to) {
+			const start = Math.max(from, global) - global;
+			const end = Math.min(to, chunkEnd) - global;
+			chunk.copy(out, written, start, end);
+			written += end - start;
+		}
+		global = chunkEnd;
+		if (global >= to) break;
+	}
+	return out;
+}
+
+/** Drop the first `count` bytes from the pending chunk list in place. */
+function dropChunkFront(chunks: Buffer[], count: number): void {
+	let removed = 0;
+	while (chunks.length > 0) {
+		const head = chunks[0];
+		if (removed + head.length <= count) {
+			removed += head.length;
+			chunks.shift();
+		} else {
+			chunks[0] = head.subarray(count - removed);
+			break;
+		}
+	}
+}
+
+/**
+ * Incremental Content-Length frame decoder for a JSON message byte stream.
+ *
+ * Incoming bytes are buffered as a list of chunks and only joined when a full
+ * message is framed — concatenating the accumulator on every read is O(n^2) for
+ * messages that span many reads (e.g. a large initial diagnostics burst). Feed
+ * raw chunks with {@link push}, pull every complete message with {@link drain},
+ * and persist {@link remainder} when the reader stops so a restarted reader
+ * resumes mid-message.
+ */
+export class MessageFramer {
+	readonly #pendingChunks: Buffer[] = [];
+	#pendingLen = 0;
+
+	/** Seed the buffer with any unparsed remainder left by a previous reader. */
+	constructor(seed: Buffer) {
+		if (seed.length > 0) {
+			this.#pendingChunks.push(seed);
+			this.#pendingLen = seed.length;
+		}
+	}
+
+	/** Append a freshly read chunk to the pending buffer. */
+	push(chunk: Buffer): void {
+		this.#pendingChunks.push(chunk);
+		this.#pendingLen += chunk.length;
+	}
+
+	/**
+	 * Yield the JSON text of every complete message currently buffered. A header
+	 * block without a `Content-Length` is non-protocol noise (e.g. a server
+	 * printing to stdout); `onResync` is invoked with the offending header text
+	 * and the framer drops past the bogus terminator to recover instead of
+	 * stalling on the same junk header forever.
+	 */
+	*drain(onResync: (headerText: string) => void): Generator<string> {
+		while (true) {
+			const headerEnd = findHeaderEndInChunks(this.#pendingChunks);
+			if (headerEnd === -1) break;
+
+			const headerText = MESSAGE_DECODER.decode(copyChunkRange(this.#pendingChunks, 0, headerEnd));
+			const contentLengthMatch = headerText.match(/Content-Length: (\d+)/i);
+			if (!contentLengthMatch) {
+				onResync(headerText);
+				dropChunkFront(this.#pendingChunks, headerEnd + 4);
+				this.#pendingLen -= headerEnd + 4;
+				continue;
+			}
+
+			const contentLength = Number.parseInt(contentLengthMatch[1], 10);
+			const messageStart = headerEnd + 4; // Skip \r\n\r\n
+			const messageEnd = messageStart + contentLength;
+			if (this.#pendingLen < messageEnd) break;
+
+			const messageText = MESSAGE_DECODER.decode(copyChunkRange(this.#pendingChunks, messageStart, messageEnd));
+			dropChunkFront(this.#pendingChunks, messageEnd);
+			this.#pendingLen -= messageEnd;
+			yield messageText;
+		}
+	}
+
+	/** The unparsed remainder, to persist when the reader stops. */
+	remainder(): Buffer {
+		return this.#pendingChunks.length === 0
+			? Buffer.alloc(0)
+			: this.#pendingChunks.length === 1
+				? this.#pendingChunks[0]
+				: Buffer.concat(this.#pendingChunks, this.#pendingLen);
+	}
+}

package/src/lsp/client.ts

@@ -1,5 +1,6 @@
 import * as path from "node:path";
 import { isEnoent, logger, ptree, untilAborted } from "@oh-my-pi/pi-utils";
+import { MessageFramer } from "../jsonrpc/message-framing";
 import { ToolAbortError, throwIfAborted } from "../tools/tool-errors";
 import { applyWorkspaceEdit } from "./edits";
 import { getLspmuxCommand, isLspmuxSupported } from "./lspmux";
@@ -179,69 +180,6 @@ const CLIENT_CAPABILITIES = {
 // LSP Message Protocol
 // =============================================================================
 
-// Reused for all full (non-streaming) decodes; each decode() resets state, so a
-// single instance is safe and avoids per-message TextDecoder allocation.
-const MESSAGE_DECODER = new TextDecoder("utf-8");
-
-/**
- * Locate the `\r\n\r\n` header terminator across the pending chunk list.
- * Returns the absolute byte index of the first `\r`, or -1 when not present.
- * Equivalent to scanning the contiguous concatenation of the chunks.
- */
-function findHeaderEndInChunks(chunks: Buffer[]): number {
-	let global = 0;
-	let b0 = -1;
-	let b1 = -1;
-	let b2 = -1;
-	for (const chunk of chunks) {
-		for (let i = 0; i < chunk.length; i++) {
-			const b3 = chunk[i];
-			if (b0 === 13 && b1 === 10 && b2 === 13 && b3 === 10) {
-				return global - 3;
-			}
-			b0 = b1;
-			b1 = b2;
-			b2 = b3;
-			global++;
-		}
-	}
-	return -1;
-}
-
-/** Copy the byte range [from, to) out of the pending chunk list into one Buffer. */
-function copyChunkRange(chunks: Buffer[], from: number, to: number): Buffer {
-	const out = Buffer.allocUnsafe(to - from);
-	let global = 0;
-	let written = 0;
-	for (const chunk of chunks) {
-		const chunkEnd = global + chunk.length;
-		if (chunkEnd > from && global < to) {
-			const start = Math.max(from, global) - global;
-			const end = Math.min(to, chunkEnd) - global;
-			chunk.copy(out, written, start, end);
-			written += end - start;
-		}
-		global = chunkEnd;
-		if (global >= to) break;
-	}
-	return out;
-}
-
-/** Drop the first `count` bytes from the pending chunk list in place. */
-function dropChunkFront(chunks: Buffer[], count: number): void {
-	let removed = 0;
-	while (chunks.length > 0) {
-		const head = chunks[0];
-		if (removed + head.length <= count) {
-			removed += head.length;
-			chunks.shift();
-		} else {
-			chunks[0] = head.subarray(count - removed);
-			break;
-		}
-	}
-}
-
 async function writeMessage(
 	sink: Bun.FileSink,
 	message: LspJsonRpcRequest | LspJsonRpcNotification | LspJsonRpcResponse,
@@ -274,54 +212,25 @@ async function startMessageReader(client: LspClient): Promise<void> {
 
 	const reader = (client.proc.stdout as ReadableStream<Uint8Array>).getReader();
 
-	// Incoming bytes are buffered as a list of chunks and only joined when a full
-	// message is framed. Concatenating the accumulator on every read was O(n^2)
-	// for messages that span many reads (e.g. a large initial diagnostics burst).
-	const pendingChunks: Buffer[] = [];
-	let pendingLen = 0;
-	if (client.messageBuffer.length > 0) {
-		const seed = Buffer.from(client.messageBuffer);
-		pendingChunks.push(seed);
-		pendingLen = seed.length;
-	}
+	const framer = new MessageFramer(Buffer.from(client.messageBuffer));
 
 	try {
 		while (true) {
 			const { done, value } = await reader.read();
 			if (done) break;
 
-			pendingChunks.push(Buffer.from(value));
-			pendingLen += value.length;
+			framer.push(Buffer.from(value));
 
 			// Drain every complete message currently buffered.
-			while (true) {
-				const headerEnd = findHeaderEndInChunks(pendingChunks);
-				if (headerEnd === -1) break;
-
-				const headerText = MESSAGE_DECODER.decode(copyChunkRange(pendingChunks, 0, headerEnd));
-				const contentLengthMatch = headerText.match(/Content-Length: (\d+)/i);
-				if (!contentLengthMatch) {
-					// Non-protocol bytes on stdout (e.g. a wrapper script printing).
-					// Drop past the bogus terminator and resync instead of stalling
-					// on the same junk header forever.
-					logger.warn("LSP framing resync: header block without Content-Length", {
-						server: client.name,
-						header: headerText.slice(0, 200),
-					});
-					dropChunkFront(pendingChunks, headerEnd + 4);
-					pendingLen -= headerEnd + 4;
-					continue;
-				}
-
-				const contentLength = Number.parseInt(contentLengthMatch[1], 10);
-				const messageStart = headerEnd + 4; // Skip \r\n\r\n
-				const messageEnd = messageStart + contentLength;
-				if (pendingLen < messageEnd) break;
-
-				const messageText = MESSAGE_DECODER.decode(copyChunkRange(pendingChunks, messageStart, messageEnd));
-				dropChunkFront(pendingChunks, messageEnd);
-				pendingLen -= messageEnd;
-
+			for (const messageText of framer.drain(headerText => {
+				// Non-protocol bytes on stdout (e.g. a wrapper script printing).
+				// Drop past the bogus terminator and resync instead of stalling
+				// on the same junk header forever.
+				logger.warn("LSP framing resync: header block without Content-Length", {
+					server: client.name,
+					header: headerText.slice(0, 200),
+				});
+			})) {
 				// A malformed message or a throwing server-request handler must not
 				// kill the reader — later messages are still well-framed.
 				try {
@@ -392,12 +301,7 @@ async function startMessageReader(client: LspClient): Promise<void> {
 		client.pendingRequests.clear();
 	} finally {
 		// Persist any unparsed remainder so a restarted reader resumes mid-message.
-		client.messageBuffer =
-			pendingChunks.length === 0
-				? new Uint8Array(0)
-				: pendingChunks.length === 1
-					? pendingChunks[0]
-					: Buffer.concat(pendingChunks, pendingLen);
+		client.messageBuffer = framer.remainder();
 		reader.releaseLock();
 		client.isReading = false;
 		// Reader exited while the server process is still alive (unrecoverable

package/src/mnemopi/embed-client.ts

@@ -1,208 +1,76 @@
-import * as path from "node:path";
-import { $env, isBunTestRuntime, isCompiledBinary, logger, workerHostEntry } from "@oh-my-pi/pi-utils";
-import type { Subprocess } from "bun";
+import { logger } from "@oh-my-pi/pi-utils";
+import {
+	createUnavailableWorker,
+	createWorkerHandle,
+	createWorkerSubprocess,
+	logWorkerMessage,
+	resolveWorkerSpawnCmd,
+	SMOKE_TEST_TIMEOUT_MS,
+	type SpawnedSubprocess,
+	smokeTestWorker,
+	spawnWorkerOrUnavailable,
+	type WorkerHandle,
+	workerEnvFromParent,
+} from "../subprocess/worker-client";
 import type { MnemopiEmbedModelId, MnemopiEmbedWorkerInbound, MnemopiEmbedWorkerOutbound } from "./embed-protocol";
 
 /**
- * Abstraction over the mnemopi embeddings subprocess. The runtime
+ * Parent-side handle for the mnemopi embeddings subprocess. The runtime
  * implementation is a Bun child process so `onnxruntime-node`'s NAPI
  * constructor + finalizer never run inside the main agent address space —
  * those destructors segfault Bun on Windows when mnemopi's local embedding
  * provider loads fastembed in the main process (issue #3031; the mnemopi
  * sibling of the tiny-model fix from #1606 / #1607).
  */
-export interface MnemopiEmbedWorkerHandle {
-	send(message: MnemopiEmbedWorkerInbound): void;
-	onMessage(handler: (message: MnemopiEmbedWorkerOutbound) => void): () => void;
-	onError(handler: (error: Error) => void): () => void;
-	terminate(): Promise<void>;
-}
+export type MnemopiEmbedWorkerHandle = WorkerHandle<MnemopiEmbedWorkerInbound, MnemopiEmbedWorkerOutbound>;
 
 type PendingRequest =
 	| { kind: "init"; model: MnemopiEmbedModelId; resolve: (ok: boolean) => void }
 	| { kind: "embed"; model: MnemopiEmbedModelId; resolve: (vectors: number[][] | Error) => void };
 
-// Cold-starting the worker from a compiled binary (decompress + module graph load)
-// is slow on contended CI runners; the probe only proves the worker spawns and
-// ponges, so a generous bound removes flakes without weakening the check.
-const SMOKE_TEST_TIMEOUT_MS = 30_000;
-
 /**
  * Hidden subcommand on the main CLI that boots the mnemopi embeddings worker
  * in the spawned subprocess. Kept in sync with the dispatch in `cli.ts`.
  */
 export const MNEMOPI_EMBED_WORKER_ARG = "__omp_worker_mnemopi_embed";
 
-/**
- * Env handed to the embeddings subprocess. The child inherits the parent's
- * environment verbatim — fastembed honours `HF_HUB_*`, `HTTPS_PROXY`, etc.,
- * and our `loadFastembed()` reads the same `OMP_*` runtime-install knobs the
- * parent uses. `process.env` carries `undefined` slots that Bun.spawn rejects;
- * filter them out.
- */
-function mnemopiEmbedWorkerEnv(): Record<string, string> {
-	const base = $env as Record<string, string | undefined>;
-	const merged: Record<string, string> = {};
-	for (const key in base) {
-		const value = base[key];
-		if (typeof value === "string") merged[key] = value;
-	}
-	return merged;
-}
-
-interface MnemopiEmbedWorkerSpawnCommand {
-	cmd: string[];
-	cwd?: string;
-}
-
-/**
- * Resolve the command used to relaunch the agent CLI into mnemopi-embed-worker
- * mode. In a compiled binary the entry point is the binary itself; otherwise
- * re-enter the declared worker-host entry (cwd-relative for reliable Bun IPC),
- * falling back to this package's own `src/cli.ts` when no host entry is
- * declared (bun test, SDK embedding).
- */
-function mnemopiEmbedWorkerSpawnCmd(): MnemopiEmbedWorkerSpawnCommand {
-	if (isCompiledBinary()) return { cmd: [process.execPath, MNEMOPI_EMBED_WORKER_ARG] };
-	const hostEntry = workerHostEntry();
-	if (hostEntry) {
-		return {
-			cmd: [process.execPath, path.basename(hostEntry), MNEMOPI_EMBED_WORKER_ARG],
-			cwd: path.dirname(hostEntry),
-		};
-	}
-	const packageRoot = path.resolve(import.meta.dir, "..", "..");
-	return { cmd: [process.execPath, "src/cli.ts", MNEMOPI_EMBED_WORKER_ARG], cwd: packageRoot };
-}
-
-interface SpawnedSubprocess {
-	proc: Subprocess<"ignore", "ignore", "ignore">;
-	inbound: Set<(message: MnemopiEmbedWorkerOutbound) => void>;
-	errors: Set<(error: Error) => void>;
-	/**
-	 * Flipped to `true` right before the deliberate SIGKILL so `onExit` can
-	 * distinguish the expected hard-kill from a crash (SIGSEGV from a native
-	 * fault, OOM SIGKILL, operator `kill -9`). Only the latter surfaces as a
-	 * worker error so callers don't await forever.
-	 */
-	intentionalExit: { value: boolean };
-}
-
 /**
  * Spawn the mnemopi embeddings worker as a subprocess. Exported for tests and
  * the smoke probe; production callers go through {@link spawnMnemopiEmbedWorker}.
+ * The child inherits the parent env verbatim — fastembed honours `HF_HUB_*`,
+ * `HTTPS_PROXY`, etc., and our `loadFastembed()` reads the same `OMP_*`
+ * runtime-install knobs the parent uses.
  */
-export function createMnemopiEmbedSubprocess(): SpawnedSubprocess {
-	const inbound = new Set<(message: MnemopiEmbedWorkerOutbound) => void>();
-	const errors = new Set<(error: Error) => void>();
-	const intentionalExit = { value: false };
-	const spawnCommand = mnemopiEmbedWorkerSpawnCmd();
-	const proc = Bun.spawn({
-		cmd: spawnCommand.cmd,
-		cwd: spawnCommand.cwd,
-		env: mnemopiEmbedWorkerEnv(),
-		stdin: "ignore",
-		stdout: "ignore",
-		stderr: "ignore",
-		serialization: "advanced",
-		windowsHide: true,
-		ipc(message) {
-			for (const handler of inbound) handler(message as MnemopiEmbedWorkerOutbound);
-		},
-		onExit(_proc, exitCode, signalCode) {
-			if (exitCode === 0) return;
-			if (exitCode === null && intentionalExit.value) return;
-			const reason = exitCode !== null ? `code ${exitCode}` : `signal ${signalCode ?? "unknown"}`;
-			const err = new Error(`mnemopi embed subprocess exited with ${reason}`);
-			for (const handler of errors) handler(err);
-		},
+export function createMnemopiEmbedSubprocess(): SpawnedSubprocess<MnemopiEmbedWorkerOutbound> {
+	return createWorkerSubprocess<MnemopiEmbedWorkerOutbound>({
+		spawnCommand: resolveWorkerSpawnCmd(MNEMOPI_EMBED_WORKER_ARG),
+		env: workerEnvFromParent(),
+		exitLabel: "mnemopi embed subprocess",
 	});
-	// Don't keep the parent event loop alive on an idle worker; the agent
-	// dispose path calls `terminate()` explicitly. Bun's test runner starves
-	// IPC for unref'd subprocesses, so keep it referenced only under tests.
-	if (!isBunTestRuntime()) proc.unref();
-	return { proc, inbound, errors, intentionalExit };
-}
-
-function wrapSubprocess({ proc, inbound, errors, intentionalExit }: SpawnedSubprocess): MnemopiEmbedWorkerHandle {
-	return {
-		send(message) {
-			try {
-				proc.send(message);
-			} catch (error) {
-				logger.debug("mnemopi-embed: send to subprocess failed", {
-					error: error instanceof Error ? error.message : String(error),
-				});
-			}
-		},
-		onMessage(handler) {
-			inbound.add(handler);
-			return () => inbound.delete(handler);
-		},
-		onError(handler) {
-			errors.add(handler);
-			return () => errors.delete(handler);
-		},
-		async terminate() {
-			// SIGKILL: the point of subprocess isolation is that the parent
-			// never runs `onnxruntime-node`'s NAPI finalizer (it crashes Bun
-			// on Windows). Hard-kill instead; the OS reclaims the model
-			// memory. Flip the intentional-exit flag *before* killing so
-			// `onExit` can tell this apart from a native crash.
-			intentionalExit.value = true;
-			try {
-				proc.kill("SIGKILL");
-			} catch {
-				// Already gone.
-			}
-		},
-	};
 }
 
-function spawnInlineUnavailableWorker(error: unknown): MnemopiEmbedWorkerHandle {
-	const listeners = new Set<(message: MnemopiEmbedWorkerOutbound) => void>();
-	const errorMessage = error instanceof Error ? error.message : String(error);
-	const emit = (message: MnemopiEmbedWorkerOutbound): void => {
-		for (const listener of listeners) listener(message);
-	};
-	return {
-		send(message) {
-			queueMicrotask(() => {
-				if (message.type === "ping") {
-					emit({ type: "pong", id: message.id });
-					return;
-				}
-				emit({ type: "error", id: message.id, error: errorMessage });
+function wrapSubprocess(spawned: SpawnedSubprocess<MnemopiEmbedWorkerOutbound>): MnemopiEmbedWorkerHandle {
+	const { proc } = spawned;
+	// Embed keeps its own guarded `proc.send` (neutralizes only the synchronous
+	// throw, not the async EPIPE rejection) rather than the shared `safeSend`
+	// the other workers use — behaviour preserved verbatim.
+	return createWorkerHandle<MnemopiEmbedWorkerInbound, MnemopiEmbedWorkerOutbound>(spawned, message => {
+		try {
+			proc.send(message);
+		} catch (error) {
+			logger.debug("mnemopi-embed: send to subprocess failed", {
+				error: error instanceof Error ? error.message : String(error),
 			});
-		},
-		onMessage(handler) {
-			listeners.add(handler);
-			return () => listeners.delete(handler);
-		},
-		onError() {
-			return () => {};
-		},
-		async terminate() {
-			listeners.clear();
-		},
-	};
+		}
+	});
 }
 
 function spawnMnemopiEmbedWorker(): MnemopiEmbedWorkerHandle {
-	try {
-		return wrapSubprocess(createMnemopiEmbedSubprocess());
-	} catch (error) {
-		logger.warn("mnemopi embed worker spawn failed; local embeddings disabled", {
-			error: error instanceof Error ? error.message : String(error),
-		});
-		return spawnInlineUnavailableWorker(error);
-	}
-}
-
-function logWorkerMessage(message: Extract<MnemopiEmbedWorkerOutbound, { type: "log" }>): void {
-	if (message.level === "debug") logger.debug(message.msg, message.meta);
-	else if (message.level === "warn") logger.warn(message.msg, message.meta);
-	else logger.error(message.msg, message.meta);
+	return spawnWorkerOrUnavailable(
+		() => wrapSubprocess(createMnemopiEmbedSubprocess()),
+		createUnavailableWorker<MnemopiEmbedWorkerInbound, MnemopiEmbedWorkerOutbound>,
+		"mnemopi embed worker spawn failed; local embeddings disabled",
+	);
 }
 
 /**
@@ -374,28 +242,5 @@ export async function smokeTestMnemopiEmbedWorker({
 }: {
 	timeoutMs?: number;
 } = {}): Promise<void> {
-	const handle = wrapSubprocess(createMnemopiEmbedSubprocess());
-	const { promise, resolve, reject } = Promise.withResolvers<void>();
-	const timer = setTimeout(
-		() => reject(new Error(`mnemopi embed worker did not pong within ${timeoutMs}ms`)),
-		timeoutMs,
-	);
-	const unsubscribeMessage = handle.onMessage(message => {
-		if (message.type === "pong") {
-			resolve();
-			return;
-		}
-		if (message.type === "log") return;
-		reject(new Error(`mnemopi embed worker: expected pong, got ${JSON.stringify(message)}`));
-	});
-	const unsubscribeError = handle.onError(reject);
-	try {
-		handle.send({ type: "ping", id: "smoke" } satisfies MnemopiEmbedWorkerInbound);
-		await promise;
-	} finally {
-		clearTimeout(timer);
-		unsubscribeMessage();
-		unsubscribeError();
-		await handle.terminate();
-	}
+	await smokeTestWorker(wrapSubprocess(createMnemopiEmbedSubprocess()), "mnemopi embed worker", timeoutMs);
 }

package/src/modes/components/agent-dashboard.ts

@@ -21,7 +21,6 @@ import {
 	type Component,
 	Container,
 	Editor,
-	extractPrintableText,
 	fuzzyMatch,
 	Input,
 	matchesKey,
@@ -59,6 +58,7 @@ import {
 	matchesSelectUp,
 } from "../utils/keybinding-matchers";
 import { DynamicBorder } from "./dynamic-border";
+import { clampSelection, handleTabSwitchKey, padLinesToHeight, searchableChar } from "./selector-helpers";
 
 type SourceTabId = "all" | AgentSource;
 type AgentScope = "project" | "user";
@@ -521,31 +521,19 @@ export class AgentDashboard extends Container {
 		const lines = super.render(width);
 		// Pad to the full viewport so every state (list, edit, create) covers the
 		// screen as a true full-screen view instead of letting the transcript peek
-		// through below it. Copy before padding — the container's render result is
-		// component-owned and must not be mutated.
-		const rows = this.#terminalRows();
-		if (lines.length >= rows) return lines;
-		const padded = lines.slice();
-		while (padded.length < rows) padded.push("");
-		return padded;
+		// through below it.
+		return padLinesToHeight(lines, this.#terminalRows());
 	}
 
 	#clampSelection(): void {
-		if (this.#filteredAgents.length === 0) {
-			this.#selectedIndex = 0;
-			this.#scrollOffset = 0;
-			return;
-		}
-
-		this.#selectedIndex = Math.min(this.#selectedIndex, this.#filteredAgents.length - 1);
-		this.#selectedIndex = Math.max(0, this.#selectedIndex);
-
-		const maxVisible = this.#getMaxVisibleItems();
-		if (this.#selectedIndex < this.#scrollOffset) {
-			this.#scrollOffset = this.#selectedIndex;
-		} else if (this.#selectedIndex >= this.#scrollOffset + maxVisible) {
-			this.#scrollOffset = this.#selectedIndex - maxVisible + 1;
-		}
+		const next = clampSelection(
+			this.#selectedIndex,
+			this.#scrollOffset,
+			this.#filteredAgents.length,
+			this.#getMaxVisibleItems(),
+		);
+		this.#selectedIndex = next.selectedIndex;
+		this.#scrollOffset = next.scrollOffset;
 	}
 
 	#persistDisabledAgents(): void {
@@ -1150,12 +1138,7 @@ export class AgentDashboard extends Container {
 			return;
 		}
 
-		if (matchesKey(data, "tab") || matchesKey(data, "right")) {
-			this.#switchTab(1);
-			return;
-		}
-		if (matchesKey(data, "shift+tab") || matchesKey(data, "left")) {
-			this.#switchTab(-1);
+		if (handleTabSwitchKey(data, direction => this.#switchTab(direction))) {
 			return;
 		}
 
@@ -1190,17 +1173,11 @@ export class AgentDashboard extends Container {
 			return;
 		}
 
-		const printableText = extractPrintableText(data);
-		if (printableText && printableText.length === 1) {
-			const printableCharCode = printableText.charCodeAt(0);
-			if (printableCharCode > 32 && printableCharCode < 127) {
-				if (printableText === "j" || printableText === "k") {
-					return;
-				}
-				this.#searchQuery += printableText;
-				this.#applyFilters();
-				this.#buildLayout();
-			}
+		const char = searchableChar(data);
+		if (char !== null) {
+			this.#searchQuery += char;
+			this.#applyFilters();
+			this.#buildLayout();
 		}
 	}
 }