@f5-sales-demo/pi-utils 19.51.2

package/src/mermaid-color.ts

@@ -0,0 +1,231 @@
+/**
+ * Mermaid color helpers — terminal color-mode selection, diagram-type detection,
+ * and a best-effort per-node tint pass for ASCII/Unicode mermaid output.
+ *
+ * `beautiful-mermaid` colorizes strictly by global character role (text/border/
+ * line/arrow/…), so per-node hues are not reachable through its API. `tintMermaidNodes`
+ * adds them as a post-pass: it detects node-box rectangles in the rendered output and
+ * overrides the foreground color of each box's border + label cells with a cycled accent.
+ * It is intentionally fail-safe — any ambiguity returns the input unchanged so the
+ * library's per-role coloring still shows through.
+ */
+
+/** Color mode subset we drive `beautiful-mermaid` with. */
+export type MermaidColorMode = "none" | "ansi256" | "truecolor";
+
+export interface ColorModeInput {
+	/** NO_COLOR set, output piped, or color explicitly disabled. */
+	noColor: boolean;
+	/** Terminal advertises 24-bit color. */
+	trueColor: boolean;
+}
+
+/** Choose the richest color mode the environment robustly supports. */
+export function pickColorMode({ noColor, trueColor }: ColorModeInput): MermaidColorMode {
+	if (noColor) return "none";
+	return trueColor ? "truecolor" : "ansi256";
+}
+
+/**
+ * Complexity ceiling for mermaid sources. beautiful-mermaid's ASCII edge router
+ * (A* pathfinder) can allocate unbounded memory and hang for tens of seconds —
+ * then throw `RangeError: Out of memory` — on large/dense graphs. Callers should
+ * reject sources past this limit BEFORE rendering rather than attempt the layout.
+ */
+export const MERMAID_MAX_CHARS = 20000;
+export const MERMAID_MAX_LINES = 400;
+
+/** True when a mermaid source is too large to render safely (see limits above). */
+export function mermaidSourceExceedsLimit(source: string): boolean {
+	if (source.length > MERMAID_MAX_CHARS) return true;
+	let lines = 1;
+	for (let i = 0; i < source.length; i++) if (source.charCodeAt(i) === 10 && ++lines > MERMAID_MAX_LINES) return true;
+	return false;
+}
+
+export type MermaidDiagramType = "flowchart" | "sequence" | "class" | "er" | "state" | "xychart" | "unknown";
+
+/** Detect the diagram type from the first meaningful header line of mermaid source. */
+export function detectDiagramType(source: string): MermaidDiagramType {
+	for (const raw of source.split("\n")) {
+		const line = raw.trim();
+		// Skip blanks, YAML frontmatter fences, %%{init}%% directives, and %% comments.
+		if (line === "" || line === "---" || line.startsWith("%%")) continue;
+		// Skip frontmatter key/value lines (anything before we hit a known header).
+		if (/^(graph|flowchart)\b/.test(line)) return "flowchart";
+		if (/^sequenceDiagram\b/.test(line)) return "sequence";
+		if (/^classDiagram(-v2)?\b/.test(line)) return "class";
+		if (/^erDiagram\b/.test(line)) return "er";
+		if (/^stateDiagram(-v2)?\b/.test(line)) return "state";
+		if (/^xychart(-beta)?\b/.test(line)) return "xychart";
+		// A header-shaped token that isn't recognized → give up (avoid matching frontmatter values).
+		if (/^[A-Za-z]/.test(line) && !line.includes(":")) return "unknown";
+	}
+	return "unknown";
+}
+
+// ── per-node tint pass ──────────────────────────────────────────────────────
+
+interface Cell {
+	char: string;
+	/** Active foreground SGR sequence ("" = default). */
+	fg: string;
+}
+
+interface Rect {
+	top: number;
+	left: number;
+	bottom: number;
+	right: number;
+}
+
+const TL = new Set(["┌", "╭", "+"]);
+const isH = (ch: string): boolean => ch === "─" || ch === "-";
+const isV = (ch: string): boolean => ch === "│" || ch === "|";
+// Borders may carry an edge-attachment junction (a tee/cross) where an edge meets
+// the box; accept those so attached nodes are still detected and tinted.
+const isHBorder = (ch: string): boolean => isH(ch) || ch === "┬" || ch === "┴" || ch === "┼";
+const isVBorder = (ch: string): boolean => isV(ch) || ch === "├" || ch === "┤" || ch === "┼";
+
+/** Parse a colored line into per-visible-cell {char, fg}, tracking the active fg color. */
+function parseCells(line: string): Cell[] {
+	const cells: Cell[] = [];
+	let fg = "";
+	const re = /\x1b\[[0-9;]*m/g;
+	let last = 0;
+	for (let m = re.exec(line); m !== null; m = re.exec(line)) {
+		for (const ch of line.slice(last, m.index)) cells.push({ char: ch, fg });
+		fg = nextFg(fg, m[0]);
+		last = re.lastIndex;
+	}
+	for (const ch of line.slice(last)) cells.push({ char: ch, fg });
+	return cells;
+}
+
+/** Compute the new active fg from an SGR sequence (only fg-affecting codes matter). */
+function nextFg(prev: string, seq: string): string {
+	const params = seq.slice(2, -1); // strip ESC[ and trailing m
+	if (params === "" || params === "0") return "";
+	if (params.startsWith("38;2;") || params.startsWith("38;5;")) return seq;
+	if (params === "39") return "";
+	if (/^(3[0-7]|9[0-7])$/.test(params)) return seq;
+	return prev; // bold/underline/bg/etc. — leave fg unchanged
+}
+
+/** Locate a single rectangle whose top-left corner is at (r,c), or null. */
+function readRect(grid: string[][], r: number, c: number): Rect | null {
+	const tl = grid[r]?.[c];
+	if (tl === undefined || !TL.has(tl)) return null;
+	const ascii = tl === "+";
+	const trCh = ascii ? "+" : tl === "╭" ? "╮" : "┐";
+	const blCh = ascii ? "+" : tl === "╭" ? "╰" : "└";
+	const brCh = ascii ? "+" : tl === "╭" ? "╯" : "┘";
+
+	const row = grid[r]!;
+	let right = -1;
+	for (let x = c + 1; x < row.length; x++) {
+		const ch = row[x]!;
+		if (ch === trCh) {
+			right = x;
+			break;
+		}
+		if (!isHBorder(ch)) break;
+	}
+	if (right < c + 2) return null; // need interior width
+
+	let bottom = -1;
+	for (let y = r + 1; y < grid.length; y++) {
+		const ch = grid[y]?.[c];
+		if (ch === undefined) break;
+		if (ch === blCh) {
+			bottom = y;
+			break;
+		}
+		if (!isVBorder(ch)) break;
+	}
+	if (bottom < r + 2) return null; // need interior height
+
+	if (grid[bottom]?.[right] !== brCh) return null;
+	// Verify bottom edge and right edge (junctions where edges attach are allowed).
+	for (let x = c + 1; x < right; x++) if (!isHBorder(grid[bottom]?.[x] ?? "")) return null;
+	for (let y = r + 1; y < bottom; y++) if (!isVBorder(grid[y]?.[right] ?? "")) return null;
+
+	return { top: r, left: c, bottom, right };
+}
+
+function findRects(grid: string[][]): Rect[] {
+	const rects: Rect[] = [];
+	for (let r = 0; r < grid.length; r++) {
+		const row = grid[r]!;
+		for (let c = 0; c < row.length; c++) {
+			if (TL.has(row[c]!)) {
+				const rect = readRect(grid, r, c);
+				if (rect) rects.push(rect);
+			}
+		}
+	}
+	return rects;
+}
+
+function contains(a: Rect, b: Rect): boolean {
+	if (a === b) return false;
+	return a.top <= b.top && a.left <= b.left && a.bottom >= b.bottom && a.right >= b.right;
+}
+
+/**
+ * Tint each node box a cycled accent color. `coloredLines` is the role-colored
+ * mermaid render; `accentsAnsi` is a list of fg SGR escapes to cycle across nodes.
+ * Returns the input unchanged if no boxes are found or no accents are given.
+ */
+export function tintMermaidNodes(coloredLines: string[], accentsAnsi: string[]): string[] {
+	if (accentsAnsi.length === 0) return coloredLines;
+	try {
+		const rows = coloredLines.map(parseCells);
+		const grid = rows.map(cells => cells.map(cell => cell.char));
+		const rects = findRects(grid);
+		if (rects.length === 0) return coloredLines;
+
+		// Nodes are the innermost rectangles (a subgraph frame contains others → skip it).
+		const nodes = rects
+			.filter(rect => !rects.some(other => contains(rect, other)))
+			.sort((p, q) => p.top - q.top || p.left - q.left);
+		if (nodes.length === 0) return coloredLines;
+
+		// overrides: "r,c" → accent fg sequence.
+		const overrides = new Map<string, string>();
+		nodes.forEach((rect, i) => {
+			const accent = accentsAnsi[i % accentsAnsi.length]!;
+			for (let x = rect.left; x <= rect.right; x++) {
+				overrides.set(`${rect.top},${x}`, accent);
+				overrides.set(`${rect.bottom},${x}`, accent);
+			}
+			for (let y = rect.top; y <= rect.bottom; y++) {
+				overrides.set(`${y},${rect.left}`, accent);
+				overrides.set(`${y},${rect.right}`, accent);
+				for (let x = rect.left + 1; x < rect.right; x++) {
+					if ((grid[y]?.[x] ?? " ") !== " ") overrides.set(`${y},${x}`, accent);
+				}
+			}
+		});
+
+		return rows.map((cells, r) => {
+			const hasOverride = cells.some((_, c) => overrides.has(`${r},${c}`));
+			if (!hasOverride) return coloredLines[r]!;
+			let out = "";
+			let lastFg = "";
+			for (let c = 0; c < cells.length; c++) {
+				const cell = cells[c]!;
+				const fg = overrides.get(`${r},${c}`) ?? cell.fg;
+				if (fg !== lastFg) {
+					out += fg === "" ? "\x1b[39m" : fg;
+					lastFg = fg;
+				}
+				out += cell.char;
+			}
+			if (lastFg !== "") out += "\x1b[0m";
+			return out;
+		});
+	} catch {
+		return coloredLines;
+	}
+}

package/src/mime.ts

@@ -0,0 +1,159 @@
+import { peekFile, peekFileSync } from "./peek-file";
+
+const DEFAULT_IMAGE_METADATA_HEADER_BYTES = 256 * 1024;
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
+const WEBP_RIFF_MAGIC = Buffer.from([0x52, 0x49, 0x46, 0x46]);
+const WEBP_MAGIC = Buffer.from([0x57, 0x45, 0x42, 0x50]);
+const PNG_IHDR = Buffer.from("IHDR");
+const GIF87A = Buffer.from("GIF87a");
+const GIF89A = Buffer.from("GIF89a");
+const WEBP_VP8X = Buffer.from("VP8X");
+const WEBP_VP8L = Buffer.from("VP8L");
+const WEBP_VP8 = Buffer.from("VP8 ");
+
+export const SUPPORTED_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+
+export type ImageMetadata =
+	| { mimeType: "image/png"; width?: number; height?: number; channels?: number; hasAlpha?: boolean }
+	| { mimeType: "image/jpeg"; width?: number; height?: number; channels?: number; hasAlpha?: false }
+	| { mimeType: "image/gif"; width?: number; height?: number; channels?: 3; hasAlpha?: never }
+	| { mimeType: "image/webp"; width?: number; height?: number; channels?: number; hasAlpha?: boolean };
+
+function magicEquals(header: Uint8Array, offset: number, magic: Buffer): boolean {
+	if (header.length < offset + magic.length) {
+		return false;
+	}
+	return magic.equals(header.subarray(offset, offset + magic.length));
+}
+
+function parsePngMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, PNG_MAGIC)) return null;
+	if (!magicEquals(header, 12, PNG_IHDR)) return { mimeType: "image/png" };
+	if (header.length < 26) return { mimeType: "image/png" };
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	const width = view.getUint32(16, false);
+	const height = view.getUint32(20, false);
+	const colorType = view.getUint8(25);
+	if (colorType === 0) return { mimeType: "image/png", width, height, channels: 1, hasAlpha: false };
+	if (colorType === 2) return { mimeType: "image/png", width, height, channels: 3, hasAlpha: false };
+	if (colorType === 3) return { mimeType: "image/png", width, height, channels: 3 };
+	if (colorType === 4) return { mimeType: "image/png", width, height, channels: 2, hasAlpha: true };
+	if (colorType === 6) return { mimeType: "image/png", width, height, channels: 4, hasAlpha: true };
+	return { mimeType: "image/png", width, height };
+}
+
+function parseJpegMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, JPEG_MAGIC)) return null;
+	if (header.length < 4) return { mimeType: "image/jpeg" };
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	let offset = 2;
+	while (offset + 9 < header.length) {
+		if (header[offset] !== 0xff) {
+			offset += 1;
+			continue;
+		}
+
+		let markerOffset = offset + 1;
+		while (markerOffset < header.length && header[markerOffset] === 0xff) {
+			markerOffset += 1;
+		}
+		if (markerOffset >= header.length) break;
+
+		const marker = header[markerOffset];
+		const segmentOffset = markerOffset + 1;
+		if (marker === 0xd8 || marker === 0xd9 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+			offset = segmentOffset;
+			continue;
+		}
+		if (segmentOffset + 1 >= header.length) break;
+
+		const segmentLength = view.getUint16(segmentOffset, false);
+		if (segmentLength < 2) break;
+
+		const isStartOfFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+		if (isStartOfFrame) {
+			if (segmentOffset + 7 >= header.length) break;
+			const height = view.getUint16(segmentOffset + 3, false);
+			const width = view.getUint16(segmentOffset + 5, false);
+			const channels = header[segmentOffset + 7];
+			return {
+				mimeType: "image/jpeg",
+				width,
+				height,
+				channels: Number.isFinite(channels) ? channels : undefined,
+				hasAlpha: false,
+			};
+		}
+
+		offset = segmentOffset + segmentLength;
+	}
+
+	return { mimeType: "image/jpeg" };
+}
+
+function parseGifMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, GIF87A) && !magicEquals(header, 0, GIF89A)) return null;
+	if (header.length < 10) return { mimeType: "image/gif" };
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	return {
+		mimeType: "image/gif",
+		width: view.getUint16(6, true),
+		height: view.getUint16(8, true),
+		channels: 3,
+	};
+}
+
+function parseWebpMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, WEBP_RIFF_MAGIC)) return null;
+	if (!magicEquals(header, 8, WEBP_MAGIC)) return null;
+	if (header.length < 30) return { mimeType: "image/webp" };
+
+	if (magicEquals(header, 12, WEBP_VP8X)) {
+		const hasAlpha = (header[20] & 0x10) !== 0;
+		const width = (header[24] | (header[25] << 8) | (header[26] << 16)) + 1;
+		const height = (header[27] | (header[28] << 8) | (header[29] << 16)) + 1;
+		return { mimeType: "image/webp", width, height, channels: hasAlpha ? 4 : 3, hasAlpha };
+	}
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	if (magicEquals(header, 12, WEBP_VP8L)) {
+		if (header.length < 25) return { mimeType: "image/webp" };
+		const bits = view.getUint32(21, true);
+		const width = (bits & 0x3fff) + 1;
+		const height = ((bits >> 14) & 0x3fff) + 1;
+		const hasAlpha = ((bits >> 28) & 0x1) === 1;
+		return { mimeType: "image/webp", width, height, channels: hasAlpha ? 4 : 3, hasAlpha };
+	}
+
+	if (magicEquals(header, 12, WEBP_VP8)) {
+		const width = view.getUint16(26, true) & 0x3fff;
+		const height = view.getUint16(28, true) & 0x3fff;
+		return { mimeType: "image/webp", width, height, channels: 3, hasAlpha: false };
+	}
+
+	return { mimeType: "image/webp" };
+}
+
+export function parseImageMetadata(header: Uint8Array): ImageMetadata | null {
+	return (
+		parsePngMetadata(header) ?? parseJpegMetadata(header) ?? parseGifMetadata(header) ?? parseWebpMetadata(header)
+	);
+}
+
+export function readImageMetadataSync(
+	filePath: string,
+	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+): ImageMetadata | null {
+	return peekFileSync(filePath, maxBytes, parseImageMetadata);
+}
+
+export function readImageMetadata(
+	filePath: string,
+	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+): Promise<ImageMetadata | null> {
+	return peekFile(filePath, maxBytes, parseImageMetadata);
+}

