@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/src/modules/workspace/file-readers/extract-in-worker.ts

@@ -0,0 +1,183 @@
+import { Worker } from 'node:worker_threads';
+import { exchange, MAX_TIMER_MS, sizingOption, WorkerPool } from '../worker-pool.js';
+import {
+  extractionTimeoutNotice,
+  type IDocumentExtractor,
+  type IsolatedExtraction,
+} from './document-extractor.contract.js';
+import type { ExtractionJob, ExtractionReply } from './extraction-worker.js';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('documents');
+
+/**
+ * Extraction time one document may spend in its worker: the platform's rule,
+ * not a deployment's (decided 2026-10-19). A longer wait is too unresponsive
+ * for a read or a search; the hour a timeout is remembered for is what keeps a
+ * hanging file cheap (see `DocExtractService`).
+ */
+export const EXTRACTION_BUDGET_MS = 10_000;
+
+/** What a document answers when its worker failed outside the parser: never the worker's own error. */
+export const EXTRACTION_WORKER_FAILED = 'could not be read: its extraction failed on the server; try again later';
+
+/** The worker script: a module that calls `serveExtractions` (see `extraction-worker.ts`). */
+export interface ExtractionWorkerEntry {
+  url: URL;
+  /** Node options for the worker thread — a TypeScript entry needs its loader. */
+  execArgv: string[];
+}
+
+export interface WorkerDocumentExtractorOptions {
+  /** Worker time one extraction may spend. Default {@link EXTRACTION_BUDGET_MS}. */
+  budgetMs?: number;
+  /** Workers kept for extractions at once; one past this waits for a worker. Default 4. */
+  poolMax?: number;
+  /**
+   * Extractions that may wait for a worker at once. A waiting extraction holds
+   * the file's bytes, so the queue is capped: past it an extraction is answered
+   * `busy`, and nothing about the file is remembered. Default 32.
+   */
+  maxWaiting?: number;
+  /**
+   * The worker script. Default: the document extractors (`extract.worker`).
+   * A composition serving other extractors — a test's misbehaving parser —
+   * names its own module calling `serveExtractions`.
+   */
+  entry?: ExtractionWorkerEntry;
+}
+
+/**
+ * The one place a document's extractor runs (see {@link IDocumentExtractor}):
+ * a pooled worker thread — the extraction worker kind of the shared
+ * {@link WorkerPool}, which `grep`'s regex matcher is the other kind of —
+ * under a budget per file.
+ *
+ * The bytes are COPIED once on the request thread and the copy transferred,
+ * so the caller's buffer (already hashed for the cache key, and possibly a
+ * slice of Node's shared pool) is never detached. Past the budget the worker is
+ * terminated, which stops a parser mid-loop, and the file answers the timeout
+ * notice. A worker that answers with a dangling rejection, raises, or dies is
+ * never reused; the pool replaces it. A rejection the worker cannot pin on
+ * this job — it had served another before (see `serveExtractions`) — runs the
+ * job again in a fresh worker, so one file's failure is never another's.
+ */
+export class WorkerDocumentExtractor implements IDocumentExtractor {
+  private readonly budgetMs: number;
+  private readonly pool: WorkerPool;
+  private nextJob = 1;
+  private closing = false;
+
+  constructor(opts: WorkerDocumentExtractorOptions = {}) {
+    this.budgetMs = sizingOption('WorkerDocumentExtractor', 'budgetMs', opts.budgetMs ?? EXTRACTION_BUDGET_MS, 1, MAX_TIMER_MS);
+    const entry = opts.entry ?? defaultEntry();
+    this.pool = new WorkerPool(
+      () => new Worker(entry.url, { execArgv: entry.execArgv }),
+      {
+        // Three documents extracted at once each get a worker of their own.
+        poolMax: sizingOption('WorkerDocumentExtractor', 'poolMax', opts.poolMax ?? 4, 1),
+        maxWaiting: sizingOption('WorkerDocumentExtractor', 'maxWaiting', opts.maxWaiting ?? 32, 0),
+      },
+      () => new ExtractionBusyError(),
+    );
+  }
+
+  async extract(extension: string, bytes: Buffer): Promise<IsolatedExtraction> {
+    const first = await this.attempt(extension, bytes, this.budgetMs, false);
+    if (!('unattributed' in first)) return first;
+    // A rejection came while a worker that had served another job ran this one,
+    // and may be that job's: run it again where it is the first job, so what
+    // the file is answered (and remembered) as is its own. With the WHOLE
+    // budget again: the first run was cut short by another file's leftover,
+    // not by this file, and a run given only what was left would time out a
+    // sound document — and remember that timeout for an hour.
+    const again = await this.attempt(extension, bytes, this.budgetMs, true);
+    // In a fresh worker the worker never answers `unattributed`; a crash of the moment if it ever did —
+    // and never with that rejection's words, which may be another file's.
+    return 'unattributed' in again ? { ok: false, failure: 'crashed', message: EXTRACTION_WORKER_FAILED } : again;
+  }
+
+  private async attempt(
+    extension: string,
+    bytes: Buffer,
+    budgetMs: number,
+    fresh: boolean,
+  ): Promise<IsolatedExtraction | { unattributed: true; message: string }> {
+    let w: Worker;
+    try {
+      w = await (fresh ? this.pool.acquireFresh() : this.pool.acquire());
+    } catch {
+      return busy();
+    }
+    const copy = new Uint8Array(bytes);
+    const job: ExtractionJob = { id: this.nextJob++, extension, bytes: copy };
+    const outcome = await exchange<ExtractionReply>(w, job, budgetMs, [copy.buffer]);
+    if ('timeout' in outcome) {
+      this.pool.discard(w);
+      return { ok: false, failure: 'timeout', message: extractionTimeoutNotice(this.budgetMs) };
+    }
+    if ('error' in outcome) {
+      // Raised outside every guard the worker installs — its script failed to
+      // load, or it ran out of memory: a fault of the moment rather than of
+      // the bytes. The worker is ending, and the pool replaces it. What went
+      // wrong is the server's (a module path, a heap size): logged here, and
+      // the reader is told — and the hour remembers — the same words each time.
+      log.error('an extraction worker failed', { err: outcome.error });
+      return { ok: false, failure: 'crashed', message: EXTRACTION_WORKER_FAILED };
+    }
+    if ('exited' in outcome) {
+      if (this.closing) return busy();
+      // Exit 0 is the worker ending itself over an earlier job's straggler that
+      // landed between jobs (see `serveExtractions`), after this job was posted
+      // but before it was taken up: it says nothing about this file. Run it
+      // again in a fresh worker, as for any rejection it cannot pin on this job.
+      if (outcome.exited === 0 && !fresh) return { unattributed: true, message: EXTRACTION_WORKER_FAILED };
+      return {
+        ok: false,
+        failure: 'crashed',
+        message: `could not be read: its extraction stopped unexpectedly (exit code ${outcome.exited})`,
+      };
+    }
+    const { reply } = outcome;
+    if (reply.retire) this.pool.discard(w);
+    else this.pool.release(w);
+    if (reply.unattributed && !reply.ok) return { unattributed: true, message: reply.message };
+    return reply.ok
+      ? { ok: true, summary: reply.summary, text: reply.text }
+      : { ok: false, failure: reply.transient ? 'crashed' : 'parser', message: reply.message };
+  }
+
+  close(): Promise<void> {
+    this.closing = true;
+    return this.pool.close();
+  }
+}
+
+/** Every worker busy and the queue for one full. */
+class ExtractionBusyError extends Error {
+  constructor() {
+    super('every extraction worker is busy');
+    this.name = 'ExtractionBusyError';
+  }
+}
+
+function busy(): IsolatedExtraction {
+  return {
+    ok: false,
+    failure: 'busy',
+    message: 'could not be read: too many documents are being extracted at once; try again in a few seconds',
+  };
+}
+
+/**
+ * The document extractors' worker, beside this module. Run from the build it
+ * is plain JavaScript; run from source (the test suites) it is TypeScript,
+ * which a worker thread loads through `tsx`, as the suites themselves are.
+ */
+function defaultEntry(): ExtractionWorkerEntry {
+  const fromSource = import.meta.url.endsWith('.ts');
+  return {
+    url: new URL(fromSource ? './extract.worker.ts' : './extract.worker.js', import.meta.url),
+    execArgv: fromSource ? ['--import', 'tsx'] : [],
+  };
+}

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

