@oh-my-pi/pi-coding-agent 17.2.11 → 17.2.12

package/src/tools/read-pdf-images.ts

@@ -0,0 +1,250 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { isEexist, isEnotempty, readImageMetadata, untilAborted } from "@oh-my-pi/pi-utils";
+import type { ToolSession } from "../sdk";
+import { loadImageInput, MAX_IMAGE_INPUT_BYTES, webpExclusionForModel } from "../utils/image-loading";
+import { convertFileWithMarkit } from "../utils/markit";
+import type { ReadToolDetails } from "./read";
+import { prependSuffixResolutionNotice } from "./read-format";
+import { isNotFoundError } from "./read-path-resolution";
+import { formatBytes } from "./render-utils";
+import { ToolError } from "./tool-errors";
+import { toolResult } from "./tool-result";
+
+const MAX_IMAGE_SIZE = MAX_IMAGE_INPUT_BYTES;
+
+const PDF_IMAGE_PLACEHOLDER_RE = /<!--\s*image:\s*([^\s<>]+)(.*?)-->/g;
+const PDF_IMAGE_MEMBER_RE = /^(.*\.pdf):(.*)$/i;
+const PDF_IMAGE_MEMBER_EXTENSION_RE = /\.png$/i;
+const PDF_IMAGE_CACHE_BASENAME_MAX_LENGTH = 96;
+
+interface PdfImageSnapshot {
+	directory: string;
+	filePath: string;
+	digest: string;
+}
+
+interface PdfImageExtraction {
+	controller: AbortController;
+	promise: Promise<string>;
+	settled: boolean;
+	waiters: number;
+}
+
+const pdfImageExtractions = new Map<string, PdfImageExtraction>();
+
+function pdfImageMemberPath(pdfPath: string, imageId: string): string {
+	const member = PDF_IMAGE_MEMBER_EXTENSION_RE.test(imageId) ? imageId : `${imageId}.png`;
+	return `${pdfPath}:${member}`;
+}
+
+export function rewritePdfImagePlaceholders(markdown: string, pdfPath: string): string {
+	return markdown.replace(PDF_IMAGE_PLACEHOLDER_RE, (_match: string, imageId: string, metadataText: string) => {
+		const metadata = metadataText.trim();
+		const suffix = metadata.length > 0 ? ` (${metadata})` : "";
+		return `Image ${imageId}${suffix}: read \`${pdfImageMemberPath(pdfPath, imageId)}\``;
+	});
+}
+
+export function splitPdfImageMemberReadPath(readPath: string): { pdfPath: string; member: string } | null {
+	const match = PDF_IMAGE_MEMBER_RE.exec(readPath);
+	if (!match) return null;
+	const pdfPath = match[1];
+	const member = match[2];
+	if (pdfPath === undefined || member === undefined) return null;
+	if (member.length !== 0 && !PDF_IMAGE_MEMBER_EXTENSION_RE.test(member)) return null;
+	return { pdfPath, member };
+}
+function pdfImageCacheDir(session: ToolSession, absolutePdfPath: string, contentDigest: string): string {
+	const artifactsDir = session.getArtifactsDir?.();
+	let root = artifactsDir ?? undefined;
+	if (root === undefined) {
+		const sessionFile = session.getSessionFile();
+		root = sessionFile?.endsWith(".jsonl") ? sessionFile.slice(0, -6) : path.join(os.tmpdir(), "omp-read-pdf-images");
+	}
+	const basename = path
+		.basename(absolutePdfPath)
+		.replace(/[^A-Za-z0-9._-]/g, "_")
+		.slice(0, PDF_IMAGE_CACHE_BASENAME_MAX_LENGTH);
+	const pathDigest = Bun.hash(absolutePdfPath).toString(36);
+	return path.join(root, "read-pdf-images", `${basename}-${pathDigest}-${contentDigest}`);
+}
+
+async function snapshotPdfSource(absolutePdfPath: string, signal?: AbortSignal): Promise<PdfImageSnapshot> {
+	const directory = await fs.mkdtemp(path.join(os.tmpdir(), "omp-read-pdf-"));
+	try {
+		const bytes = await untilAborted(signal, () => Bun.file(absolutePdfPath).bytes());
+		signal?.throwIfAborted();
+		const digest = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+		const filePath = path.join(directory, "source.pdf");
+		await Bun.write(filePath, bytes);
+		signal?.throwIfAborted();
+		return { directory, filePath, digest };
+	} catch (error) {
+		await fs.rm(directory, { recursive: true, force: true });
+		throw error;
+	}
+}
+
+async function listPdfImageMembers(imageDir: string): Promise<string[]> {
+	try {
+		const entries = await fs.readdir(imageDir, { withFileTypes: true });
+		const members: string[] = [];
+		for (const entry of entries) {
+			if (entry.isFile() && PDF_IMAGE_MEMBER_EXTENSION_RE.test(entry.name)) members.push(entry.name);
+		}
+		return members.sort();
+	} catch (error) {
+		if (isNotFoundError(error)) return [];
+		throw error;
+	}
+}
+
+async function extractPdfImages(snapshot: PdfImageSnapshot, imageDir: string, signal: AbortSignal): Promise<string> {
+	const markerPath = path.join(imageDir, ".extracted");
+	try {
+		await fs.stat(markerPath);
+		return imageDir;
+	} catch (error) {
+		if (!isNotFoundError(error)) throw error;
+	}
+
+	await fs.mkdir(path.dirname(imageDir), { recursive: true });
+	const stagingDir = await fs.mkdtemp(`${imageDir}.tmp-`);
+	let published = false;
+	try {
+		const result = await convertFileWithMarkit(snapshot.filePath, signal, { imageDir: stagingDir });
+		if (!result.ok) {
+			throw new ToolError(`Cannot extract images from PDF: ${result.error ?? "conversion failed"}`);
+		}
+		await Bun.write(path.join(stagingDir, ".extracted"), "ok");
+		try {
+			await fs.rename(stagingDir, imageDir);
+			published = true;
+		} catch (error) {
+			if (!isEexist(error) && !isEnotempty(error)) throw error;
+			try {
+				await fs.stat(markerPath);
+			} catch (markerError) {
+				if (isNotFoundError(markerError)) throw error;
+				throw markerError;
+			}
+		}
+		return imageDir;
+	} finally {
+		if (!published) await fs.rm(stagingDir, { recursive: true, force: true });
+	}
+}
+
+function createPdfImageExtraction(snapshot: PdfImageSnapshot, imageDir: string): PdfImageExtraction {
+	const controller = new AbortController();
+	const promise = extractPdfImages(snapshot, imageDir, controller.signal).finally(() =>
+		fs.rm(snapshot.directory, { recursive: true, force: true }),
+	);
+	const extraction: PdfImageExtraction = { controller, promise, settled: false, waiters: 0 };
+	const settle = () => {
+		extraction.settled = true;
+		if (pdfImageExtractions.get(imageDir) === extraction) pdfImageExtractions.delete(imageDir);
+	};
+	void promise.then(settle, settle);
+	return extraction;
+}
+
+async function waitForPdfImageExtraction(
+	extraction: PdfImageExtraction,
+	signal: AbortSignal | undefined,
+): Promise<string> {
+	extraction.waiters++;
+	try {
+		return await untilAborted(signal, extraction.promise);
+	} finally {
+		extraction.waiters--;
+		if (extraction.waiters === 0 && !extraction.settled) {
+			extraction.controller.abort();
+			try {
+				await extraction.promise;
+			} catch {}
+		}
+	}
+}
+
+async function ensurePdfImageCache(
+	session: ToolSession,
+	absolutePdfPath: string,
+	signal?: AbortSignal,
+): Promise<string> {
+	const snapshot = await snapshotPdfSource(absolutePdfPath, signal);
+	const imageDir = pdfImageCacheDir(session, absolutePdfPath, snapshot.digest);
+	const existing = pdfImageExtractions.get(imageDir);
+	if (existing && !existing.settled && !existing.controller.signal.aborted) {
+		await fs.rm(snapshot.directory, { recursive: true, force: true });
+		return waitForPdfImageExtraction(existing, signal);
+	}
+
+	const extraction = createPdfImageExtraction(snapshot, imageDir);
+	pdfImageExtractions.set(imageDir, extraction);
+	return waitForPdfImageExtraction(extraction, signal);
+}
+
+export async function readPdfImageMember(
+	session: ToolSession,
+	autoResizeImages: boolean,
+	absolutePdfPath: string,
+	pdfDisplayPath: string,
+	member: string,
+	suffixResolution: { from: string; to: string } | undefined,
+	signal?: AbortSignal,
+): Promise<AgentToolResult<ReadToolDetails>> {
+	const imageDir = await ensurePdfImageCache(session, absolutePdfPath, signal);
+	const members = await listPdfImageMembers(imageDir);
+	if (member.length === 0) {
+		const text =
+			members.length === 0
+				? "No extractable PDF image members found."
+				: `Extractable PDF image members:\n${members
+						.map(imageMember => `- read \`${pdfDisplayPath}:${imageMember}\``)
+						.join("\n")}`;
+		return toolResult<ReadToolDetails>({ resolvedPath: absolutePdfPath, suffixResolution })
+			.text(prependSuffixResolutionNotice(text, suffixResolution))
+			.sourcePath(absolutePdfPath)
+			.done();
+	}
+
+	if (!members.includes(member)) {
+		const available = members.length === 0 ? "(none)" : members.join(", ");
+		throw new ToolError(`PDF image member '${member}' not found. Available members: ${available}`);
+	}
+
+	const imagePath = path.join(imageDir, member);
+	const imageStat = await Bun.file(imagePath).stat();
+	if (imageStat.size > MAX_IMAGE_SIZE) {
+		const sizeStr = formatBytes(imageStat.size);
+		const maxStr = formatBytes(MAX_IMAGE_SIZE);
+		throw new ToolError(`Image file too large: ${sizeStr} exceeds ${maxStr} limit.`);
+	}
+	const metadata = await readImageMetadata(imagePath);
+	const mimeType = metadata?.mimeType;
+	if (!mimeType) throw new ToolError(`PDF image member '${member}' is not a supported image.`);
+	const imageInput = await loadImageInput({
+		path: `${pdfDisplayPath}:${member}`,
+		cwd: session.cwd,
+		autoResize: autoResizeImages,
+		maxBytes: MAX_IMAGE_SIZE,
+		resolvedPath: imagePath,
+		detectedMimeType: mimeType,
+		excludeWebP: webpExclusionForModel(session.getActiveModel?.()),
+	});
+	if (!imageInput) {
+		throw new ToolError(`Read image file [${mimeType}] failed: unsupported image format.`);
+	}
+	const textNote = prependSuffixResolutionNotice(imageInput.textNote, suffixResolution);
+	return toolResult<ReadToolDetails>({ resolvedPath: absolutePdfPath, suffixResolution })
+		.content([
+			{ type: "text", text: textNote },
+			{ type: "image", data: imageInput.data, mimeType: imageInput.mimeType },
+		])
+		.sourcePath(imageInput.resolvedPath)
+		.done();
+}

package/src/tools/read-renderer.ts

@@ -0,0 +1,289 @@
+import * as path from "node:path";
+import type { Component } from "@oh-my-pi/pi-tui";
+import { Text } from "@oh-my-pi/pi-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
+import { fileHyperlink, renderCodeCell, renderMarkdownCell, renderStatusLine, tryResolveInternalUrlSync } from "../tui";
+import { CachedOutputBlock, markFramedBlockComponent } from "../tui/output-block";
+import { type ReadUrlToolDetails, renderReadUrlCall, renderReadUrlResult } from "./fetch";
+import { formatFullOutputReference, formatStyledTruncationWarning, stripOutputNotice } from "./output-meta";
+import { isReadableUrlPath, splitInternalUrlSel, splitPathAndSel } from "./path-utils";
+import type { ReadToolDetails } from "./read";
+import { isRawSelector, parseSel } from "./read-selector";
+import { formatBytes, replaceTabs, shortenPath, wrapBrackets } from "./render-utils";
+
+// =============================================================================
+// TUI Renderer
+// =============================================================================
+
+interface ReadRenderArgs {
+	path?: unknown;
+	file_path?: unknown;
+	// Legacy fields from old schema — tolerated for in-flight tool calls during transition
+	offset?: number;
+	limit?: number;
+	raw?: boolean;
+}
+
+const INTERNAL_URL_LIKE_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+function splitReadRenderPath(rawPath: string): { path: string; sel?: string } {
+	if (INTERNAL_URL_LIKE_RE.test(rawPath)) {
+		const internal = splitInternalUrlSel(rawPath);
+		if (internal.sel) return internal;
+	}
+	return splitPathAndSel(rawPath);
+}
+
+function firstReadSelectorLine(sel: string | undefined): number | undefined {
+	if (!sel) return undefined;
+	try {
+		const parsed = parseSel(sel);
+		if (parsed.kind !== "lines") return undefined;
+		return parsed.ranges[0].startLine;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Absolute fs path the read result actually resolved to, used as the OSC 8 link
+ * target when the structured `resolvedPath` isn't set (the common plain-file and
+ * image reads only record the path in `meta.source`). URL/internal sources are
+ * not fs paths, so only `type: "path"` qualifies. */
+function readSourceFsPath(details: ReadToolDetails | undefined): string | undefined {
+	const source = details?.meta?.source;
+	return source?.type === "path" ? source.value : undefined;
+}
+
+function formatReadPathLink(
+	rawPath: string,
+	options: {
+		resolvedPath?: string;
+		sourcePath?: string;
+		suffixResolution?: { from: string; to: string };
+		offset?: number;
+		fallbackLabel?: string;
+	},
+): string {
+	const split = splitReadRenderPath(rawPath);
+	const basePath = split.path || rawPath;
+	const selectorSuffix = split.sel ? `:${split.sel}` : "";
+	const plainDisplayPath = options.suffixResolution
+		? shortenPath(options.suffixResolution.to)
+		: shortenPath(basePath || options.resolvedPath || options.fallbackLabel || rawPath);
+	const absoluteInputPath = path.isAbsolute(basePath) ? basePath : undefined;
+	const target =
+		options.resolvedPath ?? options.sourcePath ?? tryResolveInternalUrlSync(basePath) ?? absoluteInputPath;
+	const line = firstReadSelectorLine(split.sel) ?? options.offset;
+	const linkOptions = line !== undefined ? { line } : undefined;
+	const linkedPath = target ? fileHyperlink(target, plainDisplayPath, linkOptions) : plainDisplayPath;
+	return `${linkedPath}${selectorSuffix}`;
+}
+
+export const readToolRenderer = {
+	renderCall(args: ReadRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const rawPath =
+			typeof args.file_path === "string" ? args.file_path : typeof args.path === "string" ? args.path : "";
+		if (isReadableUrlPath(rawPath)) {
+			return renderReadUrlCall({ path: rawPath, raw: args.raw }, _options, uiTheme);
+		}
+
+		const offset = args.offset;
+		const limit = args.limit;
+
+		let pathDisplay = formatReadPathLink(rawPath, { offset, fallbackLabel: "…" }) || "…";
+		if (offset !== undefined || limit !== undefined) {
+			const startLine = offset ?? 1;
+			const endLine = limit !== undefined ? startLine + limit - 1 : "";
+			pathDisplay += `:${startLine}${endLine ? `-${endLine}` : ""}`;
+		}
+
+		const text = renderStatusLine({ icon: "pending", title: "Read", description: pathDisplay }, uiTheme);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: ReadToolDetails; isError?: boolean },
+		options: RenderResultOptions,
+		uiTheme: Theme,
+		args?: ReadRenderArgs,
+	): Component {
+		const urlDetails = result.details as ReadUrlToolDetails | undefined;
+		const baseRawPathForKind =
+			typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
+		if (urlDetails?.kind === "url" || isReadableUrlPath(baseRawPathForKind)) {
+			return renderReadUrlResult(
+				result as {
+					content: Array<{ type: string; text?: string }>;
+					details?: ReadUrlToolDetails;
+					isError?: boolean;
+				},
+				options,
+				uiTheme,
+			);
+		}
+
+		if (result.isError) {
+			const rawErrorText = result.content?.find(c => c.type === "text")?.text ?? "";
+			const errorText = (rawErrorText || "Unknown error").replace(/^Error:\s*/, "");
+			const rawPath =
+				typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
+			const filePath =
+				formatReadPathLink(rawPath, { offset: args?.offset, sourcePath: readSourceFsPath(result.details) }) ||
+				shortenPath(rawPath);
+			let title = filePath ? `Read ${filePath}` : "Read";
+			if (args?.offset !== undefined || args?.limit !== undefined) {
+				const startLine = args.offset ?? 1;
+				const endLine = args.limit !== undefined ? startLine + args.limit - 1 : "";
+				title += `:${startLine}${endLine ? `-${endLine}` : ""}`;
+			}
+			const header = renderStatusLine({ icon: "error", title }, uiTheme);
+			const errorLines = errorText.split("\n").map(line => uiTheme.fg("error", replaceTabs(line)));
+			const outputBlock = new CachedOutputBlock();
+			return markFramedBlockComponent({
+				render: (width: number) =>
+					outputBlock.render({ header, state: "error", sections: [{ lines: errorLines }], width }, uiTheme),
+				invalidate: () => outputBlock.invalidate(),
+			});
+		}
+		const details = result.details;
+		const rawText = result.content?.find(c => c.type === "text")?.text ?? "";
+		// Prefer structured `displayContent` from details when available so the TUI
+		// shows clean file content (no model-only hashline anchors) without parsing the formatted text.
+		// Fall back to the raw text, but strip the LLM-facing notice so it doesn't
+		// echo next to the styled warning line below.
+		const contentText = details?.displayContent?.text ?? stripOutputNotice(rawText, details?.meta);
+		const imageContent = result.content?.find(c => c.type === "image");
+		const rawPath =
+			typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
+		const renderPath = splitReadRenderPath(rawPath);
+		const lang = getLanguageFromPath(renderPath.path);
+
+		const warningLines: string[] = [];
+		const truncation = details?.meta?.truncation;
+		const fallback = details?.truncation;
+		if (details?.resolvedPath) {
+			warningLines.push(uiTheme.fg("dim", wrapBrackets(`Resolved path: ${details.resolvedPath}`, uiTheme)));
+		}
+		if (truncation) {
+			if (fallback?.firstLineExceedsLimit) {
+				let warning = `First line exceeds ${formatBytes(fallback.outputBytes ?? fallback.totalBytes)} limit`;
+				if (truncation.artifactId) {
+					warning += `. ${formatFullOutputReference(truncation.artifactId)}`;
+				}
+				warningLines.push(uiTheme.fg("warning", wrapBrackets(warning, uiTheme)));
+			} else {
+				const warning = formatStyledTruncationWarning(details?.meta, uiTheme);
+				if (warning) warningLines.push(warning);
+			}
+		}
+
+		if (imageContent) {
+			const suffix = details?.suffixResolution;
+			const displayPath = formatReadPathLink(rawPath, {
+				resolvedPath: details?.resolvedPath,
+				sourcePath: readSourceFsPath(details),
+				suffixResolution: suffix,
+				fallbackLabel: "image",
+			});
+			const correction = suffix ? ` ${uiTheme.fg("dim", `(corrected from ${shortenPath(suffix.from)})`)}` : "";
+			const header = renderStatusLine(
+				{ icon: suffix ? "warning" : "success", title: "Read", description: `${displayPath}${correction}` },
+				uiTheme,
+			);
+			const detailLines = contentText ? contentText.split("\n").map(line => uiTheme.fg("toolOutput", line)) : [];
+			const lines = [...detailLines, ...warningLines];
+			const outputBlock = new CachedOutputBlock();
+			return markFramedBlockComponent({
+				render: (width: number) =>
+					outputBlock.render(
+						{
+							header,
+							state: "success",
+							sections: [
+								{
+									label: uiTheme.fg("toolTitle", "Details"),
+									lines: lines.length > 0 ? lines : [uiTheme.fg("dim", "(image)")],
+								},
+							],
+							width,
+						},
+						uiTheme,
+					),
+				invalidate: () => outputBlock.invalidate(),
+			});
+		}
+
+		const suffix = details?.suffixResolution;
+		// resolvedPath is the absolute fs path when a read resolved/corrected the
+		// input (suffix match, internal URL, archive/sqlite/notebook); plain file
+		// reads only record the absolute path in meta.source, so fall back to that
+		// (and then to a sync internal-URL resolver) to keep the title clickable.
+		const displayPath = formatReadPathLink(rawPath, {
+			resolvedPath: details?.resolvedPath,
+			sourcePath: readSourceFsPath(details),
+			suffixResolution: suffix,
+			offset: args?.offset,
+		});
+		const correction = suffix ? ` ${uiTheme.fg("dim", `(corrected from ${shortenPath(suffix.from)})`)}` : "";
+		let title = displayPath ? `Read ${displayPath}${correction}` : "Read";
+		if (args?.offset !== undefined || args?.limit !== undefined) {
+			const startLine = args.offset ?? 1;
+			const endLine = args.limit !== undefined ? startLine + args.limit - 1 : "";
+			title += `:${startLine}${endLine ? `-${endLine}` : ""}`;
+		}
+		if (details?.summary) {
+			title += ` (summary: ${details.summary.elidedSpans} elided span${details.summary.elidedSpans === 1 ? "" : "s"})`;
+		}
+		if (details?.conflictCount && details.conflictCount > 0) {
+			const n = details.conflictCount;
+			title += ` ${uiTheme.fg("warning", `(⚠ ${n} conflict${n === 1 ? "" : "s"})`)}`;
+		}
+		const rawRequested = args?.raw === true || isRawSelector(parseSel(renderPath.sel));
+		const isMarkdown = details?.contentType === "text/markdown" && !rawRequested;
+		let cachedWidth: number | undefined;
+		let cachedExpanded: boolean | undefined;
+		let cachedLines: string[] | undefined;
+		return markFramedBlockComponent({
+			render: (width: number) => {
+				const expanded = options.expanded;
+				if (cachedLines && cachedWidth === width && cachedExpanded === expanded) return cachedLines;
+				cachedLines = isMarkdown
+					? renderMarkdownCell(
+							{
+								content: contentText,
+								title,
+								status: "complete",
+								output: warningLines.length > 0 ? warningLines.join("\n") : undefined,
+								expanded,
+								width,
+							},
+							uiTheme,
+						)
+					: renderCodeCell(
+							{
+								code: contentText,
+								language: lang,
+								title,
+								status: "complete",
+								output: warningLines.length > 0 ? warningLines.join("\n") : undefined,
+								expanded,
+								codeStartLine: details?.displayContent?.startLine,
+								codeLineNumbers: details?.displayContent?.lineNumbers,
+								width,
+							},
+							uiTheme,
+						);
+				cachedWidth = width;
+				cachedExpanded = expanded;
+				return cachedLines;
+			},
+			invalidate: () => {
+				cachedWidth = undefined;
+				cachedExpanded = undefined;
+				cachedLines = undefined;
+			},
+		});
+	},
+	mergeCallAndResult: true,
+};

package/src/tools/read-selector.ts

@@ -0,0 +1,84 @@
+import type { LineRange } from "./path-utils";
+import { parseLineRanges } from "./path-utils";
+import { ToolError } from "./tool-errors";
+/** Parsed representation of a path-embedded selector. */
+export type ParsedSelector =
+	| { kind: "none" }
+	| { kind: "raw" }
+	| { kind: "conflicts" }
+	| { kind: "lines"; ranges: [LineRange, ...LineRange[]]; raw?: boolean };
+
+/** Returns true when the selector requested verbatim/raw output (alone or combined with a range). */
+export function isRawSelector(parsed: ParsedSelector): boolean {
+	return parsed.kind === "raw" || (parsed.kind === "lines" && parsed.raw === true);
+}
+
+/** Returns true when the selector requested multiple line ranges. */
+export function isMultiRange(parsed: ParsedSelector): boolean {
+	return parsed.kind === "lines" && parsed.ranges.length > 1;
+}
+
+function selectorChunkLooksReadLike(chunk: string): boolean {
+	const lower = chunk.toLowerCase();
+	return (
+		lower === "raw" || lower === "conflicts" || /^-\d+(?:[-+]\d+)?$/.test(chunk) || parseLineRanges(chunk) !== null
+	);
+}
+
+function invalidSelector(sel: string): ToolError {
+	return new ToolError(
+		`Invalid selector ':${sel}'. Use :N, :N-M, :N+K, :N- (open-ended), a comma-separated list of ranges, :raw, or a range combined with raw (e.g. :raw:50-100).`,
+	);
+}
+
+export function parseSel(sel: string | undefined): ParsedSelector {
+	if (!sel || sel.length === 0) return { kind: "none" };
+
+	// Compound selector: `1-50:raw` or `raw:1-50`. Split into chunks and accept
+	// exactly one line range (possibly multi) plus the literal `raw`. Selector-like
+	// compounds that are not in that accepted set are invalid rather than "none";
+	// otherwise `read` can silently widen a malformed selector like
+	// `artifact://5:conflicts:1-1` while `grep` rejects it.
+	if (sel.includes(":")) {
+		const chunks = sel.split(":");
+		if (chunks.length === 2) {
+			const [a, b] = chunks as [string, string];
+			const aIsRaw = a.toLowerCase() === "raw";
+			const bIsRaw = b.toLowerCase() === "raw";
+			const rangeChunk = aIsRaw ? b : bIsRaw ? a : null;
+			const rawChunk = aIsRaw ? a : bIsRaw ? b : null;
+			if (rangeChunk !== null && rawChunk !== null) {
+				const ranges = parseLineRanges(rangeChunk);
+				if (ranges) {
+					return { kind: "lines", ranges, raw: true };
+				}
+			}
+		}
+		if (chunks.every(selectorChunkLooksReadLike)) throw invalidSelector(sel);
+		// Unrecognized compound — fall through (sqlite/archive/url consume their own colon syntax).
+		return { kind: "none" };
+	}
+
+	if (sel.toLowerCase() === "raw") return { kind: "raw" };
+	if (sel.toLowerCase() === "conflicts") return { kind: "conflicts" };
+	const ranges = parseLineRanges(sel);
+	if (ranges) {
+		return { kind: "lines", ranges };
+	}
+	// Unrecognized selectors fall through; sqlite/archive/url readers consume their own colon syntax.
+	return { kind: "none" };
+}
+
+/**
+ * Convert a single-range selector to the offset/limit pair used by internal pagination.
+ * Returns the FIRST range only — multi-range callers MUST branch on `isMultiRange` before
+ * calling this helper.
+ */
+export function selToOffsetLimit(parsed: ParsedSelector): { offset?: number; limit?: number } {
+	if (parsed.kind === "lines") {
+		const first = parsed.ranges[0];
+		const limit = first.endLine !== undefined ? first.endLine - first.startLine + 1 : undefined;
+		return { offset: first.startLine, limit };
+	}
+	return {};
+}