@bevel-software/platform-core-backend 0.11.1 → 0.12.0

package/src/modules/workspace/file-readers/doc-extract.service.ts

@@ -0,0 +1,104 @@
+import { extractionMarker, fileExtension, type ExtractFn, type ExtractResult } from './doc-extract.types.js';
+import { DocExtractionCache, gitBlobSha } from './extraction-cache.js';
+
+/** An extraction ready for a consumer: the honest marker header + the text. */
+export interface DocExtraction {
+  /** e.g. `[extracted text of Plugins/GTM/deck.pptx — 14 slides + notes; layout, images and formatting omitted]` */
+  marker: string;
+  text: string;
+}
+
+/** What `extract` returns: a marker+text, or a typed could-not-parse failure. */
+export type DocExtractOutcome =
+  | ({ ok: true } & DocExtraction)
+  | { ok: false; message: string };
+
+/**
+ * The content-hash CACHE wrap around document text extraction. The per-format
+ * `DocumentReader`s in the file-reader registry stay pure (each pairs one
+ * extension with one extract function); this service adds the caching
+ * generically — a reader hands its extract function in, and the service only
+ * runs it on a cache miss.
+ *
+ * Caching: keyed by the git BLOB sha of the bytes (see `gitBlobSha`) PLUS the
+ * path's extension, stored as `{ summary, text }` WITHOUT the path — the
+ * marker is assembled per call so the same content read under two paths
+ * (copies, branches) shares one entry yet each read's marker names the path
+ * that was read. The extension is part of the key because identical bytes
+ * extract DIFFERENTLY per format: a `.odt` renamed `.ods` must run the ods
+ * extractor, not return the odt extraction. Extraction is deterministic
+ * (stable slide/sheet/page ordering), which is what makes a content-keyed
+ * cache correct. Failures are NOT cached (rare, and fail fast). The key also carries
+ * `EXTRACTION_SCHEMA`, so an upgrade that changes what an extractor emits does
+ * not keep serving the previous release's text for unchanged bytes.
+ */
+/**
+ * Bumped whenever extraction OUTPUT changes — a new extractor, a fixed one, a
+ * reworded summary, a different marker.
+ *
+ * The rest of the key is content, and content-addressing is only correct while
+ * the same bytes mean the same text. An upgrade that changes what an extractor
+ * emits breaks that: every already-cached document would keep serving the OLD
+ * extraction forever, because its bytes never changed. Bumping this retires
+ * those entries (the cache evicts by age, so they cost nothing for long).
+ *
+ * v2: extraction moved from hand-rolled scanning to a real XML/HTML parser,
+ * which changed self-closing paragraphs, entity edge cases and recovery from
+ * malformed parts.
+ */
+export const EXTRACTION_SCHEMA = 'v2';
+
+export class DocExtractService {
+  private readonly cache: DocExtractionCache;
+  /**
+   * Cold extractions currently running, by cache key. Two reads of the same
+   * document arriving together would otherwise BOTH parse it — the expensive
+   * half of this service, run twice for one answer — because neither had
+   * written the cache entry yet when the other looked.
+   */
+  private readonly inFlight = new Map<string, Promise<ExtractResult>>();
+
+  constructor(cacheRoot: string) {
+    this.cache = new DocExtractionCache(cacheRoot);
+  }
+
+  /**
+   * The CACHED extraction for these bytes, or undefined on a cache miss —
+   * never extracts. `grep` uses this (via `DocumentReader.greppableText`) to
+   * search already-extracted documents for free and apply its per-walk budget
+   * only to cold ones.
+   */
+  async getCached(path: string, bytes: Buffer): Promise<DocExtraction | undefined> {
+    const hit = await this.cache.get(this.cacheKey(path, bytes));
+    return hit && { marker: extractionMarker(path, hit.summary), text: hit.text };
+  }
+
+  /** Extract via `extractFn` (cache hit or parse + store). `path` supplies the marker AND the key's format part. */
+  async extract(path: string, bytes: Buffer, extractFn: ExtractFn): Promise<DocExtractOutcome> {
+    const key = this.cacheKey(path, bytes);
+    const hit = await this.cache.get(key);
+    if (hit) return { ok: true, marker: extractionMarker(path, hit.summary), text: hit.text };
+    const running = this.inFlight.get(key);
+    const result = await (running ??
+      (() => {
+        // The cache write stays INSIDE the shared promise: were the entry
+        // dropped as soon as parsing settled, a read arriving during the
+        // write would miss both the cache and the in-flight map — and parse
+        // the same document again.
+        const started = (async (): Promise<ExtractResult> => {
+          const res = await extractFn(bytes);
+          if (res.ok) await this.cache.put(key, { summary: res.summary, text: res.text });
+          return res;
+        })().finally(() => this.inFlight.delete(key));
+        this.inFlight.set(key, started);
+        return started;
+      })());
+    if (!result.ok) return result;
+    return { ok: true, marker: extractionMarker(path, result.summary), text: result.text };
+  }
+
+  /** Content hash + lowercased extension — e.g. `…sha….odt` (see the class doc). */
+  private cacheKey(path: string, bytes: Buffer): string {
+    return `${gitBlobSha(bytes)}${fileExtension(path)}.${EXTRACTION_SCHEMA}`;
+  }
+}

