agent-nuvira 3.3.3 → 3.3.5

package/dist/tools/extract/pdf.js

@@ -0,0 +1,197 @@
+/**
+ * PDF text extraction — real parsing, table rows preserved.
+ *
+ * Why a parser is required (and why the previous implementation could never work):
+ * a PDF stores its glyphs inside FlateDecode-compressed content streams, positioned
+ * by a text matrix, with the glyph codes mapped back to characters through the
+ * font's encoding/ToUnicode CMap. Reading the file as UTF-8 and stripping
+ * non-printable bytes therefore recovers the *container*, never the text — which
+ * is what `read_extract` used to present as a successful extraction.
+ *
+ * `pdfjs-dist/legacy/build/pdf.mjs` is used rather than the modern build: pdf.js
+ * itself prints "Please use the `legacy` build in Node.js environments" for the
+ * default entry, and the legacy build is the one that avoids browser-only globals.
+ *
+ * Table structure is reconstructed from geometry, because a lab report is a table
+ * and the value/reference-range pairing is the whole point of reading it:
+ *   - items are grouped into lines by their baseline `y` (transform[5]);
+ *   - items on a line are ordered by `x` (transform[4]);
+ *   - the horizontal gap between consecutive items decides the separator —
+ *     nothing (a run split mid-word by kerning), a space, or ` | ` (a column
+ *     boundary).
+ * A page with no text items at all is reported as having no text layer rather
+ * than returned as empty text, so a scanned report is a typed refusal instead of
+ * a silent blank.
+ */
+/** Thrown for inputs pdf.js parsed but could not read (encrypted, corrupt). */
+export class PdfExtractError extends Error {
+    encrypted;
+    constructor(message, encrypted = false) {
+        super(message);
+        this.encrypted = encrypted;
+        this.name = 'PdfExtractError';
+    }
+}
+/** Bump when the reconstruction rules change. */
+export const PDF_EXTRACTOR_VERSION = 1;
+/**
+ * Extract text from A4-ish PDF bytes, page by page.
+ *
+ * `maxChars` bounds the returned text; `truncated` says whether it was hit, so a
+ * caller can never mistake a partial document for the whole one.
+ */
+export async function extractPdfText(bytes, opts) {
+    const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    // A document is untrusted input: no font/image fetching from inside the parser,
+    // and no font faces built for a canvas we never render to.
+    const task = pdfjs.getDocument({
+        data: bytes,
+        useWorkerFetch: false,
+        useSystemFonts: true,
+        disableFontFace: true,
+    });
+    let doc;
+    try {
+        doc = await task.promise;
+    }
+    catch (err) {
+        const name = err?.name ?? '';
+        if (name === 'PasswordException') {
+            throw new PdfExtractError('The PDF is password-protected, so its text could not be read.', true);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new PdfExtractError(`The PDF could not be opened: ${msg}`);
+    }
+    const pages = [];
+    const pagesWithoutText = [];
+    let budget = opts.maxChars;
+    let truncated = false;
+    try {
+        for (let pageNo = 1; pageNo <= doc.numPages; pageNo++) {
+            const page = await doc.getPage(pageNo);
+            const content = await page.getTextContent();
+            const items = toPositionedItems(content.items);
+            const pageText = renderLines(items);
+            if (pageText.length === 0) {
+                pagesWithoutText.push(pageNo);
+                // Kept in the output: a missing page is information, and silently
+                // skipping it would misreport the document's shape.
+                pages.push(`[Page ${pageNo}: no extractable text — this page is an image (scanned) or empty]`);
+                continue;
+            }
+            if (pageText.length > budget) {
+                pages.push(pageText.slice(0, Math.max(0, budget)) + '\n…[page truncated]');
+                truncated = true;
+                budget = 0;
+            }
+            else {
+                pages.push(pageText);
+                budget -= pageText.length;
+            }
+            page.cleanup();
+            if (budget <= 0 && pageNo < doc.numPages) {
+                truncated = true;
+                pages.push(`[Remaining ${doc.numPages - pageNo} page(s) not read — increase the character budget to read them]`);
+                break;
+            }
+        }
+    }
+    finally {
+        // Release the parsed document (and its worker) — the loading task owns the
+        // lifecycle in pdf.js v5+, not the document proxy.
+        await task.destroy().catch(() => undefined);
+    }
+    const text = pages
+        .map((p, i) => (doc.numPages > 1 ? `[Page ${i + 1}]\n${p}` : p))
+        .join('\n\n');
+    return {
+        text,
+        pages: doc.numPages,
+        pagesWithText: doc.numPages - pagesWithoutText.length,
+        pagesWithoutText,
+        truncated,
+    };
+}
+// ─── Internals ──────────────────────────────────────────────────────────────
+/** Reduce pdf.js text items to positioned strings, dropping empty runs. */
+function toPositionedItems(items) {
+    const out = [];
+    for (const raw of items) {
+        const it = raw;
+        const str = it.str ?? '';
+        if (str.trim().length === 0)
+            continue;
+        const t = it.transform;
+        if (!t || t.length < 6)
+            continue;
+        // transform = [a, b, c, d, e, f]; e/f are the run's x/y origin, d is the
+        // vertical scale — effectively the font size for horizontal text.
+        const size = Math.abs(t[3]) || Math.abs(t[0]) || 10;
+        out.push({
+            str,
+            x: t[4],
+            y: t[5],
+            width: it.width ?? 0,
+            size,
+        });
+    }
+    return out;
+}
+/** Group items into visual lines and join each one. */
+function renderLines(items) {
+    if (items.length === 0)
+        return '';
+    // Group by baseline. Tolerance scales with the glyph size so a line whose runs
+    // sit a hair apart vertically is not split into two rows.
+    const lines = [];
+    for (const item of items) {
+        const tol = Math.max(1.5, item.size * 0.4);
+        const line = lines.find((l) => Math.abs(l.y - item.y) <= tol);
+        if (line) {
+            line.items.push(item);
+            // Track the average so a slow drift across a wide table does not create
+            // a new line on every column.
+            line.y = (line.y * (line.items.length - 1) + item.y) / line.items.length;
+        }
+        else {
+            lines.push({ y: item.y, items: [item] });
+        }
+    }
+    // PDF y grows upward, so the topmost line has the largest y.
+    lines.sort((a, b) => b.y - a.y);
+    return lines
+        .map((l) => joinLine(l.items.slice().sort((a, b) => a.x - b.x)))
+        .filter((l) => l.length > 0)
+        .join('\n');
+}
+/**
+ * Join the runs of one line, choosing a separator from the gap between them.
+ * Gap thresholds are expressed in multiples of the glyph size (em).
+ */
+export function joinLine(items) {
+    let out = '';
+    let prev = null;
+    for (const item of items) {
+        const text = item.str.replace(/\s+$/, '');
+        if (text.length === 0)
+            continue;
+        if (prev === null) {
+            out = text;
+            prev = item;
+            continue;
+        }
+        const em = Math.max(prev.size, item.size) || 10;
+        const gap = item.x - (prev.x + prev.width);
+        let sep;
+        if (gap <= em * 0.12)
+            sep = ''; // same word, split by kerning
+        else if (gap <= em * 0.7)
+            sep = ' '; // a space within a phrase
+        else
+            sep = ' | '; // a column boundary
+        out += sep + text;
+        prev = item;
+    }
+    return out.replace(/\s+/g, ' ').trim();
+}
+//# sourceMappingURL=pdf.js.map

package/dist/tools/extract/pdf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf.js","sourceRoot":"","sources":["../../../src/tools/extract/pdf.ts"],"names":[],"mappings":"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"}

package/dist/tools/extract/pptx.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PPTX text extraction via `fflate` + direct XML reading.
+ *
+ * A `.pptx` is a ZIP of XML parts; slide text lives in `ppt/slides/slideN.xml`
+ * inside `<a:t>` runs, grouped into paragraphs by `<a:p>`. The reader unzips in
+ * memory, walks the slides in numeric order, and keeps each `<a:p>` on its own
+ * line — so bullet lines stay distinct rather than collapsing into one blob.
+ *
+ * `fflate` was chosen over a spreadsheet library's bundled ZIP code because it is
+ * a zero-dependency leaf and this is the only place a raw ZIP is needed. Spreadsheet
+ * text deliberately goes through SheetJS instead (see xlsx.ts) so cell formats are
+ * interpreted rather than guessed.
+ */
+export interface PptxExtractResult {
+    text: string;
+    slides: number;
+    truncated: boolean;
+    /** Slide numbers present in the file that carried no text at all. */
+    emptySlides: number[];
+}
+export declare class PptxExtractError extends Error {
+    constructor(message: string);
+}
+export declare function extractPptxText(bytes: Buffer, opts: {
+    maxChars: number;
+}): Promise<PptxExtractResult>;
+/**
+ * Pull the text out of one slide's XML: each `<a:p>` paragraph on its own line,
+ * its `<a:t>` runs concatenated (run splits are kerning, not word breaks).
+ */
+export declare function slideText(xml: string): string;
+//# sourceMappingURL=pptx.d.ts.map

package/dist/tools/extract/pptx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pptx.d.ts","sourceRoot":"","sources":["../../../src/tools/extract/pptx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,iBAAiB,CAAC,CA8C5B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAY7C"}

package/dist/tools/extract/pptx.js

@@ -0,0 +1,77 @@
+/**
+ * PPTX text extraction via `fflate` + direct XML reading.
+ *
+ * A `.pptx` is a ZIP of XML parts; slide text lives in `ppt/slides/slideN.xml`
+ * inside `<a:t>` runs, grouped into paragraphs by `<a:p>`. The reader unzips in
+ * memory, walks the slides in numeric order, and keeps each `<a:p>` on its own
+ * line — so bullet lines stay distinct rather than collapsing into one blob.
+ *
+ * `fflate` was chosen over a spreadsheet library's bundled ZIP code because it is
+ * a zero-dependency leaf and this is the only place a raw ZIP is needed. Spreadsheet
+ * text deliberately goes through SheetJS instead (see xlsx.ts) so cell formats are
+ * interpreted rather than guessed.
+ */
+import { decodeEntities } from './html-text.js';
+export class PptxExtractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PptxExtractError';
+    }
+}
+export async function extractPptxText(bytes, opts) {
+    const { unzipSync, strFromU8 } = await import('fflate');
+    let entries;
+    try {
+        entries = unzipSync(new Uint8Array(bytes));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new PptxExtractError(`The presentation could not be opened as a ZIP container: ${msg}`);
+    }
+    const slideNumbers = Object.keys(entries)
+        .map((path) => /^ppt\/slides\/slide(\d+)\.xml$/.exec(path))
+        .filter((m) => m !== null)
+        .map((m) => Number.parseInt(m[1], 10))
+        .sort((a, b) => a - b);
+    if (slideNumbers.length === 0) {
+        throw new PptxExtractError('No slides were found — the file does not look like a .pptx presentation.');
+    }
+    const parts = [];
+    const emptySlides = [];
+    let used = 0;
+    let truncated = false;
+    for (const n of slideNumbers) {
+        const xml = strFromU8(entries[`ppt/slides/slide${n}.xml`]);
+        const body = slideText(xml);
+        if (body.length === 0) {
+            emptySlides.push(n);
+            continue;
+        }
+        const chunk = `## Slide ${n}\n${body}`;
+        if (used + chunk.length > opts.maxChars) {
+            parts.push(`${chunk.slice(0, Math.max(0, opts.maxChars - used))}\n…[slides truncated]`);
+            truncated = true;
+            break;
+        }
+        parts.push(chunk);
+        used += chunk.length;
+    }
+    return { text: parts.join('\n\n'), slides: slideNumbers.length, truncated, emptySlides };
+}
+/**
+ * Pull the text out of one slide's XML: each `<a:p>` paragraph on its own line,
+ * its `<a:t>` runs concatenated (run splits are kerning, not word breaks).
+ */
+export function slideText(xml) {
+    const paragraphs = xml.split(/<\/a:p>/);
+    return paragraphs
+        .map((p) => {
+        const runs = [...p.matchAll(/<a:t(?:\s[^>]*)?>([\s\S]*?)<\/a:t>/g)]
+            .map((m) => decodeEntities(m[1]))
+            .join('');
+        return runs.replace(/\s+/g, ' ').trim();
+    })
+        .filter((line) => line.length > 0)
+        .join('\n');
+}
+//# sourceMappingURL=pptx.js.map

