@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/work/src/document-reader/index.ts

@@ -0,0 +1,181 @@
+/**
+ * Bounded PDF/Office literal-text extraction adapter for the Prism coding
+ * read tool (plan 018 closeout `doc-reader`).
+ *
+ * Explicit activation only: the host wires the returned {@link DocumentReader}
+ * into `createReadTool({ documentReader })`; no file-extension sniffing ever
+ * enables parsing. Bounds live here (input bytes, pages, output text bytes);
+ * parsing is delegated to optional peer libraries (`pdf-parse`, `mammoth`)
+ * that fail closed at creation when absent. Literal text only — no embedded
+ * script execution, no macro evaluation, no external resource fetching.
+ */
+
+import type { SecretRedactor } from "@arnilo/prism";
+import { reviveWorkerTaskError, runInPool, shouldOffloadToPool } from "../runtime/worker-pool.js";
+import { DocumentReaderError } from "./errors.js";
+import { createDocxParser, createOoxmlParser, createPdfParser } from "./parsers.js";
+
+export { createDocxParser, createOoxmlParser, createPdfParser } from "./parsers.js";
+export { DocumentReaderError };
+
+/** Structural reader contract accepted by coding-tools' host injection seam. */
+export interface DocumentReader {
+  readonly maxInputBytes: number;
+  readonly maxTextBytes: number;
+  extract(input: {
+    readonly buffer: Uint8Array;
+    readonly path: string;
+    readonly signal?: AbortSignal;
+  }): Promise<DocumentReaderResult | null>;
+}
+
+export interface DocumentReaderResult {
+  readonly text: string;
+  readonly format: string;
+  readonly pages: number;
+  readonly truncatedBy: "pages" | "bytes" | null;
+  readonly pageSpans?: readonly { readonly page: number; readonly start: number; readonly end: number }[];
+}
+
+// --- caps (module-local; additive package, no shared limits surface) ---
+
+export const DEFAULT_MAX_DOCUMENT_BYTES = 32 * 1024 * 1024;
+export const HARD_MAX_DOCUMENT_BYTES = 512 * 1024 * 1024;
+export const DEFAULT_MAX_DOCUMENT_PAGES = 1000;
+export const HARD_MAX_DOCUMENT_PAGES = 10_000;
+export const DEFAULT_MAX_DOCUMENT_TEXT_BYTES = 2 * 1024 * 1024;
+export const HARD_MAX_DOCUMENT_TEXT_BYTES = 64 * 1024 * 1024;
+
+function validateCap(name: string, value: number, hard: number): number {
+  if (!Number.isInteger(value) || value <= 0 || value > hard) {
+    throw new RangeError(`document-reader ${name} must be an integer in (0, ${hard}], got ${value}`);
+  }
+  return value;
+}
+
+/** Host-selected per-format parser implementation. */
+export interface DocumentParser {
+  readonly format: string;
+  /**
+   * Cheap magic-byte gate; false means "this buffer is not my format" (never reaches the parser).
+   * Receives `Uint8Array` so a worker-shaped payload works without a `Buffer.from` wrap; every
+   * `Buffer`-only helper (`toString`, `includes`) must go through a view first.
+   */
+  detect(bytes: Uint8Array): boolean;
+  /**
+   * Extract literal text. Must never execute embedded content or fetch
+   * external resources. Over-page documents must refuse; over-text results
+   * must be truncated with `truncatedBy: "bytes"`.
+   */
+  extract(
+    bytes: Uint8Array,
+    options: { readonly maxPages: number; readonly maxTextBytes: number; readonly signal?: AbortSignal },
+  ): Promise<Omit<DocumentReaderResult, "format">>;
+}
+
+export interface CreateDocumentReaderOptions {
+  /** Hard input size cap in bytes (default 32 MiB, hard ceiling 512 MiB). */
+  readonly maxBytes?: number;
+  /** Hard page/sheet cap for formats that report pages (default 1000, ceiling 10000). */
+  readonly maxPages?: number;
+  /** Hard extracted-literal-text cap in bytes (default 2 MiB, ceiling 64 MiB). */
+  readonly maxTextBytes?: number;
+  /** Host-selected parsers; default wiring uses the pdf-parse and mammoth optional peers. */
+  readonly parsers?: readonly DocumentParser[];
+  /** Optional redactor applied to extracted text at the adapter boundary. */
+  readonly redactor?: SecretRedactor;
+}
+
+/**
+ * Create a bounded document reader for `createReadTool({ documentReader })`.
+ * Throws {@link DocumentReaderError} when a selected format's peer parser is
+ * absent. Unsupported buffers return `null` from `extract` (the read tool
+ * falls through to its 0.1.5 text path).
+ */
+export async function createDocumentReader(options: CreateDocumentReaderOptions = {}): Promise<DocumentReader> {
+  const maxBytes = validateCap("maxBytes", options.maxBytes ?? DEFAULT_MAX_DOCUMENT_BYTES, HARD_MAX_DOCUMENT_BYTES);
+  const maxPages = validateCap("maxPages", options.maxPages ?? DEFAULT_MAX_DOCUMENT_PAGES, HARD_MAX_DOCUMENT_PAGES);
+  const maxTextBytes = validateCap("maxTextBytes", options.maxTextBytes ?? DEFAULT_MAX_DOCUMENT_TEXT_BYTES, HARD_MAX_DOCUMENT_TEXT_BYTES);
+  const usesDefaultParsers = options.parsers === undefined;
+  const parsers = options.parsers ?? [
+    // Default wiring: the optional peers, probed once at creation (fail closed).
+    await createPdfParser(),
+    await createDocxParser(),
+    createOoxmlParser("xlsx", "sheet", "xl/workbook.xml"),
+    createOoxmlParser("pptx", "deck", "ppt/presentation.xml"),
+  ];
+  if (parsers.length === 0) {
+    throw new DocumentReaderError("createDocumentReader requires at least one parser (or the optional peers installed)");
+  }
+
+  return {
+    maxInputBytes: maxBytes,
+    maxTextBytes,
+    extract: async (input) => {
+      input.signal?.throwIfAborted();
+      if (input.buffer.byteLength > maxBytes) {
+        throw new DocumentReaderError(`document exceeds maxBytes cap (${maxBytes}); refusing to extract`);
+      }
+      const parser = parsers.find((candidate) => candidate.detect(input.buffer));
+      if (!parser) return null;
+      // Plan 127 Task 3 + further action #1: the 250-378 ms default-parser extract runs on the pool
+      // for large buffers, priced in both directions — bytes in at the flat clone rate, and one text
+      // value plus up to `maxPages` page spans back (a cloned string is shared rather than copied:
+      // 27 KiB and 2 MB text payloads both clone in ~0.06 ms, evidence §12). The inline estimate is
+      // the measured ~1 ms per KiB of PDF (§3: 250-378 ms for the 281 KiB fixture).
+      // Host-supplied parsers are functions and stay in-process; caps, redaction and the result
+      // shape stay here. The parser itself never honors a mid-parse abort either, so checking the
+      // signal before and after preserves the existing observable behavior.
+      let result: Omit<DocumentReaderResult, "format">;
+      if (
+        usesDefaultParsers &&
+        shouldOffloadToPool({
+          inputBytes: input.buffer.byteLength,
+          resultValues: 1 + maxPages * 4,
+          computeMs: input.buffer.byteLength / 1024,
+        })
+      ) {
+        try {
+          result = await runInPool({
+            kind: "document.extract",
+            payload: { format: parser.format, bytes: input.buffer, maxPages, maxTextBytes },
+          });
+        } catch (error) {
+          throw reviveWorkerTaskError(error, [DocumentReaderError]) ?? error;
+        }
+      } else {
+        result = await parser.extract(input.buffer, { maxPages, maxTextBytes, signal: input.signal });
+      }
+      input.signal?.throwIfAborted();
+      if (Buffer.byteLength(result.text, "utf8") > maxTextBytes) {
+        throw new DocumentReaderError(`parser returned text beyond the maxTextBytes cap (${maxTextBytes})`);
+      }
+      const redacted = options.redactor ? options.redactor.redact(result.text) : result.text;
+      return {
+        text: redacted,
+        format: parser.format,
+        pages: result.pages,
+        truncatedBy: result.truncatedBy,
+        ...(!options.redactor && result.pageSpans ? { pageSpans: result.pageSpans } : {}),
+      } satisfies DocumentReaderResult;
+    },
+  };
+}
+
+export type { CreateMistralOcrParserOptions, OcrPageSpan, OcrUsage } from "./mistral-ocr.js";
+
+export {
+  createMistralOcrParser,
+  DEFAULT_OCR_BASE_URL,
+  DEFAULT_OCR_MAX_BYTES,
+  DEFAULT_OCR_MAX_CONCURRENT,
+  DEFAULT_OCR_MAX_PAGES,
+  DEFAULT_OCR_MAX_RESPONSE_BYTES,
+  DEFAULT_OCR_MODEL,
+  DEFAULT_OCR_TIMEOUT_MS,
+  HARD_OCR_MAX_BYTES,
+  HARD_OCR_MAX_CONCURRENT,
+  HARD_OCR_MAX_PAGES,
+  HARD_OCR_MAX_RESPONSE_BYTES,
+  HARD_OCR_TIMEOUT_MS,
+} from "./mistral-ocr.js";