package/src/modules/workspace/file-readers/doc-extract.types.ts

@@ -0,0 +1,63 @@
+/**
+ * Server-side document text extraction — shared types.
+ *
+ * The extractors turn an office document (`.docx` / `.pptx` / `.xlsx`), an
+ * OpenDocument file (`.odt` / `.odp` / `.ods`) or a PDF into plain text an
+ * agent can read and grep. They are HONEST about being
+ * lossy: every successful extraction carries a one-line `summary` the consumer
+ * turns into a marker header (`[extracted text of <path> — <summary>]`) so the
+ * reader knows it is looking at extracted text, not the file's bytes.
+ *
+ * The `summary` (not a full marker) is what extractors return and what the
+ * cache stores, because the cache is keyed by CONTENT (git blob sha): the same
+ * document at two workspace paths shares one cache entry, and baking a path
+ * into the cached value would surface the wrong path on the second read.
+ */
+
+/** A successful extraction: the marker-summary line + the extracted text. */
+export interface ExtractedDoc {
+  /**
+   * One-line description for the marker header, e.g.
+   * `14 slides + notes; layout, images and formatting omitted`.
+   */
+  summary: string;
+  /** The extracted text: paragraphs/rows as lines, with `[slide N]` / `[sheet: Name]` / `[page N]` structure markers. */
+  text: string;
+}
+
+/**
+ * Extraction outcome. `ok: false` is a TYPED failure (corrupt/unparseable
+ * file) the consumers turn into an honest message — extraction never throws
+ * for bad file content, so a broken upload cannot 500 a read.
+ */
+export type ExtractResult =
+  | ({ ok: true } & ExtractedDoc)
+  | { ok: false; message: string };
+
+/**
+ * A format's PURE extract function — bytes in, `ExtractResult` out (async for
+ * pdf.js). One per supported format (extract-docx.ts and friends); each is
+ * paired with its extension by a `DocumentReader` entry in the file-reader
+ * registry, and cache-wrapped by `DocExtractService`.
+ */
+export type ExtractFn = (bytes: Buffer) => ExtractResult | Promise<ExtractResult>;
+
+/**
+ * Build the honest ONE-LINE header consumers prepend to extracted text.
+ *
+ * One line is a promise the rest of the read path keeps: grep counts on the
+ * marker occupying exactly one, so read_file and grep agree on line numbers.
+ * A path may legally carry a CR or LF, which would forge extra lines and shift
+ * every number after it, so those are shown as escapes rather than obeyed.
+ */
+export function extractionMarker(path: string, summary: string): string {
+  const oneLine = path.replace(/[\r\n]/g, (c) => (c === '\r' ? '\\r' : '\\n'));
+  return `[extracted text of ${oneLine} — ${summary}]`;
+}
+
+/** Lowercased extension of `path` including the dot, or '' when there is none. */
+export function fileExtension(path: string): string {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot).toLowerCase() : '';
+}

