@project-ava-supernova/core 0.2.71

package/dist/tools/discover-news.js

@@ -0,0 +1,261 @@
+/**
+ * The story menu — what newsrooms actually ran today.
+ *
+ * DISCOVERY IS NOT A SEARCH. It reads the front pages: the RSS feeds of real
+ * newsrooms, whose editors already decided what mattered this morning.
+ *
+ * The first cut searched, and it failed in a way worth remembering. Each desk ran
+ * a keyword query against the news index, and the World desk's query returned SIX
+ * hits — five of them section fronts, one real story. So Ava reported that one
+ * story every single time and looked fixated on a war. She wasn't: it was the only
+ * thing on her desk.
+ *
+ * The flaw was structural, not a bad keyword. A SEARCH IS A PULL — you only get
+ * back what you already suspected — and nobody, human or model, thinks to ask for
+ * "Bangkok bar fire" at 6am. Twenty-seven people died and the story reaches us by
+ * luck. Letting the MODEL write the queries doesn't fix that; it just moves the
+ * guess somewhere less inspectable, and a model's guess about today is even worse,
+ * because today is precisely what it doesn't know.
+ *
+ * A FRONT PAGE IS A PUSH. The Guardian's world editor put the fire on the page
+ * BECAUSE IT HAPPENED. So: SEE (feeds) → CHOOSE (Ava) → VERIFY (research_story).
+ * Search is still used — but only to stand up a story she has already seen, never
+ * to decide what the news is.
+ *
+ * Deliberately does NOT cluster. Syndication detection compares TEXT, which is
+ * exactly right within one story and wrong across a whole desk: twenty unrelated
+ * pieces sharing a house style would collapse into one "story" that doesn't exist.
+ * Clustering belongs in research_story, where every hit is about the same event.
+ *
+ * The selection is the skill, and it belongs to her, not to a ranking function:
+ * a story everyone has is rarely worth writing; a story only one outlet has is a
+ * story that needs CHECKING, not repeating.
+ */
+/**
+ * Each desk is a SPREAD of angles, not one standing phrase.
+ *
+ * The first cut used a single query per desk ("breaking world news today"). It
+ * was measured against live Brave News and it was a disaster:
+ *
+ *   world  →  6 hits, 5 of them section fronts, ONE real story
+ *   sport  →  2 hits, both section fronts, ZERO real stories
+ *
+ * So the World desk had exactly one card to play — the US/Iran story — and Ava
+ * played it every single time. It looked like she was obsessed with the war. She
+ * wasn't: it was the only thing on the desk. A newsroom that can only see one
+ * story isn't reporting, it's echoing, and that is the failure this whole room
+ * exists to avoid.
+ *
+ * Two things were wrong with the phrasing, and they pull against each other:
+ *   - "… news today" reads like a SECTION FRONT to a search index, so it matches
+ *     "World News and International Headlines : NPR" rather than any event.
+ *   - one query, however phrased, can only ever surface one slice of a desk.
+ *
+ * So: several concrete angles per desk, merged and de-duplicated. Politics AND
+ * disasters AND diplomacy AND the economy — because that IS what "world" means,
+ * and if we only ask for one of them, that's the only one she can report.
+ *
+ * Same measurement, after: world went from 1 real story to ~50 — Japan's new
+ * intelligence agency, the Bangkok bar fire, Israel's October elections, the
+ * Bangladesh floods, a wildfire in Antelope Valley, the World Cup.
+ *
+ * Ids MUST stay in step with NEWS_CATEGORIES on the web and the hub.
+ */
+const DESK_ANGLES = {
+    'world': [
+        'world news',
+        'international politics election government',
+        'protest disaster earthquake flood wildfire',
+        'diplomacy summit treaty sanctions',
+    ],
+    'ai': [
+        'artificial intelligence news',
+        'AI model release lab announcement',
+        'AI regulation policy lawsuit',
+        'AI research breakthrough paper',
+    ],
+    'technology': [
+        'technology news',
+        'software developer tools release',
+        'hardware chips semiconductor',
+        'big tech company announcement',
+    ],
+    'open-source': [
+        'open source software',
+        'open source project release github',
+        'open source licensing foundation governance',
+        'linux kernel community',
+    ],
+    'security-privacy': [
+        'cybersecurity attack',
+        'data breach hack ransomware',
+        'privacy surveillance regulation GDPR',
+        'vulnerability exploit CVE patch',
+    ],
+    'business': [
+        'business economy news',
+        'markets earnings company results',
+        'inflation interest rates central bank',
+        'merger acquisition funding round',
+    ],
+    'science': [
+        'science research discovery',
+        'space astronomy mission telescope',
+        'climate environment study',
+        'medicine biology genetics study',
+    ],
+    'health': [
+        'health news',
+        'public health disease outbreak',
+        'fitness exercise nutrition study',
+        'mental health wellbeing research',
+    ],
+    'food': [
+        'food news',
+        'nutrition diet study',
+        'food industry recall safety',
+        'restaurant chef cooking trends',
+    ],
+    'education': [
+        'education news',
+        'schools teachers policy funding',
+        'university higher education students',
+        'edtech learning technology',
+    ],
+    'sport': [
+        'sport news results',
+        'football soccer match result',
+        'transfer injury manager club',
+        'tennis cricket rugby athletics olympics',
+    ],
+};
+/**
+ * A section front is not a story.
+ *
+ * "World News and International Headlines : NPR", "Germany: Newsroom", "News
+ * Today Live Updates" — these are the paper's front door, not something that
+ * happened. They carry no event, nothing to stand up, and nothing to quote, and
+ * on the thin desks they were crowding out the real reporting entirely (sport
+ * was 2 hits and BOTH were these).
+ *
+ * Deliberately narrow. It only catches titles that are self-evidently an index —
+ * a real headline about a genuine "breaking news" event ("Breaking news anchor
+ * resigns") keeps its noun and survives, because the pattern needs the phrase to
+ * BE the whole title, not appear in it.
+ */
+const INDEX_PAGE = new RegExp([
+    // Section fronts and headline lists.
+    '^news:', 'headlines$', 'headlines\\s*[:|-]', 'news headlines', 'newsroom$',
+    'latest news$', 'top stories$', 'breaking news$', 'news today live',
+    'live updates?$', 'news roundup',
+    // Sport's version of a section front: the fixtures/scores table. These were
+    // literally the ONLY two things the sport desk returned before the fan-out.
+    '^scores\\b', 'scores?\\s*(&|and)\\s*(fixtures|schedule|results)',
+    'fixtures?\\s*(&|and)\\s*(results|scores)',
+    'results?\\s*(&|and)\\s*fixtures',
+].join('|'), 'i');
+export class DiscoverNewsTool {
+    name = 'discover_news';
+    description = "Read a desk's FRONT PAGES — the stories real newsrooms ran today, straight from their own feeds. No searching, no keywords: you see what happened, not what someone thought to ask for. This is your story menu.";
+    riskLevel = 'safe';
+    requiresConfirmation = false;
+    schema = {
+        name: 'discover_news',
+        description: "Read a desk's FRONT PAGES — the stories real newsrooms actually ran today, pulled from their own feeds (Guardian, BBC, Al Jazeera, NPR, DW, France 24, Reuters-carrying outlets, and so on, depending on the desk). This is NOT a search: nothing here was chosen by a keyword, so you are seeing what happened rather than what someone thought to ask for. Call it when the operator asks what's happening or what's worth covering. Read WIDELY before you choose — the whole point is that you are not being handed one running story. Pass `query` INSTEAD only when you are chasing a specific story you already know exists; that runs a real search. Never invent a story; if it comes back empty, say so plainly.",
+        parameters: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    enum: ['world', 'ai', 'technology', 'open-source', 'security-privacy', 'business', 'science', 'health', 'food', 'education', 'sport'],
+                    description: "The desk whose front pages to read.",
+                },
+                query: { type: 'string', description: 'Only for chasing a specific story you ALREADY know exists (e.g. "Bangkok bar fire death toll"). Runs a search INSTEAD of reading the front pages. Leave empty for a desk scan — a search can only return what you already suspected, which is how a desk ends up reporting the same story every day.' },
+                freshness: { type: 'string', enum: ['pd', 'pw', 'pm'], description: 'Only applies to `query`. pd = past day (default), pw = past week, pm = past month.' },
+            },
+            required: [],
+        },
+    };
+    async execute(args, context) {
+        const feeds = context.sharedState?.newsFeeds;
+        const search = context.sharedState?.newsSearch;
+        const category = String(args.category ?? '').trim();
+        const freeText = String(args.query ?? '').trim();
+        const desk = DESK_ANGLES[category] ? category : 'world';
+        const freshness = (['pd', 'pw', 'pm'].includes(String(args.freshness))
+            ? String(args.freshness)
+            : 'pd');
+        let hits;
+        let source;
+        if (freeText) {
+            // She's chasing something specific she already knows exists — that IS a
+            // search, and search is the right tool for it.
+            if (!search) {
+                return { success: false, output: 'News search is not available in this context. The host must inject `newsSearch` into shared state.' };
+            }
+            hits = await search(freeText, 20, freshness);
+            source = `search: "${freeText}"`;
+        }
+        else if (feeds) {
+            // A desk scan READS THE FRONT PAGES. No query, no guessing — what those
+            // newsrooms actually ran.
+            hits = await feeds(desk);
+            source = 'front pages';
+        }
+        else if (search) {
+            // Fallback ONLY: a surface that hasn't injected the feed reader. Keyword
+            // angles are strictly worse (this is the mode that gave the World desk one
+            // story), so it is a floor, not the design.
+            const batches = await Promise.all(DESK_ANGLES[desk].map((q) => search(q, 10, freshness).catch(() => [])));
+            hits = batches.flat();
+            source = 'keyword fallback (no feed reader injected)';
+        }
+        else {
+            return { success: false, output: 'Neither `newsFeeds` nor `newsSearch` is available in this context. The host must inject at least one.' };
+        }
+        // De-duplicate by URL and drop section fronts / fixtures tables — a headline
+        // index is not a story: nothing happened, nothing to stand up, nothing to quote.
+        const byUrl = new Map();
+        for (const hit of hits) {
+            if (!hit.url || byUrl.has(hit.url))
+                continue;
+            if (INDEX_PAGE.test(hit.title))
+                continue;
+            byUrl.set(hit.url, hit);
+        }
+        const stories = [...byUrl.values()].slice(0, 40);
+        // Stash for the quote checker — she may quote straight off the menu if she
+        // covers one of these without a deeper pull.
+        if (context.sharedState) {
+            const existing = context.sharedState.fetchedCorpus ?? { hits: [] };
+            const seen = new Set(existing.hits.map((h) => h.url));
+            context.sharedState.fetchedCorpus = {
+                hits: [...existing.hits, ...stories.filter((h) => !seen.has(h.url))],
+            };
+        }
+        if (stories.length === 0) {
+            return {
+                success: true,
+                output: JSON.stringify({
+                    desk,
+                    source,
+                    stories: [],
+                    note: 'Nothing came back. Say so — do NOT fall back on what you think is happening. An invented story is worse than an empty desk.',
+                }),
+            };
+        }
+        const outlets = [...new Set(stories.map((s) => s.outlet).filter(Boolean))];
+        return {
+            success: true,
+            output: JSON.stringify({
+                desk,
+                source,
+                outlets,
+                count: stories.length,
+                stories: stories.map((h) => ({ outlet: h.outlet, headline: h.title, url: h.url, age: h.age ?? null, excerpt: h.excerpt.slice(0, 240) })),
+                note: 'This is the front page, not the story — these are the pieces real newsrooms ran today, across several outlets that often disagree with each other. Nobody searched for them, so nothing here was pre-selected by a keyword: read WIDELY before you choose. A desk that only ever reports the one running story is echoing, not reporting. Then, for whatever you pick: call research_story to see who else has it, whether it is independent reporting or one wire echoed, and where outlets diverge. The selection is the skill — a story everyone has is rarely worth writing; a story only one outlet has needs CHECKING, not repeating.',
+            }),
+        };
+    }
+}
+//# sourceMappingURL=discover-news.js.map

