@project-ava-supernova/core 0.2.71

package/dist/tools/paper-fetch.js

@@ -0,0 +1,236 @@
+import { fetchPaper } from '../papers/paper-fetcher.js';
+import { arxivPdfUrl } from '../papers/arxiv-client.js';
+import { logger } from '../core/logger.js';
+/**
+ * paper_fetch_full_text — read-only paper fetcher used by the Tutor
+ * (and any other persona/mode) when the abstract isn't enough to give
+ * a real explanation.
+ *
+ * For arXiv preprints we fetch the rendered HTML version when available
+ * (`https://arxiv.org/html/{id}`) and structure-extract section
+ * headings + paragraph text. arXiv's HTML coverage is ~70% of recent
+ * preprints; falls back to abstract-only for older ones or papers
+ * without HTML rendering.
+ *
+ * For non-arXiv papers we return abstract + open-access PDF URL when
+ * known. Full PDF parsing isn't done in 1.0 — adding pdf-parse to the
+ * core dependency tree would blow up the bundle and PDFs vary too
+ * much for reliable text extraction without per-publisher logic. The
+ * Tutor can still cite sections from the abstract and run a web_search
+ * on specific claims for verification.
+ *
+ * Read-only, safe risk level, no confirmation required. Network-only
+ * tool — never touches the filesystem or runs commands.
+ */
+const ARXIV_HTML_BASE = 'https://arxiv.org/html';
+const MAX_HTML_BYTES = 2 * 1024 * 1024; // 2MB cap on the HTML fetch
+const MAX_OUTPUT_CHARS = 25_000; // ~6k tokens — fits comfortably in any context
+const SECTION_PARA_LIMIT = 4; // First N paragraphs per section to extract
+/**
+ * Strip HTML tags + collapse whitespace. Targeted at arXiv's clean
+ * LaTeX-to-HTML output, not arbitrary web pages — so we don't need
+ * a full DOM parser to get usable text.
+ */
+function stripHtml(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[\s\S]*?<\/style>/gi, '')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Pull section headings and the first few paragraphs under each from
+ * arXiv's HTML output. arXiv's structure is consistent: `<h2>` /
+ * `<h3>` for section titles, `<p>` for body. We grab everything
+ * between successive headings, dropping math-block markers and
+ * citations the abstract layer can't show anyway.
+ */
+function extractArxivSections(html) {
+    const sections = [];
+    // Slice on h2/h3 boundaries — keeps the heading attached to its body.
+    const headingRe = /<h([23])[^>]*>([\s\S]*?)<\/h\1>/gi;
+    const matches = [...html.matchAll(headingRe)];
+    for (let i = 0; i < matches.length; i++) {
+        const m = matches[i];
+        const heading = stripHtml(m[2]).trim();
+        if (!heading || heading.length > 200)
+            continue;
+        const start = m.index + m[0].length;
+        const end = i + 1 < matches.length ? matches[i + 1].index : html.length;
+        const body = html.slice(start, end);
+        const paras = [...body.matchAll(/<p[^>]*>([\s\S]*?)<\/p>/gi)]
+            .map(p => stripHtml(p[1]))
+            .filter(t => t.length > 40)
+            .slice(0, SECTION_PARA_LIMIT);
+        if (paras.length > 0) {
+            sections.push({ heading, paragraphs: paras });
+        }
+    }
+    return sections;
+}
+async function fetchArxivHtml(arxivId, signal) {
+    try {
+        const res = await fetch(`${ARXIV_HTML_BASE}/${arxivId}`, { signal });
+        if (!res.ok)
+            return null;
+        const reader = res.body?.getReader();
+        if (!reader) {
+            const text = await res.text();
+            return text.length > MAX_HTML_BYTES ? text.slice(0, MAX_HTML_BYTES) : text;
+        }
+        let total = 0;
+        const chunks = [];
+        while (total < MAX_HTML_BYTES) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+            total += value.byteLength;
+        }
+        const decoder = new TextDecoder();
+        return chunks.map(c => decoder.decode(c)).join('');
+    }
+    catch (err) {
+        logger.debug(`[paper_fetch] arxiv html fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+function formatPaperBlock(args) {
+    const lines = [];
+    lines.push(`# ${args.title}`);
+    if (args.authors.length > 0) {
+        const authorLine = args.authors.length > 6
+            ? `${args.authors.slice(0, 6).join(', ')}, et al.`
+            : args.authors.join(', ');
+        lines.push(`**Authors:** ${authorLine}`);
+    }
+    if (args.year)
+        lines.push(`**Year:** ${args.year}`);
+    if (args.discipline)
+        lines.push(`**Discipline:** ${args.discipline}`);
+    if (args.citation_count != null)
+        lines.push(`**Citations:** ${args.citation_count}`);
+    if (args.retracted)
+        lines.push(`**⚠ RETRACTED.** This paper has been withdrawn — discuss findings with that flag visible to the learner.`);
+    if (args.primary_url)
+        lines.push(`**Primary URL:** ${args.primary_url}`);
+    if (args.oa_pdf_url && args.oa_pdf_url !== args.primary_url)
+        lines.push(`**Open-access PDF:** ${args.oa_pdf_url}`);
+    lines.push('');
+    if (args.abstract) {
+        lines.push('## Abstract');
+        lines.push(args.abstract);
+        lines.push('');
+    }
+    if (args.sections && args.sections.length > 0) {
+        lines.push('## Body (extracted sections)');
+        for (const s of args.sections) {
+            lines.push(`### ${s.heading}`);
+            for (const p of s.paragraphs)
+                lines.push(p);
+            lines.push('');
+        }
+    }
+    if (args.fullTextNote) {
+        lines.push(`_${args.fullTextNote}_`);
+    }
+    let out = lines.join('\n');
+    if (out.length > MAX_OUTPUT_CHARS) {
+        out = out.slice(0, MAX_OUTPUT_CHARS) + '\n\n[…truncated; fetch the PDF directly for the full body.]';
+    }
+    return out;
+}
+export class PaperFetchFullTextTool {
+    name = 'paper_fetch_full_text';
+    description = 'Fetch the title, authors, abstract, and (when available) section-extracted body of a scientific paper from arXiv, OpenAlex, or Crossref. Use when explaining a paper to a learner needs more depth than the abstract.';
+    riskLevel = 'safe';
+    requiresConfirmation = false;
+    schema = {
+        name: 'paper_fetch_full_text',
+        description: 'Fetch a scientific paper by identifier and return structured content for explanation. ' +
+            'Accepts arXiv IDs (e.g. "2310.06825"), DOIs ("10.1038/nature12373" or "doi:10.1038/nature12373"), ' +
+            'OpenAlex IDs ("W2741809807"), or any of the corresponding URLs. Returns title, authors, year, ' +
+            'abstract, citation count, discipline, and — for arXiv preprints with HTML rendering available — ' +
+            'extracted section headings with the first paragraphs under each. ' +
+            'Read-only, no confirmation needed. Use this in Teach mode after the user picks a paper to "Read with Ava", ' +
+            'or in any mode when the user pastes a paper identifier and asks for an explanation. ' +
+            'If the paper is retracted upstream marks it — surface that to the learner before discussing findings.',
+        parameters: {
+            type: 'object',
+            properties: {
+                identifier: {
+                    type: 'string',
+                    description: 'arXiv ID, DOI, OpenAlex ID, or any corresponding URL (arxiv.org/abs/..., doi.org/..., openalex.org/...).',
+                },
+            },
+            required: ['identifier'],
+        },
+    };
+    async execute(args, _context) {
+        const identifier = args.identifier?.trim();
+        if (!identifier) {
+            return { success: false, output: 'identifier is required (arXiv ID, DOI, OpenAlex ID, or URL).' };
+        }
+        const signal = AbortSignal.timeout(12_000);
+        const paper = await fetchPaper({ identifier }, signal);
+        if (!paper) {
+            return {
+                success: false,
+                output: `No paper found for identifier "${identifier}". Verify the ID/DOI/URL is correct and the paper is publicly indexed.`,
+            };
+        }
+        let sections;
+        let fullTextNote;
+        if (paper.arxiv_id) {
+            const html = await fetchArxivHtml(paper.arxiv_id, signal);
+            if (html) {
+                sections = extractArxivSections(html);
+                if (sections.length === 0) {
+                    fullTextNote = `arXiv HTML was available but no extractable sections were found. PDF: ${arxivPdfUrl(paper.arxiv_id)}`;
+                }
+            }
+            else {
+                fullTextNote = `arXiv has no rendered HTML for this paper — explanation will work from the abstract. Full PDF: ${arxivPdfUrl(paper.arxiv_id)}`;
+            }
+        }
+        else if (!paper.abstract) {
+            fullTextNote = `Full text not directly available; recommend the learner open the primary URL for the full paper.`;
+        }
+        else {
+            fullTextNote = `Full text not fetched (paper not on arXiv). Working from abstract. Primary URL: ${paper.primary_url ?? 'unknown'}`;
+        }
+        const output = formatPaperBlock({
+            title: paper.title,
+            authors: paper.authors.map(a => a.name),
+            year: paper.year,
+            abstract: paper.abstract,
+            primary_url: paper.primary_url,
+            oa_pdf_url: paper.oa_pdf_url,
+            retracted: paper.retracted,
+            citation_count: paper.citation_count,
+            discipline: paper.discipline,
+            sections,
+            fullTextNote,
+        });
+        return {
+            success: true,
+            output,
+            metadata: {
+                arxiv_id: paper.arxiv_id,
+                doi: paper.doi,
+                openalex_id: paper.openalex_id,
+                year: paper.year,
+                retracted: paper.retracted ?? false,
+                sections_count: sections?.length ?? 0,
+            },
+        };
+    }
+}
+//# sourceMappingURL=paper-fetch.js.map

package/dist/tools/paper-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paper-fetch.js","sourceRoot":"","sources":["../../src/tools/paper-fetch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,eAAe,GAAG,wBAAwB,CAAC;AACjD,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAO,4BAA4B;AAC1E,MAAM,gBAAgB,GAAG,MAAM,CAAC,CAAc,+CAA+C;AAC7F,MAAM,kBAAkB,GAAG,CAAC,CAAC,CAAkB,4CAA4C;AAO3F;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI;SACR,OAAO,CAAC,6BAA6B,EAAE,EAAE,CAAC;SAC1C,OAAO,CAAC,2BAA2B,EAAE,EAAE,CAAC;SACxC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,IAAY;IACxC,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,sEAAsE;IACtE,MAAM,SAAS,GAAG,mCAAmC,CAAC;IACtD,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACrB,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,GAAG;YAAE,SAAS;QAC/C,MAAM,KAAK,GAAG,CAAC,CAAC,KAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACrC,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QACzE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC;aAC1D,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aACzB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC;aAC1B,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;QAChC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,OAAe,EAAE,MAAoB;IACjE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,eAAe,IAAI,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACzB,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7E,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,MAAM,MAAM,GAAiB,EAAE,CAAC;QAChC,OAAO,KAAK,GAAG,cAAc,EAAE,CAAC;YAC9B,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC;QAC5B,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,0CAA0C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3G,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,IAYzB;IACC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YACxC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU;YAClD,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,gBAAgB,UAAU,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,IAAI,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;IACrF,IAAI,IAAI,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,0GAA0G,CAAC,CAAC;IAC3I,IAAI,IAAI,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,oBAAoB,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACzE,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,wBAAwB,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IACnH,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QAC3C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YAC/B,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU;gBAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,GAAG,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAClC,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,GAAG,6DAA6D,CAAC;IACvG,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,sBAAsB;IACxB,IAAI,GAAG,uBAAuB,CAAC;IAC/B,WAAW,GAAG,uNAAuN,CAAC;IACtO,SAAS,GAAkB,MAAM,CAAC;IAClC,oBAAoB,GAAG,KAAK,CAAC;IAE7B,MAAM,GAAmB;QAChC,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EACT,wFAAwF;YACxF,oGAAoG;YACpG,gGAAgG;YAChG,kGAAkG;YAClG,mEAAmE;YACnE,6GAA6G;YAC7G,sFAAsF;YACtF,uGAAuG;QACzG,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0GAA0G;iBACxH;aACF;YACD,QAAQ,EAAE,CAAC,YAAY,CAAC;SACzB;KACF,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,IAA6B,EAAE,QAA8B;QACzE,MAAM,UAAU,GAAI,IAAI,CAAC,UAAqB,EAAE,IAAI,EAAE,CAAC;QACvD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,8DAA8D,EAAE,CAAC;QACpG,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,EAAE,UAAU,EAAE,EAAE,MAAM,CAAC,CAAC;QACvD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,kCAAkC,UAAU,wEAAwE;aAC7H,CAAC;QACJ,CAAC;QAED,IAAI,QAAwC,CAAC;QAC7C,IAAI,YAAgC,CAAC;QACrC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC1D,IAAI,IAAI,EAAE,CAAC;gBACT,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;gBACtC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,YAAY,GAAG,yEAAyE,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxH,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,YAAY,GAAG,kGAAkG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjJ,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC3B,YAAY,GAAG,kGAAkG,CAAC;QACpH,CAAC;aAAM,CAAC;YACN,YAAY,GAAG,mFAAmF,KAAK,CAAC,WAAW,IAAI,SAAS,EAAE,CAAC;QACrI,CAAC;QAED,MAAM,MAAM,GAAG,gBAAgB,CAAC;YAC9B,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YACvC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,QAAQ;YACR,YAAY;SACb,CAAC,CAAC;QAEH,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM;YACN,QAAQ,EAAE;gBACR,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,KAAK;gBACnC,cAAc,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;aACtC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/tools/post-performance.d.ts

@@ -0,0 +1,17 @@
+import type { Tool, ToolResult, ToolExecutionContext, ToolRiskLevel } from './types.js';
+import type { FunctionSchema } from '../providers/types.js';
+/**
+ * See how recent Bluesky posts actually performed (likes/reposts/replies/quotes)
+ * so Ava leans into what landed. Bluesky only — the platform we auto-track. The
+ * DB read is the surface-injected `postMetricsReader` (binds the user); this
+ * tool does the sort + format. Content is Ava's own posts, so trusted.
+ */
+export declare class PostPerformanceTool implements Tool {
+    readonly name = "post_performance";
+    readonly description = "See how recent Bluesky posts actually performed \u2014 likes, reposts, replies. Call when drafting so you lean into what landed and avoid repeating what flopped. Bluesky only.";
+    readonly riskLevel: ToolRiskLevel;
+    readonly requiresConfirmation = false;
+    readonly schema: FunctionSchema;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+}
+//# sourceMappingURL=post-performance.d.ts.map

package/dist/tools/post-performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-performance.d.ts","sourceRoot":"","sources":["../../src/tools/post-performance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,IAAI;IAC9C,QAAQ,CAAC,IAAI,sBAAsB;IACnC,QAAQ,CAAC,WAAW,qLAC2J;IAC/K,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAU;IAC3C,QAAQ,CAAC,oBAAoB,SAAS;IAEtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAW7B;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;CAsCjG"}

package/dist/tools/post-performance.js

@@ -0,0 +1,58 @@
+/**
+ * See how recent Bluesky posts actually performed (likes/reposts/replies/quotes)
+ * so Ava leans into what landed. Bluesky only — the platform we auto-track. The
+ * DB read is the surface-injected `postMetricsReader` (binds the user); this
+ * tool does the sort + format. Content is Ava's own posts, so trusted.
+ */
+export class PostPerformanceTool {
+    name = 'post_performance';
+    description = 'See how recent Bluesky posts actually performed — likes, reposts, replies. Call when drafting so you lean into what landed and avoid repeating what flopped. Bluesky only.';
+    riskLevel = 'safe';
+    requiresConfirmation = false;
+    schema = {
+        name: 'post_performance',
+        description: 'See how recent Bluesky posts actually performed — likes, reposts, replies. Call this when drafting so you can lean into what landed and avoid repeating what flopped. Bluesky only (the platform we auto-track); other platforms are posted manually and not tracked here.',
+        parameters: {
+            type: 'object',
+            properties: {
+                sort: { type: 'string', enum: ['top', 'recent'], description: '"top" = best engagement first (default), "recent" = newest first.' },
+                limit: { type: 'number', description: 'How many posts to return (default 8, max 20).' },
+            },
+            required: [],
+        },
+    };
+    async execute(args, context) {
+        const reader = context.sharedState?.postMetricsReader;
+        if (!reader) {
+            return {
+                success: false,
+                output: 'Post performance is not available in this context. The host must inject `postMetricsReader` into shared state.',
+            };
+        }
+        const sort = args.sort === 'recent' ? 'recent' : 'top';
+        const limit = Math.min(Math.max(Number(args.limit) || 8, 1), 20);
+        let rows;
+        try {
+            rows = await reader.recent();
+        }
+        catch (err) {
+            return { success: false, output: `Couldn't read post performance: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        if (!rows || rows.length === 0) {
+            return {
+                success: true,
+                output: 'No Bluesky performance data yet — posts are tracked once they have been live long enough to gather engagement.',
+            };
+        }
+        let arr = rows.map(r => ({ ...r, eng: (r.likes || 0) + (r.reposts || 0) + (r.replies || 0) + (r.quotes || 0) }));
+        if (sort === 'top')
+            arr.sort((a, b) => b.eng - a.eng);
+        arr = arr.slice(0, limit);
+        const lines = arr.map(r => `${r.eng} eng (${r.likes || 0} likes, ${r.reposts || 0} reposts, ${r.replies || 0} replies) — "${String(r.content || '').split('\n')[0].slice(0, 80)}"`);
+        return {
+            success: true,
+            output: `Bluesky post performance (${sort}, from the last ~50 tracked posts):\n${lines.join('\n')}`,
+        };
+    }
+}
+//# sourceMappingURL=post-performance.js.map

package/dist/tools/post-performance.js.map

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

package/dist/tools/present-plan.d.ts

@@ -0,0 +1,34 @@
+import type { Tool, ToolResult, ToolExecutionContext, ToolRiskLevel } from './types.js';
+import type { FunctionSchema } from '../providers/types.js';
+/** What the user decided when the plan card was approved. */
+export interface PlanDecision {
+    /** The `label` of the alternative they picked, if the plan offered any. */
+    selection?: string;
+    /** Anything they typed alongside the choice. */
+    note?: string;
+}
+/**
+ * The sentence Ava receives when a plan is approved.
+ *
+ * Lives in core because both surfaces have to say the same thing, and until
+ * now they did not: the extension built its own string, the IDE passed the
+ * user's free text through verbatim, and the IDE had no way to send a choice
+ * at all. One fact, two hand-written copies — the shape that has caused most
+ * of the faults in this area.
+ *
+ * The wording matters more than it looks. When an approach was chosen, Ava is
+ * told to build THAT ONE. Seen live 2026-08-19: a plan offering "all eleven
+ * tasks" against "minimal four-task core loop first" was approved without a
+ * choice ever being asked for, and eleven tasks were dispatched — the operator
+ * read it as her picking for him, or splicing the two together.
+ */
+export declare function formatPlanDecision(decision?: PlanDecision): string;
+export declare class PresentPlanTool implements Tool {
+    readonly name = "present_plan";
+    readonly description = "Present a structured plan for the user to review and approve before execution. Use in Plan mode for proposals, in Work mode before complex multi-step tasks, and in Brainstorm mode for refined action plans. Shows steps, effort estimates, and trade-offs.";
+    readonly riskLevel: ToolRiskLevel;
+    readonly requiresConfirmation = true;
+    readonly schema: FunctionSchema;
+    execute(_args: Record<string, unknown>, _context: ToolExecutionContext): Promise<ToolResult>;
+}
+//# sourceMappingURL=present-plan.d.ts.map

package/dist/tools/present-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"present-plan.d.ts","sourceRoot":"","sources":["../../src/tools/present-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAE,YAAiB,GAAG,MAAM,CAetE;AAED,qBAAa,eAAgB,YAAW,IAAI;IAC1C,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,WAAW,kQAAkQ;IACtR,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAW;IAC5C,QAAQ,CAAC,oBAAoB,QAAQ;IAErC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAmE7B;IAEI,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;CAenG"}

package/dist/tools/present-plan.js

@@ -0,0 +1,117 @@
+/**
+ * The sentence Ava receives when a plan is approved.
+ *
+ * Lives in core because both surfaces have to say the same thing, and until
+ * now they did not: the extension built its own string, the IDE passed the
+ * user's free text through verbatim, and the IDE had no way to send a choice
+ * at all. One fact, two hand-written copies — the shape that has caused most
+ * of the faults in this area.
+ *
+ * The wording matters more than it looks. When an approach was chosen, Ava is
+ * told to build THAT ONE. Seen live 2026-08-19: a plan offering "all eleven
+ * tasks" against "minimal four-task core loop first" was approved without a
+ * choice ever being asked for, and eleven tasks were dispatched — the operator
+ * read it as her picking for him, or splicing the two together.
+ */
+export function formatPlanDecision(decision = {}) {
+    const selection = decision.selection?.trim();
+    const note = decision.note?.trim();
+    const parts = ['Plan approved.'];
+    if (selection) {
+        parts.push(`The user chose the "${selection}" approach. Build THAT approach only — ` +
+            'do not carry over steps from the alternatives they did not pick, and do ' +
+            'not combine them.');
+    }
+    if (note)
+        parts.push(`They added: "${note}"`);
+    parts.push(selection ? 'Execute its steps.' : 'Execute the steps.');
+    return parts.join(' ');
+}
+export class PresentPlanTool {
+    name = 'present_plan';
+    description = 'Present a structured plan for the user to review and approve before execution. Use in Plan mode for proposals, in Work mode before complex multi-step tasks, and in Brainstorm mode for refined action plans. Shows steps, effort estimates, and trade-offs.';
+    riskLevel = 'write';
+    requiresConfirmation = true;
+    schema = {
+        name: 'present_plan',
+        description: 'Present a structured plan to the user for review and approval before making changes. ' +
+            'The user will see the plan as a card with Approve/Reject buttons. ' +
+            'Always use this when you have a multi-step plan ready. ' +
+            'If there are multiple valid approaches, include them as alternatives so the user can choose.',
+        parameters: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Brief plan title (e.g. "Add dark mode toggle")',
+                },
+                goal: {
+                    type: 'string',
+                    description: 'One-sentence description of what this plan achieves',
+                },
+                steps: {
+                    type: 'array',
+                    description: 'Ordered list of implementation steps',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            description: {
+                                type: 'string',
+                                description: 'What this step does',
+                            },
+                            files: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'File paths this step touches (optional)',
+                            },
+                        },
+                        required: ['description'],
+                    },
+                },
+                verification: {
+                    type: 'string',
+                    description: 'How to verify the plan worked (e.g. "Run npm test and npm run build")',
+                },
+                confidence: {
+                    type: 'string',
+                    enum: ['high', 'medium', 'low'],
+                    description: 'Your overall confidence in this plan succeeding. Be honest — high means you\'ve verified the approach, low means you\'re unsure.',
+                },
+                alternatives: {
+                    type: 'array',
+                    description: 'Optional alternative approaches for the user to choose from',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            label: {
+                                type: 'string',
+                                description: 'Short name for this approach (e.g. "Redis caching")',
+                            },
+                            description: {
+                                type: 'string',
+                                description: 'Brief explanation of this approach and its trade-offs',
+                            },
+                        },
+                        required: ['label', 'description'],
+                    },
+                },
+            },
+            required: ['title', 'goal', 'steps', 'verification'],
+        },
+    };
+    async execute(_args, _context) {
+        // Normally bypassed — the confirmation handler returns a string result directly.
+        // This is a fallback in case the handler returns true instead of a string.
+        //
+        // In Auto Mode the host's TaskExecutor will pick up the approved task list
+        // and dispatch a fresh Builder agent per step. The conductor model should
+        // call todo_write to materialise the task list and then stop — the Builder
+        // hand-off is automatic.
+        return {
+            success: true,
+            output: 'Plan approved by user. Call todo_write to materialise the task list, ' +
+                'then stop — the Builder will execute each task automatically.',
+        };
+    }
+}
+//# sourceMappingURL=present-plan.js.map

package/dist/tools/present-plan.js.map

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

package/dist/tools/project-index.d.ts

@@ -0,0 +1,11 @@
+import type { Tool, ToolResult, ToolExecutionContext, ToolRiskLevel } from './types.js';
+import type { FunctionSchema } from '../providers/types.js';
+export declare class ProjectIndexTool implements Tool {
+    readonly name = "project_index";
+    readonly description = "Scan, refresh, or display the project structure index";
+    readonly riskLevel: ToolRiskLevel;
+    readonly requiresConfirmation = false;
+    readonly schema: FunctionSchema;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+}
+//# sourceMappingURL=project-index.d.ts.map

package/dist/tools/project-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-index.d.ts","sourceRoot":"","sources":["../../src/tools/project-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,qBAAa,gBAAiB,YAAW,IAAI;IAC3C,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,WAAW,2DAA2D;IAC/E,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAU;IAC3C,QAAQ,CAAC,oBAAoB,SAAS;IAEtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAsB7B;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;CAgEjG"}

package/dist/tools/project-index.js

@@ -0,0 +1,88 @@
+const ALLOWED_ACTIONS = new Set(['scan', 'refresh', 'show']);
+export class ProjectIndexTool {
+    name = 'project_index';
+    description = 'Scan, refresh, or display the project structure index';
+    riskLevel = 'safe';
+    requiresConfirmation = false;
+    schema = {
+        name: 'project_index',
+        description: 'Scan, refresh, or display the project structure index. ' +
+            'The index provides a bird\'s-eye view of the codebase: frameworks, ' +
+            'languages, entry points, test setup, and directory structure. ' +
+            'Run "scan" the first time to build the index. Use "show" to view it. ' +
+            'Use "refresh" to re-scan if the project has changed.',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['scan', 'refresh', 'show'],
+                    description: '"scan" builds the index from scratch (first time or full rescan). ' +
+                        '"refresh" re-scans only if the index is stale (>1 hour old). ' +
+                        '"show" displays the current cached index summary.',
+                },
+            },
+            required: ['action'],
+        },
+    };
+    async execute(args, context) {
+        const action = args.action;
+        if (!ALLOWED_ACTIONS.has(action)) {
+            return {
+                success: false,
+                output: `Invalid action "${action}". Use one of: ${[...ALLOWED_ACTIONS].join(', ')}`,
+            };
+        }
+        const indexer = context.sharedState?.projectIndexer;
+        if (!indexer) {
+            return { success: false, output: 'Project indexer is not available in this context.' };
+        }
+        try {
+            switch (action) {
+                case 'scan': {
+                    const index = await indexer.scan();
+                    const summary = indexer.summarize();
+                    return {
+                        success: true,
+                        output: `Project indexed successfully (${index.languages.reduce((n, l) => n + l.files, 0)} source files).\n\n${summary}`,
+                        metadata: {
+                            fileCount: index.languages.reduce((n, l) => n + l.files, 0),
+                            framework: index.framework.name,
+                            packageManager: index.packageManager,
+                        },
+                    };
+                }
+                case 'refresh': {
+                    if (!indexer.isStale()) {
+                        const summary = indexer.summarize();
+                        return {
+                            success: true,
+                            output: `Index is fresh (less than 1 hour old). No rescan needed.\n\n${summary}`,
+                        };
+                    }
+                    const index = await indexer.scan();
+                    const summary = indexer.summarize();
+                    return {
+                        success: true,
+                        output: `Index refreshed (${index.languages.reduce((n, l) => n + l.files, 0)} source files).\n\n${summary}`,
+                    };
+                }
+                case 'show': {
+                    // Try to load from disk if not in memory
+                    if (!indexer.getIndex()) {
+                        await indexer.load();
+                    }
+                    const summary = indexer.summarize();
+                    return { success: true, output: summary };
+                }
+                default:
+                    return { success: false, output: `Unknown action: ${action}` };
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { success: false, output: `Project index failed: ${message}` };
+        }
+    }
+}
+//# sourceMappingURL=project-index.js.map

package/dist/tools/project-index.js.map

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

package/dist/tools/propose-hooks.d.ts

@@ -0,0 +1,17 @@
+import type { Tool, ToolResult, ToolExecutionContext, ToolRiskLevel } from './types.js';
+import type { FunctionSchema } from '../providers/types.js';
+/**
+ * Offer the operator 2–3 candidate opening hooks BEFORE writing the full post.
+ * Side-effect-free: validate + hand the proposal to the surface-injected
+ * `hookStore`, which the surface renders as a picker. Then Ava WAITS for the
+ * operator to choose (the persona rule) — unless they delegated the call.
+ */
+export declare class ProposeHooksTool implements Tool {
+    readonly name = "propose_hooks";
+    readonly description = "Offer the operator 2-3 candidate opening hooks to choose from before writing the full post. Then WAIT \u2014 do not write_post in the same turn unless the operator delegated the choice.";
+    readonly riskLevel: ToolRiskLevel;
+    readonly requiresConfirmation = false;
+    readonly schema: FunctionSchema;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+}
+//# sourceMappingURL=propose-hooks.d.ts.map

package/dist/tools/propose-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propose-hooks.d.ts","sourceRoot":"","sources":["../../src/tools/propose-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D;;;;;GAKG;AACH,qBAAa,gBAAiB,YAAW,IAAI;IAC3C,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,WAAW,+LACqK;IACzL,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAU;IAC3C,QAAQ,CAAC,oBAAoB,SAAS;IAEtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAwB7B;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;CAqCjG"}