@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/core/research/orchestrator.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Multi-hop research orchestrator.
+ *
+ * `research.deep` without an LLM in the loop: hop 1 searches the original
+ * query, later hops search follow-up queries derived from the previous hop's
+ * top titles (titles are keyword-dense), then the top URLs are extracted.
+ * Every hop's results carry their provider id and URL, so the
+ * reasoning-guard can attribute claims to sources (`sources`).
+ */
+import type { CrawlOpts, CrawlResult, ExtractOpts, ExtractProvider, ExtractResult, ResearchProvider, SearchOpts, SearchResult } from './types.js';
+/** One citable source for reasoning-guard claim grounding. */
+export interface SourceAttribution {
+    readonly url: string;
+    readonly title: string;
+    /** Provider id that produced this source, e.g. `'arxiv'`. */
+    readonly provider: string;
+}
+export interface DeepResearchOptions {
+    /** Total search hops (1–3). Default 2. */
+    readonly maxHops?: number;
+    /** Results per individual query. Default 5. */
+    readonly perQueryLimit?: number;
+    /** Follow-up queries spawned per hop. Default 3. */
+    readonly followUpsPerHop?: number;
+    /** URLs to extract after the search hops. Default 3. */
+    readonly maxExtracts?: number;
+    readonly signal?: AbortSignal;
+}
+export interface DeepResearchResult {
+    readonly query: string;
+    readonly results: readonly SearchResult[];
+    readonly extracts: readonly ExtractResult[];
+    /** Every unique source seen across hops, for reasoning-guard grounding. */
+    readonly sources: readonly SourceAttribution[];
+    readonly hopsCompleted: number;
+    readonly followUpQueries: readonly string[];
+}
+export interface OrchestratorDeps {
+    /** Resolved search chain (see `resolveSearchProviders`). */
+    readonly searchChain: readonly ResearchProvider[];
+    /**
+     * Engines `academic()` may search. Optional: absent means `searchChain`,
+     * which is right for a caller that passes the whole chain in. The gateway
+     * passes the wider free pool instead, because its default chain omits the
+     * scholarly engines for latency — asking for them by name must still work.
+     */
+    readonly academicChain?: readonly ResearchProvider[];
+    /** Resolved extract backend (see `resolveExtractProvider`). */
+    readonly extractProvider: ExtractProvider;
+}
+/**
+ * Run the search chain for one query.
+ *
+ * Paid providers (contiguous leading segment of the chain) run as a
+ * sequential fallback chain — the first non-empty success WINS ALONE: the
+ * free fan-out is skipped, because merging it in buys nothing and costs the
+ * fan-out's latency on top of an answer that is already better ranked. Free
+ * providers run in parallel under one shared budget (`fanOutSignal`) as the
+ * fallback path — the way this chain is configured by default.
+ *
+ * Everything is deduped by URL and clamped to `limit`.
+ */
+export declare function searchChain(query: string, chain: readonly ResearchProvider[], opts?: SearchOpts): Promise<SearchResult[]>;
+/**
+ * Search only the scholarly providers in the chain (`arxiv`, `openalex`,
+ * `semanticScholar`), in parallel under the same shared budget as the
+ * free fan-out. Returns [] when none are present.
+ */
+export declare function academicSearch(query: string, chain: readonly ResearchProvider[], opts?: SearchOpts): Promise<SearchResult[]>;
+export declare class ResearchOrchestrator {
+    #private;
+    constructor(deps: OrchestratorDeps);
+    /** Single-shot search through the chain (used by `research.search`). */
+    search(query: string, opts?: SearchOpts): Promise<SearchResult[]>;
+    /** Scholarly-only search (used by `research.academic`). */
+    academic(query: string, opts?: SearchOpts): Promise<SearchResult[]>;
+    /**
+     * Extract one URL to markdown (used by `research.extract`).
+     *
+     * Security choke point: the URL is user-supplied, so it is validated
+     * and sanitized (`sanitizeExtractUrl`) BEFORE reaching the extract
+     * backend — non-http(s) schemes are rejected and embedded credentials
+     * are stripped so they can never leak to a third-party reader.
+     *
+     * P1-8: URLs that look like documents (`.pdf`/`.docx`) are parsed
+     * locally by `research.parse` (zero-dep, quota-guarded) instead of being
+     * sent to a third-party reader — the bytes never leave the gateway.
+     * `research.deep` routes through here, so deep research gets document
+     * parsing for free.
+     *
+     * `opts.offset` pages through long documents: the provider re-fetches
+     * and serves the next window (see `ExtractOpts`).
+     */
+    extract(url: string, signal?: AbortSignal, opts?: ExtractOpts): Promise<ExtractResult>;
+    /**
+     * Multi-page same-site crawl (used by `research.crawl`).
+     *
+     * BFS over the resolved extract backend; caps are clamped here so the
+     * engine's hard limits (10 pages, depth 2) can never be bypassed by a
+     * larger tool argument. The start URL passes the same
+     * `sanitizeExtractUrl` choke point as `extract()`.
+     */
+    crawl(url: string, opts?: CrawlOpts): Promise<CrawlResult>;
+    /**
+     * Multi-hop deep research (used by `research.deep`).
+     *
+     * Hop 1 searches the original query; each further hop searches follow-up
+     * queries derived from the previous hop's top titles. After the search
+     * hops, the top `maxExtracts` unique URLs are extracted. Sources are
+     * attributed per provider for reasoning-guard grounding.
+     */
+    deep(query: string, opts?: DeepResearchOptions): Promise<DeepResearchResult>;
+}

