@demigodmode/pi-web-agent 0.2.1 → 0.3.1

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;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demigodmode/pi-web-agent",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Pi package for reliable web access with explicit search, fetch, and headless boundaries.",
   "type": "module",
   "main": "./dist/extension.js",
@@ -40,6 +40,9 @@
     "test": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "tsc -p tsconfig.json --noEmit",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "eval:live": "npm run build:dev && node dist/scripts/live-web-eval.js",
     "release:dry-run": "node scripts/release.mjs --dry-run",
     "release": "node scripts/release.mjs"
@@ -62,6 +65,7 @@
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^3.2.4",
     "typescript": "^5.8.0",
+    "vitepress": "^1.6.4",
     "vitest": "^3.2.0"
   },
   "peerDependencies": {