package/src/models-yml.ts

@@ -0,0 +1,162 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDbPath } from "./dirs";
+
+/**
+ * Shared reader for `~/.xcsh/agent/models.yml`.
+ *
+ * Parses only the shape written by the LiteLLM auto-config:
+ *
+ *     providers:
+ *       <name>:
+ *         baseUrl: "https://..."
+ *         apiKey: ENV_VAR | "literal" | !shellSecret
+ *
+ * Consumers (anthropic-auth, auto-config) interpret the structured result
+ * and apply their own fallback / resolution policy.
+ */
+
+export type ApiKeyValue =
+	| { kind: "envVar"; name: string }
+	| { kind: "literal"; value: string; wasQuoted: boolean }
+	| { kind: "shellSecret"; raw: string };
+
+export interface ProviderYmlEntry {
+	baseUrl?: string;
+	apiKey?: ApiKeyValue;
+}
+
+/**
+ * Read a named provider block from models.yml.
+ * Returns null if the file is unreadable or the named block is absent.
+ *
+ * The parser pins two indent levels once it enters the `providers:` section:
+ *
+ *   - `providersChildIndent` — the column where provider names live. A line
+ *     only qualifies as a provider header when its indent matches this level,
+ *     so a nested `anthropic:` inside another provider's sub-map is ignored.
+ *   - `fieldIndent` — the column of the first key-value line inside the
+ *     target block. Only lines at exactly this indent are considered for
+ *     `baseUrl` / `apiKey`, so deeper nested maps (e.g. `discovery:`) cannot
+ *     leak values back into the target block.
+ */
+export function readProviderFromModelsYml(providerName: string, modelsYmlPath?: string): ProviderYmlEntry | null {
+	const resolvedPath = resolveModelsYmlPath(modelsYmlPath);
+	if (!resolvedPath) return null;
+
+	let content: string;
+	try {
+		content = fs.readFileSync(resolvedPath, "utf-8");
+	} catch {
+		return null;
+	}
+
+	const lines = content.split("\n");
+	const providerHeaderRe = new RegExp(`^\\s*${escapeRegex(providerName)}\\s*:\\s*$`);
+
+	let inProviders = false;
+	let providersChildIndent = -1;
+	let _providerIndent = -1;
+	let fieldIndent = -1;
+	let inTargetBlock = false;
+	let baseUrl: string | undefined;
+	let apiKey: ApiKeyValue | undefined;
+
+	for (const rawLine of lines) {
+		const line = rawLine.trimEnd();
+		if (line === "" || line.trimStart().startsWith("#")) continue;
+
+		const indent = line.length - line.trimStart().length;
+
+		if (indent === 0) {
+			inProviders = /^providers\s*:/.test(line);
+			inTargetBlock = false;
+			providersChildIndent = -1;
+			_providerIndent = -1;
+			fieldIndent = -1;
+			continue;
+		}
+
+		if (!inProviders) continue;
+
+		// First indented child fixes the provider-name indent level.
+		if (providersChildIndent === -1) providersChildIndent = indent;
+
+		// A line at the provider-name indent is always a provider header,
+		// and it ends the previous target block (if any).
+		if (indent === providersChildIndent) {
+			inTargetBlock = providerHeaderRe.test(line);
+			_providerIndent = inTargetBlock ? indent : -1;
+			fieldIndent = -1;
+			continue;
+		}
+
+		if (!inTargetBlock) continue;
+
+		// Pin field indent on the first in-block line; reject anything deeper.
+		if (fieldIndent === -1) fieldIndent = indent;
+		if (indent !== fieldIndent) continue;
+
+		const kvMatch = line.match(/^\s+(baseUrl|apiKey)\s*:\s*(.*)$/);
+		if (!kvMatch) continue;
+		const [, key, rawValue] = kvMatch;
+		const trimmed = rawValue.trim();
+
+		if (key === "baseUrl") {
+			baseUrl = stripQuotes(trimmed);
+		} else if (key === "apiKey") {
+			apiKey = parseApiKeyValue(trimmed);
+		}
+	}
+
+	if (baseUrl === undefined && apiKey === undefined) return null;
+	return { baseUrl, apiKey };
+}
+
+function resolveModelsYmlPath(explicit?: string): string | null {
+	if (explicit) return explicit;
+	try {
+		return path.join(path.dirname(getAgentDbPath()), "models.yml");
+	} catch {
+		return null;
+	}
+}
+
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stripQuotes(s: string): string {
+	if (s.length >= 2) {
+		const first = s[0];
+		const last = s[s.length - 1];
+		if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+			return s.slice(1, -1);
+		}
+	}
+	return s;
+}
+
+/**
+ * Env-var reference heuristic: all-caps identifier with at least one
+ * underscore. The underscore requirement is what distinguishes a reference
+ * like `LITELLM_API_KEY` from a hand-edited unquoted literal such as
+ * `SK12345`, which would otherwise be silently resolved via `process.env`
+ * and almost always come back undefined.
+ */
+function looksLikeEnvVarName(s: string): boolean {
+	return /^[A-Z][A-Z0-9_]*$/.test(s) && s.includes("_");
+}
+
+function parseApiKeyValue(raw: string): ApiKeyValue {
+	if (raw.startsWith("!")) return { kind: "shellSecret", raw };
+	if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+		const inner = raw.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+		return { kind: "literal", value: inner, wasQuoted: true };
+	}
+	if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) {
+		return { kind: "literal", value: raw.slice(1, -1), wasQuoted: true };
+	}
+	if (looksLikeEnvVarName(raw)) return { kind: "envVar", name: raw };
+	return { kind: "literal", value: raw, wasQuoted: false };
+}