package/dist/tools/extract/pptx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pptx.js","sourceRoot":"","sources":["../../../src/tools/extract/pptx.ts"],"names":[],"mappings":"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"}

package/dist/tools/extract/xlsx.d.ts

@@ -0,0 +1,47 @@
+/**
+ * XLSX text extraction via SheetJS (`@e965/xlsx`).
+ *
+ * A `.xlsx` is a ZIP of XML parts; the old implementation returned an empty string
+ * and an "requires xlsx library" error (honest, but useless).
+ *
+ * Why SheetJS and not a hand-rolled ZIP+XML reader: `raw: false` makes SheetJS
+ * apply each cell's number format, so a date cell comes out as a date rather than
+ * its serial (45000-ish). Emitting serials to a model reading a health panel would
+ * be exactly the silent-wrongness this workstream exists to remove, and re-deriving
+ * Excel's format rules is not a small job.
+ *
+ * Distribution note: the `xlsx` name on the public npm registry is stale at 0.18.5
+ * (SheetJS moved distribution to cdn.sheetjs.com). `@e965/xlsx` republishes the
+ * official 0.20.3 build on the registry with zero dependencies; it is pinned
+ * exactly in package.json. See TOOL_TRUTHFULNESS_TRACKER.md P1.1.
+ *
+ * Every cell is formatted to a string and rows become `a | b | c` lines, so the
+ * row/column pairing survives — the same shape as the CSV and DOCX readers.
+ */
+export interface XlsxExtractResult {
+    text: string;
+    sheets: string[];
+    /** Total non-empty rows across all sheets. */
+    rows: number;
+    truncated: boolean;
+    /** Sheet names skipped because the character budget ran out. */
+    skippedSheets: string[];
+}
+export declare class XlsxExtractError extends Error {
+    constructor(message: string);
+}
+/**
+ * Re-format every date cell to ISO, and drop its cached rendering (`w`) so it is
+ * recomputed.
+ *
+ * A sheet's own date format is usually `m/d/yy`, which is genuinely ambiguous —
+ * `3/4/26` is a different day either side of the Atlantic, and a model reasoning
+ * about a health trend across months cannot resolve it. `dateNF` alone does not win
+ * against a cell that already carries a format, which is why this is explicit.
+ * Exported for tests.
+ */
+export declare function normalizeDateFormats(sheet: unknown, iso: string): void;
+export declare function extractXlsxText(bytes: Buffer, opts: {
+    maxChars: number;
+}): Promise<XlsxExtractResult>;
+//# sourceMappingURL=xlsx.d.ts.map