package/dist/tools/discover-news.js.map

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

package/dist/tools/doc-generate.d.ts

@@ -0,0 +1,17 @@
+import type { Tool, ToolResult, ToolExecutionContext, ToolRiskLevel } from './types.js';
+import type { FunctionSchema } from '../providers/types.js';
+export declare class DocGenerateTool implements Tool {
+    readonly name = "doc_generate";
+    readonly description = "Generate project documentation (README, API docs, architecture overview) from source code";
+    readonly riskLevel: ToolRiskLevel;
+    readonly requiresConfirmation = true;
+    readonly schema: FunctionSchema;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+    private gatherProjectInfo;
+    private generateReadme;
+    private generateApi;
+    private generateArchitecture;
+    private generateGettingStarted;
+    private extractExports;
+}
+//# sourceMappingURL=doc-generate.d.ts.map

package/dist/tools/doc-generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-generate.d.ts","sourceRoot":"","sources":["../../src/tools/doc-generate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,qBAAa,eAAgB,YAAW,IAAI;IAC1C,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,WAAW,+FAA+F;IACnH,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAW;IAC5C,QAAQ,CAAC,oBAAoB,QAAQ;IAErC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAqB7B;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;YAuClF,iBAAiB;IA0C/B,OAAO,CAAC,cAAc;YA+BR,WAAW;IAyBzB,OAAO,CAAC,oBAAoB;IA4B5B,OAAO,CAAC,sBAAsB;IA6B9B,OAAO,CAAC,cAAc;CAavB"}