package/work/src/document-reader/mistral-ocr.ts

@@ -0,0 +1,318 @@
+/**
+ * Optional Mistral Document AI OCR parser. Host-selected only — never wired
+ * into default `createDocumentReader()`. Native fetch (no SDK peer). Inline
+ * base64 by default so nothing is uploaded to the Files API (no cleanup).
+ */
+
+import { assertSsrfAllowedUrl, type SsrfPolicy } from "@arnilo/prism";
+import { pinnedFetch } from "@arnilo/prism/net";
+import { DocumentReaderError } from "./errors.js";
+import type { DocumentParser } from "./index.js";
+
+export const DEFAULT_OCR_MODEL = "mistral-ocr-latest";
+export const DEFAULT_OCR_BASE_URL = "https://api.mistral.ai";
+export const DEFAULT_OCR_TIMEOUT_MS = 60_000;
+export const HARD_OCR_TIMEOUT_MS = 180_000;
+export const DEFAULT_OCR_MAX_BYTES = 8 * 1024 * 1024;
+export const HARD_OCR_MAX_BYTES = 50 * 1024 * 1024;
+export const DEFAULT_OCR_MAX_PAGES = 32;
+export const HARD_OCR_MAX_PAGES = 10_000;
+export const DEFAULT_OCR_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+export const HARD_OCR_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+export const DEFAULT_OCR_MAX_CONCURRENT = 1;
+export const HARD_OCR_MAX_CONCURRENT = 4;
+
+const PDF_MAGIC = "%PDF-";
+
+export interface OcrUsage {
+  readonly model: string;
+  readonly pagesProcessed: number;
+  readonly bytes: number;
+}
+
+export interface OcrPageSpan {
+  readonly page: number;
+  readonly start: number;
+  readonly end: number;
+}
+
+export interface CreateMistralOcrParserOptions {
+  /** Mistral API key. Required. Never read from the environment. */
+  readonly apiKey: string;
+  /** OCR model alias. Default `mistral-ocr-latest`. */
+  readonly model?: string;
+  /** API origin (residency). Default `https://api.mistral.ai`. */
+  readonly baseUrl?: string;
+  /**
+   * Host-authorized document URL Mistral should fetch. SSRF-checked.
+   * When omitted, the buffer is sent as a data URL (no Files API upload).
+   */
+  readonly documentUrl?: string;
+  readonly timeoutMs?: number;
+  readonly maxBytes?: number;
+  readonly maxPages?: number;
+  readonly maxResponseBytes?: number;
+  readonly maxConcurrent?: number;
+  readonly ssrf?: SsrfPolicy;
+  /** Host transport; host owns DNS/SSRF when set. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Task 7 admission hook. Called after a successful HTTP 200, before over-page refusal. */
+  readonly recordUsage?: (usage: OcrUsage) => void | Promise<void>;
+}
+
+function cap(name: string, value: number, hard: number): number {
+  if (!Number.isInteger(value) || value <= 0 || value > hard) {
+    throw new RangeError(`mistral-ocr ${name} must be an integer in (0, ${hard}], got ${value}`);
+  }
+  return value;
+}
+
+/** Zero-copy `Buffer` view: `toString`/`base64` need it once the parser accepts plain `Uint8Array`. */
+function byteView(bytes: Uint8Array): Buffer {
+  return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+function detectKind(bytes: Uint8Array): "pdf" | "image" | null {
+  const view = byteView(bytes);
+  if (bytes.length >= PDF_MAGIC.length && view.toString("latin1", 0, PDF_MAGIC.length) === PDF_MAGIC) return "pdf";
+  if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return "image";
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image";
+  if (bytes.length >= 6 && view.toString("ascii", 0, 3) === "GIF") return "image";
+  if (bytes.length >= 12 && view.toString("ascii", 0, 4) === "RIFF" && view.toString("ascii", 8, 12) === "WEBP") {
+    return "image";
+  }
+  return null;
+}
+
+function imageMediaType(bytes: Uint8Array): string {
+  if (bytes[0] === 0x89) return "image/png";
+  if (bytes[0] === 0xff) return "image/jpeg";
+  if (byteView(bytes).toString("ascii", 0, 3) === "GIF") return "image/gif";
+  return "image/webp";
+}
+
+function originUrl(baseUrl: string): URL {
+  let url: URL;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new DocumentReaderError("mistral-ocr baseUrl must be an absolute URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new DocumentReaderError("mistral-ocr baseUrl must use http(s)");
+  }
+  if (url.username || url.password) throw new DocumentReaderError("mistral-ocr baseUrl must not embed credentials");
+  if (url.hash) throw new DocumentReaderError("mistral-ocr baseUrl must not contain a fragment");
+  try {
+    assertSsrfAllowedUrl(url.href);
+  } catch (error) {
+    throw new DocumentReaderError("mistral-ocr baseUrl is not allowed", { cause: error });
+  }
+  return url;
+}
+
+function limiter(max: number) {
+  let active = 0;
+  const wait: Array<() => void> = [];
+  return {
+    async acquire(signal?: AbortSignal): Promise<void> {
+      signal?.throwIfAborted();
+      while (active >= max) {
+        await new Promise<void>((resolve, reject) => {
+          const resume = () => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+          };
+          const onAbort = () => {
+            const i = wait.indexOf(resume);
+            if (i >= 0) wait.splice(i, 1);
+            reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+          };
+          wait.push(resume);
+          signal?.addEventListener("abort", onAbort, { once: true });
+        });
+        signal?.throwIfAborted();
+      }
+      active += 1;
+    },
+    release(): void {
+      active -= 1;
+      wait.shift()?.();
+    },
+  };
+}
+
+function withTimeout(signal: AbortSignal | undefined, timeoutMs: number): { signal: AbortSignal; dispose: () => void } {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const onAbort = () => controller.abort();
+  signal?.addEventListener("abort", onAbort, { once: true });
+  if (signal?.aborted) controller.abort();
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+interface OcrPage {
+  readonly index?: number;
+  readonly markdown?: string;
+}
+
+function parseOcrBody(body: unknown): { pages: OcrPage[]; model: string; pagesProcessed: number } {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    throw new DocumentReaderError("mistral-ocr: invalid response");
+  }
+  const record = body as Record<string, unknown>;
+  if (!Array.isArray(record.pages) || record.pages.length === 0) throw new DocumentReaderError("mistral-ocr: invalid response");
+  const pages: OcrPage[] = [];
+  for (const page of record.pages) {
+    if (typeof page !== "object" || page === null) throw new DocumentReaderError("mistral-ocr: invalid response");
+    const row = page as Record<string, unknown>;
+    pages.push({
+      index: typeof row.index === "number" ? row.index : undefined,
+      markdown: typeof row.markdown === "string" ? row.markdown : undefined,
+    });
+  }
+  const usage = record.usage_info;
+  const pagesProcessed =
+    typeof usage === "object" && usage !== null && typeof (usage as { pages_processed?: unknown }).pages_processed === "number"
+      ? (usage as { pages_processed: number }).pages_processed
+      : pages.length;
+  return {
+    pages,
+    model: typeof record.model === "string" ? record.model : DEFAULT_OCR_MODEL,
+    pagesProcessed,
+  };
+}
+
+function assemblePages(
+  pages: readonly OcrPage[],
+  maxTextBytes: number,
+): { text: string; pageSpans: OcrPageSpan[]; truncatedBy: "bytes" | null } {
+  const spans: OcrPageSpan[] = [];
+  let text = "";
+  for (let i = 0; i < pages.length; i += 1) {
+    const markdown = pages[i]?.markdown ?? "";
+    const page = pages[i]?.index ?? i + 1;
+    const chunk = `${i === 0 ? "" : "\n\n"}<!-- prism-page ${page} -->\n${markdown}`;
+    const next = text + chunk;
+    if (Buffer.byteLength(next, "utf8") > maxTextBytes) {
+      const buf = Buffer.from(next, "utf8").subarray(0, maxTextBytes).toString("utf8");
+      spans.push({ page, start: text.length, end: buf.length });
+      return { text: buf, pageSpans: spans, truncatedBy: "bytes" };
+    }
+    spans.push({ page, start: text.length, end: next.length });
+    text = next;
+  }
+  return { text, pageSpans: spans, truncatedBy: null };
+}
+
+/**
+ * Host-selected OCR/layout parser. Not a default `createDocumentReader` parser.
+ * Extracted content is untrusted inert text.
+ */
+export function createMistralOcrParser(options: CreateMistralOcrParserOptions): DocumentParser {
+  const apiKey = options.apiKey.trim();
+  if (!apiKey) throw new DocumentReaderError("mistral-ocr requires apiKey");
+  const model = options.model?.trim() || DEFAULT_OCR_MODEL;
+  const origin = originUrl(options.baseUrl?.trim() || DEFAULT_OCR_BASE_URL);
+  const timeoutMs = cap("timeoutMs", options.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS, HARD_OCR_TIMEOUT_MS);
+  const maxBytes = cap("maxBytes", options.maxBytes ?? DEFAULT_OCR_MAX_BYTES, HARD_OCR_MAX_BYTES);
+  const parserMaxPages = cap("maxPages", options.maxPages ?? DEFAULT_OCR_MAX_PAGES, HARD_OCR_MAX_PAGES);
+  const maxResponseBytes = cap("maxResponseBytes", options.maxResponseBytes ?? DEFAULT_OCR_MAX_RESPONSE_BYTES, HARD_OCR_MAX_RESPONSE_BYTES);
+  const maxConcurrent = cap("maxConcurrent", options.maxConcurrent ?? DEFAULT_OCR_MAX_CONCURRENT, HARD_OCR_MAX_CONCURRENT);
+  const documentUrl = options.documentUrl?.trim();
+  if (documentUrl) {
+    try {
+      assertSsrfAllowedUrl(documentUrl, options.ssrf);
+    } catch (error) {
+      throw new DocumentReaderError("mistral-ocr documentUrl is not allowed", { cause: error });
+    }
+  }
+  const gate = limiter(maxConcurrent);
+  const transport = options.fetch;
+
+  return {
+    format: "ocr",
+    detect: (bytes) => detectKind(bytes) !== null,
+    extract: async (bytes, { maxPages, maxTextBytes, signal }) => {
+      signal?.throwIfAborted();
+      if (bytes.byteLength > maxBytes) {
+        throw new DocumentReaderError(`mistral-ocr document exceeds maxBytes cap (${maxBytes})`);
+      }
+      const kind = detectKind(bytes);
+      if (!kind) throw new DocumentReaderError("mistral-ocr: buffer is not a PDF or image");
+      const pageCap = Math.min(maxPages, parserMaxPages);
+      const endpoint = new URL("/v1/ocr", origin);
+      const document = documentUrl
+        ? kind === "pdf"
+          ? { type: "document_url", document_url: documentUrl }
+          : { type: "image_url", image_url: documentUrl }
+        : kind === "pdf"
+          ? { type: "document_url", document_url: `data:application/pdf;base64,${byteView(bytes).toString("base64")}` }
+          : { type: "image_url", image_url: `data:${imageMediaType(bytes)};base64,${byteView(bytes).toString("base64")}` };
+      const payload = JSON.stringify({
+        model,
+        document,
+        include_image_base64: false,
+      });
+      await gate.acquire(signal);
+      const timed = withTimeout(signal, timeoutMs);
+      try {
+        const init: RequestInit = {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${apiKey}`,
+            "content-type": "application/json",
+          },
+          body: payload,
+          signal: timed.signal,
+        };
+        const response = transport
+          ? await transport(endpoint, init)
+          : await pinnedFetch(endpoint, init, {
+              errorPrefix: "mistral-ocr",
+              ssrf: options.ssrf,
+              maxResponseBytes,
+            });
+        if (!response.ok) {
+          await response.body?.cancel().catch(() => undefined);
+          throw new DocumentReaderError(`mistral-ocr HTTP ${response.status}`);
+        }
+        const raw = Buffer.from(await response.arrayBuffer());
+        if (raw.byteLength > maxResponseBytes) {
+          throw new DocumentReaderError(`mistral-ocr response exceeds maxResponseBytes cap (${maxResponseBytes})`);
+        }
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(raw.toString("utf8"));
+        } catch {
+          throw new DocumentReaderError("mistral-ocr: invalid response");
+        }
+        const body = parseOcrBody(parsed);
+        await options.recordUsage?.({
+          model: body.model,
+          pagesProcessed: body.pagesProcessed,
+          bytes: bytes.byteLength,
+        });
+        if (body.pages.length > pageCap) {
+          throw new DocumentReaderError(`document has ${body.pages.length} pages, exceeds maxPages cap (${pageCap}); refusing to extract`);
+        }
+        const assembled = assemblePages(body.pages, maxTextBytes);
+        return {
+          text: assembled.text,
+          pages: body.pages.length,
+          truncatedBy: assembled.truncatedBy,
+          pageSpans: assembled.pageSpans,
+        };
+      } finally {
+        timed.dispose();
+        gate.release();
+      }
+    },
+  };
+}

package/work/src/document-reader/parsers.ts

@@ -0,0 +1,171 @@
+import type { CellValue, DocumentKind, DocumentModel } from "../documents/types.js";
+import { DocumentReaderError } from "./errors.js";
+import type { DocumentParser } from "./index.js";
+
+/**
+ * Default parser wiring for the document reader, split out of `index.ts` so the worker entry
+ * (`runtime/worker-pool-entry.ts`) can build the same parsers on the pool thread (plan 127 Task 3).
+ * Non-public module: the package export map points `./document-reader` at `index.js`, which
+ * re-exports the two historical public factories. The documents stack is imported lazily inside
+ * the OOXML parser so a PDF-only worker does not load it.
+ */
+
+let parseDocumentModule: Promise<typeof import("../documents/parse.js")> | undefined;
+
+/** `%PDF-` as bytes: a plain `Uint8Array` stringifies to "37,80,68,70,45", so the gate compares bytes. */
+const PDF_MAGIC = [0x25, 0x50, 0x44, 0x46, 0x2d] as const;
+
+/**
+ * Zero-copy `Buffer` view over any byte input. `Buffer`-only helpers (`includes`, `toString`) answer
+ * wrongly for a plain `Uint8Array` — the shape a worker payload arrives as (plan 127 further action
+ * #2) — so the byte checks that need a string view go through this.
+ */
+function byteView(bytes: Uint8Array): Buffer {
+  return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+/** Byte-safe truncation to at most `maxBytes` UTF-8 bytes. */
+function truncateToBytes(text: string, maxBytes: number): string {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.byteLength <= maxBytes) return text;
+  return buffer.subarray(0, maxBytes).toString("utf8");
+}
+
+async function loadPeer(name: string): Promise<unknown> {
+  try {
+    const mod = await import(name);
+    // CJS peers expose their export as `default` under Node ESM interop.
+    return (mod as { default?: unknown }).default ?? mod;
+  } catch {
+    throw new DocumentReaderError(
+      `document-reader: optional peer parser "${name}" is not installed. ` +
+        `Install it (npm i ${name}) or supply a host-selected parser via createDocumentReader({ parsers }); ` +
+        `refusing to create a reader that cannot extract this format.`,
+    );
+  }
+}
+
+/** v2 `PDFParse` surface used by the adapter (typed locally; the package is ambient). */
+type PdfParseResult = { readonly total: number; readonly text: string };
+type PdfParseCtor = new (options: {
+  readonly data: Uint8Array;
+  readonly isEvalSupported?: boolean;
+}) => {
+  getText(options?: { readonly pageJoiner?: string }): Promise<PdfParseResult>;
+  destroy(): Promise<void>;
+};
+
+/** Default PDF parser backed by the optional `pdf-parse` peer (v2 `PDFParse` class). */
+export async function createPdfParser(): Promise<DocumentParser> {
+  const ctor = (await loadPeer("pdf-parse")) as { PDFParse?: unknown };
+  if (typeof ctor.PDFParse !== "function") {
+    throw new DocumentReaderError('document-reader: optional peer "pdf-parse" (v2+) does not export the PDFParse class');
+  }
+  const PDFParse = ctor.PDFParse as PdfParseCtor;
+  return {
+    format: "pdf",
+    detect: (bytes) => bytes.length >= PDF_MAGIC.length && PDF_MAGIC.every((byte, index) => bytes[index] === byte),
+    extract: async (bytes, { maxPages, maxTextBytes, signal }) => {
+      signal?.throwIfAborted();
+      // v2 runs pdf.js in a worker thread and claims the TypedArray (transfer);
+      // the adapter never reuses the buffer after parse, so passing a fresh
+      // Uint8Array view is safe. isEvalSupported:false keeps PDF functions from
+      // executing embedded scripts — the document-reader contract forbids it.
+      const parser = new PDFParse({ data: new Uint8Array(bytes), isEvalSupported: false });
+      let data: { total: number; text: string };
+      try {
+        // pageJoiner:'' keeps v2's page-boundary markers out of extracted text
+        // (v1 emitted none; goldens assert on raw page text).
+        data = await parser.getText({ pageJoiner: "" });
+      } finally {
+        await parser.destroy();
+      }
+      if (data.total > maxPages) {
+        throw new DocumentReaderError(`document has ${data.total} pages, exceeds maxPages cap (${maxPages}); refusing to extract`);
+      }
+      const text = data.text ?? "";
+      if (Buffer.byteLength(text, "utf8") > maxTextBytes) {
+        return { text: truncateToBytes(text, maxTextBytes), pages: data.total, truncatedBy: "bytes" };
+      }
+      return { text, pages: data.total, truncatedBy: null };
+    },
+  };
+}
+
+/** Default DOCX parser backed by the optional `mammoth` peer (raw text only). */
+export async function createDocxParser(): Promise<DocumentParser> {
+  const mammoth = (await loadPeer("mammoth")) as {
+    extractRawText(input: { buffer: Buffer }): Promise<{ value: string }>;
+  };
+  return {
+    format: "docx",
+    // zip container + main document part marker; entry names are stored
+    // uncompressed, so the literal name appears verbatim in the headers.
+    detect: (bytes) =>
+      bytes.length >= 4 &&
+      bytes[0] === 0x50 &&
+      bytes[1] === 0x4b &&
+      bytes[2] === 0x03 &&
+      bytes[3] === 0x04 &&
+      byteView(bytes).includes("word/document.xml"),
+    extract: async (bytes, { maxTextBytes, signal }) => {
+      signal?.throwIfAborted();
+      const { value } = await mammoth.extractRawText({ buffer: byteView(bytes) });
+      const text = value ?? "";
+      if (Buffer.byteLength(text, "utf8") > maxTextBytes) {
+        return { text: truncateToBytes(text, maxTextBytes), pages: 1, truncatedBy: "bytes" };
+      }
+      return { text, pages: 1, truncatedBy: null };
+    },
+  };
+}
+
+function cellText(value: CellValue): string {
+  if (value === null) return "";
+  if (typeof value !== "object") return String(value);
+  if ("formula" in value) return value.cachedValue === undefined || value.cachedValue === null ? value.formula : String(value.cachedValue);
+  return value.value;
+}
+
+function modelText(model: DocumentModel): string {
+  if (model.kind === "sheet") {
+    return model.sheets.map((sheet) => [sheet.name, ...sheet.cells.map((row) => row.map(cellText).join("\t"))].join("\n")).join("\n\n");
+  }
+  if (model.kind === "deck") {
+    return model.slides
+      .map((slide, index) => [`Slide ${index + 1}`, slide.title, slide.subtitle, ...(slide.bullets ?? [])].filter(Boolean).join("\n"))
+      .join("\n\n");
+  }
+  return "";
+}
+
+/** OOXML (xlsx/pptx) parser over the documents model — the same shared core the tools use. */
+export function createOoxmlParser(format: "xlsx" | "pptx", kind: DocumentKind, part: string): DocumentParser {
+  return {
+    format,
+    detect: (bytes) =>
+      bytes.length >= 4 &&
+      bytes[0] === 0x50 &&
+      bytes[1] === 0x4b &&
+      bytes[2] === 0x03 &&
+      bytes[3] === 0x04 &&
+      byteView(bytes).includes(part),
+    extract: async (bytes, { maxPages, maxTextBytes, signal }) => {
+      signal?.throwIfAborted();
+      parseDocumentModule ??= import("../documents/parse.js");
+      const { parseDocument } = await parseDocumentModule;
+      const model = await parseDocument(bytes, {
+        kind,
+        caps:
+          kind === "sheet"
+            ? { maxBytes: bytes.byteLength, maxSheets: Math.min(maxPages, 1_000) }
+            : { maxBytes: bytes.byteLength, maxSlides: Math.min(maxPages, 2_000) },
+      });
+      const pages = model.kind === "sheet" ? model.sheets.length : model.kind === "deck" ? model.slides.length : 0;
+      const text = modelText(model);
+      return Buffer.byteLength(text, "utf8") > maxTextBytes
+        ? { text: truncateToBytes(text, maxTextBytes), pages, truncatedBy: "bytes" as const }
+        : { text, pages, truncatedBy: null };
+    },
+  };
+}