@wahack/pi-coding-agent 15.11.0

package/src/debug/profiler.ts

@@ -0,0 +1,162 @@
+/**
+ * CPU and heap profiling wrappers for debug reports.
+ */
+
+export interface CpuProfile {
+	data: string;
+	markdown: string;
+}
+
+export interface ProfilerSession {
+	/** Stop profiling and return the profile data */
+	stop(): Promise<CpuProfile>;
+}
+
+/** V8 CPU Profile node structure */
+interface CpuProfileNode {
+	id: number;
+	callFrame?: {
+		functionName?: string;
+		url?: string;
+		lineNumber?: number;
+	};
+	hitCount?: number;
+	children?: number[];
+}
+
+/** V8 CPU Profile structure */
+interface CpuProfileData {
+	nodes?: CpuProfileNode[];
+	samples?: number[];
+	timeDeltas?: number[];
+	startTime?: number;
+	endTime?: number;
+}
+
+/**
+ * Format CPU profile data as markdown for LLM analysis.
+ * Extracts top functions by self time and call counts.
+ */
+function formatProfileAsMarkdown(profileJson: string): string {
+	try {
+		const profile = JSON.parse(profileJson) as CpuProfileData;
+		const nodes = profile.nodes ?? [];
+
+		interface NodeInfo {
+			id: number;
+			functionName: string;
+			url: string;
+			lineNumber: number;
+			selfTime: number;
+			hitCount: number;
+		}
+
+		const nodeMap = new Map<number, NodeInfo>();
+		for (const node of nodes) {
+			nodeMap.set(node.id, {
+				id: node.id,
+				functionName: node.callFrame?.functionName ?? "(anonymous)",
+				url: node.callFrame?.url ?? "",
+				lineNumber: node.callFrame?.lineNumber ?? 0,
+				selfTime: 0,
+				hitCount: node.hitCount ?? 0,
+			});
+		}
+
+		// Distribute sample times to nodes
+		const samples = profile.samples ?? [];
+		const timeDeltas = profile.timeDeltas ?? [];
+		for (let i = 0; i < samples.length; i++) {
+			const nodeId = samples[i];
+			const info = nodeId !== undefined ? nodeMap.get(nodeId) : undefined;
+			const delta = timeDeltas[i] ?? 0;
+			if (info) {
+				info.selfTime += delta;
+			}
+		}
+
+		// Sort by self time and get top functions
+		const sorted = Array.from(nodeMap.values())
+			.filter(n => n.selfTime > 0 && n.functionName !== "(root)" && n.functionName !== "(idle)")
+			.sort((a, b) => b.selfTime - a.selfTime)
+			.slice(0, 30);
+
+		if (sorted.length === 0) {
+			return "# CPU Profile Summary\n\nNo significant CPU activity recorded.";
+		}
+
+		const totalTime = sorted.reduce((sum, n) => sum + n.selfTime, 0);
+
+		const lines = ["# CPU Profile Summary", ""];
+		lines.push(`Total profiled time: ${(totalTime / 1000).toFixed(1)}ms`);
+		lines.push("");
+		lines.push("## Top Functions by Self Time");
+		lines.push("");
+		lines.push("| Function | Self Time (ms) | % | Location |");
+		lines.push("|----------|----------------|---|----------|");
+
+		for (const node of sorted) {
+			const selfMs = (node.selfTime / 1000).toFixed(1);
+			const pct = ((node.selfTime / totalTime) * 100).toFixed(1);
+			const location = node.url ? `${node.url}:${node.lineNumber}` : "-";
+			lines.push(`| ${node.functionName} | ${selfMs} | ${pct}% | ${location} |`);
+		}
+
+		return lines.join("\n");
+	} catch {
+		return "# CPU Profile Summary\n\nFailed to parse profile data.";
+	}
+}
+
+/**
+ * Start CPU profiling.
+ * Returns a session that can be stopped to get the profile data.
+ */
+export async function startCpuProfile(): Promise<ProfilerSession> {
+	const v8 = await import("node:v8");
+	v8.setFlagsFromString("--allow-natives-syntax");
+
+	const { Session } = await import("node:inspector/promises");
+	const session = new Session();
+	session.connect();
+
+	await session.post("Profiler.enable");
+	// Default CDP interval is 1ms, which mis-attributes await-resumption samples
+	// to the line after `await` (one sparse sample inherits the entire wait). 100µs
+	// scatters samples enough to keep CPU vs. async-wait attribution honest.
+	await session.post("Profiler.setSamplingInterval", { interval: 100 });
+	await session.post("Profiler.start");
+
+	return {
+		async stop(): Promise<CpuProfile> {
+			const result = await session.post("Profiler.stop");
+			await session.post("Profiler.disable");
+			session.disconnect();
+
+			const data = JSON.stringify(result.profile, null, 2);
+			const markdown = formatProfileAsMarkdown(data);
+
+			return { data, markdown };
+		},
+	};
+}
+
+export interface HeapSnapshot {
+	data: string;
+}
+
+/**
+ * Generate a heap snapshot.
+ * Uses Bun's built-in generateHeapSnapshot.
+ */
+export function generateHeapSnapshotData(): HeapSnapshot {
+	// Force GC before snapshot
+	Bun.gc(true);
+
+	// Use V8 format for Chrome DevTools compatibility
+	const snapshot = Bun.generateHeapSnapshot("v8");
+
+	return {
+		data: snapshot,
+	};
+}

