@zocomputer/agent-sdk 0.5.0

package/src/dir-conventions.ts

@@ -0,0 +1,238 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Directory-conventions riders for the `read` tool: the first time a session
+// reads a file under a directory that carries its own conventions file
+// (AGENTS.md by default), the read result carries that file's content along —
+// once per directory per session. This makes convention delivery structural
+// instead of hoping the model remembers to read nested AGENTS.md files
+// (Cursor's harness does exactly this; see
+// journal/ben/rib/2026-07-02-learning-from-cursor.md).
+//
+// The root conventions file is deliberately excluded: agents inject it as a
+// system-prompt section (createRepoConventionsInstruction), and re-delivering
+// the largest file in the chain on the first read would double-pay for it.
+//
+// Riders are tool-RESULT content, appended to the transcript — they never
+// touch tool descriptions or instructions, so this is prompt-cache-safe by
+// construction.
+
+/** One conventions rider attached to a read result. */
+export type DirConventionsRider =
+  | { readonly path: string; readonly content: string }
+  | { readonly path: string; readonly note: string };
+
+export interface DirConventionsOptions {
+  /** Workspace root; the chain walks from here (exclusive) down to the file. */
+  workspaceRoot: string;
+  /** Conventions filename to look for in each directory. Default "AGENTS.md". */
+  fileName?: string;
+  /**
+   * Per-file content cap in bytes; an oversized conventions file becomes a
+   * pointer note instead of inline content. Default 16 KB.
+   */
+  maxBytesPerFile?: number;
+  /**
+   * Max conventions files inlined per read; on a first read deep in a tree,
+   * the directories nearest the file get content and the rest get pointer
+   * notes. Default 4.
+   */
+  maxFilesPerRead?: number;
+  /**
+   * File loader, injectable for tests. Returns the file's content or null
+   * when it doesn't exist (sync or async — a sandbox-backed read is async).
+   * Defaults to a UTF-8 fs read. Callers with a per-call I/O backend (the
+   * read tool resolving a sandbox session) pass a loader to `collect`
+   * instead, which overrides this one.
+   */
+  loadFile?: (absPath: string) => string | null | Promise<string | null>;
+  /**
+   * Max sessions tracked per workspace; least-recently-used sessions evict
+   * first (an evicted session that reappears re-delivers). Default 100.
+   */
+  maxSessions?: number;
+}
+
+export interface DirConventionsTracker {
+  /**
+   * Riders for a read of `relPath` (workspace-relative), marking every
+   * directory on its chain as delivered for `sessionId`. No session id (a
+   * caller outside an eve session) → no riders, no tracking. `loadFile`
+   * overrides the tracker's own loader for this call — the read tool passes
+   * its per-call workspace IO here so riders come off the same backend
+   * (local disk or sandbox) as the read itself.
+   */
+  collect(
+    sessionId: string | undefined,
+    relPath: string,
+    loadFile?: (absPath: string) => string | null | Promise<string | null>,
+  ): Promise<DirConventionsRider[]>;
+}
+
+const DEFAULT_MAX_BYTES_PER_FILE = 16 * 1024;
+const DEFAULT_MAX_FILES_PER_READ = 4;
+// Bound per-tracker memory over a long-lived process; least-recently-used
+// sessions drop first (worst case: an evicted session re-delivers).
+const DEFAULT_MAX_SESSIONS = 100;
+
+/**
+ * Normalize a workspace-relative path to forward slashes. Riders and chain
+ * entries always use `/` regardless of platform, so equality checks and
+ * reported paths can't diverge between a `/`-style relPath and a
+ * `\`-style `path.join` product on Windows.
+ */
+function normalizeRel(relPath: string): string {
+  return relPath
+    .split(/[\\/]+/)
+    .filter((s) => s.length > 0)
+    .join("/");
+}
+
+/**
+ * The directory chain a read of `relPath` passes through, shallow → deep,
+ * excluding the workspace root itself. Accepts `/` or `\` separators and
+ * returns `/`-joined entries. Pure; exported for tests.
+ */
+export function dirChain(relPath: string): string[] {
+  const segments = normalizeRel(relPath).split("/").filter((s) => s.length > 0);
+  const dirs: string[] = [];
+  // The last segment is the file itself.
+  for (let i = 0; i < segments.length - 1; i++) {
+    dirs.push(segments.slice(0, i + 1).join("/"));
+  }
+  return dirs;
+}
+
+function defaultLoadFile(absPath: string): string | null {
+  try {
+    return readFileSync(absPath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// Trackers are deduped per workspaceRoot+fileName on globalThis: eve's dev
+// runtime rebuilds authored artifacts mid-session and a rebuilt module graph
+// would otherwise hold a fresh (empty) delivered-set and re-deliver every
+// conventions file. Same hazard and same fix as the task registry
+// (see ./async-tasks.ts); Symbol.for is shared across module copies.
+const TRACKER_CACHE_KEY = Symbol.for("zocomputer.agent-sdk.dir-conventions");
+
+interface TrackerState {
+  /** sessionId → directories already considered (delivered or absent). */
+  sessions: Map<string, Set<string>>;
+}
+
+function trackerStateCache(): Map<string, TrackerState> {
+  const holder = globalThis as { [TRACKER_CACHE_KEY]?: Map<string, TrackerState> };
+  holder[TRACKER_CACHE_KEY] ??= new Map();
+  return holder[TRACKER_CACHE_KEY];
+}
+
+/** Test-only: drop the per-process tracker state dedupe. */
+export function __resetDirConventionsCacheForTests(): void {
+  trackerStateCache().clear();
+}
+
+export function createDirConventionsTracker(
+  options: DirConventionsOptions,
+): DirConventionsTracker {
+  const {
+    workspaceRoot,
+    fileName = "AGENTS.md",
+    maxBytesPerFile = DEFAULT_MAX_BYTES_PER_FILE,
+    maxFilesPerRead = DEFAULT_MAX_FILES_PER_READ,
+    loadFile = defaultLoadFile,
+    maxSessions = DEFAULT_MAX_SESSIONS,
+  } = options;
+
+  // State (not the tracker) is what dedupes: two tracker instances over the
+  // same root/fileName share one delivered-set even across module copies.
+  const cache = trackerStateCache();
+  const cacheKey = `${workspaceRoot}\u0000${fileName}`;
+  let state = cache.get(cacheKey);
+  if (!state) {
+    state = { sessions: new Map() };
+    cache.set(cacheKey, state);
+  }
+  const sessions = state.sessions;
+
+  function deliveredSet(sessionId: string): Set<string> {
+    const existing = sessions.get(sessionId);
+    // LRU: re-insert on every access so an active session is never the
+    // eviction victim — only sessions idle past 100 newer ones drop.
+    if (existing) {
+      sessions.delete(sessionId);
+      sessions.set(sessionId, existing);
+      return existing;
+    }
+    const set = new Set<string>();
+    sessions.set(sessionId, set);
+    // Maps iterate in insertion order, so the first key is least recently used.
+    while (sessions.size > maxSessions) {
+      const oldest = sessions.keys().next().value;
+      if (oldest === undefined) break;
+      sessions.delete(oldest);
+    }
+    return set;
+  }
+
+  return {
+    async collect(sessionId, relPath, loadOverride) {
+      if (!sessionId) return [];
+      const load = loadOverride ?? loadFile;
+      const delivered = deliveredSet(sessionId);
+      const normalizedRel = normalizeRel(relPath);
+
+      // Directories with an undelivered conventions file, shallow → deep.
+      // Rider paths stay `/`-joined on every platform; only the filesystem
+      // read converts to a native path (join handles `/` everywhere).
+      const found: { dir: string; path: string; content: string }[] = [];
+      for (const dir of dirChain(normalizedRel)) {
+        if (delivered.has(dir)) continue;
+        const riderRel = `${dir}/${fileName}`;
+        // Reading the conventions file itself delivers it — no rider needed.
+        if (riderRel === normalizedRel) {
+          delivered.add(dir);
+          continue;
+        }
+        // Reserve the slot BEFORE the async load: a turn's tool calls run
+        // concurrently, and two reads first entering the same directory must
+        // not both deliver its conventions.
+        delivered.add(dir);
+        let loaded: string | null;
+        try {
+          loaded = await load(join(workspaceRoot, riderRel));
+        } catch {
+          // A throwing loader is a transient failure (a sandbox hop, a
+          // permissions blip), not a missing file: release the slot so a
+          // later read under this directory retries the delivery. (A
+          // concurrent read that skipped meanwhile also retries later —
+          // at-most-once holds either way.)
+          delivered.delete(dir);
+          continue;
+        }
+        // Absent/empty after a successful load is a settled answer (nothing
+        // to deliver): the reservation stands and the dir never re-probes.
+        const content = loaded?.trim() ?? "";
+        if (content.length === 0) continue;
+        found.push({ dir, path: riderRel, content });
+      }
+      if (found.length === 0) return [];
+
+      // The directories nearest the file get inline content; shallower
+      // overflow (rare: >maxFilesPerRead conventions files on one chain)
+      // becomes pointer notes so the result stays bounded.
+      const inlineFrom = Math.max(0, found.length - maxFilesPerRead);
+      return found.map(({ path, content }, index) => {
+        if (index < inlineFrom || Buffer.byteLength(content, "utf8") > maxBytesPerFile) {
+          return {
+            path,
+            note: `This directory has its own conventions — read ${path} before working here.`,
+          };
+        }
+        return { path, content };
+      });
+    },
+  };
+}

package/src/extract/cache.ts

@@ -0,0 +1,40 @@
+// Stat-validated memo for document extraction. Paging through a long PDF
+// re-runs `read_file` with a new offset each call; without this, every page
+// of the window re-extracts the whole document. Keyed by path, validated by
+// mtime+size, insertion-ordered LRU. Failures are not cached: `compute`
+// throwing stores nothing, so a corrupt file is re-tried after it's fixed.
+
+export interface StatIdentity {
+  readonly mtimeMs: number;
+  readonly size: number;
+}
+
+export interface StatCache<T> {
+  get(key: string, id: StatIdentity, compute: () => Promise<T>): Promise<T>;
+  /** Current entry count, for tests. */
+  size(): number;
+}
+
+export function createStatCache<T>(limit: number): StatCache<T> {
+  const entries = new Map<string, { id: StatIdentity; value: T }>();
+  return {
+    async get(key, id, compute) {
+      const hit = entries.get(key);
+      if (hit !== undefined && hit.id.mtimeMs === id.mtimeMs && hit.id.size === id.size) {
+        // Refresh recency: Map iteration order is insertion order.
+        entries.delete(key);
+        entries.set(key, hit);
+        return hit.value;
+      }
+      const value = await compute();
+      entries.delete(key);
+      entries.set(key, { id, value });
+      if (entries.size > limit) {
+        const oldest = entries.keys().next();
+        if (!oldest.done) entries.delete(oldest.value);
+      }
+      return value;
+    },
+    size: () => entries.size,
+  };
+}

package/src/extract/docx.ts

@@ -0,0 +1,18 @@
+import mammoth from "mammoth";
+
+// DOCX → plain text via mammoth. Raw text (not HTML/markdown): the model
+// wants the words, and `read_file`'s line-numbered view supplies structure.
+
+export type DocxExtraction =
+  | { readonly ok: true; readonly text: string }
+  | { readonly ok: false; readonly reason: string };
+
+export async function extractDocx(buffer: Buffer): Promise<DocxExtraction> {
+  try {
+    const result = await mammoth.extractRawText({ buffer });
+    // mammoth ends every paragraph with "\n\n"; collapse the trailing run.
+    return { ok: true, text: result.value.replace(/\n+$/, "\n") };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/extract/pdf.ts

@@ -0,0 +1,54 @@
+import { openPdf } from "clawpdf";
+
+// PDF → text via clawpdf (PDFium compiled to WASM; no native addons). Pages
+// are joined under explicit markers so the model can cite page numbers and
+// `read`'s offset/limit pagination has stable anchors.
+
+export type PdfExtraction =
+  | { readonly ok: true; readonly text: string; readonly pages: number }
+  | { readonly ok: false; readonly reason: string };
+
+// Shown in place of a page with no text layer. eve tool results are
+// text/json only, so the agent can't fall back to rendering the page for the
+// model the way OpenClaw does — say so instead of showing silent emptiness.
+export const PDF_EMPTY_PAGE_NOTE =
+  "[no text on this page — likely scanned or image-only; rendered pages cannot be attached]";
+
+// Extraction page cap. `read`'s view budget paginates the *text*; this bounds
+// the extraction work itself, so a 10,000-page PDF doesn't churn PDFium for
+// pages nobody asked for. `pages` still reports the true total.
+export const PDF_PAGE_CAP = 200;
+
+export async function extractPdf(
+  bytes: Uint8Array,
+  options: { readonly pageCap?: number } = {},
+): Promise<PdfExtraction> {
+  const pageCap = options.pageCap ?? PDF_PAGE_CAP;
+  let pdf: Awaited<ReturnType<typeof openPdf>>;
+  try {
+    pdf = await openPdf(bytes);
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  try {
+    const pages = pdf.pageCount;
+    const extracted = Math.min(pages, pageCap);
+    const parts: string[] = [];
+    for (let n = 1; n <= extracted; n++) {
+      // PDFium emits \r\n line separators; normalize to the repo's \n.
+      const text = pdf.page(n).text().replaceAll("\r\n", "\n").trim();
+      parts.push(`=== page ${n} of ${pages} ===`);
+      parts.push(text.length > 0 ? text : PDF_EMPTY_PAGE_NOTE);
+    }
+    if (extracted < pages) {
+      parts.push(
+        `[extraction stopped at the page cap — ${extracted} of ${pages} pages extracted]`,
+      );
+    }
+    return { ok: true, text: parts.join("\n"), pages };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  } finally {
+    await pdf[Symbol.asyncDispose]();
+  }
+}

package/src/extract/sheet.ts

@@ -0,0 +1,56 @@
+import { read, utils } from "xlsx";
+
+// Spreadsheet → per-sheet TSV under explicit sheet markers. SheetJS parses the
+// whole family from bytes (xlsx/xlsm zip, legacy xls CFB, OpenDocument ods) —
+// detection picks the family, this module never needs to know which. Cells
+// read as computed values (SheetJS's default), the right answer for an agent
+// reading data. TSV over CSV: tabs survive the line-numbered view better than
+// quoted commas.
+
+export interface SheetMeta {
+  readonly name: string;
+  readonly rows: number;
+  readonly cols: number;
+}
+
+export type SheetExtraction =
+  | { readonly ok: true; readonly text: string; readonly sheets: readonly SheetMeta[] }
+  | { readonly ok: false; readonly reason: string };
+
+// Per-sheet row cap. The 50 KB view budget usually bites first; this keeps a
+// pathological million-row sheet from being TSV-serialized at all.
+export const SHEET_ROW_CAP = 5_000;
+
+export function extractSheets(buffer: Buffer, rowCap: number = SHEET_ROW_CAP): SheetExtraction {
+  let workbook: ReturnType<typeof read>;
+  try {
+    workbook = read(buffer, { type: "buffer", dense: true, sheetRows: rowCap + 1 });
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  const parts: string[] = [];
+  const sheets: SheetMeta[] = [];
+  for (const name of workbook.SheetNames) {
+    const sheet = workbook.Sheets[name];
+    if (sheet === undefined) continue;
+    const ref = sheet["!fullref"] ?? sheet["!ref"];
+    const range = typeof ref === "string" ? utils.decode_range(ref) : null;
+    const rows = range === null ? 0 : range.e.r - range.s.r + 1;
+    const cols = range === null ? 0 : range.e.c - range.s.c + 1;
+    sheets.push({ name, rows, cols });
+    parts.push(`=== sheet "${name}" (${rows} rows x ${cols} cols) ===`);
+    if (rows === 0) {
+      parts.push("[empty sheet]");
+      continue;
+    }
+    const tsv = utils.sheet_to_csv(sheet, { FS: "\t", blankrows: false }).replace(/\n+$/, "");
+    const lines = tsv.split("\n");
+    if (lines.length > rowCap) {
+      parts.push(lines.slice(0, rowCap).join("\n"));
+      parts.push(`[sheet truncated at ${rowCap} rows]`);
+    } else {
+      parts.push(tsv);
+    }
+  }
+  return { ok: true, text: parts.join("\n"), sheets };
+}

package/src/file-kind.ts

@@ -0,0 +1,258 @@
+import { extname } from "node:path";
+
+// Content-first filetype detection for the `read` tool. Magic bytes decide the
+// family — an extension can lie, bytes can't — and the extension only
+// disambiguates within a container family (docx/xlsx/pptx share the same zip
+// magic; xls/doc/ppt share the same CFB magic; telling them apart from content
+// would mean parsing container entries).
+
+export type ImageFormat = "png" | "jpeg" | "gif" | "webp";
+
+/** The MIME type for a detected image format (for data URLs / file parts). */
+export function imageMediaType(format: ImageFormat): string {
+  return `image/${format}`;
+}
+
+/** Video containers `read` detects. Delivery to the model is provider-gated
+ * (see the attach options on the read/webfetch factories). */
+export type VideoFormat = "mp4" | "mov" | "webm" | "mkv" | "avi";
+
+/** The MIME type for a detected video format (for data URLs / file parts). */
+export function videoMediaType(format: VideoFormat): string {
+  switch (format) {
+    case "mp4":
+      return "video/mp4";
+    case "mov":
+      return "video/quicktime";
+    case "webm":
+      return "video/webm";
+    case "mkv":
+      return "video/x-matroska";
+    case "avi":
+      return "video/x-msvideo";
+  }
+}
+
+/** Audio formats `read` detects. Same provider-gated delivery as video. */
+export type AudioFormat = "mp3" | "wav" | "ogg" | "flac" | "m4a";
+
+/** The MIME type for a detected audio format (for data URLs / file parts). */
+export function audioMediaType(format: AudioFormat): string {
+  switch (format) {
+    case "mp3":
+      return "audio/mpeg";
+    case "wav":
+      return "audio/wav";
+    case "ogg":
+      return "audio/ogg";
+    case "flac":
+      return "audio/flac";
+    case "m4a":
+      return "audio/mp4";
+  }
+}
+
+/** Spreadsheet formats SheetJS parses; all route to the sheet extractor. */
+export type SheetFormat = "xlsx" | "xlsm" | "xls" | "ods";
+
+/** Text encodings `read` decodes. UTF-16 is BOM-detected (a NUL-sniff alone
+ * would misclassify UTF-16 text — common in Windows-exported CSVs — as binary). */
+export type TextEncoding = "utf8" | "utf16le" | "utf16be";
+
+export type FileKind =
+  | { readonly kind: "text"; readonly encoding: TextEncoding }
+  | { readonly kind: "pdf" }
+  | { readonly kind: "docx" }
+  | { readonly kind: "sheet"; readonly format: SheetFormat }
+  | { readonly kind: "image"; readonly format: ImageFormat }
+  | { readonly kind: "video"; readonly format: VideoFormat }
+  | { readonly kind: "audio"; readonly format: AudioFormat }
+  | { readonly kind: "binary"; readonly description: string };
+
+// A NUL byte in the first 8 KB marks a file binary — the same heuristic git
+// and ripgrep use (and read-text.ts uses for search).
+const BINARY_SNIFF_BYTES = 8_192;
+
+function startsWith(buf: Buffer, bytes: readonly number[], at = 0): boolean {
+  if (buf.length < at + bytes.length) return false;
+  for (const [i, b] of bytes.entries()) if (buf[at + i] !== b) return false;
+  return true;
+}
+
+const PDF_MAGIC = [0x25, 0x50, 0x44, 0x46, 0x2d]; // %PDF-
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG_MAGIC = [0xff, 0xd8, 0xff];
+const GIF_MAGIC = [0x47, 0x49, 0x46, 0x38]; // GIF8
+const RIFF_MAGIC = [0x52, 0x49, 0x46, 0x46]; // RIFF
+const WEBP_TAG = [0x57, 0x45, 0x42, 0x50]; // WEBP at offset 8
+const AVI_TAG = [0x41, 0x56, 0x49, 0x20]; // "AVI " at offset 8
+const WAVE_TAG = [0x57, 0x41, 0x56, 0x45]; // WAVE at offset 8
+const FTYP_TAG = [0x66, 0x74, 0x79, 0x70]; // ftyp at offset 4 (ISO BMFF: mp4/mov/m4a/heic)
+const EBML_MAGIC = [0x1a, 0x45, 0xdf, 0xa3]; // Matroska/WebM
+const ID3_MAGIC = [0x49, 0x44, 0x33]; // ID3 (mp3 tag header)
+const OGG_MAGIC = [0x4f, 0x67, 0x67, 0x53]; // OggS
+const FLAC_MAGIC = [0x66, 0x4c, 0x61, 0x43]; // fLaC
+const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04]; // PK\x03\x04
+const CFB_MAGIC = [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]; // legacy Office container
+const UTF16LE_BOM = [0xff, 0xfe];
+const UTF16BE_BOM = [0xfe, 0xff];
+
+// ISO BMFF `ftyp` major brands that are still-image containers (HEIF/AVIF),
+// not video — models take png/jpeg/gif/webp, so these get an honest rejection
+// steering toward conversion instead of misclassifying as mp4.
+const BMFF_IMAGE_BRANDS = new Set([
+  "avif",
+  "avis",
+  "heic",
+  "heix",
+  "heim",
+  "heis",
+  "hevc",
+  "hevx",
+  "mif1",
+  "msf1",
+]);
+
+// `M4A `/`M4B `/`M4P ` mark audio-only MP4 containers.
+const BMFF_AUDIO_BRANDS = new Set(["M4A ", "M4B ", "M4P "]);
+
+// Audio-only MP4 extensions, the tiebreak when the brands are generic.
+const BMFF_AUDIO_EXTENSIONS = new Set([".m4a", ".m4b", ".m4p"]);
+
+// Corrupt ftyp sizes shouldn't send the brand scan across the whole file;
+// real ftyp boxes are a few dozen bytes.
+const BMFF_FTYP_SCAN_CAP = 256;
+
+/**
+ * Every brand in the `ftyp` box: the major brand (bytes 8–12) plus the
+ * compatible-brands list (bytes 16 to the box's size, 4 bytes each). Audio
+ * files often carry a generic major brand (`isom`, `mp42`) with `M4A ` only
+ * in the compatible list, so classification must read all of them.
+ */
+function bmffBrands(buf: Buffer): string[] {
+  const boxSize = buf.length >= 4 ? buf.readUInt32BE(0) : 0;
+  const end = Math.min(boxSize, buf.length, BMFF_FTYP_SCAN_CAP);
+  const brands = [buf.subarray(8, 12).toString("latin1")];
+  for (let off = 16; off + 4 <= end; off += 4) {
+    brands.push(buf.subarray(off, off + 4).toString("latin1"));
+  }
+  return brands;
+}
+
+/** Classify an ISO BMFF (`ftyp`) container by its brands. */
+function bmffKind(buf: Buffer, path: string): FileKind {
+  const brands = bmffBrands(buf);
+  const major = brands[0] ?? "";
+  // Like audio below, image brands can hide behind a generic major brand
+  // (HEIC with major `mif1` carries `heic` in the compatible list — and
+  // `mif1` itself is generic enough that some encoders bury both).
+  const imageBrand = brands.find((brand) =>
+    BMFF_IMAGE_BRANDS.has(brand.toLowerCase()),
+  );
+  if (imageBrand !== undefined) {
+    return {
+      kind: "binary",
+      description: `an HEIF/AVIF image (brand "${imageBrand.trim()}") with no supported renderer — convert it to PNG or JPEG`,
+    };
+  }
+  if (brands.some((brand) => BMFF_AUDIO_BRANDS.has(brand))) {
+    return { kind: "audio", format: "m4a" };
+  }
+  if (major.startsWith("qt")) return { kind: "video", format: "mov" };
+  // Generic brands (isom/iso2/mp41/mp42…) say "MP4 container", not what's
+  // inside; honor an audio extension before defaulting to video.
+  if (BMFF_AUDIO_EXTENSIONS.has(extname(path).toLowerCase())) {
+    return { kind: "audio", format: "m4a" };
+  }
+  return { kind: "video", format: "mp4" };
+}
+
+/** Classify an EBML container: WebM vs generic Matroska by DocType. */
+function ebmlKind(buf: Buffer): FileKind {
+  // The DocType string sits in the EBML header, always within the first
+  // few dozen bytes; a plain substring scan beats parsing element lengths.
+  const header = buf.subarray(0, 64).toString("latin1");
+  if (header.includes("webm")) return { kind: "video", format: "webm" };
+  return { kind: "video", format: "mkv" };
+}
+
+function zipKind(path: string): FileKind {
+  switch (extname(path).toLowerCase()) {
+    case ".docx":
+      return { kind: "docx" };
+    case ".xlsx":
+      return { kind: "sheet", format: "xlsx" };
+    case ".xlsm":
+      return { kind: "sheet", format: "xlsm" };
+    case ".ods":
+      return { kind: "sheet", format: "ods" };
+    case ".pptx":
+      return { kind: "binary", description: "a PowerPoint deck (.pptx) with no text extractor" };
+    case ".odt":
+      return {
+        kind: "binary",
+        description: "an OpenDocument text file (.odt) with no text extractor",
+      };
+    case ".epub":
+      return { kind: "binary", description: "an EPUB e-book with no text extractor" };
+    default:
+      return { kind: "binary", description: "a zip archive" };
+  }
+}
+
+function cfbKind(path: string): FileKind {
+  switch (extname(path).toLowerCase()) {
+    case ".xls":
+      return { kind: "sheet", format: "xls" };
+    case ".doc":
+      return {
+        kind: "binary",
+        description: "a legacy Word document (.doc) with no text extractor — convert it to .docx",
+      };
+    case ".ppt":
+      return {
+        kind: "binary",
+        description:
+          "a legacy PowerPoint deck (.ppt) with no text extractor — convert it to .pptx",
+      };
+    default:
+      return { kind: "binary", description: "a legacy Office (CFB) container" };
+  }
+}
+
+export function detectFileKind(buf: Buffer, path: string): FileKind {
+  if (startsWith(buf, PDF_MAGIC)) return { kind: "pdf" };
+  if (startsWith(buf, PNG_MAGIC)) return { kind: "image", format: "png" };
+  if (startsWith(buf, JPEG_MAGIC)) return { kind: "image", format: "jpeg" };
+  if (startsWith(buf, GIF_MAGIC)) return { kind: "image", format: "gif" };
+  if (startsWith(buf, RIFF_MAGIC)) {
+    if (startsWith(buf, WEBP_TAG, 8)) return { kind: "image", format: "webp" };
+    if (startsWith(buf, AVI_TAG, 8)) return { kind: "video", format: "avi" };
+    if (startsWith(buf, WAVE_TAG, 8)) return { kind: "audio", format: "wav" };
+    // Other RIFF payloads fall through to the NUL sniff (→ binary).
+  }
+  if (startsWith(buf, FTYP_TAG, 4)) return bmffKind(buf, path);
+  if (startsWith(buf, EBML_MAGIC)) return ebmlKind(buf);
+  if (startsWith(buf, OGG_MAGIC)) return { kind: "audio", format: "ogg" };
+  if (startsWith(buf, FLAC_MAGIC)) return { kind: "audio", format: "flac" };
+  if (startsWith(buf, ID3_MAGIC)) return { kind: "audio", format: "mp3" };
+  // A bare MPEG frame sync (no ID3 tag) is only 11 set bits — too weak a
+  // signature alone, so require the extension to agree.
+  if (
+    buf.length >= 2 &&
+    buf[0] === 0xff &&
+    ((buf[1] ?? 0) & 0xe0) === 0xe0 &&
+    extname(path).toLowerCase() === ".mp3"
+  ) {
+    return { kind: "audio", format: "mp3" };
+  }
+  if (startsWith(buf, ZIP_MAGIC)) return zipKind(path);
+  if (startsWith(buf, CFB_MAGIC)) return cfbKind(path);
+  // BOM checks must precede the NUL sniff: UTF-16 text is full of NULs.
+  if (startsWith(buf, UTF16LE_BOM)) return { kind: "text", encoding: "utf16le" };
+  if (startsWith(buf, UTF16BE_BOM)) return { kind: "text", encoding: "utf16be" };
+  if (buf.subarray(0, BINARY_SNIFF_BYTES).includes(0)) {
+    return { kind: "binary", description: "binary data (unrecognized format)" };
+  }
+  return { kind: "text", encoding: "utf8" };
+}