@@ -1,5 +1,8 @@
 import type { ExtractResult } from './doc-extract.types.js';
 import { MAX_DOC_PART_BYTES } from './ooxml-text.js';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('documents');
 
 /**
  * Extract a PDF's TEXT LAYER page by page with pdf.js (`pdfjs-dist`,
@@ -67,9 +70,19 @@ export async function extractPdf(bytes: Buffer): Promise<ExtractResult> {
   // The loading TASK is what gets destroyed at the end, not the document:
   // pdf.js 6 dropped `PDFDocumentProxy.destroy()`, and destroying the task
   // frees the document (and its pages) with it — the shape the viewer uses.
-  let task: Awaited<ReturnType<typeof openPdf>>;
+  let getDocument: PdfJs['getDocument'];
+  try {
+    ({ getDocument } = await loadPdfJs());
+  } catch (err) {
+    // The reader, not the file: a later read must try this file again. Why
+    // it did not load is the server's to know (a module path, a missing
+    // dependency) — logged here, never quoted to the reader.
+    log.error('the PDF reader did not load', { err });
+    return { ok: false, transient: true, message: READER_DID_NOT_LOAD };
+  }
+  let task: ReturnType<typeof openPdf>;
   try {
-    task = await openPdf(bytes);
+    task = openPdf(getDocument, bytes);
   } catch (err) {
     return { ok: false, message: `could not be parsed as a PDF (${(err as Error).message})` };
   }
@@ -167,10 +180,13 @@ export async function extractPdf(bytes: Buffer): Promise<ExtractResult> {
   }
 }
 
+/** What a PDF read answers when pdf.js itself failed to load: the same words, whatever the cause. */
+export const READER_DID_NOT_LOAD = 'could not be read: the PDF reader did not load on the server; try again later';
+
 type PdfJs = typeof import('pdfjs-dist/legacy/build/pdf.mjs');
 let pdfjsPromise: Promise<PdfJs> | undefined;
 