package/dist/tools/extract/xlsx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xlsx.d.ts","sourceRoot":"","sources":["../../../src/tools/extract/xlsx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAUtE;AAYD,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAsE5B"}

package/dist/tools/extract/xlsx.js

@@ -0,0 +1,111 @@
+/**
+ * XLSX text extraction via SheetJS (`@e965/xlsx`).
+ *
+ * A `.xlsx` is a ZIP of XML parts; the old implementation returned an empty string
+ * and an "requires xlsx library" error (honest, but useless).
+ *
+ * Why SheetJS and not a hand-rolled ZIP+XML reader: `raw: false` makes SheetJS
+ * apply each cell's number format, so a date cell comes out as a date rather than
+ * its serial (45000-ish). Emitting serials to a model reading a health panel would
+ * be exactly the silent-wrongness this workstream exists to remove, and re-deriving
+ * Excel's format rules is not a small job.
+ *
+ * Distribution note: the `xlsx` name on the public npm registry is stale at 0.18.5
+ * (SheetJS moved distribution to cdn.sheetjs.com). `@e965/xlsx` republishes the
+ * official 0.20.3 build on the registry with zero dependencies; it is pinned
+ * exactly in package.json. See TOOL_TRUTHFULNESS_TRACKER.md P1.1.
+ *
+ * Every cell is formatted to a string and rows become `a | b | c` lines, so the
+ * row/column pairing survives — the same shape as the CSV and DOCX readers.
+ */
+export class XlsxExtractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'XlsxExtractError';
+    }
+}
+/**
+ * Re-format every date cell to ISO, and drop its cached rendering (`w`) so it is
+ * recomputed.
+ *
+ * A sheet's own date format is usually `m/d/yy`, which is genuinely ambiguous —
+ * `3/4/26` is a different day either side of the Atlantic, and a model reasoning
+ * about a health trend across months cannot resolve it. `dateNF` alone does not win
+ * against a cell that already carries a format, which is why this is explicit.
+ * Exported for tests.
+ */
+export function normalizeDateFormats(sheet, iso) {
+    if (!sheet || typeof sheet !== 'object')
+        return;
+    for (const [key, cell] of Object.entries(sheet)) {
+        if (key.startsWith('!') || !cell || typeof cell !== 'object')
+            continue;
+        const c = cell;
+        if (c.t === 'd') {
+            c.z = iso;
+            delete c.w;
+        }
+    }
+}
+export async function extractXlsxText(bytes, opts) {
+    const mod = await import('@e965/xlsx');
+    const XLSX = (mod.default ?? mod);
+    if (typeof XLSX.read !== 'function' || typeof XLSX.utils?.sheet_to_json !== 'function') {
+        throw new XlsxExtractError('The XLSX reader (SheetJS) did not load correctly.');
+    }
+    let workbook;
+    try {
+        // `cellDates` surfaces genuine date cells as type 'd' so their presentation can
+        // be normalised below, instead of leaving them as numbers with a date format.
+        workbook = XLSX.read(bytes, { type: 'buffer', cellDates: true });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new XlsxExtractError(`The spreadsheet could not be read: ${msg}`);
+    }
+    const parts = [];
+    const sheets = [];
+    const skippedSheets = [];
+    let rows = 0;
+    let used = 0;
+    let truncated = false;
+    for (const name of workbook.SheetNames) {
+        if (used >= opts.maxChars) {
+            truncated = true;
+            skippedSheets.push(name);
+            continue;
+        }
+        normalizeDateFormats(workbook.Sheets[name], 'yyyy-mm-dd');
+        const table = XLSX.utils.sheet_to_json(workbook.Sheets[name], {
+            header: 1,
+            raw: false, // apply number formats: dates as dates, not serials
+            dateNF: 'yyyy-mm-dd',
+            defval: '',
+            blankrows: false,
+        });
+        const body = table
+            .map((row) => (Array.isArray(row) ? row.map((c) => String(c ?? '').trim()).join(' | ').trim() : ''))
+            .filter((line) => line.length > 0)
+            .join('\n');
+        if (body.length === 0) {
+            sheets.push(name);
+            continue;
+        }
+        const header = `## Sheet: ${name}`;
+        const chunk = `${header}\n${body}`;
+        const remaining = opts.maxChars - used;
+        if (chunk.length > remaining) {
+            parts.push(`${chunk.slice(0, Math.max(0, remaining))}\n…[sheet truncated]`);
+            truncated = true;
+            used = opts.maxChars;
+        }
+        else {
+            parts.push(chunk);
+            used += chunk.length;
+        }
+        sheets.push(name);
+        rows += table.length;
+    }
+    return { text: parts.join('\n\n'), sheets, rows, truncated, skippedSheets };
+}
+//# sourceMappingURL=xlsx.js.map

