@demigodmode/pi-web-agent 0.2.2 → 0.3.1

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,34 @@
+export function buildExplorePresentation(result) {
+    if (result.status === 'error') {
+        return {
+            mode: 'compact',
+            views: {
+                compact: `Research failed: ${result.error?.message ?? 'Unknown research failure.'}`
+            }
+        };
+    }
+    const preview = result.findings.map((finding) => `- ${finding}`).join('\n');
+    const verbose = [
+        'Findings',
+        ...result.findings.map((finding) => `- ${finding}`),
+        '',
+        'Sources',
+        ...result.sources.map((source) => `- ${source.title}: ${source.url}`),
+        result.caveat ? `\nCaveat\n${result.caveat}` : undefined
+    ]
+        .filter((line) => line !== undefined)
+        .join('\n');
+    return {
+        mode: 'compact',
+        views: {
+            compact: `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`,
+            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;

package/dist/presentation/search-presentation.js

@@ -0,0 +1,30 @@
+function formatCompact(result) {
+    if (result.status === 'error') {
+        return `Search failed: ${result.error?.message ?? 'Unknown search failure.'}`;
+    }
+    const suffix = result.results.length === 1 ? 'result' : 'results';
+    return `Found ${result.results.length} ${suffix}`;
+}
+export function buildSearchPresentation(result) {
+    const preview = result.results
+        .slice(0, 3)
+        .map((item, index) => `${index + 1}. ${item.title}`)
+        .join('\n');
+    const verbose = result.results
+        .slice(0, 5)
+        .map((item, index) => `${index + 1}. ${item.title}\n   ${item.url}\n   ${item.snippet}`)
+        .join('\n');
+    return {
+        mode: 'compact',
+        views: {
+            compact: formatCompact(result),
+            preview: preview || undefined,
+            verbose: verbose || undefined
+        },
+        metrics: {
+            resultCount: result.results.length,
+            cacheHit: result.metadata.cacheHit
+        },
+        sources: result.results.map((item) => ({ title: item.title, url: item.url }))
+    };
+}

package/dist/presentation/select-view.d.ts

@@ -0,0 +1,2 @@
+import type { PresentationEnvelope, PresentationMode } from './types.js';
+export declare function selectPresentationView(envelope: PresentationEnvelope | undefined, requestedMode: PresentationMode): string | undefined;

package/dist/presentation/select-view.js

@@ -0,0 +1,12 @@
+export function selectPresentationView(envelope, requestedMode) {
+    if (!envelope) {
+        return undefined;
+    }
+    if (requestedMode === 'preview' && envelope.views.preview) {
+        return envelope.views.preview;
+    }
+    if (requestedMode === 'verbose' && envelope.views.verbose) {
+        return envelope.views.verbose;
+    }
+    return envelope.views.compact;
+}

package/dist/presentation/types.d.ts

@@ -0,0 +1,50 @@
+export declare const PRESENTATION_MODES: readonly ["compact", "preview", "verbose"];
+export type PresentationMode = (typeof PRESENTATION_MODES)[number];
+export type PresentationViews = {
+    compact: string;
+    preview?: string;
+    verbose?: string;
+};
+export type PresentationMetrics = {
+    durationMs?: number;
+    resultCount?: number;
+    sourceCount?: number;
+    wordCount?: number;
+    statusCode?: number;
+    cacheHit?: boolean;
+    truncated?: boolean;
+};
+export type PresentationSource = {
+    title: string;
+    url: string;
+    domain?: string;
+};
+export type PresentationEnvelope = {
+    mode: PresentationMode;
+    views: PresentationViews;
+    metrics?: PresentationMetrics;
+    sources?: PresentationSource[];
+    debug?: Record<string, unknown>;
+};
+export type PresentationToolName = 'web_search' | 'web_fetch' | 'web_fetch_headless' | 'web_explore';
+export type PresentationScope = 'global' | 'project';
+export type PresentationToolOverrideMode = PresentationMode;
+export type PresentationToolConfig = {
+    mode: PresentationToolOverrideMode;
+};
+export type PresentationConfig = {
+    defaultMode: PresentationMode;
+    tools: Partial<Record<PresentationToolName, PresentationToolConfig>>;
+};
+export type PresentationConfigOverride = {
+    defaultMode?: PresentationMode;
+    tools: Partial<Record<PresentationToolName, PresentationToolConfig>>;
+};
+export type PresentationConfigFile = {
+    presentation?: {
+        defaultMode?: unknown;
+        tools?: Partial<Record<PresentationToolName, {
+            mode?: unknown;
+        }>>;
+    };
+};

package/dist/presentation/types.js

@@ -0,0 +1 @@
+export const PRESENTATION_MODES = ['compact', 'preview', 'verbose'];

package/dist/search/duckduckgo.d.ts

@@ -1,4 +1,9 @@
 import type { SearchResult } from '../types.js';
+export type ParsedDuckDuckGoResults = {
+    results: SearchResult[];
+    noResults: boolean;
+    hasResultContainers: boolean;
+};
 export declare function buildSearchUrl(query: string): string;
 export declare function fetchDuckDuckGoHtml(query: string): Promise<string>;
-export declare function parseDuckDuckGoResults(html: string): SearchResult[];
+export declare function parseDuckDuckGoResults(html: string): ParsedDuckDuckGoResults;

package/dist/search/duckduckgo.js

@@ -30,7 +30,8 @@ export async function fetchDuckDuckGoHtml(query) {
 }
 export function parseDuckDuckGoResults(html) {
     const $ = cheerio.load(html);
-    return $('.result')
+    const resultContainers = $('.result');
+    const results = resultContainers
         .map((_, element) => {
         const title = $(element).find('.result__a').first().text().trim();
         const url = normalizeDuckDuckGoUrl($(element).find('.result__a').first().attr('href')?.trim() ?? '');
@@ -39,4 +40,13 @@ export function parseDuckDuckGoResults(html) {
     })
         .get()
         .filter((value) => value !== null);
+    const text = $.text().toLowerCase();
+    const noResults = text.includes('no results found') ||
+        text.includes('no more results') ||
+        text.includes('did not match any documents');
+    return {
+        results,
+        noResults,
+        hasResultContainers: resultContainers.length > 0
+    };
 }

package/dist/tools/web-explore.d.ts

@@ -22,23 +22,13 @@ export declare function createWebExploreTool({ explore }?: {
 }): ({ query }: {
     query: string;
 }) => Promise<{
-    status: "error";
-    findings: never[];
-    sources: never[];
-    error: {
-        code: string;
-        message: string;
-    };
-    caveat?: undefined;
-    text?: undefined;
-} | {
-    status: "ok";
+    presentation: import("../presentation/types.js").PresentationEnvelope;
+    status: "ok" | "error";
     findings: string[];
-    sources: {
+    sources: Array<{
         title: string;
         url: string;
-    }[];
-    caveat: string | undefined;
-    text: string;
-    error?: undefined;
+    }>;
+    caveat?: string;
+    error?: import("../types.js").ToolError;
 }>;

package/dist/tools/web-explore.js

@@ -1,4 +1,5 @@
 import { createResearchWorkflow } from '../orchestration/index.js';
+import { buildExplorePresentation } from '../presentation/explore-presentation.js';
 function findingFromEvidence(evidence, index) {
     if (evidence.summary.includes('Use channel')) {
         return 'Use channel for branded Chrome or Edge when possible.';
@@ -12,23 +13,21 @@ function findingFromEvidence(evidence, index) {
     }
     return evidence.summary || `Finding ${index + 1}`;
 }
-function formatExploreText({ findings, sources, caveat }) {
-    const findingLines = findings.map((finding) => `- ${finding}`).join('\n');
-    const sourceLines = sources.map((source) => `- ${source.title}: ${source.url}`).join('\n');
-    const caveatBlock = caveat ? `\n\nCaveat\n${caveat}` : '';
-    return `Findings\n${findingLines}\n\nSources\n${sourceLines}${caveatBlock}`;
-}
 export function createWebExploreTool({ explore = createResearchWorkflow() } = {}) {
     const runExplore = typeof explore === 'function' ? explore : explore.run.bind(explore);
     return async function webExplore({ query }) {
         const normalizedQuery = query.trim();
         if (!normalizedQuery) {
-            return {
+            const result = {
                 status: 'error',
                 findings: [],
                 sources: [],
                 error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
             };
+            return {
+                ...result,
+                presentation: buildExplorePresentation(result)
+            };
         }
         const result = await runExplore({ query: normalizedQuery });
         const findings = result.evidence.slice(0, 5).map(findingFromEvidence);
@@ -39,12 +38,15 @@ export function createWebExploreTool({ explore = createResearchWorkflow() } = {}
         const caveat = result.decision.action === 'answer'
             ? undefined
             : 'Evidence is partial, so this answer is based on the strongest source found so far.';
-        return {
+        const shaped = {
             status: 'ok',
             findings,
             sources,
-            caveat,
-            text: formatExploreText({ findings, sources, caveat })
+            caveat
+        };
+        return {
+            ...shaped,
+            presentation: buildExplorePresentation(shaped)
         };
     };
 }

package/dist/tools/web-fetch-headless.js

@@ -1,14 +1,23 @@
 import { headlessFetch } from '../fetch/headless-fetch.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
 export function createWebFetchHeadlessTool({ fetchPage = headlessFetch } = {}) {
     return async function webFetchHeadless({ url }) {
         if (!/^https?:\/\//.test(url)) {
-            return {
+            const result = {
                 status: 'unsupported',
                 url,
                 metadata: { method: 'headless', cacheHit: false },
                 error: { code: 'UNSUPPORTED_URL', message: 'Only http and https URLs are supported.' }
             };
+            return {
+                ...result,
+                presentation: buildFetchPresentation(result)
+            };
         }
-        return fetchPage(url);
+        const result = await fetchPage(url);
+        return {
+            ...result,
+            presentation: buildFetchPresentation(result)
+        };
     };
 }

package/dist/tools/web-fetch.js

@@ -1,14 +1,23 @@
 import { createHttpFetcher } from '../fetch/http-fetch.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
 export function createWebFetchTool({ fetchPage = createHttpFetcher() } = {}) {
     return async function webFetch({ url }) {
         if (!/^https?:\/\//.test(url)) {
-            return {
+            const result = {
                 status: 'unsupported',
                 url,
                 metadata: { method: 'http', cacheHit: false },
                 error: { code: 'UNSUPPORTED_URL', message: 'Only http and https URLs are supported.' }
             };
+            return {
+                ...result,
+                presentation: buildFetchPresentation(result)
+            };
         }
-        return fetchPage(url);
+        const result = await fetchPage(url);
+        return {
+            ...result,
+            presentation: buildFetchPresentation(result)
+        };
     };
 }

package/dist/tools/web-search.js

@@ -1,43 +1,130 @@
 import { createCacheKey, createTtlCache } from '../cache/ttl-cache.js';
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
 import { fetchDuckDuckGoHtml, parseDuckDuckGoResults } from '../search/duckduckgo.js';
+function classifySearchFailure(error) {
+    const rawMessage = error instanceof Error ? error.message : 'Unknown search failure.';
+    const normalized = rawMessage.toLowerCase();
+    if (normalized.includes('blocked') ||
+        normalized.includes('rate limit') ||
+        normalized.includes('rate-limit') ||
+        normalized.includes('403') ||
+        normalized.includes('429') ||
+        normalized.includes('captcha') ||
+        normalized.includes('challenge')) {
+        return {
+            code: 'BLOCKED',
+            message: 'DuckDuckGo search appears to be blocked or rate limited.'
+        };
+    }
+    return {
+        code: 'FETCH_FAILED',
+        message: `DuckDuckGo search request failed: ${rawMessage}`
+    };
+}
+function htmlLooksBlocked(html) {
+    const normalized = html.toLowerCase();
+    return (normalized.includes('captcha') ||
+        normalized.includes('challenge') ||
+        normalized.includes('verify you are human') ||
+        normalized.includes('are you a robot') ||
+        normalized.includes('unusual traffic'));
+}
 export function createWebSearchTool({ searchHtml = fetchDuckDuckGoHtml, cache = createTtlCache({ ttlMs: 30_000 }) } = {}) {
     return async function webSearch({ query }) {
         const normalizedQuery = query.trim();
         if (!normalizedQuery) {
-            return {
+            const result = {
                 status: 'error',
                 results: [],
                 metadata: { backend: 'duckduckgo', cacheHit: false },
                 error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
             };
+            return {
+                ...result,
+                presentation: buildSearchPresentation(result)
+            };
         }
         const cacheKey = createCacheKey(['web_search', normalizedQuery]);
         const cached = cache.get(cacheKey);
         if (cached) {
-            return {
+            const result = {
                 ...cached,
                 metadata: { ...cached.metadata, cacheHit: true }
             };
+            return {
+                ...result,
+                presentation: buildSearchPresentation(result)
+            };
         }
         try {
             const html = await searchHtml(normalizedQuery);
+            const parsed = parseDuckDuckGoResults(html);
+            if (parsed.results.length > 0) {
+                const result = {
+                    status: 'ok',
+                    results: parsed.results,
+                    metadata: { backend: 'duckduckgo', cacheHit: false }
+                };
+                cache.set(cacheKey, result);
+                return {
+                    ...result,
+                    presentation: buildSearchPresentation(result)
+                };
+            }
+            if (parsed.noResults) {
+                const result = {
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: 'duckduckgo', cacheHit: false },
+                    error: {
+                        code: 'NO_RESULTS',
+                        message: 'DuckDuckGo returned no usable results for this query.'
+                    }
+                };
+                return {
+                    ...result,
+                    presentation: buildSearchPresentation(result)
+                };
+            }
+            if (htmlLooksBlocked(html)) {
+                const result = {
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: 'duckduckgo', cacheHit: false },
+                    error: {
+                        code: 'BLOCKED',
+                        message: 'DuckDuckGo search appears to be blocked or rate limited.'
+                    }
+                };
+                return {
+                    ...result,
+                    presentation: buildSearchPresentation(result)
+                };
+            }
             const result = {
-                status: 'ok',
-                results: parseDuckDuckGoResults(html),
-                metadata: { backend: 'duckduckgo', cacheHit: false }
+                status: 'error',
+                results: [],
+                metadata: { backend: 'duckduckgo', cacheHit: false },
+                error: {
+                    code: 'PARSE_FAILED',
+                    message: 'DuckDuckGo returned a page, but it did not match the expected results format.'
+                }
+            };
+            return {
+                ...result,
+                presentation: buildSearchPresentation(result)
             };
-            cache.set(cacheKey, result);
-            return result;
         }
         catch (error) {
-            return {
+            const result = {
                 status: 'error',
                 results: [],
                 metadata: { backend: 'duckduckgo', cacheHit: false },
-                error: {
-                    code: 'SEARCH_FAILED',
-                    message: error instanceof Error ? error.message : 'Unknown search failure.'
-                }
+                error: classifySearchFailure(error)
+            };
+            return {
+                ...result,
+                presentation: buildSearchPresentation(result)
             };
         }
     };

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { PresentationEnvelope } from './presentation/types.js';
 export declare const TOOL_STATUSES: readonly ["ok", "needs_headless", "blocked", "unsupported", "error"];
 export type ToolStatus = (typeof TOOL_STATUSES)[number];
 export type SearchResult = {
@@ -30,6 +31,7 @@ export type WebSearchResponse = {
     status: 'ok' | 'error';
     results: SearchResult[];
     metadata: SearchMetadata;
+    presentation?: PresentationEnvelope;
     error?: ToolError;
 };
 export type WebFetchResponse = {
@@ -37,6 +39,7 @@ export type WebFetchResponse = {
     url: string;
     content?: ExtractedContent;
     metadata: FetchMetadata;
+    presentation?: PresentationEnvelope;
     error?: ToolError;
 };
 export type WebFetchHeadlessResponse = {
@@ -44,5 +47,17 @@ export type WebFetchHeadlessResponse = {
     url: string;
     content?: ExtractedContent;
     metadata: FetchMetadata;
+    presentation?: PresentationEnvelope;
+    error?: ToolError;
+};
+export type WebExploreResponse = {
+    status: 'ok' | 'error';
+    findings: string[];
+    sources: Array<{
+        title: string;
+        url: string;
+    }>;
+    caveat?: string;
+    presentation?: PresentationEnvelope;
     error?: ToolError;
 };