package/src/peek-file.ts

@@ -0,0 +1,114 @@
+/**
+ * Read the first `maxBytes` of a file (offset 0) and pass that slice to `op`.
+ *
+ * Buffers are reused to avoid allocating on every peek: sync uses one growable
+ * `Uint8Array`; async uses a small fixed pool of `Buffer`s with a bounded wait
+ * queue, falling back to a fresh allocation when the pool and queue are saturated
+ * or when `maxBytes` exceeds the pool slot size.
+ */
+import * as fs from "node:fs";
+
+/** Async pool slot size; larger peeks allocate ad hoc. */
+const POOLED_BUFFER_SIZE = 512;
+const ASYNC_POOL_SIZE = 10;
+/** Cap waiter queue so heavy concurrency does not queue unbounded; overflow uses alloc. */
+const MAX_ASYNC_WAITERS = 4;
+const INITIAL_SYNC_BUFFER_SIZE = 1024;
+const EMPTY_BUFFER = Buffer.alloc(0);
+
+const asyncPool = Array.from({ length: ASYNC_POOL_SIZE }, () => Buffer.allocUnsafe(POOLED_BUFFER_SIZE));
+const availableAsyncPoolIndexes = Array.from({ length: ASYNC_POOL_SIZE }, (_, index) => index);
+const asyncPoolWaiters: Array<(index: number) => void> = [];
+let syncPool = new Uint8Array(INITIAL_SYNC_BUFFER_SIZE);
+
+/** Returns a pool slot index, or `-1` when the caller should use a standalone buffer. */
+function acquireAsyncPoolIndex(): Promise<number> | number {
+	const index = availableAsyncPoolIndexes.pop();
+	if (index !== undefined) {
+		return index;
+	}
+	if (asyncPoolWaiters.length >= MAX_ASYNC_WAITERS) {
+		return -1;
+	}
+	const { promise, resolve } = Promise.withResolvers<number>();
+	asyncPoolWaiters.push(resolve);
+	return promise;
+}
+
+function releaseAsyncPoolIndex(index: number): void {
+	if (index < 0) {
+		return;
+	}
+	const waiter = asyncPoolWaiters.shift();
+	if (waiter) {
+		waiter(index);
+		return;
+	}
+	availableAsyncPoolIndexes.push(index);
+}
+
+async function withAsyncPoolBuffer<T>(maxBytes: number, op: (buffer: Buffer) => Promise<T>): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+	if (maxBytes > POOLED_BUFFER_SIZE) {
+		return op(Buffer.allocUnsafe(maxBytes));
+	}
+
+	const poolIndex = await acquireAsyncPoolIndex();
+	const buffer = poolIndex >= 0 ? asyncPool[poolIndex] : Buffer.allocUnsafe(maxBytes);
+	try {
+		return await op(buffer.subarray(0, maxBytes));
+	} finally {
+		releaseAsyncPoolIndex(poolIndex);
+	}
+}
+
+function withSyncPoolBuffer<T>(maxBytes: number, op: (buffer: Uint8Array) => T): T {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+	if (maxBytes > syncPool.byteLength) {
+		syncPool = new Uint8Array(maxBytes + (maxBytes >> 1));
+	}
+	return op(syncPool.subarray(0, maxBytes));
+}
+
+/**
+ * Synchronously reads up to `maxBytes` from the start of `filePath` and returns `op(header)`.
+ * If the file is shorter, `header` is only the bytes actually read.
+ */
+export function peekFileSync<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): T {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = fs.openSync(filePath, "r");
+	try {
+		return withSyncPoolBuffer(maxBytes, buffer => {
+			const bytesRead = fs.readSync(fileHandle, buffer, 0, buffer.byteLength, 0);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		fs.closeSync(fileHandle);
+	}
+}
+
+/**
+ * Like {@link peekFileSync} but uses async I/O.
+ */
+export async function peekFile<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = await fs.promises.open(filePath, "r");
+	try {
+		return await withAsyncPoolBuffer(maxBytes, async buffer => {
+			const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, 0);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		await fileHandle.close();
+	}
+}