package/src/modules/workspace/file-readers/document-reader.ts

@@ -0,0 +1,64 @@
+import type { DocExtractService } from './doc-extract.service.js';
+import type { ExtractFn } from './doc-extract.types.js';
+import { displayPath, oneLine, type FileReader, type ReadResult } from './file-reader.js';
+
+/**
+ * FileReader over one document format: a thin wrapper pairing the format's
+ * PURE extract function (extract-docx.ts and friends) with the shared
+ * content-hash extraction cache (`DocExtractService`). Reads return the
+ * extraction under its honest `[extracted text of …]` marker; a parse failure
+ * becomes a refusal message, never a 500.
+ *
+ * `grep` semantics: `greppableText` serves only the CACHED extraction (a hit
+ * costs one small JSON read), returning null for a cold document — whether to
+ * spend grep's per-walk extraction budget on a cold one is the walk's call,
+ * which then extracts through `read` (see grepWalk in workspace.tools.ts).
+ * grep also branches on `instanceof DocumentReader` for exactly that decision.
+ */
+export class DocumentReader implements FileReader {
+  readonly extensions: readonly string[];
+  /**
+   * `read_file` returns an EXTRACTION for these types, so text written back
+   * could not round-trip — the write tools refuse (documents are replaced by
+   * uploading a new version).
+   */
+  readonly textEditable = false;
+
+  constructor(
+    extension: string,
+    private readonly extract: ExtractFn,
+    private readonly service: DocExtractService,
+  ) {
+    this.extensions = [extension];
+  }
+
+  async read(bytes: Buffer, path: string): Promise<ReadResult> {
+    // An extractor is contracted to ANSWER for bad content rather than throw,
+    // but it wraps third-party parsers, and one of those throwing past its own
+    // guard is a corrupt file — not a server fault. read_file says so instead
+    // of failing the whole tool call with a 500.
+    let res: Awaited<ReturnType<typeof this.service.extract>>;
+    try {
+      res = await this.service.extract(path, bytes, this.extract);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      return {
+        kind: 'refusal',
+        message: `[${displayPath(path)} could not be extracted (${oneLine(reason)}) — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`,
+      };
+    }
+
+    return res.ok
+      ? { kind: 'text', text: `${res.marker}\n${res.text}` }
+      : {
+          kind: 'refusal',
+          message: `[${displayPath(path)} ${oneLine(res.message)} — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`,
+        };
+  }
+
+  /** The cached extraction (marker line included, so grep's line numbers match read_file's), or null when cold. */
+  async greppableText(bytes: Buffer, path: string): Promise<string | null> {
+    const hit = await this.service.getCached(path, bytes);
+    return hit ? `${hit.marker}\n${hit.text}` : null;
+  }
+}

package/src/modules/workspace/file-readers/email-reader.ts

@@ -0,0 +1,21 @@
+import { DocumentReader } from './document-reader.js';
+
+/**
+ * FileReader over one email format (`.eml` / `.msg`): a `DocumentReader` in
+ * every mechanical respect — cache-wrapped extraction, greppable when cached,
+ * corrupt files answered with the typed could-not-be-parsed refusal — with
+ * only the WRITE-refusal copy specialized. The generic document refusal talks
+ * about round-tripping an office document; an email deserves the honest
+ * version of the same "no": the file is a snapshot of a message, and editing
+ * a snapshot's text is not a thing.
+ */
+export class EmailReader extends DocumentReader {
+  /** The write-refusal for the agent text-editing tools (see `assertNotDocumentEdit`). */
+  editRefusal(path: string): string {
+    return (
+      `"${path}" is an email file — a snapshot of a message. read_file returns EXTRACTED text for it, ` +
+      'and a snapshot cannot be text-edited; to change what is stored, replace the file by uploading ' +
+      'a new version.'
+    );
+  }
+}

package/src/modules/workspace/file-readers/email-text.ts