-async function openPdf(bytes: Buffer) {
+function loadPdfJs(): Promise<PdfJs> {
   pdfjsPromise ??= import('pdfjs-dist/legacy/build/pdf.mjs').catch((err: unknown) => {
     // A FAILED load must not be memoized: left in place, the rejected promise
     // would answer every later read and disable PDF extraction for the whole
@@ -178,7 +194,10 @@ async function openPdf(bytes: Buffer) {
     pdfjsPromise = undefined;
     throw err;
   });
-  const { getDocument } = await pdfjsPromise;
+  return pdfjsPromise;
+}
+
+function openPdf(getDocument: PdfJs['getDocument'], bytes: Buffer) {
   // Returns the loading task; the caller awaits `.promise` for the document
   // and destroys the task when done (see `extractPdf`).
   return getDocument({

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

@@ -0,0 +1,5 @@
+import { DOCUMENT_EXTRACTORS } from './document-extractors.js';
+import { serveExtractions } from './extraction-worker.js';
+
+/** The extraction worker's entry: the document extractors, served one job at a time (see `extract-in-worker.ts`). */
+serveExtractions(DOCUMENT_EXTRACTORS);

package/src/modules/workspace/file-readers/extraction-cache.ts

@@ -15,6 +15,15 @@ export function gitBlobSha(bytes: Buffer): string {
   return createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
 }
 
+/**
+ * What the cache holds for a key: the extraction, or the notice a failed one
+ * answered with. A failure with `until` (epoch ms) is remembered only until
+ * then — a lookup past it is a miss; one without is remembered like a success.
+ */
+export type CachedExtraction =
+  | ({ failed?: undefined } & ExtractedDoc)
+  | { failed: true; message: string; until?: number };
+
 /** Default size bound for the on-disk extraction cache. */
 const DEFAULT_MAX_TOTAL_BYTES = 512 * 1024 * 1024; // 512MB
 
@@ -24,7 +33,8 @@ const DEFAULT_MAX_TOTAL_BYTES = 512 * 1024 * 1024; // 512MB
  * re-upload of identical bytes, or the same document on another branch or
  * path, hits the same entry; extension, so identical bytes under another
  * FORMAT never return the wrong extractor's output). One JSON file per entry
- * (`<key>.json` holding the `{ summary, text }`), under a dedicated root
+ * (`<key>.json` holding the `{ summary, text }`, or a failure's
+ * `{ failed, message, until? }`), under a dedicated root
  * that — like the spill
  * store's — sits BESIDE the workspaces root, never inside a workspace and
  * never committed.
@@ -43,16 +53,23 @@ export class DocExtractionCache {
     private readonly maxTotalBytes: number = DEFAULT_MAX_TOTAL_BYTES,
   ) {}
 
-  /** The cached extraction for `sha`, or undefined on miss/corrupt entry. */
-  async get(sha: string): Promise<ExtractedDoc | undefined> {
+  /**
+   * The cached entry for `sha`, or undefined on miss/corrupt entry — and for a
+   * failure remembered only until a moment `now` (epoch ms) has passed.
+   */
+  async get(sha: string, now: number): Promise<CachedExtraction | undefined> {
     try {
       const parsed: unknown = JSON.parse(await fs.readFile(this.entryPath(sha), 'utf8'));
-      if (
-        typeof parsed === 'object' && parsed !== null &&
-        typeof (parsed as ExtractedDoc).summary === 'string' &&
-        typeof (parsed as ExtractedDoc).text === 'string'
-      ) {
-        return { summary: (parsed as ExtractedDoc).summary, text: (parsed as ExtractedDoc).text };
+      if (typeof parsed !== 'object' || parsed === null) return undefined;
+      const entry = parsed as Record<string, unknown>;
+      if (entry.failed === true && typeof entry.message === 'string') {
+        if (entry.until === undefined) return { failed: true, message: entry.message };
+        return typeof entry.until === 'number' && now < entry.until
+          ? { failed: true, message: entry.message, until: entry.until }
+          : undefined;
+      }
+      if (typeof entry.summary === 'string' && typeof entry.text === 'string') {
+        return { summary: entry.summary, text: entry.text };
       }
       return undefined;
     } catch {
@@ -74,11 +91,15 @@ export class DocExtractionCache {
   /** The prune in flight, so concurrent puts share ONE scan instead of racing their own. */
   private pruning: Promise<void> | undefined;
 
-  /** Store an extraction under `sha`; prunes towards the size bound. Never throws. */
-  async put(sha: string, doc: ExtractedDoc): Promise<void> {
+  /** Store an extraction (or a failure) under `sha`; prunes towards the size bound. Never throws. */
+  async put(sha: string, entry: CachedExtraction): Promise<void> {
     try {
       await fs.mkdir(this.root, { recursive: true });
-      const payload = JSON.stringify({ summary: doc.summary, text: doc.text });
+      const payload = JSON.stringify(
+        entry.failed
+          ? { failed: true, message: entry.message, ...(entry.until === undefined ? {} : { until: entry.until }) }
+          : { summary: entry.summary, text: entry.text },
+      );
       await fs.writeFile(this.entryPath(sha), payload, 'utf8');
       this.writtenSinceScan += Buffer.byteLength(payload);
       if (

package/src/modules/workspace/file-readers/extraction-worker.ts

@@ -0,0 +1,86 @@
+import { parentPort } from 'node:worker_threads';
+import type { ExtractFn, ExtractResult } from './doc-extract.types.js';
+
+/** One job, host → worker: the bytes (transferred, not copied) and the format to read them as. */
+export interface ExtractionJob {
+  id: number;
+  extension: string;
+  bytes: Uint8Array;
+}
+
+/**
+ * One answer, worker → host. `retire` says the worker must not run another
+ * job: a parser left a promise rejected behind it, so its state is no longer
+ * something a next job should inherit. `unattributed` says the rejection came
+ * while a worker that had served an earlier job was running this one, so it
+ * may be that earlier job's: the answer says nothing about this job's file,
+ * and the host runs the job again in a fresh worker.
+ */
+export type ExtractionReply = { id: number; retire?: true; unattributed?: true } & ExtractResult;
+
+/**
+ * The worker side of document extraction: answer each job with what its
+ * format's extractor returns, ONE job at a time.
+ *
+ * A parser is contracted to answer for bad content rather than throw, but it
+ * is third-party code: one that throws is answered as the job's failure, and
+ * one that rejects a promise nobody awaits — pdf.js did, on a damaged
+ * cross-reference table, and took a whole server down with it (2026-10-15) —
+ * is caught HERE, in the worker's own process events, and answered as the
+ * job's failure with that rejection's message. Nothing a parser does reaches
+ * the server's process: the worker's events are the worker's.
+ *
+ * A rejection is pinned on a job only when that job is the first this worker
+ * ran: no other job's parser has run here, so the rejection is the job's own.
+ * One arriving while a LATER job runs may be a straggler from an earlier one —
+ * the host hands a worker its next job the moment it answers — so it is
+ * answered `unattributed`, and the host runs the job again where it is first.
+ * One arriving between jobs has nothing left to fail; the worker ends itself
+ * instead of carrying it into the next job.
+ */
+export function serveExtractions(extractors: Readonly<Record<string, ExtractFn>>): void {
+  const port = parentPort;
+  if (!port) throw new Error('serveExtractions runs inside a worker thread.');
+  let current: number | undefined;
+  let served = 0;
+
+  const answer = (reply: ExtractionReply): void => {
+    if (current !== reply.id) return; // already answered — by a dangling rejection, say
+    current = undefined;
+    port.postMessage(reply);
+  };
+  const failCurrent = (reason: unknown): void => {
+    // A straggler from a job already answered: this worker's parser state is
+    // no longer to be trusted, and left running it could pin the rejection on
+    // the NEXT job's file. It ends itself; the pool replaces it. Exit code 0 is
+    // this signal: the host may already have posted the next job, and runs that
+    // job again in a fresh worker rather than answering it as crashed.
+    if (current === undefined) process.exit(0);
+    const ownJob = served === 1;
+    answer({ id: current, ok: false, message: couldNotBeExtracted(reason), retire: true, ...(ownJob ? {} : { unattributed: true }) });
+  };
+  process.on('unhandledRejection', failCurrent);
+  process.on('uncaughtException', failCurrent);
+
+  port.on('message', (job: ExtractionJob) => {
+    current = job.id;
+    served++;
+    void (async () => {
+      let result: ExtractResult;
+      try {
+        const extract = extractors[job.extension];
+        result = extract
+          ? await extract(Buffer.from(job.bytes.buffer, job.bytes.byteOffset, job.bytes.byteLength))
+          : { ok: false, message: `could not be extracted (no extractor reads "${job.extension}" files)` };
+      } catch (err) {
+        result = { ok: false, message: couldNotBeExtracted(err) };
+      }
+      answer({ id: job.id, ...result });
+    })();
+  });
+}
+
+/** The notice a parser's own error earns: the same words a thrown extractor always earned in `read_file`. */
+function couldNotBeExtracted(reason: unknown): string {
+  return `could not be extracted (${reason instanceof Error ? reason.message : String(reason)})`;
+}

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

@@ -1,15 +1,7 @@
 import type { DocExtractService } from './doc-extract.service.js';
 import { DocumentReader } from './document-reader.js';
+import { EMAIL_EXTENSIONS, OFFICE_DOCUMENT_EXTENSIONS } from './document-formats.js';
 import { EmailReader } from './email-reader.js';
-import { extractDocx } from './extract-docx.js';
-import { extractEml } from './extract-eml.js';
-import { extractMsg } from './extract-msg.js';
-import { extractOdp } from './extract-odp.js';
-import { extractOds } from './extract-ods.js';
-import { extractOdt } from './extract-odt.js';
-import { extractPdf } from './extract-pdf.js';
-import { extractPptx } from './extract-pptx.js';
-import { extractXlsx } from './extract-xlsx.js';
 import { FileReaderRegistry } from './file-reader.js';
 import { ImageReader } from './image-reader.js';
 import { BinaryReader, LegacyOfficeReader, TextReader } from './text-reader.js';
@@ -19,24 +11,18 @@ import { BinaryReader, LegacyOfficeReader, TextReader } from './text-reader.js';
  * which extension. Adding a format is one entry here (plus its reader/extract
  * function); read_file, grep and the write-refusal all follow automatically.
  *
- * `docExtract` is the shared content-hash extraction cache the document
- * readers wrap their pure extract functions with (see DocumentReader).
+ * `docExtract` is the shared content-hash extraction service every document
+ * reader extracts through (see DocumentReader); the extractors themselves run
+ * in its worker, never here.
  * Everything not claimed below falls back to the TextReader.
  */
 export function createFileReaderRegistry(docExtract: DocExtractService): FileReaderRegistry {
   return new FileReaderRegistry(
     [
-      new DocumentReader('.docx', extractDocx, docExtract),
-      new DocumentReader('.pptx', extractPptx, docExtract),
-      new DocumentReader('.xlsx', extractXlsx, docExtract),
-      new DocumentReader('.pdf', extractPdf, docExtract),
-      new DocumentReader('.odt', extractOdt, docExtract),
-      new DocumentReader('.odp', extractOdp, docExtract),
-      new DocumentReader('.ods', extractOds, docExtract),
+      ...OFFICE_DOCUMENT_EXTENSIONS.map((ext) => new DocumentReader(ext, docExtract)),
       // Email files ride the same document machinery (cached extraction,
       // greppable, not text-editable) with an email-honest write refusal.
-      new EmailReader('.eml', extractEml, docExtract),
-      new EmailReader('.msg', extractMsg, docExtract),
+      ...EMAIL_EXTENSIONS.map((ext) => new EmailReader(ext, docExtract)),
       new ImageReader(),
       new LegacyOfficeReader(),
       // Bytes no text tool may write: the image formats read_file does not

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

@@ -47,17 +47,27 @@ export const oneLine = displayPath;
  */
 export type FileKind = 'text' | 'document' | 'image' | 'archive' | 'binary';
 
+/** Where a read came from: the workspace whose file it is. A document reader reports a failed extraction there. */
+export interface ReadOrigin {
+  workspaceId: string;
+}
+
 /** A per-format file reader. Register implementations in `createFileReaderRegistry`. */
 export interface FileReader {
   /** The extensions this reader owns — lowercase, with the dot. Empty for the default (fallback) reader. */
   readonly extensions: readonly string[];
-  /** Read `bytes` (read at `path`) into what the read tools return. Must not throw for bad file content. */
-  read(bytes: Buffer, path: string): Promise<ReadResult>;
+  /**
+   * Read `bytes` (read at `path`) into what the read tools return. Must not
+   * throw for bad file content. `origin`, when the caller has one, is the
+   * workspace the read happened in.
+   */
+  read(bytes: Buffer, path: string, origin?: ReadOrigin): Promise<ReadResult>;
   /**
    * Text `grep` may search, or null when there is nothing (cheaply) searchable.
    * Default readers: the decoded text content (TextReader; null on NUL bytes) /
-   * the CACHED extraction (DocumentReader — cold extraction is grep's call,
-   * under its per-walk budget) / absent = never greppable (ImageReader).
+   * absent = never greppable this way (ImageReader; DocumentReader, whose
+   * remembered extraction grep asks for through `cachedRead` — cold
+   * extraction is grep's call, under its per-walk budget).
    */
   greppableText?(bytes: Buffer, path: string): Promise<string | null>;
   /** May the agent TEXT-editing tools (write_file/write_files/edit_file) touch this file? */

package/src/modules/workspace/first-run.ts

@@ -32,7 +32,7 @@ import nodeFs from 'node:fs/promises';
 import { join } from 'node:path';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import { NEW_KNOWLEDGE_BASE_SECTION_ID } from '../agent-guide/index.js';
-import { BevelIgnoreStack } from '../kb-fs/bevel-ignore.js';
+import { BevelIgnoreStack } from '../kb-fs/index.js';
 
 /**
  * The starter guide the template seeds at the top of the knowledge folder

package/src/modules/workspace/git-internals.middleware.ts

@@ -2,7 +2,7 @@ import express from 'express';
 import { GitInternalsError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 /** The query and body fields through which a workspace route names a path. */
 const GIT_GUARDED_QUERY_KEYS = ['path', 'toDir'] as const;

package/src/modules/workspace/index.ts

@@ -35,3 +35,40 @@ export {
   type AgentAccessGate,
 } from './agent-access.gate.js';
 export { SpillStore } from './spill-store.js';
+/**
+ * Document text extraction: the content-hash cache wrap, the extractor
+ * contract it runs extractions through, and the one extractor — a pooled
+ * worker under a budget per file. The composition root wires the product's
+ * pair through this surface; a suite that registers the workspace tools
+ * builds its own the same way.
+ */
+export { DocExtractService } from './file-readers/doc-extract.service.js';
+export type { IDocumentExtractor } from './file-readers/document-extractor.contract.js';
+export { WorkerDocumentExtractor } from './file-readers/extract-in-worker.js';
+/**
+ * What `grep` runs a caller's pattern with: the matcher contract, its one
+ * implementation (ripgrep), and the boot check that ripgrep is there. The
+ * composition root wires them through this surface, as a suite does.
+ */
+export {
+  compareSearchPaths,
+  PATTERN_DIALECT,
+  PatternRefusedError,
+  PatternTooExpensiveError,
+  SearchAbandonedError,
+  SearchBusyError,
+  type FileMatches,
+  type IPatternMatcher,
+  type IPatternSearch,
+  type TreeScope,
+  type TreeSearchOptions,
+} from './pattern-matcher.contract.js';
+export { RipgrepPatternMatcher, type RipgrepPatternMatcherOptions } from './ripgrep-search.js';
+export { assertRipgrep } from './ripgrep-version.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { isTextBytes } from './file-readers/text-reader.js';
+export { isUntouchedStarterPage, knowledgeFolderIsNew } from './first-run.js';
+export type { FirstRunStarter, FirstRunStarterSource, MayRead } from './first-run.js';
+export type { WorkspaceService } from './workspace.service.js';
+export { sessionIdInputOf } from './workspace.tools.js';
+export type { ReadForTool } from './workspace.tools.js';

package/src/modules/workspace/kb-repository.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { logger } from '../../shared/logging.js';
-import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
+import type { GitRunError} from '../../shared/git.contract.js';
+import { type IGitRunner } from '../../shared/git.contract.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import type { AddWorktreeOptions, FetchOptions, IKbRepository } from './kb-repository.contract.js';
@@ -12,7 +13,7 @@ import {
   cloneTrackingConfigArgs,
   ORIGIN_FETCH_REFSPEC,
   SAFE_IMPLICIT_FETCH_ARGS,
-} from '../kb-fs/clone-config.js';
+} from '../kb-fs/index.js';
 
 const log = logger('kb-repository');
 

package/src/modules/workspace/not-found.ts

@@ -1,4 +1,4 @@
-import { ToolError } from '../tool-helpers/tool.contract.js';
+import { ToolError } from '../tool-helpers/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { NOT_FOUND_NEXT_STEP, PathNotFoundError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';

package/src/modules/workspace/nul-scan.ts

@@ -0,0 +1,50 @@
+import { constants as fsConstants, type Stats } from 'node:fs';
+import nodeFs from 'node:fs/promises';
+import type { IPatternSearch } from './pattern-matcher.contract.js';
+
+/** How much of a file {@link holdsNul} holds in memory at once. */
+export const NUL_SCAN_CHUNK = 64 * 1024;
+
+/**
+ * Whether the file at `absolute` holds a NUL, read a chunk at a time and
+ * stopped at the first, under the search's budget: a check that outlives it
+ * is answered as the search is, and reads no further. The file is opened
+ * without following a link, and only the file that was judged (`judged`, its
+ * device and inode) is read: a link or another file swapped in since, here or
+ * in a folder above it, is not, and holds nothing.
+ *
+ * The check a named text file gets from `grep` when ripgrep answers no line
+ * from it (see `workspace.tools.ts`, `grepTextFile`): ripgrep stops reading a
+ * file at the lines the answer can take, so a NUL past them goes unseen by it,
+ * and "no searchable text" must be told from "no match" by this read.
+ */
+export async function holdsNul(absolute: string, judged: Stats, search: IPatternSearch): Promise<boolean> {
+  let stopped = false;
+  try {
+    return await search.charged(async () => {
+      let handle: nodeFs.FileHandle;
+      try {
+        handle = await nodeFs.open(absolute, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+      } catch (err) {
+        // ELOOP: the name is a link now. Anything else is the caller's to answer.
+        if ((err as { code?: unknown } | null)?.code === 'ELOOP') return false;
+        throw err;
+      }
+      try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.dev !== judged.dev || opened.ino !== judged.ino) return false;
+        const chunk = Buffer.alloc(NUL_SCAN_CHUNK);
+        while (!stopped) {
+          const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+          if (bytesRead === 0) return false;
+          if (chunk.subarray(0, bytesRead).includes(0)) return true;
+        }
+        return false;
+      } finally {
+        await handle.close();
+      }
+    });
+  } finally {
+    stopped = true;
+  }
+}