package/src/debug/protocol-probe.ts

@@ -0,0 +1,267 @@
+/**
+ * Terminal protocol smoke-test panel for the debug menu.
+ *
+ * Exercises every "special" escape protocol the renderer can emit so a human
+ * can eyeball which ones the active terminal actually honors:
+ *   - SGR text styling + 24-bit truecolor,
+ *   - OSC 8 hyperlinks,
+ *   - OSC 66 text sizing (large text),
+ *   - inline graphics (Kitty / iTerm2 / Sixel),
+ *   - OSC 9 / OSC 99 desktop notifications (fired by the caller).
+ *
+ * The sample image is generated in-process (a deterministic RGB gradient PNG)
+ * so the graphics test needs no asset on disk and works across all three image
+ * protocols, each of which decodes a standard PNG.
+ */
+import * as zlib from "node:zlib";
+import {
+	type Component,
+	Container,
+	encodeTextSized,
+	Image,
+	type ImageBudget,
+	ImageProtocol,
+	NotifyProtocol,
+	Spacer,
+	TERMINAL,
+	Text,
+	type TextSizingScale,
+} from './stubs/tui/index.ts';
+import { DynamicBorder } from "../modes/components/dynamic-border";
+import { theme } from "../modes/theme/theme";
+
+const PNG_SIGNATURE = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+
+/** Frame a PNG chunk: 4-byte big-endian length, type+data, then the CRC-32 of type+data. */
+function pngChunk(type: string, data: Uint8Array): Uint8Array {
+	const body = Buffer.concat([Buffer.from(type, "latin1"), data]);
+	const out = Buffer.alloc(body.length + 8);
+	out.writeUInt32BE(data.length, 0);
+	body.copy(out, 4);
+	out.writeUInt32BE(Bun.hash.crc32(body) >>> 0, out.length - 4);
+	return out;
+}
+
+/**
+ * Encode raw 8-bit RGB pixels (`width * height * 3` bytes, row-major) as a PNG
+ * (color type 2, no interlacing). The IDAT payload is a real zlib stream from
+ * {@link zlib.deflateSync}, so the output is a fully valid PNG that every image
+ * protocol — including Sixel, which decodes the bytes natively — accepts.
+ */
+export function encodeRgbPng(width: number, height: number, rgb: Uint8Array): Uint8Array {
+	const ihdr = Buffer.alloc(13);
+	ihdr.writeUInt32BE(width, 0);
+	ihdr.writeUInt32BE(height, 4);
+	ihdr[8] = 8; // bit depth
+	ihdr[9] = 2; // color type: truecolor RGB
+	// compression (0), filter (0), interlace (0) are already zeroed.
+
+	const stride = width * 3;
+	// Each scanline is prefixed with a filter-type byte (0 = None).
+	const raw = Buffer.alloc((stride + 1) * height);
+	for (let y = 0; y < height; y++) {
+		raw.set(rgb.subarray(y * stride, y * stride + stride), y * (stride + 1) + 1);
+	}
+	const idat = zlib.deflateSync(raw);
+
+	return Buffer.concat([
+		PNG_SIGNATURE,
+		pngChunk("IHDR", ihdr),
+		pngChunk("IDAT", idat),
+		pngChunk("IEND", new Uint8Array(0)),
+	]);
+}
+
+export interface SampleImage {
+	base64: string;
+	mimeType: string;
+	dimensions: { widthPx: number; heightPx: number };
+}
+
+/** Build a deterministic RGB gradient PNG (red across, green down, constant blue). */
+export function buildSampleImage(width = 192, height = 128): SampleImage {
+	const denomX = Math.max(1, width - 1);
+	const denomY = Math.max(1, height - 1);
+	const rgb = new Uint8Array(width * height * 3);
+	for (let y = 0; y < height; y++) {
+		for (let x = 0; x < width; x++) {
+			const i = (y * width + x) * 3;
+			rgb[i] = Math.round((x / denomX) * 255);
+			rgb[i + 1] = Math.round((y / denomY) * 255);
+			rgb[i + 2] = 128;
+		}
+	}
+	const png = encodeRgbPng(width, height, rgb);
+	return {
+		base64: Buffer.from(png).toString("base64"),
+		mimeType: "image/png",
+		dimensions: { widthPx: width, heightPx: height },
+	};
+}
+
+const LARGE_TEXT_SAMPLE = "Aa Bb 123";
+
+/**
+ * OSC 66 text-sizing sample lines, one scaled span per requested scale. Each
+ * scaled row is followed by `scale - 1` blank rows that reserve the vertical
+ * cells its multi-cell glyphs occupy — mirroring the markdown H1 renderer so
+ * the next line does not paint over the bottom of the glyphs.
+ */
+export function buildLargeTextLines(scales: readonly TextSizingScale[] = [2, 3]): string[] {
+	const lines: string[] = [];
+	for (const scale of scales) {
+		lines.push(`  ${theme.fg("accent", encodeTextSized(`${LARGE_TEXT_SAMPLE} (${scale}x)`, { scale }))}`);
+		for (let reserved = 1; reserved < scale; reserved++) lines.push("");
+	}
+	return lines;
+}
+
+/** HSV (h in degrees, s/v in 0..1) to 8-bit RGB, for the truecolor demo bar. */
+function hsvToRgb(h: number, s: number, v: number): [number, number, number] {
+	const c = v * s;
+	const hp = (((h % 360) + 360) % 360) / 60;
+	const x = c * (1 - Math.abs((hp % 2) - 1));
+	let r = 0;
+	let g = 0;
+	let b = 0;
+	if (hp < 1) [r, g, b] = [c, x, 0];
+	else if (hp < 2) [r, g, b] = [x, c, 0];
+	else if (hp < 3) [r, g, b] = [0, c, x];
+	else if (hp < 4) [r, g, b] = [0, x, c];
+	else if (hp < 5) [r, g, b] = [x, 0, c];
+	else [r, g, b] = [c, 0, x];
+	const m = v - c;
+	const to8 = (n: number) => Math.round((n + m) * 255);
+	return [to8(r), to8(g), to8(b)];
+}
+
+/** A 24-bit-color hue sweep rendered as background-painted cells (one space each). */
+function truecolorBar(cells: number): string {
+	let out = "";
+	for (let i = 0; i < cells; i++) {
+		const [r, g, b] = hsvToRgb((i / cells) * 360, 0.85, 1);
+		out += `\x1b[48;2;${r};${g};${b}m `;
+	}
+	return `${out}\x1b[0m`;
+}
+
+function notifyProtocolLabel(): string {
+	switch (TERMINAL.notifyProtocol) {
+		case NotifyProtocol.Osc99:
+			return "OSC 99 (kitty)";
+		case NotifyProtocol.Osc9:
+			return "OSC 9 (iTerm2/WezTerm)";
+		default:
+			return "BEL";
+	}
+}
+
+function imageProtocolLabel(): string {
+	switch (TERMINAL.imageProtocol) {
+		case ImageProtocol.Kitty:
+			return "Kitty graphics";
+		case ImageProtocol.Iterm2:
+			return "iTerm2 inline images";
+		case ImageProtocol.Sixel:
+			return "Sixel";
+		default:
+			return "none — text fallback";
+	}
+}
+
+/** Emits a fixed list of lines verbatim — no wrapping or padding. Used for OSC 66 spans. */
+class RawLines implements Component {
+	#lines: readonly string[];
+	constructor(lines: readonly string[]) {
+		this.#lines = lines;
+	}
+	invalidate(): void {}
+	render(): string[] {
+		return [...this.#lines];
+	}
+}
+
+export interface ProtocolProbeOptions {
+	image: SampleImage;
+	imageBudget: ImageBudget;
+	/** Whether the desktop notification was suppressed (e.g. `PI_NOTIFICATIONS=off`). */
+	notificationSuppressed: boolean;
+}
+
+/**
+ * Self-contained panel that renders one sample of every special terminal
+ * protocol into the chat transcript.
+ */
+export class ProtocolProbeComponent extends Container {
+	constructor(options: ProtocolProbeOptions) {
+		super();
+		const hyperlinksOn = TERMINAL.hyperlinks;
+		const sizingOn = TERMINAL.textSizing;
+		const yesNo = (on: boolean) => (on ? theme.fg("success", "supported") : theme.fg("muted", "unsupported"));
+
+		this.addChild(new DynamicBorder());
+		this.addChild(new Text(theme.bold(theme.fg("accent", "Terminal Protocol Test")), 1, 0));
+
+		// Styling: SGR attributes, themed foregrounds, and a truecolor sweep.
+		const styling = [
+			theme.fg("muted", "Styling (SGR)"),
+			`  ${theme.bold("bold")}  ${theme.italic("italic")}  ${theme.underline("underline")}  ${theme.strikethrough("strike")}  ${theme.inverse(" inverse ")}  ${theme.fg("dim", "dim")}`,
+			`  ${theme.fg("accent", "accent")}  ${theme.fg("success", "success")}  ${theme.fg("warning", "warning")}  ${theme.fg("error", "error")}`,
+			`  truecolor: ${truecolorBar(32)} (${theme.fg("muted", `24-bit ${TERMINAL.trueColor ? "on" : "off"}`)})`,
+		].join("\n");
+		this.addChild(new Text(styling, 1, 0));
+		this.addChild(new Spacer(1));
+
+		// Hyperlinks: OSC 8. Renders as plain text where unsupported.
+		this.addChild(
+			new Text(
+				[
+					`${theme.fg("muted", "Hyperlinks (OSC 8)")} — ${yesNo(hyperlinksOn)}`,
+					`  \x1b]8;;https://github.com/can1357/oh-my-pi\x07oh-my-pi repo\x1b]8;;\x07`,
+				].join("\n"),
+				1,
+				0,
+			),
+		);
+		this.addChild(new Spacer(1));
+
+		// Text sizing: OSC 66.
+		this.addChild(new Text(`${theme.fg("muted", "Text sizing (OSC 66)")} — ${yesNo(sizingOn)}`, 1, 0));
+		if (sizingOn) {
+			this.addChild(new RawLines(buildLargeTextLines()));
+		} else {
+			this.addChild(
+				new Text(theme.fg("dim", "  (enable via the tui.textSizing setting on a Kitty terminal)"), 1, 0),
+			);
+		}
+		this.addChild(new Spacer(1));
+
+		// Graphics: Kitty / iTerm2 / Sixel, with a text fallback baked into Image.
+		this.addChild(new Text(`${theme.fg("muted", "Graphics")} — ${theme.fg("dim", imageProtocolLabel())}`, 1, 0));
+		this.addChild(
+			new Image(
+				options.image.base64,
+				options.image.mimeType,
+				{ fallbackColor: (text: string) => theme.fg("toolOutput", text) },
+				// Fixed modest caps (not the user's inline-image setting) keep the
+				// swatch a crisp, bounded preview rather than an upscaled wall.
+				{ maxWidthCells: 20, maxHeightCells: 16, budget: options.imageBudget },
+				options.image.dimensions,
+			),
+		);
+		this.addChild(new Spacer(1));
+
+		// Notifications: fired by the caller; this line reports the outcome.
+		const notifyStatus = options.notificationSuppressed
+			? theme.fg("warning", "suppressed (PI_NOTIFICATIONS)")
+			: theme.fg("success", "sent — check your desktop / titlebar");
+		this.addChild(
+			new Text(
+				`${theme.fg("muted", "Notification")} (${theme.fg("dim", notifyProtocolLabel())}) — ${notifyStatus}`,
+				1,
+				0,
+			),
+		);
+		this.addChild(new DynamicBorder());
+	}
+}

package/src/debug/raw-sse-buffer.ts

@@ -0,0 +1,273 @@
+import type { Model, ProviderResponseMetadata, RawSseEvent } from "@oh-my-pi/pi-ai";
+
+const MAX_RAW_SSE_EVENTS = 1_000;
+const MAX_RAW_SSE_CHARS = 512_000;
+const MAX_RAW_SSE_EVENT_CHARS = 64_000;
+
+export type RawSseDebugRecord =
+	| {
+			kind: "response";
+			sequence: number;
+			timestamp: number;
+			provider?: string;
+			model?: string;
+			api?: string;
+			status: number;
+			requestId?: string | null;
+			transport?: string;
+	  }
+	| {
+			kind: "event";
+			sequence: number;
+			timestamp: number;
+			provider?: string;
+			model?: string;
+			api?: string;
+			event: string | null;
+			raw: string[];
+			truncated: boolean;
+			originalChars: number;
+	  };
+
+export interface RawSseDebugSnapshot {
+	records: readonly RawSseDebugRecord[];
+	droppedRecords: number;
+	droppedChars: number;
+	totalEvents: number;
+	lastUpdatedAt?: number;
+}
+
+// Per-record char counts are stored in a parallel array (`#recordChars`) on
+// the buffer rather than stamped onto each record via a symbol property.
+// Stamping triggered hidden-class transitions in V8/JSC — the previous
+// revision saw `trimRawLines` regress 4× (0.5s → 2.0s in a 50s profile)
+// because every event-record allocation went through the slow dictionary
+// path. The parallel array keeps records as plain monomorphic objects.
+type TrimResult = { raw: string[]; truncated: boolean; originalChars: number; chars: number };
+
+// Single-pass trim. Returns the final `chars` count using the historical
+// formula `reduce(line.length + 1, init = 1)` so the new accounting matches
+// the previous `countRecordChars` byte-for-byte (the trailing +1 covers the
+// record-level newline that `rawRecordText` appends in `toRawText`).
+//
+// When the event fits within budget the input `raw` array is returned
+// **by reference** — see the ownership contract documented at
+// `RawSseDebugBuffer.recordEvent` below.
+function trimRawLines(raw: string[]): TrimResult {
+	let originalChars = 0;
+	for (let i = 0; i < raw.length; i++) originalChars += raw[i].length + 1;
+
+	if (originalChars <= MAX_RAW_SSE_EVENT_CHARS) {
+		return { raw, truncated: false, originalChars, chars: originalChars + 1 };
+	}
+
+	const trimmed: string[] = [];
+	let remaining = MAX_RAW_SSE_EVENT_CHARS;
+	let chars = 1; // matches reduce(.., init = 1)
+	for (const line of raw) {
+		if (remaining <= 0) break;
+		if (line.length + 1 <= remaining) {
+			trimmed.push(line);
+			chars += line.length + 1;
+			remaining -= line.length + 1;
+			continue;
+		}
+		const slice = line.slice(0, Math.max(0, remaining));
+		trimmed.push(slice);
+		chars += slice.length + 1;
+		remaining = 0;
+	}
+	const tail = `: omp-debug-truncated originalChars=${originalChars}`;
+	trimmed.push(tail);
+	chars += tail.length + 1;
+	return { raw: trimmed, truncated: true, originalChars, chars };
+}
+
+export function formatRawSseIsoTime(timestamp: number): string {
+	return new Date(timestamp).toISOString();
+}
+
+export function formatRawSseResponseComment(record: Extract<RawSseDebugRecord, { kind: "response" }>): string {
+	const fields = [
+		"omp-response",
+		`ts=${formatRawSseIsoTime(record.timestamp)}`,
+		`status=${record.status}`,
+		record.provider ? `provider=${record.provider}` : undefined,
+		record.model ? `model=${record.model}` : undefined,
+		record.api ? `api=${record.api}` : undefined,
+		record.requestId ? `requestId=${record.requestId}` : undefined,
+		record.transport ? `transport=${record.transport}` : undefined,
+	].filter((field): field is string => field !== undefined);
+	return `: ${fields.join(" ")}`;
+}
+
+export function rawSseRecordLines(record: RawSseDebugRecord): string[] {
+	if (record.kind === "response") return [formatRawSseResponseComment(record)];
+	return record.raw;
+}
+
+function rawRecordText(record: RawSseDebugRecord): string {
+	return `${rawSseRecordLines(record).join("\n")}\n`;
+}
+
+function metadataTransport(response: ProviderResponseMetadata): string | undefined {
+	const value = response.metadata?.lastTransport;
+	return typeof value === "string" ? value : undefined;
+}
+
+export class RawSseDebugBuffer {
+	#records: RawSseDebugRecord[] = [];
+	// Parallel to `#records`: `#recordChars[i]` is the precomputed char count
+	// for `#records[i]`. Kept in lockstep by `#append` (push both) and
+	// `#enforceLimits` (shift both). See the comment above the class for why
+	// this is a sidecar array instead of a per-record property.
+	#recordChars: number[] = [];
+	#totalChars = 0;
+	#droppedRecords = 0;
+	#droppedChars = 0;
+	#totalEvents = 0;
+	#lastUpdatedAt: number | undefined;
+	#nextSequence = 1;
+	#listeners = new Set<() => void>();
+	#emitScheduled = false;
+
+	subscribe(listener: () => void): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+
+	recordResponse(response: ProviderResponseMetadata, model?: Model): void {
+		const record: RawSseDebugRecord = {
+			kind: "response",
+			sequence: this.#nextSequence++,
+			timestamp: Date.now(),
+			provider: model?.provider,
+			model: model?.id,
+			api: model?.api,
+			status: response.status,
+			requestId: response.requestId,
+			transport: metadataTransport(response),
+		};
+		this.#append(record, formatRawSseResponseComment(record).length + 1);
+	}
+
+	// Ownership contract for `event.raw`:
+	//   The caller (`notifyRawSseEvent` in `packages/ai/src/utils/sse-debug.ts`)
+	//   hands us a freshly-allocated `string[]` per event and never retains,
+	//   mutates, or re-dispatches it.
+	//   That lets `trimRawLines` keep the array by reference instead of
+	//   cloning on every chunk — a measurable savings on the streaming hot
+	//   path. If a future observer-chain mutates the array, restore the
+	//   `raw.slice()` defensive copy inside `trimRawLines`.
+	recordEvent(event: RawSseEvent, model?: Model): void {
+		const trimmed = trimRawLines(event.raw);
+		this.#totalEvents += 1;
+		this.#append(
+			{
+				kind: "event",
+				sequence: this.#nextSequence++,
+				timestamp: Date.now(),
+				provider: model?.provider,
+				model: model?.id,
+				api: model?.api,
+				event: event.event,
+				raw: trimmed.raw,
+				truncated: trimmed.truncated,
+				originalChars: trimmed.originalChars,
+			},
+			trimmed.chars,
+		);
+	}
+
+	snapshot(): RawSseDebugSnapshot {
+		return {
+			records: [...this.#records],
+			droppedRecords: this.#droppedRecords,
+			droppedChars: this.#droppedChars,
+			totalEvents: this.#totalEvents,
+			lastUpdatedAt: this.#lastUpdatedAt,
+		};
+	}
+
+	toRawText(): string {
+		// Reads the live array directly: `rawRecordText` only computes a string
+		// from each record, so no caller-visible mutation is possible.
+		const body = this.#records.map(rawRecordText).join("\n");
+		if (this.#droppedRecords === 0) return body;
+		const dropped = `: omp-debug-dropped records=${this.#droppedRecords} chars=${this.#droppedChars}\n\n`;
+		return body.length > 0 ? `${dropped}${body}` : dropped;
+	}
+
+	#append(record: RawSseDebugRecord, chars: number): void {
+		this.#records.push(record);
+		this.#recordChars.push(chars);
+		this.#totalChars += chars;
+		this.#lastUpdatedAt = record.timestamp;
+		this.#enforceLimits();
+		this.#emit();
+	}
+
+	#enforceLimits(): void {
+		while (this.#records.length > MAX_RAW_SSE_EVENTS || this.#totalChars > MAX_RAW_SSE_CHARS) {
+			if (this.#records.length === 0) return;
+			this.#records.shift();
+			const chars = this.#recordChars.shift() ?? 0;
+			this.#totalChars = Math.max(0, this.#totalChars - chars);
+			this.#droppedRecords += 1;
+			this.#droppedChars += chars;
+		}
+	}
+
+	#emit(): void {
+		const count = this.#listeners.size;
+		if (count === 0) return;
+		// With a single listener (the common case — RawSse debug viewer is the
+		// only subscriber), keep eager emit so per-event semantics are
+		// preserved. With multiple listeners, coalesce bursts of events into
+		// one microtask-deferred fan-out to avoid N×M listener invocations
+		// during a streaming response.
+		if (count === 1) {
+			this.#fanOut();
+			return;
+		}
+		if (this.#emitScheduled) return;
+		this.#emitScheduled = true;
+		queueMicrotask(() => {
+			this.#emitScheduled = false;
+			this.#fanOut();
+		});
+	}
+
+	#fanOut(): void {
+		for (const listener of this.#listeners) {
+			try {
+				listener();
+			} catch {
+				// Debug viewers must not be able to break stream capture.
+			}
+		}
+	}
+}
+
+const globalFallbackBuffer = new RawSseDebugBuffer();
+const kRawSseDebugBuffer = Symbol("debug.rawSseBuffer");
+type OwnerWithBuffer = object & { rawSseDebugBuffer?: unknown; [kRawSseDebugBuffer]?: RawSseDebugBuffer };
+
+export function resolveRawSseDebugBuffer(owner?: object): RawSseDebugBuffer {
+	if (!owner) return globalFallbackBuffer;
+
+	const tagged = owner as OwnerWithBuffer;
+	const declared = tagged.rawSseDebugBuffer;
+	if (declared instanceof RawSseDebugBuffer) return declared;
+
+	const existing = tagged[kRawSseDebugBuffer];
+	if (existing) return existing;
+
+	const buffer = new RawSseDebugBuffer();
+	try {
+		tagged[kRawSseDebugBuffer] = buffer;
+	} catch {
+		// Non-extensible owner: caller gets a fresh buffer on each call.
+	}
+	return buffer;
+}