@demigodmode/pi-web-agent 0.2.2 → 0.4.0

package/dist/orchestration/research-orchestrator.d.ts

@@ -1,5 +1,5 @@
 import type { WebFetchHeadlessResponse } from '../types.js';
-import type { ResearchEvidence, ResearchWorkerResult } from './research-types.js';
+import type { ResearchEvidence, ResearchOrchestratorDecision, ResearchWorkerResult } from './research-types.js';
 export declare function createResearchOrchestrator({ worker, headlessFetch }: {
     worker: {
         run: (input: {
@@ -15,29 +15,14 @@ export declare function createResearchOrchestrator({ worker, headlessFetch }: {
     run({ query }: {
         query: string;
     }): Promise<{
-        decision: {
-            action: "answer";
-            rationale: string;
-            approvedEvidence: ResearchEvidence[];
-        };
-        evidence: ResearchEvidence[];
-        workerPass: ResearchWorkerResult;
-    } | {
-        decision: {
-            action: "escalate-headless";
-            rationale: string;
-            url: string;
-            approvedEvidence: ResearchEvidence[];
-        };
+        decision: ResearchOrchestratorDecision;
         evidence: ResearchEvidence[];
         workerPass: ResearchWorkerResult;
-    } | {
-        decision: {
-            action: "research-again";
-            rationale: string;
-            followupQuery: string;
+        metadata: {
+            searchPasses: number;
+            fetchedPages: number;
+            headlessAttempts: number;
+            exhaustedBudget: boolean;
         };
-        evidence: ResearchEvidence[];
-        workerPass: ResearchWorkerResult;
     }>;
 };

package/dist/orchestration/research-orchestrator.js

@@ -1,87 +1,199 @@
-function sourceRank(sourceKind) {
-    switch (sourceKind) {
-        case 'official-docs':
-            return 0;
-        case 'official-api':
-            return 1;
-        case 'official-discussion':
-            return 2;
-        case 'issue-thread':
-            return 3;
-        case 'community':
-            return 4;
-        case 'package-page':
-            return 5;
-        default:
-            return 6;
-    }
+import { rankEvidence } from './evidence-ranker.js';
+import { planSearchQueries } from './query-planner.js';
+import { decideNextResearchStep } from './stop-decider.js';
+const DEFAULT_MAX_PASSES = 3;
+const DEFAULT_MAX_FETCHES_PER_PASS = 4;
+const DEFAULT_MAX_HEADLESS_ATTEMPTS = 2;
+function classifyEvidenceUrl(url) {
+    if (url.includes('/docs/api/') || url.includes('/config/'))
+        return 'official-api';
+    if (url.includes('playwright.dev/docs') || url.includes('vitest.dev/guide/'))
+        return 'official-docs';
+    if (url.includes('github.com/vitest-dev/vitest') && url.includes('/docs/'))
+        return 'official-docs';
+    if (url.includes('learn.microsoft.com'))
+        return 'official-docs';
+    if (url.includes('github.com/') && url.includes('/issues/'))
+        return 'issue-thread';
+    if (url.includes('npmjs.com/package/'))
+        return 'package-page';
+    return 'community';
 }
-function sortEvidence(evidence) {
-    return [...evidence].sort((left, right) => sourceRank(left.sourceKind) - sourceRank(right.sourceKind));
+function summarizeText(text, maxLength = 180) {
+    return text.replace(/\s+/g, ' ').trim().slice(0, maxLength);
 }
-function strongEvidence(evidence) {
-    return evidence.filter((item) => item.sourceKind === 'official-docs' ||
-        item.sourceKind === 'official-api' ||
-        item.sourceKind === 'official-discussion');
+function isBotCheckContent({ title = '', text }) {
+    return /performing security verification|security service|verify you are not a bot|just a moment|checking your browser/i.test(`${title}\n${text}`);
 }
-function hasOfficialDocsOrApi(evidence) {
-    return evidence.some((item) => item.sourceKind === 'official-docs' || item.sourceKind === 'official-api');
+function evidenceFromHeadless(result) {
+    if (result.status !== 'ok' || !result.content?.text.trim())
+        return null;
+    if (isBotCheckContent({ title: result.content.title, text: result.content.text }))
+        return null;
+    return {
+        title: result.content.title ?? result.url,
+        url: result.url,
+        sourceKind: classifyEvidenceUrl(result.url),
+        method: 'headless',
+        summary: summarizeText(result.content.text),
+        supports: [summarizeText(result.content.text, 120)]
+    };
 }
-function hasBotCheck(outcomes) {
-    return outcomes.some((outcome) => outcome.kind === 'bot-check');
+function fallbackWorkerPass({ previousQueries, allGaps, allLowValueOutcomes, exhaustedBudget }) {
+    return {
+        searchQueries: previousQueries,
+        evidence: [],
+        gaps: allGaps,
+        lowValueOutcomes: allLowValueOutcomes,
+        exhaustedBudget
+    };
 }
-function isHeadlessWorthTrying(pass, approvedEvidence) {
-    if (!pass.suggestedHeadlessUrl)
-        return false;
-    if (hasBotCheck(pass.lowValueOutcomes))
-        return false;
-    if (approvedEvidence.length >= 2 && hasOfficialDocsOrApi(approvedEvidence))
-        return false;
-    const candidate = pass.suggestedHeadlessUrl;
-    return !candidate.includes('npmjs.com/package/');
+function buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutcomes, headlessAttempts, exhaustedBudget }) {
+    return {
+        searchPasses: previousQueries.length,
+        fetchedPages: allEvidence.length + allGaps.length + allLowValueOutcomes.length,
+        headlessAttempts,
+        exhaustedBudget
+    };
+}
+function decisionForAnswer(action, query, ranked) {
+    if (action === 'answer') {
+        return {
+            action: 'answer',
+            rationale: 'Adaptive research gathered enough strong evidence.',
+            approvedEvidence: ranked
+        };
+    }
+    return {
+        action: 'research-again',
+        rationale: 'Research budget exhausted; answer with caveat.',
+        followupQuery: query
+    };
 }
 export function createResearchOrchestrator({ worker, headlessFetch }) {
     return {
         async run({ query }) {
-            const pass = await worker.run({ query, maxSearchRounds: 1, maxFetches: 3 });
-            const approvedEvidence = sortEvidence(pass.evidence.filter((item) => item.sourceKind !== 'package-page'));
-            const strong = strongEvidence(approvedEvidence);
-            const enoughEvidence = strong.length >= 2 && hasOfficialDocsOrApi(approvedEvidence);
-            if (enoughEvidence) {
-                const decision = {
-                    action: 'answer',
-                    rationale: 'Two strong sources with official support are enough to answer safely.',
-                    approvedEvidence
-                };
-                return { decision, evidence: approvedEvidence, workerPass: pass };
-            }
-            if (isHeadlessWorthTrying(pass, approvedEvidence)) {
-                const url = pass.suggestedHeadlessUrl;
-                await headlessFetch({ url });
-                const decision = {
-                    action: 'escalate-headless',
-                    rationale: 'One high-value page is worth a single orchestrator-approved headless retry.',
-                    url,
-                    approvedEvidence
-                };
-                return { decision, evidence: approvedEvidence, workerPass: pass };
-            }
-            const hasConcreteGap = pass.gaps.length > 0;
-            const onlyLowValueOutcomes = pass.lowValueOutcomes.length > 0 && pass.evidence.length === 0;
-            if (!hasConcreteGap || onlyLowValueOutcomes) {
-                const decision = {
-                    action: 'research-again',
-                    rationale: 'Current results did not justify more escalation; continue only with a more targeted pass.',
-                    followupQuery: query
-                };
-                return { decision, evidence: approvedEvidence, workerPass: pass };
+            const allEvidence = [];
+            const allGaps = [];
+            const allLowValueOutcomes = [];
+            const previousQueries = [];
+            const suggestedHeadlessUrls = [];
+            let headlessAttempts = 0;
+            let lastPass;
+            for (let passIndex = 0; passIndex < DEFAULT_MAX_PASSES; passIndex++) {
+                const queries = planSearchQueries({
+                    originalQuery: query,
+                    passIndex,
+                    previousQueries,
+                    gaps: allGaps.map((gap) => gap.message)
+                });
+                for (const plannedQuery of queries) {
+                    previousQueries.push(plannedQuery);
+                    const pass = await worker.run({
+                        query: plannedQuery,
+                        maxSearchRounds: 1,
+                        maxFetches: DEFAULT_MAX_FETCHES_PER_PASS
+                    });
+                    lastPass = pass;
+                    allEvidence.push(...pass.evidence);
+                    allGaps.push(...pass.gaps);
+                    allLowValueOutcomes.push(...pass.lowValueOutcomes);
+                    if (pass.suggestedHeadlessUrl)
+                        suggestedHeadlessUrls.push(pass.suggestedHeadlessUrl);
+                    const ranked = rankEvidence(allEvidence.filter((item) => item.sourceKind !== 'package-page'));
+                    const decision = decideNextResearchStep({
+                        evidence: ranked,
+                        suggestedHeadlessUrls,
+                        passIndex,
+                        maxPasses: DEFAULT_MAX_PASSES,
+                        headlessAttempts,
+                        maxHeadlessAttempts: DEFAULT_MAX_HEADLESS_ATTEMPTS
+                    });
+                    if (decision.action === 'headless') {
+                        headlessAttempts++;
+                        const headlessResult = await headlessFetch({ url: decision.url });
+                        const headlessEvidence = evidenceFromHeadless(headlessResult);
+                        if (headlessEvidence) {
+                            allEvidence.push(headlessEvidence);
+                            const updatedRanked = rankEvidence(allEvidence.filter((item) => item.sourceKind !== 'package-page'));
+                            const updatedDecision = decideNextResearchStep({
+                                evidence: updatedRanked,
+                                suggestedHeadlessUrls: [],
+                                passIndex,
+                                maxPasses: DEFAULT_MAX_PASSES,
+                                headlessAttempts,
+                                maxHeadlessAttempts: DEFAULT_MAX_HEADLESS_ATTEMPTS
+                            });
+                            return {
+                                decision: decisionForAnswer(updatedDecision.action === 'answer' ? 'answer' : 'answer-with-caveat', query, updatedRanked),
+                                evidence: updatedRanked,
+                                workerPass: lastPass,
+                                metadata: buildMetadata({
+                                    previousQueries,
+                                    allEvidence,
+                                    allGaps,
+                                    allLowValueOutcomes,
+                                    headlessAttempts,
+                                    exhaustedBudget: updatedDecision.action !== 'answer'
+                                })
+                            };
+                        }
+                        return {
+                            decision: {
+                                action: 'escalate-headless',
+                                rationale: 'One high-value page is worth a single orchestrator-approved headless retry.',
+                                url: decision.url,
+                                approvedEvidence: ranked
+                            },
+                            evidence: ranked,
+                            workerPass: lastPass,
+                            metadata: buildMetadata({
+                                previousQueries,
+                                allEvidence,
+                                allGaps,
+                                allLowValueOutcomes,
+                                headlessAttempts,
+                                exhaustedBudget: false
+                            })
+                        };
+                    }
+                    if (decision.action === 'answer' || decision.action === 'answer-with-caveat') {
+                        return {
+                            decision: decisionForAnswer(decision.action, query, ranked),
+                            evidence: ranked,
+                            workerPass: lastPass,
+                            metadata: buildMetadata({
+                                previousQueries,
+                                allEvidence,
+                                allGaps,
+                                allLowValueOutcomes,
+                                headlessAttempts,
+                                exhaustedBudget: decision.action === 'answer-with-caveat'
+                            })
+                        };
+                    }
+                }
             }
-            const decision = {
-                action: 'research-again',
-                rationale: 'The first pass did not gather enough strong evidence to answer safely.',
-                followupQuery: query
+            const ranked = rankEvidence(allEvidence.filter((item) => item.sourceKind !== 'package-page'));
+            return {
+                decision: decisionForAnswer('answer-with-caveat', query, ranked),
+                evidence: ranked,
+                workerPass: lastPass ??
+                    fallbackWorkerPass({
+                        previousQueries,
+                        allGaps,
+                        allLowValueOutcomes,
+                        exhaustedBudget: true
+                    }),
+                metadata: buildMetadata({
+                    previousQueries,
+                    allEvidence,
+                    allGaps,
+                    allLowValueOutcomes,
+                    headlessAttempts,
+                    exhaustedBudget: true
+                })
             };
-            return { decision, evidence: approvedEvidence, workerPass: pass };
         }
     };
 }

package/dist/orchestration/research-types.d.ts

@@ -25,6 +25,12 @@ export type ResearchWorkerResult = {
     suggestedHeadlessUrl?: string;
     exhaustedBudget: boolean;
 };
+export type ResearchRunMetadata = {
+    searchPasses: number;
+    fetchedPages: number;
+    headlessAttempts: number;
+    exhaustedBudget: boolean;
+};
 export type ResearchOrchestratorDecision = {
     action: 'answer';
     rationale: string;

package/dist/orchestration/research-worker.js

@@ -1,8 +1,11 @@
+import { selectCandidates } from './candidate-selector.js';
 function classifySource(url) {
     if (url.includes('/docs/api/') || url.includes('/config/'))
         return 'official-api';
     if (url.includes('playwright.dev/docs') || url.includes('vitest.dev/guide/'))
         return 'official-docs';
+    if (url.includes('github.com/vitest-dev/vitest') && url.includes('/docs/'))
+        return 'official-docs';
     if (url.includes('learn.microsoft.com'))
         return 'official-docs';
     if (url.includes('github.com/') && url.includes('/issues/'))
@@ -91,7 +94,11 @@ export function createResearchWorker({ search, fetchPage }) {
                     exhaustedBudget: false
                 };
             }
-            const candidates = searchResult.results.slice(0, maxFetches);
+            const candidates = selectCandidates({
+                results: searchResult.results,
+                seenUrls: new Set(evidence.map((item) => item.url)),
+                maxCandidates: maxFetches
+            });
             for (const candidate of candidates) {
                 const fetched = await fetchPage({ url: candidate.url });
                 if (fetched.status === 'ok') {

package/dist/orchestration/stop-decider.d.ts

@@ -0,0 +1,19 @@
+import type { ResearchEvidence } from './research-types.js';
+export type ResearchStepDecision = {
+    action: 'answer';
+} | {
+    action: 'answer-with-caveat';
+} | {
+    action: 'search-again';
+} | {
+    action: 'headless';
+    url: string;
+};
+export declare function decideNextResearchStep({ evidence, suggestedHeadlessUrls, passIndex, maxPasses, headlessAttempts, maxHeadlessAttempts }: {
+    evidence: ResearchEvidence[];
+    suggestedHeadlessUrls: string[];
+    passIndex: number;
+    maxPasses: number;
+    headlessAttempts: number;
+    maxHeadlessAttempts: number;
+}): ResearchStepDecision;

package/dist/orchestration/stop-decider.js

@@ -0,0 +1,14 @@
+import { hasOfficialEvidence, strongEvidenceCount } from './evidence-ranker.js';
+export function decideNextResearchStep({ evidence, suggestedHeadlessUrls, passIndex, maxPasses, headlessAttempts, maxHeadlessAttempts }) {
+    if (strongEvidenceCount(evidence) >= 2 && hasOfficialEvidence(evidence)) {
+        return { action: 'answer' };
+    }
+    const headlessUrl = suggestedHeadlessUrls.find((url) => !url.includes('npmjs.com/package/'));
+    if (headlessUrl && headlessAttempts < maxHeadlessAttempts) {
+        return { action: 'headless', url: headlessUrl };
+    }
+    if (passIndex + 1 < maxPasses) {
+        return { action: 'search-again' };
+    }
+    return { action: 'answer-with-caveat' };
+}

package/dist/presentation/config-store.d.ts

@@ -0,0 +1,23 @@
+import type { PresentationConfig, PresentationConfigOverride, PresentationScope } from './types.js';
+export type PresentationConfigStoreOptions = {
+    homeDir?: string;
+    projectDir?: string;
+};
+export type PresentationConfigLayer = {
+    path: string;
+    exists: boolean;
+    rawConfig?: PresentationConfigOverride;
+    error?: string;
+};
+export type LoadedPresentationConfig = {
+    global: PresentationConfigLayer;
+    project: PresentationConfigLayer;
+    effectiveConfig: PresentationConfig;
+};
+export declare function getPresentationConfigPaths(options?: PresentationConfigStoreOptions): {
+    globalPath: string;
+    projectPath: string;
+};
+export declare function loadPresentationConfigLayers(options?: PresentationConfigStoreOptions): Promise<LoadedPresentationConfig>;
+export declare function savePresentationConfigScope(options: PresentationConfigStoreOptions, scope: PresentationScope, config: PresentationConfigOverride): Promise<void>;
+export declare function resetPresentationConfigScope(options: PresentationConfigStoreOptions, scope: PresentationScope): Promise<void>;

package/dist/presentation/config-store.js

@@ -0,0 +1,64 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_PRESENTATION_CONFIG, extractPresentationConfigOverride, mergePresentationConfigLayers } from './config.js';
+export function getPresentationConfigPaths(options = {}) {
+    const homeDir = options.homeDir ?? process.env.USERPROFILE ?? process.env.HOME ?? '';
+    const projectDir = options.projectDir ?? process.cwd();
+    return {
+        globalPath: path.join(homeDir, '.pi', 'agent', 'extensions', 'pi-web-agent', 'config.json'),
+        projectPath: path.join(projectDir, '.pi', 'extensions', 'pi-web-agent', 'config.json')
+    };
+}
+async function readPresentationConfigFile(filePath) {
+    try {
+        const rawText = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(rawText);
+        return {
+            path: filePath,
+            exists: true,
+            rawConfig: extractPresentationConfigOverride(parsed)
+        };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return { path: filePath, exists: false };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            path: filePath,
+            exists: true,
+            error: message
+        };
+    }
+}
+function serializePresentationConfigOverride(config) {
+    const presentation = {};
+    if (config.defaultMode) {
+        presentation.defaultMode = config.defaultMode;
+    }
+    if (Object.keys(config.tools).length > 0) {
+        presentation.tools = config.tools;
+    }
+    return { presentation };
+}
+export async function loadPresentationConfigLayers(options = {}) {
+    const { globalPath, projectPath } = getPresentationConfigPaths(options);
+    const global = await readPresentationConfigFile(globalPath);
+    const project = await readPresentationConfigFile(projectPath);
+    return {
+        global,
+        project,
+        effectiveConfig: mergePresentationConfigLayers(DEFAULT_PRESENTATION_CONFIG, global.rawConfig, project.rawConfig)
+    };
+}
+export async function savePresentationConfigScope(options, scope, config) {
+    const { globalPath, projectPath } = getPresentationConfigPaths(options);
+    const filePath = scope === 'global' ? globalPath : projectPath;
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(serializePresentationConfigOverride(config), null, 2) + '\n', 'utf8');
+}
+export async function resetPresentationConfigScope(options, scope) {
+    const { globalPath, projectPath } = getPresentationConfigPaths(options);
+    const filePath = scope === 'global' ? globalPath : projectPath;
+    await rm(filePath, { force: true });
+}

package/dist/presentation/config.d.ts

@@ -0,0 +1,7 @@
+import { type PresentationConfig, type PresentationConfigFile, type PresentationConfigOverride, type PresentationMode, type PresentationToolName } from './types.js';
+export declare const DEFAULT_PRESENTATION_CONFIG: PresentationConfig;
+export declare function isPresentationMode(value: unknown): value is PresentationMode;
+export declare function extractPresentationConfigOverride(file: PresentationConfigFile | null | undefined): PresentationConfigOverride;
+export declare function normalizePresentationConfigFile(file: PresentationConfigFile | null | undefined): PresentationConfig;
+export declare function mergePresentationConfigLayers(defaults: PresentationConfig, globalConfig?: PresentationConfigOverride, projectConfig?: PresentationConfigOverride): PresentationConfig;
+export declare function resolvePresentationMode(toolName: PresentationToolName, config?: PresentationConfig): PresentationMode;

package/dist/presentation/config.js

@@ -0,0 +1,44 @@
+import { PRESENTATION_MODES } from './types.js';
+const PRESENTATION_MODE_SET = new Set(PRESENTATION_MODES);
+export const DEFAULT_PRESENTATION_CONFIG = {
+    defaultMode: 'compact',
+    tools: {}
+};
+export function isPresentationMode(value) {
+    return typeof value === 'string' && PRESENTATION_MODE_SET.has(value);
+}
+export function extractPresentationConfigOverride(file) {
+    const presentation = file?.presentation;
+    const tools = Object.fromEntries(Object.entries(presentation?.tools ?? {}).flatMap(([toolName, value]) => {
+        if (!value || !isPresentationMode(value.mode)) {
+            return [];
+        }
+        return [[toolName, { mode: value.mode }]];
+    }));
+    return {
+        defaultMode: isPresentationMode(presentation?.defaultMode)
+            ? presentation.defaultMode
+            : undefined,
+        tools
+    };
+}
+export function normalizePresentationConfigFile(file) {
+    const override = extractPresentationConfigOverride(file);
+    return {
+        defaultMode: override.defaultMode ?? DEFAULT_PRESENTATION_CONFIG.defaultMode,
+        tools: override.tools
+    };
+}
+export function mergePresentationConfigLayers(defaults, globalConfig, projectConfig) {
+    return {
+        defaultMode: projectConfig?.defaultMode ?? globalConfig?.defaultMode ?? defaults.defaultMode,
+        tools: {
+            ...defaults.tools,
+            ...globalConfig?.tools,
+            ...projectConfig?.tools
+        }
+    };
+}
+export function resolvePresentationMode(toolName, config = DEFAULT_PRESENTATION_CONFIG) {
+    return config.tools[toolName]?.mode ?? config.defaultMode;
+}

package/dist/presentation/explore-presentation.d.ts

@@ -0,0 +1,3 @@
+import type { WebExploreResponse } from '../types.js';
+import type { PresentationEnvelope } from './types.js';
+export declare function buildExplorePresentation(result: WebExploreResponse): PresentationEnvelope;

package/dist/presentation/explore-presentation.js

@@ -0,0 +1,56 @@
+function internalReaderLabel(method) {
+    if (method === 'headless')
+        return 'web_fetch_headless';
+    if (method === 'http')
+        return 'web_fetch';
+    return 'web_explore';
+}
+export function buildExplorePresentation(result) {
+    if (result.status === 'error') {
+        return {
+            mode: 'compact',
+            views: {
+                compact: `Research failed: ${result.error?.message ?? 'Unknown research failure.'}`
+            }
+        };
+    }
+    const internalSummary = result.metadata
+        ? `Internal research: web_search ×${result.metadata.searchPasses}, web_fetch ×${result.metadata.fetchedPages}, web_fetch_headless ×${result.metadata.headlessAttempts}`
+        : undefined;
+    const hasEvidence = result.findings.length > 0 || result.sources.length > 0;
+    const evidenceLines = hasEvidence
+        ? result.findings.map((finding, index) => `- [${internalReaderLabel(result.sources[index]?.method)}] ${finding}`)
+        : ['No usable evidence found.'];
+    const preview = [
+        ...evidenceLines,
+        internalSummary ? `\n${internalSummary}` : undefined
+    ]
+        .filter((line) => line !== undefined)
+        .join('\n');
+    const verbose = [
+        'Findings',
+        ...evidenceLines,
+        '',
+        'Sources',
+        ...result.sources.map((source) => `- [${internalReaderLabel(source.method)}] ${source.title}: ${source.url}`),
+        internalSummary ? `\nInternal tools\n${internalSummary}` : undefined,
+        result.caveat ? `\nCaveat\n${result.caveat}` : undefined
+    ]
+        .filter((line) => line !== undefined)
+        .join('\n');
+    return {
+        mode: 'compact',
+        views: {
+            compact: hasEvidence
+                ? `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`
+                : 'No usable evidence found',
+            preview,
+            verbose
+        },
+        metrics: {
+            sourceCount: result.sources.length,
+            resultCount: result.findings.length
+        },
+        sources: result.sources
+    };
+}

package/dist/presentation/fetch-presentation.d.ts

@@ -0,0 +1,5 @@
+import type { WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
+import type { PresentationEnvelope } from './types.js';
+type FetchLike = WebFetchResponse | WebFetchHeadlessResponse;
+export declare function buildFetchPresentation(result: FetchLike): PresentationEnvelope;
+export {};

package/dist/presentation/fetch-presentation.js

@@ -0,0 +1,40 @@
+function countWords(text) {
+    return text?.trim() ? text.trim().split(/\s+/).length : undefined;
+}
+function firstExcerpt(text, maxChars = 240) {
+    if (!text) {
+        return undefined;
+    }
+    return text.length <= maxChars ? text : `${text.slice(0, maxChars).trimEnd()}…`;
+}
+export function buildFetchPresentation(result) {
+    const wordCount = countWords(result.content?.text);
+    const compact = result.status === 'ok'
+        ? `Fetched page · article extracted${wordCount ? ` · ${wordCount} words` : ''}`
+        : result.status === 'needs_headless'
+            ? `Needs headless rendering: ${result.error?.message ?? 'Headless rendering recommended.'}`
+            : `Fetch failed: ${result.error?.message ?? 'Unknown fetch failure.'}`;
+    return {
+        mode: 'compact',
+        views: {
+            compact,
+            preview: result.content?.title
+                ? `${result.content.title}\n${firstExcerpt(result.content.text) ?? ''}`.trim()
+                : firstExcerpt(result.content?.text),
+            verbose: result.status === 'ok'
+                ? [
+                    `URL: ${result.url}`,
+                    result.content?.title ? `Title: ${result.content.title}` : undefined,
+                    firstExcerpt(result.content?.text, 500)
+                ]
+                    .filter(Boolean)
+                    .join('\n')
+                : undefined
+        },
+        metrics: {
+            wordCount,
+            cacheHit: result.metadata.cacheHit
+        },
+        sources: [{ title: result.content?.title ?? result.url, url: result.url }]
+    };
+}

package/dist/presentation/search-presentation.d.ts

@@ -0,0 +1,3 @@
+import type { WebSearchResponse } from '../types.js';
+import type { PresentationEnvelope } from './types.js';
+export declare function buildSearchPresentation(result: WebSearchResponse): PresentationEnvelope;