@@ -0,0 +1,193 @@
+/**
+ * Shared shaping for the email extractors (`extract-eml.ts` / `extract-msg.ts`).
+ *
+ * Both formats extract to the SAME text shape, so an agent greps a mailbox
+ * without caring which client saved the file:
+ *
+ *   [from] Ada Lovelace <ada@example.com>
+ *   [to] Bob <bob@example.com>, carol@example.com
+ *   [subject] Quarterly numbers
+ *   [date] 2026-01-05T10:00:00.000Z
+ *
+ *   the body…
+ *
+ *   [attachments]
+ *   report.pdf (application/pdf, 48211 bytes)
+ *
+ * Header lines are omitted when the message lacks the field (never printed
+ * empty). The body prefers the plain-text part; an HTML-only body is stripped
+ * to text (block tags become newlines so paragraphs survive) and the marker
+ * summary says so. Attachments are LISTED by name only — v1 does not extract
+ * inside them, and the summary says that too.
+ */
+import type { ExtractedDoc } from './doc-extract.types.js';
+import { Parser } from 'htmlparser2';
+import { MAX_ELEMENT_DEPTH, TOO_DEEP } from './ooxml-text.js';
+
+/** One listed attachment. Size/type are printed only when known. */
+export interface EmailAttachment {
+  name: string;
+  mimeType?: string;
+  sizeBytes?: number;
+}
+
+/** Where the body text came from — drives the honest summary + body notes. */
+export type EmailBodySource = 'text' | 'html' | 'rtf-only' | 'none';
+
+/** The format-independent email, as far as the extraction cares. */
+export interface EmailModel {
+  from?: string;
+  to?: string;
+  cc?: string;
+  bcc?: string;
+  subject?: string;
+  /** ISO timestamp when the date parsed, the raw header value otherwise. */
+  date?: string;
+  /** Body as plain text ('' when there is none or it is RTF-only). */
+  body: string;
+  bodySource: EmailBodySource;
+  attachments: EmailAttachment[];
+}
+
+/** The line a body that exists only as RTF gets INSTEAD of body text. */
+export const RTF_ONLY_BODY_LINE = '[body is RTF; no plain-text part]';
+
+/**
+ * Strip an HTML email body to plain text. Deliberately simple (the same
+ * stance as `ooxml-text.ts`): comments and `<style>`/`<script>`/`<head>`/
+ * `<title>` containers are dropped whole, `<br>` and block-level tag
+ * boundaries become newlines so paragraphs survive, every other tag is
+ * removed, and entities are decoded through the module's shared
+ * `decodeXmlEntities` (plus `&nbsp;`, which HTML has and XML does not). Runs
+ * of blank lines collapse to one.
+ *
+ * Implemented as a SINGLE-PASS linear scanner, not regexes: the earlier
+ * quote-aware tag regexes re-scanned the remaining body from every `<` when a
+ * quoted attribute never closed — malformed input with many `<` characters
+ * plus one unterminated quote pinned the server quadratically. The scanner is
+ * quote-aware the same way (a `>` INSIDE a quoted attribute value, as in
+ * `<a title="a > b">`, never ends the tag early) but amortizes the failures:
+ * a scan that reaches end-of-input marks every `<` it passed OUTSIDE quotes
+ * as known-literal (their scans would be identical tails), so no position is
+ * rescanned from more than the three possible quote states. An unterminated
+ * tag is literal text, not a tag — and so is a `<…>` span that names no
+ * element at all, which is how `1 < 2 > 0` survives into the body.
+ */
+/** Elements whose CONTENT is not body text and is dropped with the element. */
+const CONTAINER_TAGS = new Set(['script', 'style', 'head', 'title']);
+
+/** Elements whose boundaries end a line, so paragraphs survive as paragraphs. */
+const BLOCK_TAGS = new Set([
+  'p', 'div', 'section', 'article', 'header', 'footer', 'main',
+  'table', 'thead', 'tbody', 'tfoot', 'tr', 'td', 'th',
+  'li', 'ul', 'ol', 'dl', 'dt', 'dd', 'blockquote', 'pre', 'hr',
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+]);
+
+// Depth bound shared with the OOXML/ODF extractors (`ooxml-text.ts`): mail
+// nests a few dozen levels even at its most table-happy; a crafted body can
+// nest as deep as it has bytes. What was read before the bound is kept.
+
+export function htmlToEmailText(html: string): string {
+  let s = '';
+  let depth = 0;
+  let skipping = 0; // inside a container whose content is not body text
+  const parser = new Parser(
+    {
+      onopentag(name) {
+        depth++;
+        if (CONTAINER_TAGS.has(name)) skipping++;
+        else if (name === 'br' || BLOCK_TAGS.has(name)) s += '\n';
+        if (depth > MAX_ELEMENT_DEPTH) throw TOO_DEEP;
+      },
+      ontext(text) {
+        if (skipping === 0) s += text;
+      },
+      onclosetag(name) {
+        if (CONTAINER_TAGS.has(name)) {
+          if (skipping > 0) skipping--;
+        } else if (BLOCK_TAGS.has(name)) s += '\n';
+        depth--;
+      },
+    },
+    // HTML mode, not XML: an email body is HTML, with its void elements, its
+    // implied closes, its raw-text `<script>`, and its named entities.
+    { decodeEntities: true },
+  );
+  try {
+    parser.write(html);
+    parser.end();
+  } catch (err) {
+    if (err !== TOO_DEEP) throw err;
+    parser.reset();
+  }
+
+  // `&nbsp;` decodes to U+00A0, which LOOKS like a space and is not one: an
+  // agent grepping the extraction for "Para one" would miss a line that reads
+  // exactly that. Extracted text is for reading and searching, so the
+  // non-breaking space becomes an ordinary one.
+  const out: string[] = [];
+  for (const raw of s.replace(/ /g, ' ').split('\n')) {
+    const line = raw.trim();
+    if (line !== '') out.push(line);
+    else if (out.length > 0 && out[out.length - 1] !== '') out.push('');
+  }
+  while (out.length > 0 && out[out.length - 1] === '') out.pop();
+  return out.join('\n');
+}
+
+/** `name (mimeType, N bytes)` with the parenthesis dropped when nothing is known.
+ * CR/LF in the metadata are shown as escapes rather than obeyed, so each
+ * attachment stays on ONE line and grep line numbers hold. */
+function attachmentLine(a: EmailAttachment): string {
+  // The extractors default a MISSING name, but an EMPTY (or whitespace-only)
+  // one reaches here as ''; without the same fallback the section printed a
+  // blank line — or one starting with the parenthesis — for that attachment.
+  const name = a.name.trim() === '' ? 'unnamed attachment' : a.name;
+  const details = [a.mimeType, a.sizeBytes !== undefined ? `${a.sizeBytes} bytes` : undefined]
+    .filter((d): d is string => d !== undefined && d !== '')
+    .join(', ');
+  const line = details === '' ? name : `${name} (${details})`;
+  return line.replace(/[\r\n]/g, (c) => (c === '\r' ? '\\r' : '\\n'));
+}
+
+/** A header value with its line breaks made visible instead of obeyed. */
+function oneLine(value: string): string {
+  return value.replace(/[\r\n]/g, (c) => (c === '\r' ? '\\r' : '\\n'));
+}
+
+/** Render the model into the marker summary + extraction text (see module doc). */
+export function emailExtraction(model: EmailModel): ExtractedDoc {
+  const header: string[] = [];
+  // Absent OR blank fields are omitted — a header marker is never printed empty.
+  const pushHeader = (label: string, value: string | undefined): void => {
+    if (value === undefined || value.trim() === '') return;
+    // A header marker is ONE line. A From or Subject carrying CR/LF would
+    // otherwise forge further lines into the extraction — including lines that
+    // read like other markers — so the breaks are shown as escapes.
+    header.push(`[${label}] ${oneLine(value)}`);
+  };
+  pushHeader('from', model.from);
+  pushHeader('to', model.to);
+  pushHeader('cc', model.cc);
+  pushHeader('bcc', model.bcc);
+  pushHeader('subject', model.subject);
+  pushHeader('date', model.date);
+
+  const sections: string[] = [];
+  if (header.length > 0) sections.push(header.join('\n'));
+  if (model.bodySource === 'rtf-only') sections.push(RTF_ONLY_BODY_LINE);
+  else if (model.body !== '') sections.push(model.body);
+  if (model.attachments.length > 0) {
+    sections.push(`[attachments]\n${model.attachments.map(attachmentLine).join('\n')}`);
+  }
+
+  const n = model.attachments.length;
+  const parts = ['email message'];
+  if (n > 0) parts.push(`${n} attachment${n === 1 ? '' : 's'} listed (names only; not extracted)`);
+  if (model.bodySource === 'html') parts.push('HTML body rendered as plain text');
+  if (model.bodySource === 'rtf-only') parts.push('body is RTF; no plain-text part');
+  parts.push('formatting and full headers omitted');
+
+  return { summary: parts.join('; '), text: sections.join('\n\n') };
+}