package/dist/tools/doc-generate.js

@@ -0,0 +1,222 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+import { glob } from 'glob';
+import { validatePath } from './security.js';
+export class DocGenerateTool {
+    name = 'doc_generate';
+    description = 'Generate project documentation (README, API docs, architecture overview) from source code';
+    riskLevel = 'write';
+    requiresConfirmation = true;
+    schema = {
+        name: 'doc_generate',
+        description: 'Analyze the project structure and generate documentation. Types: readme (project overview with ' +
+            'setup instructions), api (exported functions/classes with signatures), architecture (directory ' +
+            'structure, dependencies, data flow), getting-started (quick start guide).',
+        parameters: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: ['readme', 'api', 'architecture', 'getting-started'],
+                    description: 'Type of documentation to generate.',
+                },
+                output_path: {
+                    type: 'string',
+                    description: 'Output file path. Default: README.md, API.md, ARCHITECTURE.md, or GETTING-STARTED.md in project root.',
+                },
+            },
+            required: ['type'],
+        },
+    };
+    async execute(args, context) {
+        const type = args.type;
+        const outputArg = args.output_path;
+        const defaultPaths = {
+            readme: 'README.md',
+            api: 'API.md',
+            architecture: 'ARCHITECTURE.md',
+            'getting-started': 'GETTING-STARTED.md',
+        };
+        const outputPath = outputArg
+            ? validatePath(outputArg, context.cwd)
+            : join(context.cwd, defaultPaths[type] || 'DOCS.md');
+        // Gather project info
+        const info = await this.gatherProjectInfo(context.cwd);
+        // Generate content
+        let content;
+        switch (type) {
+            case 'readme':
+                content = this.generateReadme(info);
+                break;
+            case 'api':
+                content = await this.generateApi(info, context.cwd);
+                break;
+            case 'architecture':
+                content = this.generateArchitecture(info);
+                break;
+            case 'getting-started':
+                content = this.generateGettingStarted(info);
+                break;
+            default: return { success: false, output: `Unknown doc type: ${type}` };
+        }
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, content, 'utf-8');
+        const lineCount = content.split('\n').length;
+        return {
+            success: true,
+            output: `Generated ${type} documentation:\n  ${outputPath}\n  ${lineCount} lines`,
+            metadata: { path: outputPath, type, lineCount },
+        };
+    }
+    async gatherProjectInfo(cwd) {
+        const info = { cwd };
+        // package.json
+        try {
+            const pkg = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf-8'));
+            info.name = pkg.name;
+            info.version = pkg.version;
+            info.description = pkg.description;
+            info.scripts = pkg.scripts;
+            info.dependencies = Object.keys(pkg.dependencies || {});
+            info.devDependencies = Object.keys(pkg.devDependencies || {});
+            info.license = pkg.license;
+            info.packageManager = 'npm';
+            if (pkg.packageManager?.startsWith('pnpm'))
+                info.packageManager = 'pnpm';
+            else if (pkg.packageManager?.startsWith('yarn'))
+                info.packageManager = 'yarn';
+        }
+        catch { /* not a JS project */ }
+        // pyproject.toml
+        try {
+            const pyproject = await readFile(join(cwd, 'pyproject.toml'), 'utf-8');
+            info.pythonProject = true;
+            const nameMatch = pyproject.match(/name\s*=\s*"([^"]+)"/);
+            if (nameMatch)
+                info.name = nameMatch[1];
+        }
+        catch { /* ignore */ }
+        // Directory structure (top 2 levels)
+        const files = await glob('**/*', { cwd, nodir: true, ignore: ['node_modules/**', 'dist/**', '.git/**', 'build/**', '.next/**'], maxDepth: 3 });
+        info.structure = files.slice(0, 100);
+        // Source files count
+        const srcFiles = await glob('**/*.{ts,tsx,js,jsx,py,go,rs}', { cwd, nodir: true, ignore: ['node_modules/**', 'dist/**'] });
+        info.sourceFileCount = srcFiles.length;
+        // README exists?
+        try {
+            info.existingReadme = await readFile(join(cwd, 'README.md'), 'utf-8');
+        }
+        catch { /* ignore */ }
+        return info;
+    }
+    generateReadme(info) {
+        const name = info.name || 'Project';
+        const desc = info.description || '';
+        const license = info.license || '';
+        const pm = info.packageManager || 'npm';
+        const scripts = info.scripts || {};
+        const deps = info.dependencies || [];
+        let out = `# ${name}\n\n`;
+        if (desc)
+            out += `${desc}\n\n`;
+        out += `## Installation\n\n\`\`\`bash\n${pm} install\n\`\`\`\n\n`;
+        if (Object.keys(scripts).length > 0) {
+            out += `## Scripts\n\n`;
+            for (const [key, value] of Object.entries(scripts)) {
+                out += `- \`${pm} run ${key}\` — \`${value}\`\n`;
+            }
+            out += '\n';
+        }
+        if (deps.length > 0) {
+            out += `## Dependencies\n\n`;
+            out += deps.map(d => `- ${d}`).join('\n') + '\n\n';
+        }
+        if (license)
+            out += `## License\n\n${license}\n`;
+        return out;
+    }
+    async generateApi(_info, cwd) {
+        const files = await glob('**/src/**/*.{ts,js}', { cwd, absolute: true, nodir: true, ignore: ['**/*.test.*', '**/*.spec.*', '**/node_modules/**'] });
+        let out = `# API Reference\n\n`;
+        for (const file of files.slice(0, 30)) {
+            try {
+                const content = await readFile(file, 'utf-8');
+                const exports = this.extractExports(content);
+                if (exports.length === 0)
+                    continue;
+                const rel = relative(cwd, file);
+                out += `## ${rel}\n\n`;
+                for (const exp of exports) {
+                    out += `### \`${exp.name}\`\n\n`;
+                    out += `- **Type:** ${exp.type}\n`;
+                    if (exp.signature)
+                        out += `- **Signature:** \`${exp.signature}\`\n`;
+                    out += '\n';
+                }
+            }
+            catch { /* skip */ }
+        }
+        return out;
+    }
+    generateArchitecture(info) {
+        const structure = info.structure || [];
+        const srcCount = info.sourceFileCount || 0;
+        let out = `# Architecture\n\n`;
+        out += `**Source files:** ${srcCount}\n\n`;
+        out += `## Directory Structure\n\n\`\`\`\n`;
+        // Group by top-level directory
+        const dirs = new Map();
+        for (const f of structure) {
+            const parts = f.split('/');
+            const topDir = parts.length > 1 ? parts[0] : '.';
+            if (!dirs.has(topDir))
+                dirs.set(topDir, []);
+            dirs.get(topDir).push(f);
+        }
+        for (const [dir, files] of dirs) {
+            out += `${dir}/\n`;
+            for (const f of files.slice(0, 10)) {
+                out += `  ${f}\n`;
+            }
+            if (files.length > 10)
+                out += `  ... (${files.length - 10} more)\n`;
+        }
+        out += `\`\`\`\n\n`;
+        return out;
+    }
+    generateGettingStarted(info) {
+        const name = info.name || 'the project';
+        const pm = info.packageManager || 'npm';
+        const scripts = info.scripts || {};
+        let out = `# Getting Started with ${name}\n\n`;
+        out += `## Prerequisites\n\n`;
+        out += `- Node.js 18+\n`;
+        out += `- ${pm}\n\n`;
+        out += `## Setup\n\n`;
+        out += `\`\`\`bash\ngit clone <repository-url>\ncd ${name}\n${pm} install\n\`\`\`\n\n`;
+        if (scripts.dev) {
+            out += `## Development\n\n\`\`\`bash\n${pm} run dev\n\`\`\`\n\n`;
+        }
+        if (scripts.build) {
+            out += `## Build\n\n\`\`\`bash\n${pm} run build\n\`\`\`\n\n`;
+        }
+        if (scripts.test) {
+            out += `## Testing\n\n\`\`\`bash\n${pm} test\n\`\`\`\n\n`;
+        }
+        return out;
+    }
+    extractExports(content) {
+        const exports = [];
+        const regex = /export\s+(?:default\s+)?(function|const|class|type|interface|enum|async\s+function)\s+(\w+)([^{;]*)/g;
+        let match;
+        while ((match = regex.exec(content)) !== null) {
+            exports.push({
+                name: match[2],
+                type: match[1].replace('async ', 'async '),
+                signature: match[3]?.trim()?.slice(0, 100) || undefined,
+            });
+        }
+        return exports;
+    }
+}
+//# sourceMappingURL=doc-generate.js.map