package/dist/tools/extract/xlsx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xlsx.js","sourceRoot":"","sources":["../../../src/tools/extract/xlsx.ts"],"names":[],"mappings":"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"}

package/dist/tools/finding-tool.d.ts

@@ -0,0 +1,76 @@
+/**
+ * WS1 (#23) — `finding`: the model states a CLAIM, the gate decides the VERDICT.
+ *
+ * WHY A TOOL, AND WHY IT DOES NOT ACCEPT A VERDICT. `src/findings/verdicts.ts`
+ * is the vocabulary and the gate; it deliberately does not decide who may
+ * produce a finding (`intent-confirm` produces one for a routing decision). This
+ * is the producer for an ORDINARY turn on every surface, and the one design rule
+ * that matters is here: the model may supply the claim, the outcome and the
+ * evidence, and must NOT be able to supply the verdict. A tool argument called
+ * `verdict` would be the exact bypass the gate exists to refuse — the model
+ * typing "CONFIRMED" is the false-success defect with a nicer name — so the
+ * parameter does not exist. `confirmFinding` promotes to CONFIRMED only when at
+ * least one non-blank evidence reference was supplied, and refuses otherwise
+ * with the reason attached.
+ *
+ * WHAT THE MODEL SEES BACK is the rendered finding (`describeFinding`), including
+ * the honest line for a PLAUSIBLE one ("no evidence — reported as PLAUSIBLE, not
+ * verified"). That is the point of returning the render rather than a summary: a
+ * model that states a claim with no evidence is told, in the tool result it must
+ * act on, that the claim was recorded as unverified rather than as fact.
+ *
+ * THE STRUCTURED COPY travels to the surface on the context bus as
+ * `finding:recorded` (the same mechanism `plan_todo` uses for `plan:changed`),
+ * so every surface reports the SAME wire form — which is what
+ * `findings-verdicts@<surface>` is proved against.
+ *
+ * A CALL THAT RECORDED NOTHING IS A FAILURE. A blank claim or a blank outcome
+ * returns `Error:` (the loop's own accounting is `ok: !startsWith('Error:')`),
+ * because a finding with no claim is not a finding — and reporting one as a
+ * successful call would be this repository's recurring defect in miniature.
+ */
+import { z } from 'zod';
+import { type Finding } from '../findings/verdicts.js';
+import type { Tool, ToolContext } from './registry.js';
+/** The registry name — one place, so the toolset/core lists and the tests agree. */
+export declare const FINDING_TOOL_NAME = "finding";
+/**
+ * The bus event carrying the structured wire finding.
+ *
+ * Named `finding:recorded` (past tense) on purpose: the event is emitted AFTER
+ * the gate has decided, so a listener never sees a claim whose verdict is still
+ * being computed — the same convention `plan:changed` follows.
+ */
+export declare const FINDING_EVENT = "finding:recorded";
+/** `finding` args. There is deliberately no `verdict` field — see the header. */
+export declare const findingSchema: z.ZodObject<{
+    claim: z.ZodString;
+    outcome: z.ZodString;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            command: "command";
+            quote: "quote";
+            file: "file";
+            observation: "observation";
+        }>;
+        ref: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type FindingToolArgs = z.infer<typeof findingSchema>;
+/**
+ * Record one finding: build it PLAUSIBLE, let the gate decide, report it.
+ *
+ * Split out from the `Tool` wrapper so the behaviour is testable without the
+ * registry, and so a caller that already has a context (the child process) can
+ * reuse it.
+ */
+export declare function recordFinding(args: FindingToolArgs, ctx?: Pick<ToolContext, 'emit'>): {
+    finding: Finding;
+    text: string;
+} | {
+    error: string;
+};
+/** The `finding` tool as the registry takes it. */
+export declare function createFindingTool(): Tool;
+//# sourceMappingURL=finding-tool.d.ts.map

package/dist/tools/finding-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding-tool.d.ts","sourceRoot":"","sources":["../../src/tools/finding-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAML,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEvD,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAKhD,iFAAiF;AACjF,eAAO,MAAM,aAAa;;;;;;;;;;;;;iBA2BxB,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,eAAe,EACrB,GAAG,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAC9B;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA2CxD;AAED,mDAAmD;AACnD,wBAAgB,iBAAiB,IAAI,IAAI,CAexC"}