package/src/modules/workspace/file-readers/extract-docx.ts

@@ -0,0 +1,67 @@
+import AdmZip from 'adm-zip';
+import type { ExtractResult } from './doc-extract.types.js';
+import { localBlocks, localElementBlocks, localName, paragraphRunText, zipEntryOversize } from './ooxml-text.js';
+
+/**
+ * Extract the BODY text of a `.docx` (Word) document.
+ *
+ * A docx is a zip whose main part is `word/document.xml`. v1 extracts the body
+ * only — headers/footers are skipped, and the marker summary says so.
+ *
+ *  - Paragraphs become lines. `<w:t>` runs are concatenated with NO separator
+ *    (Word splits runs mid-word on formatting boundaries).
+ *  - Tables become lines with cell text tab-separated, one line per row.
+ */
+export function extractDocx(bytes: Buffer): ExtractResult {
+  let xml: string;
+  try {
+    const zip = new AdmZip(bytes);
+    const entry = zip.getEntry('word/document.xml');
+    if (!entry) {
+      return { ok: false, message: 'could not be parsed as a .docx (no word/document.xml inside the archive)' };
+    }
+    // Declared-uncompressed-size bound BEFORE inflation — see zipEntryOversize.
+    const oversize = zipEntryOversize(entry);
+    if (oversize) return { ok: false, message: `could not be extracted as a .docx (${oversize})` };
+    xml = entry.getData().toString('utf8');
+  } catch (err) {
+    return { ok: false, message: `could not be parsed as a .docx (${(err as Error).message})` };
+  }
+
+  // The BODY element read by the parser rather than matched by a regex: a
+  // comment or CDATA section mentioning `<w:body>` could answer as the
+  // document body and hand back its text instead of the real one.
+  const body = localBlocks(xml, 'body')[0] ?? xml;
+
+  const lines: string[] = [];
+  let paragraphs = 0;
+  let tables = 0;
+  // Tables and paragraphs in DOCUMENT order, straight from the parser: a match
+  // is never descended into, so a table's own paragraphs stay inside it and are
+  // rendered once, as its rows. The hand-rolled splitter this replaces counted
+  // `<w:tbl>` opens and closes with a regex, which a comment or CDATA section
+  // mentioning either could throw off — splitting a paragraph in half and
+  // dropping its text.
+  for (const block of localElementBlocks(body, ['tbl', 'p'])) {
+    if (localName(block.name) === 'tbl') {
+      tables++;
+      for (const row of localBlocks(block.body ?? '', 'tr')) {
+        const cells = localBlocks(row, 'tc').map((cell) => paragraphRunText(cell, 't'));
+        lines.push(cells.join('	'));
+      }
+    } else {
+      lines.push(paragraphRunText(block.body ?? '', 't'));
+      paragraphs++;
+    }
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+
+  const parts = [`${paragraphs} paragraph${paragraphs === 1 ? '' : 's'}`];
+  if (tables > 0) parts.push(`${tables} table${tables === 1 ? '' : 's'}`);
+  return {
+    ok: true,
+    summary: `${parts.join(' + ')}; body only (headers/footers skipped); layout, images and formatting omitted`,
+    text: lines.join('\n'),
+  };
+}
+

package/src/modules/workspace/file-readers/extract-eml.ts

@@ -0,0 +1,92 @@
+import PostalMime, { type Address, type Email } from 'postal-mime';
+import type { ExtractResult } from './doc-extract.types.js';
+import { emailExtraction, htmlToEmailText, type EmailAttachment, type EmailModel } from './email-text.js';
+import { MAX_DOC_PART_BYTES } from './ooxml-text.js';
+
+/**
+ * Extract a `.eml` (RFC 822 / MIME) email into the shared email text shape
+ * (see `email-text.ts`).
+ *
+ * Parsing is `postal-mime` (postalsys, MIT-0): small, dependency-free, ESM,
+ * and the same code runs in the browser — which keeps the frontend viewer's
+ * story identical to the agent's. It normalizes encoded-word headers and
+ * multipart bodies, and hands the `Date:` header over as ISO when it parses.
+ *
+ * postal-mime is LENIENT — random bytes "parse" to an empty message rather
+ * than throwing — so recognizability is checked here: a file yielding NO
+ * email headers at all (no From/To/Cc/Bcc/Subject/Date/Message-ID) and no
+ * attachments is not an email, and gets the typed could-not-be-parsed
+ * failure instead of an empty extraction.
+ */
+export async function extractEml(bytes: Buffer): Promise<ExtractResult> {
+  // The same raw-size bound the PDF extractor applies: no container to
+  // pre-scan, so the bound is the file's size, checked before parsing.
+  if (bytes.length > MAX_DOC_PART_BYTES) {
+    return {
+      ok: false,
+      message: `could not be extracted as a .eml (the file is ${bytes.length} bytes — over the ${MAX_DOC_PART_BYTES}-byte (50 MB) extraction limit)`,
+    };
+  }
+  let email: Email;
+  try {
+    email = await PostalMime.parse(bytes);
+  } catch (err) {
+    return { ok: false, message: `could not be parsed as a .eml (${(err as Error).message})` };
+  }
+  if (
+    email.from === undefined &&
+    email.to === undefined &&
+    email.cc === undefined &&
+    email.bcc === undefined &&
+    email.subject === undefined &&
+    email.date === undefined &&
+    email.messageId === undefined &&
+    email.attachments.length === 0
+  ) {
+    return { ok: false, message: 'could not be parsed as a .eml (no email headers found)' };
+  }
+  return { ok: true, ...emailExtraction(emlModel(email)) };
+}
+
+/** postal-mime's parse, shaped into the format-independent email model. */
+function emlModel(email: Email): EmailModel {
+  const text = email.text !== undefined && email.text.trim() !== '' ? email.text : undefined;
+  const html = email.html !== undefined && email.html.trim() !== '' ? email.html : undefined;
+  const body = text ?? (html !== undefined ? htmlToEmailText(html) : '');
+  return {
+    from: email.from && addressListText([email.from]),
+    to: email.to && addressListText(email.to),
+    cc: email.cc && addressListText(email.cc),
+    bcc: email.bcc && addressListText(email.bcc),
+    subject: email.subject,
+    date: email.date !== undefined ? isoDate(email.date) : undefined,
+    body: body.replace(/\s+$/, ''),
+    bodySource: text !== undefined ? 'text' : html !== undefined ? 'html' : 'none',
+    attachments: email.attachments.map(
+      (a): EmailAttachment => ({
+        name: a.filename ?? 'unnamed attachment',
+        mimeType: a.mimeType,
+        sizeBytes: typeof a.content === 'string' ? Buffer.byteLength(a.content) : a.content.byteLength,
+      }),
+    ),
+  };
+}
+
+/** `Name <addr>, addr2, Group: member, member` — groups flattened inline. */
+function addressListText(list: Address[]): string | undefined {
+  const s = list
+    .map(function one(a: Address): string {
+      if (a.group !== undefined) return `${a.name}: ${a.group.map(one).join(', ')}`;
+      if (a.address === undefined || a.address === '') return a.name;
+      return a.name !== '' && a.name !== a.address ? `${a.name} <${a.address}>` : a.address;
+    })
+    .filter((t) => t !== '')
+    .join(', ');
+  return s === '' ? undefined : s;
+}
+
+/** postal-mime already normalizes parseable dates to ISO; keep the raw value when it could not. */
+function isoDate(value: string): string {
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? value : d.toISOString();
+}