package/dist/tools/doc-generate.js.map

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

package/dist/tools/docs-lookup.d.ts

@@ -0,0 +1,38 @@
+import type { Tool, ToolResult, ToolExecutionContext, ToolRiskLevel } from './types.js';
+import type { FunctionSchema } from '../providers/types.js';
+/**
+ * Searches Ava's own documentation. Reads the SAME canonical corpus the web,
+ * extension, and IDE render (packages/core/src/docs/content) so the tool can
+ * never drift from what users actually see — there is one source of truth.
+ *
+ * The previous implementation searched a parallel hand-maintained text file
+ * (ava-docs.ts) that had gone stale (old tool counts, retired model names).
+ * That file is gone; this tool flattens the structured DocPages to searchable
+ * text at call time.
+ */
+export declare class DocsLookupTool implements Tool {
+    readonly name = "docs_lookup";
+    readonly description = "Search Ava's own documentation (her product knowledge) to answer questions about features, setup, and troubleshooting \u2014 returns focused, cited excerpts";
+    readonly riskLevel: ToolRiskLevel;
+    readonly requiresConfirmation = false;
+    readonly schema: FunctionSchema;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+    /** A surface-availability footnote for capability-gated features, so Ava can
+     *  say where a feature works and whether it's usable on the current surface. */
+    private availabilityNote;
+    /** Availability footnote from a page's required capabilities — so Ava can say
+     *  where a feature works and whether it's usable on the current surface. */
+    private availabilityNoteFor;
+    /** Render retrieved blocks grouped by their source page, each cited so Ava can
+     *  attribute the answer. Focused evidence, not whole pages. */
+    private renderHits;
+    /** Shipping-status note so Ava never presents an unshipped feature as usable
+     *  right now. Shipped (the default) is silent — the prose already implies it. */
+    private statusNote;
+    /** Flatten a DocPage's blocks into plain searchable/printable text. Includes
+     *  the optional `deeper` ("Show me the details") layer — that's where the
+     *  technical depth now lives, so it must be searchable and returnable too. */
+    private pageToText;
+    private blockToText;
+}
+//# sourceMappingURL=docs-lookup.d.ts.map

package/dist/tools/docs-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-lookup.d.ts","sourceRoot":"","sources":["../../src/tools/docs-lookup.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;AAa5D;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,IAAI;IACzC,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,QAAQ,CAAC,WAAW,kKAA8J;IAClL,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAU;IAC3C,QAAQ,CAAC,oBAAoB,SAAS;IAEtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CA2B7B;IAEI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;IAgDhG;oFACgF;IAChF,OAAO,CAAC,gBAAgB;IAIxB;gFAC4E;IAC5E,OAAO,CAAC,mBAAmB;IAY3B;mEAC+D;IAC/D,OAAO,CAAC,UAAU;IAgBlB;qFACiF;IACjF,OAAO,CAAC,UAAU;IAMlB;;kFAE8E;IAC9E,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,WAAW;CAapB"}