package/dist/node_modules/@boombot/core/research/orchestrator.js

@@ -0,0 +1,252 @@
+/**
+ * Multi-hop research orchestrator.
+ *
+ * `research.deep` without an LLM in the loop: hop 1 searches the original
+ * query, later hops search follow-up queries derived from the previous hop's
+ * top titles (titles are keyword-dense), then the top URLs are extracted.
+ * Every hop's results carry their provider id and URL, so the
+ * reasoning-guard can attribute claims to sources (`sources`).
+ */
+import { dedupeByUrl } from './config.js';
+import { CRAWL_HARD_MAX_DEPTH, CRAWL_HARD_MAX_PAGES, crawlViaExtract } from './crawl.js';
+import { sanitizeExtractUrl, isHttpUrl } from './http.js';
+import { detectDocumentKindFromUrl, extractDocument } from './parse/index.js';
+const DEFAULT_MAX_HOPS = 2;
+const HARD_MAX_HOPS = 3;
+const DEFAULT_PER_QUERY_LIMIT = 5;
+const DEFAULT_FOLLOW_UPS = 3;
+const DEFAULT_MAX_EXTRACTS = 3;
+/**
+ * Ceiling on one round of parallel provider calls, measured across ALL of
+ * them together rather than per provider. Without it the round costs as much
+ * as its slowest engine (plus that engine's retry), and this is the call the
+ * user sits and waits on. Engines that miss the budget are dropped; whatever
+ * finished in time is still returned.
+ */
+// ponytail: a 4s free-engine budget favors responsiveness; raise it if missing sources outweigh latency.
+const SEARCH_FANOUT_BUDGET_MS = 2_500;
+/** The caller's signal plus the fan-out budget, whichever fires first. */
+function fanOutSignal(signal) {
+    const budget = AbortSignal.timeout(SEARCH_FANOUT_BUDGET_MS);
+    return signal === undefined ? budget : AbortSignal.any([signal, budget]);
+}
+/**
+ * Run the search chain for one query.
+ *
+ * Paid providers (contiguous leading segment of the chain) run as a
+ * sequential fallback chain — the first non-empty success WINS ALONE: the
+ * free fan-out is skipped, because merging it in buys nothing and costs the
+ * fan-out's latency on top of an answer that is already better ranked. Free
+ * providers run in parallel under one shared budget (`fanOutSignal`) as the
+ * fallback path — the way this chain is configured by default.
+ *
+ * Everything is deduped by URL and clamped to `limit`.
+ */
+export async function searchChain(query, chain, opts = {}) {
+    opts.signal?.throwIfAborted();
+    const limit = Math.min(Math.max(opts.limit ?? 8, 1), 20);
+    const paid = [];
+    const free = [];
+    let seenFree = false;
+    for (const provider of chain) {
+        if (provider.kind === 'paid' && !seenFree)
+            paid.push(provider);
+        else {
+            seenFree = true;
+            if (provider.kind === 'free')
+                free.push(provider);
+        }
+    }
+    for (const provider of paid) {
+        try {
+            opts.signal?.throwIfAborted();
+            const paidResults = await provider.search(query, { limit, signal: opts.signal });
+            opts.signal?.throwIfAborted();
+            // An empty success is not an answer: fall through to the free
+            // fan-out instead of returning nothing at all.
+            if (paidResults.length > 0)
+                return dedupeByUrl(paidResults).slice(0, limit);
+        }
+        catch {
+            // fall through to the next paid provider
+        }
+    }
+    opts.signal?.throwIfAborted();
+    const enough = new AbortController();
+    const signal = AbortSignal.any([fanOutSignal(opts.signal), enough.signal]);
+    const freeResults = [];
+    await Promise.allSettled(free.map(async (provider) => {
+        const results = await provider.search(query, { limit, signal });
+        freeResults.push(...results);
+        // Do not pay the slowest provider's latency once the requested result count is met.
+        if (dedupeByUrl(freeResults).length >= limit)
+            enough.abort();
+    }));
+    opts.signal?.throwIfAborted();
+    return dedupeByUrl(freeResults).slice(0, limit);
+}
+/**
+ * Search only the scholarly providers in the chain (`arxiv`, `openalex`,
+ * `semanticScholar`), in parallel under the same shared budget as the
+ * free fan-out. Returns [] when none are present.
+ */
+export async function academicSearch(query, chain, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 8, 1), 20);
+    const academicIds = new Set(['arxiv', 'openalex', 'semanticScholar']);
+    const academic = chain.filter((p) => p.kind === 'free' && academicIds.has(p.id));
+    const settled = await Promise.allSettled(academic.map((provider) => provider.search(query, { limit, signal: fanOutSignal(opts.signal) })));
+    const results = [];
+    for (const outcome of settled) {
+        if (outcome.status === 'fulfilled')
+            results.push(...outcome.value);
+    }
+    return dedupeByUrl(results).slice(0, limit);
+}
+/** Derive follow-up queries from hop results: top titles, trimmed to keywords. */
+function deriveFollowUps(query, results, count) {
+    const out = [];
+    for (const r of results) {
+        if (out.length >= count)
+            break;
+        if (r.title === '' || r.title === query)
+            continue;
+        const title = r.title.length > 80 ? r.title.slice(0, 80) : r.title;
+        out.push(`${query} — ${title}`);
+    }
+    return out;
+}
+function toAttribution(r) {
+    return { url: r.url, title: r.title, provider: r.source };
+}
+export class ResearchOrchestrator {
+    #deps;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /** Single-shot search through the chain (used by `research.search`). */
+    search(query, opts = {}) {
+        return searchChain(query, this.#deps.searchChain, opts);
+    }
+    /** Scholarly-only search (used by `research.academic`). */
+    academic(query, opts = {}) {
+        return academicSearch(query, this.#deps.academicChain ?? this.#deps.searchChain, opts);
+    }
+    /**
+     * Extract one URL to markdown (used by `research.extract`).
+     *
+     * Security choke point: the URL is user-supplied, so it is validated
+     * and sanitized (`sanitizeExtractUrl`) BEFORE reaching the extract
+     * backend — non-http(s) schemes are rejected and embedded credentials
+     * are stripped so they can never leak to a third-party reader.
+     *
+     * P1-8: URLs that look like documents (`.pdf`/`.docx`) are parsed
+     * locally by `research.parse` (zero-dep, quota-guarded) instead of being
+     * sent to a third-party reader — the bytes never leave the gateway.
+     * `research.deep` routes through here, so deep research gets document
+     * parsing for free.
+     *
+     * `opts.offset` pages through long documents: the provider re-fetches
+     * and serves the next window (see `ExtractOpts`).
+     */
+    extract(url, signal, opts) {
+        let safeUrl;
+        try {
+            safeUrl = sanitizeExtractUrl(url);
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+        if (detectDocumentKindFromUrl(safeUrl) !== undefined) {
+            return extractDocument(safeUrl, this.#deps.extractProvider, signal, opts);
+        }
+        return this.#deps.extractProvider.extract(safeUrl, signal, opts);
+    }
+    /**
+     * Multi-page same-site crawl (used by `research.crawl`).
+     *
+     * BFS over the resolved extract backend; caps are clamped here so the
+     * engine's hard limits (10 pages, depth 2) can never be bypassed by a
+     * larger tool argument. The start URL passes the same
+     * `sanitizeExtractUrl` choke point as `extract()`.
+     */
+    crawl(url, opts = {}) {
+        const clamped = {
+            maxPages: Math.min(Math.max(opts.maxPages ?? 5, 1), CRAWL_HARD_MAX_PAGES),
+            depth: Math.min(Math.max(opts.depth ?? 2, 1), CRAWL_HARD_MAX_DEPTH),
+            perPageChars: opts.perPageChars,
+            signal: opts.signal,
+        };
+        return crawlViaExtract(url, this.#deps.extractProvider, clamped);
+    }
+    /**
+     * Multi-hop deep research (used by `research.deep`).
+     *
+     * Hop 1 searches the original query; each further hop searches follow-up
+     * queries derived from the previous hop's top titles. After the search
+     * hops, the top `maxExtracts` unique URLs are extracted. Sources are
+     * attributed per provider for reasoning-guard grounding.
+     */
+    async deep(query, opts = {}) {
+        const maxHops = Math.min(Math.max(opts.maxHops ?? DEFAULT_MAX_HOPS, 1), HARD_MAX_HOPS);
+        const perQueryLimit = Math.min(Math.max(opts.perQueryLimit ?? DEFAULT_PER_QUERY_LIMIT, 1), 10);
+        const followUpsPerHop = Math.min(Math.max(opts.followUpsPerHop ?? DEFAULT_FOLLOW_UPS, 1), 5);
+        const maxExtracts = Math.min(Math.max(opts.maxExtracts ?? DEFAULT_MAX_EXTRACTS, 0), 5);
+        const signal = opts.signal;
+        let all = await this.search(query, { limit: perQueryLimit * 2, signal });
+        let previousHop = all;
+        const searched = new Set([query]);
+        const followUpQueries = [];
+        let hopsCompleted = 1;
+        for (let hop = 2; hop <= maxHops; hop += 1) {
+            if (signal?.aborted === true)
+                break;
+            const followUps = deriveFollowUps(query, previousHop, previousHop.length)
+                .filter((q) => !searched.has(q))
+                .filter((q, i, queries) => queries.indexOf(q) === i)
+                .slice(0, followUpsPerHop);
+            if (followUps.length === 0)
+                break;
+            for (const q of followUps)
+                searched.add(q);
+            followUpQueries.push(...followUps);
+            const settled = await Promise.allSettled(followUps.map((q) => searchChain(q, this.#deps.searchChain, {
+                limit: perQueryLimit,
+                signal,
+            })));
+            previousHop = dedupeByUrl(settled.flatMap((outcome) => outcome.status === 'fulfilled' ? outcome.value : []));
+            all = dedupeByUrl([...all, ...previousHop]);
+            hopsCompleted = hop;
+        }
+        const urls = dedupeByUrl(all)
+            .filter((r) => isHttpUrl(r.url))
+            .slice(0, maxExtracts)
+            .map((r) => r.url);
+        const extracted = await Promise.allSettled(
+        // Route through this.extract() so every URL — including ones that
+        // came from search results — passes the sanitizeExtractUrl choke
+        // point. A rejected URL settles as a rejection, never an extract.
+        urls.map((u) => this.extract(u, signal)));
+        const extracts = [];
+        for (const outcome of extracted) {
+            if (outcome.status === 'fulfilled')
+                extracts.push(outcome.value);
+        }
+        const results = dedupeByUrl(all);
+        const seen = new Set();
+        const sources = [];
+        for (const r of results) {
+            if (seen.has(r.url))
+                continue;
+            seen.add(r.url);
+            sources.push(toAttribution(r));
+        }
+        return {
+            query,
+            results,
+            extracts,
+            sources,
+            hopsCompleted,
+            followUpQueries,
+        };
+    }
+}

package/dist/node_modules/@boombot/core/research/parse/docx.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal DOCX text extractor — hand-written, zero npm dependencies.
+ *
+ * A `.docx` is a ZIP (OOXML) whose prose lives in `word/document.xml` as
+ * `<w:t>` runs inside `<w:p>` paragraphs. This module ships its own tiny
+ * ZIP reader (central-directory walk + `node:zlib` inflateRaw) instead of
+ * taking an npm zip library — one less supply-chain dependency, and every
+ * decompression goes through `./guards.ts` quotas (the declared-size check
+ * first, then the streaming actual-bytes check).
+ *
+ * Honestly scoped: body paragraphs (+ tables as tab/newline-separated text),
+ * headers/footers/footnotes are NOT read, complex fields are flattened to
+ * their visible text. That's the text a researcher needs from a document.
+ */
+export interface DocxExtractedText {
+    readonly text: string;
+    readonly title: string;
+}
+/**
+ * Extract text from DOCX `bytes`. Throws {@link DocumentParseError} with
+ * `CORRUPT_DOCUMENT` (not a zip / no document.xml), `ARCHIVE_LIMIT`
+ * (zip bomb), `DOCUMENT_TOO_LARGE`, or `UNSUPPORTED_TYPE` (encrypted/zip64).
+ */
+export declare function extractDocxText(bytes: Uint8Array): Promise<DocxExtractedText>;

package/dist/node_modules/@boombot/core/research/parse/docx.js

@@ -0,0 +1,183 @@
+/**
+ * Minimal DOCX text extractor — hand-written, zero npm dependencies.
+ *
+ * A `.docx` is a ZIP (OOXML) whose prose lives in `word/document.xml` as
+ * `<w:t>` runs inside `<w:p>` paragraphs. This module ships its own tiny
+ * ZIP reader (central-directory walk + `node:zlib` inflateRaw) instead of
+ * taking an npm zip library — one less supply-chain dependency, and every
+ * decompression goes through `./guards.ts` quotas (the declared-size check
+ * first, then the streaming actual-bytes check).
+ *
+ * Honestly scoped: body paragraphs (+ tables as tab/newline-separated text),
+ * headers/footers/footnotes are NOT read, complex fields are flattened to
+ * their visible text. That's the text a researcher needs from a document.
+ */
+import { Buffer } from 'node:buffer';
+import { DecompressionQuota, DocumentParseError, MAX_ZIP_ENTRIES, MAX_ZIP_ENTRY_BYTES, assertDeclaredEntrySizes, assertDocumentSize, } from './guards.js';
+const ZIP_LOCAL_SIG = 0x04034b50;
+const ZIP_CENTRAL_SIG = 0x02014b50;
+const ZIP_EOCD_SIG = 0x06054b50;
+function parseCentralDirectory(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    // The end-of-central-directory record sits in the last 64KiB + 22 bytes.
+    const minPos = Math.max(0, bytes.length - 65557);
+    let eocd = -1;
+    for (let i = bytes.length - 22; i >= minPos; i -= 1) {
+        if (view.getUint32(i, true) === ZIP_EOCD_SIG) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0) {
+        throw new DocumentParseError('CORRUPT_DOCUMENT', 'ZIP end-of-central-directory not found.');
+    }
+    const count = view.getUint16(eocd + 10, true);
+    const cdOffset = view.getUint32(eocd + 16, true);
+    if (count > MAX_ZIP_ENTRIES) {
+        throw new DocumentParseError('ARCHIVE_LIMIT', `ZIP declares ${count} entries (cap ${MAX_ZIP_ENTRIES}, possible zip bomb).`);
+    }
+    if (cdOffset > bytes.length) {
+        throw new DocumentParseError('CORRUPT_DOCUMENT', 'ZIP central directory offset is out of bounds.');
+    }
+    const entries = [];
+    let pos = cdOffset;
+    for (let e = 0; e < count; e += 1) {
+        if (pos + 46 > bytes.length) {
+            throw new DocumentParseError('CORRUPT_DOCUMENT', 'ZIP central directory is truncated.');
+        }
+        if (view.getUint32(pos, true) !== ZIP_CENTRAL_SIG) {
+            throw new DocumentParseError('CORRUPT_DOCUMENT', `Bad central directory signature at entry ${e}.`);
+        }
+        const flags = view.getUint16(pos + 8, true);
+        const method = view.getUint16(pos + 10, true);
+        const compressedSize = view.getUint32(pos + 20, true);
+        const uncompressedSize = view.getUint32(pos + 24, true);
+        const nameLen = view.getUint16(pos + 28, true);
+        const extraLen = view.getUint16(pos + 30, true);
+        const commentLen = view.getUint16(pos + 32, true);
+        const localOffset = view.getUint32(pos + 42, true);
+        if (compressedSize === 0xffffffff ||
+            uncompressedSize === 0xffffffff) {
+            throw new DocumentParseError('UNSUPPORTED_TYPE', 'ZIP64 archives are not supported.');
+        }
+        if ((flags & 0x1) !== 0) {
+            throw new DocumentParseError('UNSUPPORTED_TYPE', 'Encrypted ZIP entries are not supported.');
+        }
+        if ((flags & 0x8) !== 0) {
+            // Bit 3 = sizes live in a data descriptor after the data; a
+            // central-directory walk cannot locate the data safely.
+            throw new DocumentParseError('CORRUPT_DOCUMENT', 'ZIP entry uses a data descriptor (streaming layout not supported).');
+        }
+        const name = Buffer.from(bytes.slice(pos + 46, pos + 46 + nameLen)).toString('utf8');
+        entries.push({ name, method, compressedSize, uncompressedSize, localOffset });
+        pos += 46 + nameLen + extraLen + commentLen;
+    }
+    return entries;
+}
+async function readEntry(bytes, entry, quota) {
+    // Declared-size check FIRST (cheap zip-bomb reject)...
+    assertDeclaredEntrySizes({
+        compressedSize: entry.compressedSize,
+        uncompressedSize: entry.uncompressedSize,
+        method: entry.method,
+        label: entry.name,
+    });
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const lo = entry.localOffset;
+    if (lo + 30 > bytes.length || view.getUint32(lo, true) !== ZIP_LOCAL_SIG) {
+        throw new DocumentParseError('CORRUPT_DOCUMENT', `Bad local header for ZIP entry '${entry.name}'.`);
+    }
+    const nameLen = view.getUint16(lo + 26, true);
+    const extraLen = view.getUint16(lo + 28, true);
+    const dataStart = lo + 30 + nameLen + extraLen;
+    const dataEnd = dataStart + entry.compressedSize;
+    if (dataEnd > bytes.length) {
+        throw new DocumentParseError('CORRUPT_DOCUMENT', `ZIP entry '${entry.name}' data extends past end of file.`);
+    }
+    const data = bytes.slice(dataStart, dataEnd);
+    if (entry.method === 0) {
+        // ...then actual-bytes accounting even for stored entries.
+        quota.trackRaw(data.length, entry.name);
+        return data;
+    }
+    // ...then the streaming actual-bytes check inside inflateRaw.
+    return quota.inflateRaw(data, MAX_ZIP_ENTRY_BYTES, entry.name);
+}
+function decodeXmlEntities(s) {
+    return s
+        .replace(/&(lt|gt|amp|quot|apos);/g, (m, name) => {
+        switch (name) {
+            case 'lt': return '<';
+            case 'gt': return '>';
+            case 'amp': return '&';
+            case 'quot': return '"';
+            case 'apos': return "'";
+            default: return m;
+        }
+    })
+        .replace(/&#(\d+);/g, (_m, dec) => String.fromCodePoint(parseInt(dec, 10)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_m, hex) => String.fromCodePoint(parseInt(hex, 16)));
+}
+/**
+ * Flatten `word/document.xml` to text: `<w:t>` runs are the prose,
+ * `</w:p>` ends a paragraph, `<w:br/>` a line break, `<w:tab/>` a tab,
+ * table cells/rows get tab/newline separators so tables stay readable.
+ */
+function docxXmlToText(xml) {
+    const parts = [];
+    const re = /<\/w:p\s*>|<\/w:tr\s*>|<\/w:tc\s*>|<w:br\s*\/>|<w:tab\s*\/>|<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t\s*>/g;
+    for (;;) {
+        const m = re.exec(xml);
+        if (m === null)
+            break;
+        const tok = m[0];
+        if (tok.startsWith('</w:p') || tok.startsWith('</w:tr') || tok.startsWith('<w:br')) {
+            parts.push('\n');
+        }
+        else if (tok.startsWith('</w:tc') || tok.startsWith('<w:tab')) {
+            parts.push('\t');
+        }
+        else {
+            parts.push(decodeXmlEntities(m[1] ?? ''));
+        }
+    }
+    return parts.join('');
+}
+function findDcTitle(coreXml) {
+    const m = /<dc:title[^>]*>([\s\S]*?)<\/dc:title>/.exec(coreXml);
+    return m !== null ? decodeXmlEntities(m[1] ?? '').trim() : '';
+}
+/**
+ * Extract text from DOCX `bytes`. Throws {@link DocumentParseError} with
+ * `CORRUPT_DOCUMENT` (not a zip / no document.xml), `ARCHIVE_LIMIT`
+ * (zip bomb), `DOCUMENT_TOO_LARGE`, or `UNSUPPORTED_TYPE` (encrypted/zip64).
+ */
+export async function extractDocxText(bytes) {
+    assertDocumentSize(bytes.length, 'DOCX');
+    if (bytes.length < 4 ||
+        bytes[0] !== 0x50 ||
+        bytes[1] !== 0x4b ||
+        bytes[2] !== 0x03 ||
+        bytes[3] !== 0x04) {
+        throw new DocumentParseError('CORRUPT_DOCUMENT', 'Not a DOCX file (missing ZIP magic).');
+    }
+    const entries = parseCentralDirectory(bytes);
+    const quota = new DecompressionQuota();
+    const documentEntry = entries.find((e) => e.name === 'word/document.xml');
+    if (documentEntry === undefined) {
+        throw new DocumentParseError('CORRUPT_DOCUMENT', "ZIP has no 'word/document.xml' — not a Word document.");
+    }
+    const documentXml = Buffer.from(await readEntry(bytes, documentEntry, quota)).toString('utf8');
+    const text = docxXmlToText(documentXml);
+    let title = '';
+    const coreEntry = entries.find((e) => e.name === 'docProps/core.xml');
+    if (coreEntry !== undefined) {
+        try {
+            title = findDcTitle(Buffer.from(await readEntry(bytes, coreEntry, quota)).toString('utf8'));
+        }
+        catch {
+            // A broken core.xml must not fail the whole document.
+        }
+    }
+    return { text, title };
+}

package/dist/node_modules/@boombot/core/research/parse/guards.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Security guards for document parsing (`research.parse`).
+ *
+ * Parsing attacker-influenced bytes — a URL the model or user asked
+ * `research.extract` to read — is an attack surface: zip bombs, decompression
+ * bombs hidden in PDF content streams, and absurd entry counts. This module
+ * is the choke point every parser runs through: the same role
+ * `sanitizeExtractUrl` plays for URL inputs in `orchestrator.extract()`.
+ *
+ * Two lines of defense, because declared sizes are attacker-controlled:
+ * 1. Declared sizes are checked BEFORE inflating — cheaply rejects 42.zip-style
+ *    entries whose headers claim gigabytes.
+ * 2. Actual output bytes are counted DURING streaming inflation — closes the
+ *    understated/zero-size hole (the adm-zip CVE-2026-77301 class of bug, where
+ *    a streaming path never checked accumulated output).
+ *
+ * Fail-closed: any cap breach throws `DocumentParseError`; a parser never
+ * returns a partial buffer.
+ */
+/**
+ * Machine-readable failure codes. Additive-first: new codes are added,
+ * never renamed.
+ */
+export type DocumentParseErrorCode = 'UNSUPPORTED_TYPE' | 'DOCUMENT_TOO_LARGE' | 'ARCHIVE_LIMIT' | 'CORRUPT_DOCUMENT';
+export declare class DocumentParseError extends Error {
+    readonly code: DocumentParseErrorCode;
+    constructor(code: DocumentParseErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * Hard cap on raw document bytes accepted for parsing. Matches
+ * `DEFAULT_MAX_RESPONSE_BYTES` in `../http.ts` so a document fetch can never
+ * exceed what a normal extract response may already hold.
+ */
+export declare const MAX_DOCUMENT_BYTES = 5242880;
+/** Max entries in a ZIP central directory — a docx rarely has a few hundred. */
+export declare const MAX_ZIP_ENTRIES = 2048;
+/** Max declared uncompressed size of a single ZIP entry. */
+export declare const MAX_ZIP_ENTRY_BYTES = 20971520;
+/** Max total decompressed bytes across every inflated entry/stream of one document. */
+export declare const MAX_TOTAL_DECOMPRESSED_BYTES = 52428800;
+/**
+ * Declared compression ratio above this is treated as a bomb. Legitimate
+ * docx XML compresses ~5–20:1; real zip bombs start around 100,000:1, so
+ * 100:1 rejects every known bomb shape with wide margin for legit files.
+ */
+export declare const MAX_COMPRESSION_RATIO = 100;
+/** Max content streams inflated from a single PDF. */
+export declare const MAX_PDF_STREAMS = 20000;
+/**
+ * Ceiling on extracted plain-text characters — defense-in-depth past the
+ * byte quotas, so parser output can never blow up turn context on its own.
+ */
+export declare const MAX_EXTRACTED_CHARS = 200000;
+/** Reject an input buffer that exceeds {@link MAX_DOCUMENT_BYTES}. */
+export declare function assertDocumentSize(byteLength: number, label?: string): void;
+/**
+ * Check a ZIP entry's DECLARED sizes before touching its data.
+ * Cheap first line of defense — rejects 42.zip-style headers outright.
+ */
+export declare function assertDeclaredEntrySizes(args: {
+    readonly compressedSize: number;
+    readonly uncompressedSize: number;
+    readonly method: number;
+    readonly label: string;
+}): void;
+/**
+ * Tracks the running total of decompressed bytes for one document and
+ * inflates raw-deflate blocks with both per-entry and total caps enforced
+ * DURING decompression (streaming). Declared sizes are attacker-controlled,
+ * so this second line of defense measures actual output — an entry that
+ * understates its size still trips the cap mid-inflate instead of landing
+ * a huge buffer in memory first.
+ */
+export declare class DecompressionQuota {
+    #private;
+    /** Bytes inflated so far across all entries/streams of this document. */
+    get usedTotal(): number;
+    /** Account `byteLength` raw (stored, not inflated) bytes against the total quota. */
+    trackRaw(byteLength: number, label: string): void;
+    /**
+     * Inflate one zlib-wrapped deflate block (PDF `/FlateDecode` is zlib /
+     * RFC 1950 per the PDF spec, NOT raw deflate).
+     */
+    inflate(compressed: Uint8Array, maxEntryBytes: number, label: string): Promise<Uint8Array>;
+    /**
+     * Inflate one raw deflate block (ZIP entry data has no zlib wrapper).
+     */
+    inflateRaw(compressed: Uint8Array, maxEntryBytes: number, label: string): Promise<Uint8Array>;
+}