@selesai/code 0.1.19 → 0.2.1

package/dist/extensions/pi-web-agent/src/presentation/types.ts

@@ -0,0 +1,63 @@
+export const PRESENTATION_MODES = ['compact', 'preview', 'verbose'] as const;
+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/extensions/pi-web-agent/src/search/brave.ts

@@ -0,0 +1,114 @@
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import type { SearchResult, WebSearchResponse } from '../types.js';
+
+type BraveWebResult = {
+  title?: unknown;
+  url?: unknown;
+  description?: unknown;
+};
+
+type BraveSearchResponse = {
+  web?: {
+    results?: BraveWebResult[];
+  };
+};
+
+const BRAVE_WEB_SEARCH_URL = 'https://api.search.brave.com/res/v1/web/search';
+
+function resultWithPresentation(result: WebSearchResponse): WebSearchResponse {
+  return { ...result, presentation: buildSearchPresentation(result) };
+}
+
+function normalizeResults(response: BraveSearchResponse): SearchResult[] {
+  return (response.web?.results ?? []).flatMap((item) => {
+    if (typeof item.title !== 'string' || typeof item.url !== 'string') {
+      return [];
+    }
+
+    return [
+      {
+        title: item.title,
+        url: item.url,
+        snippet: typeof item.description === 'string' ? item.description : ''
+      }
+    ];
+  });
+}
+
+function buildBraveUrl(query: string) {
+  const url = new URL(BRAVE_WEB_SEARCH_URL);
+  url.searchParams.set('q', query);
+  return url.toString();
+}
+
+export function createBraveSearchTool({
+  apiKey,
+  fetchImpl = fetch
+}: {
+  apiKey?: string;
+  fetchImpl?: typeof fetch;
+}) {
+  return async function braveSearch({ query }: { query: string }): Promise<WebSearchResponse> {
+    const normalizedQuery = query.trim();
+
+    if (!normalizedQuery) {
+      return resultWithPresentation({
+        status: 'error',
+        results: [],
+        metadata: { backend: 'brave', cacheHit: false },
+        error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
+      });
+    }
+
+    if (!apiKey?.trim()) {
+      return resultWithPresentation({
+        status: 'error',
+        results: [],
+        metadata: { backend: 'brave', cacheHit: false },
+        error: {
+          code: 'BACKEND_CONFIG_INVALID',
+          message: 'Brave search requires PI_WEB_AGENT_BRAVE_API_KEY.'
+        }
+      });
+    }
+
+    try {
+      const response = await fetchImpl(buildBraveUrl(normalizedQuery), {
+        headers: {
+          Accept: 'application/json',
+          'X-Subscription-Token': apiKey
+        }
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      const parsed = (await response.json()) as BraveSearchResponse;
+      const results = normalizeResults(parsed);
+
+      if (results.length === 0) {
+        return resultWithPresentation({
+          status: 'error',
+          results: [],
+          metadata: { backend: 'brave', cacheHit: false },
+          error: { code: 'NO_RESULTS', message: 'Brave returned no usable results for this query.' }
+        });
+      }
+
+      return resultWithPresentation({
+        status: 'ok',
+        results,
+        metadata: { backend: 'brave', cacheHit: false }
+      });
+    } catch (error) {
+      const rawMessage = error instanceof Error ? error.message : String(error);
+      return resultWithPresentation({
+        status: 'error',
+        results: [],
+        metadata: { backend: 'brave', cacheHit: false },
+        error: { code: 'FETCH_FAILED', message: `Brave search request failed: ${rawMessage}` }
+      });
+    }
+  };
+}

package/dist/extensions/pi-web-agent/src/search/duckduckgo.ts

@@ -0,0 +1,72 @@
+import * as cheerio from 'cheerio';
+import type { SearchResult } from '../types.js';
+
+export type ParsedDuckDuckGoResults = {
+  results: SearchResult[];
+  noResults: boolean;
+  hasResultContainers: boolean;
+};
+
+function normalizeDuckDuckGoUrl(rawUrl: string): string {
+  try {
+    const absolute = rawUrl.startsWith('//') ? `https:${rawUrl}` : rawUrl;
+    const parsed = new URL(absolute);
+    const isDuckDuckGoRedirect = parsed.hostname === 'duckduckgo.com' && parsed.pathname === '/l/';
+
+    if (!isDuckDuckGoRedirect) {
+      return rawUrl;
+    }
+
+    const target = parsed.searchParams.get('uddg');
+    if (!target) {
+      return rawUrl;
+    }
+
+    return decodeURIComponent(target);
+  } catch {
+    return rawUrl;
+  }
+}
+
+export function buildSearchUrl(query: string): string {
+  const params = new URLSearchParams({ q: query });
+  return `https://html.duckduckgo.com/html/?${params.toString()}`;
+}
+
+export async function fetchDuckDuckGoHtml(query: string): Promise<string> {
+  const response = await fetch(buildSearchUrl(query));
+  if (!response.ok) {
+    throw new Error(`DuckDuckGo request failed with ${response.status}`);
+  }
+  return response.text();
+}
+
+export function parseDuckDuckGoResults(html: string): ParsedDuckDuckGoResults {
+  const $ = cheerio.load(html);
+  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() ?? ''
+      );
+      const snippet = $(element).find('.result__snippet').first().text().trim();
+
+      return title && url ? { title, url, snippet } : null;
+    })
+    .get()
+    .filter((value): value is SearchResult => 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/extensions/pi-web-agent/src/search/searxng.ts

@@ -0,0 +1,96 @@
+import type { SearxngOptions } from '../backends/config.js';
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import type { SearchResult, WebSearchResponse } from '../types.js';
+
+type SearxngResult = {
+  title?: unknown;
+  url?: unknown;
+  content?: unknown;
+};
+
+type SearxngResponse = {
+  results?: SearxngResult[];
+};
+
+function buildSearchUrl(baseUrl: string, query: string, options: SearxngOptions = {}) {
+  const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
+  url.searchParams.set('q', query);
+  url.searchParams.set('format', 'json');
+  if (options.categories?.length) url.searchParams.set('categories', options.categories.join(','));
+  if (options.language) url.searchParams.set('language', options.language);
+  if (options.safesearch !== undefined) url.searchParams.set('safesearch', String(options.safesearch));
+  return url.toString();
+}
+
+function normalizeResults(response: SearxngResponse): SearchResult[] {
+  return (response.results ?? []).flatMap((result) => {
+    if (typeof result.title !== 'string' || typeof result.url !== 'string') {
+      return [];
+    }
+
+    return [
+      {
+        title: result.title,
+        url: result.url,
+        snippet: typeof result.content === 'string' ? result.content : ''
+      }
+    ];
+  });
+}
+
+export function createSearxngSearchTool({
+  baseUrl,
+  options,
+  fetchImpl = fetch
+}: {
+  baseUrl: string;
+  options?: SearxngOptions;
+  fetchImpl?: typeof fetch;
+}) {
+  return async function searxngSearch({ query }: { query: string }): Promise<WebSearchResponse> {
+    const normalizedQuery = query.trim();
+
+    if (!normalizedQuery) {
+      const result: WebSearchResponse = {
+        status: 'error',
+        results: [],
+        metadata: { backend: 'searxng', cacheHit: false },
+        error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
+      };
+      return { ...result, presentation: buildSearchPresentation(result) };
+    }
+
+    try {
+      const response = await fetchImpl(buildSearchUrl(baseUrl, normalizedQuery, options));
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      const parsed = (await response.json()) as SearxngResponse;
+      const results = normalizeResults(parsed);
+      const result: WebSearchResponse = results.length > 0
+        ? {
+            status: 'ok',
+            results,
+            metadata: { backend: 'searxng', cacheHit: false }
+          }
+        : {
+            status: 'error',
+            results: [],
+            metadata: { backend: 'searxng', cacheHit: false },
+            error: { code: 'NO_RESULTS', message: 'SearXNG returned no usable results for this query.' }
+          };
+
+      return { ...result, presentation: buildSearchPresentation(result) };
+    } catch (error) {
+      const rawMessage = error instanceof Error ? error.message : String(error);
+      const result: WebSearchResponse = {
+        status: 'error',
+        results: [],
+        metadata: { backend: 'searxng', cacheHit: false },
+        error: { code: 'FETCH_FAILED', message: `SearXNG search request failed: ${rawMessage}` }
+      };
+      return { ...result, presentation: buildSearchPresentation(result) };
+    }
+  };
+}

package/dist/extensions/pi-web-agent/src/tools/web-explore.ts

@@ -0,0 +1,71 @@
+import { createResearchWorkflow } from '../orchestration/index.js';
+import { synthesizeAnswer } from '../orchestration/answer-synthesizer.js';
+import type { ResearchEvidence } from '../orchestration/research-types.js';
+import { buildExplorePresentation } from '../presentation/explore-presentation.js';
+import type { EvidenceCaveatReason } from '../orchestration/evidence-quality.js';
+import type { WebExploreResponse } from '../types.js';
+
+export function createWebExploreTool({
+  explore = createResearchWorkflow()
+}: {
+  explore?:
+    | {
+        run: (input: { query: string }) => Promise<{
+          decision: { action: 'answer' | 'research-again' | 'escalate-headless' };
+          evidence: ResearchEvidence[];
+          workerPass: unknown;
+          metadata?: WebExploreResponse['metadata'];
+        }>;
+      }
+    | ((input: { query: string }) => Promise<{
+        decision: { action: 'answer' | 'research-again' | 'escalate-headless' };
+        evidence: ResearchEvidence[];
+        workerPass: unknown;
+        metadata?: WebExploreResponse['metadata'];
+      }>);
+} = {}) {
+  const runExplore = typeof explore === 'function' ? explore : explore.run.bind(explore);
+
+  return async function webExplore({ query }: { query: string }) {
+    const normalizedQuery = query.trim();
+
+    if (!normalizedQuery) {
+      const result: WebExploreResponse = {
+        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 sources = result.evidence.slice(0, 4).map((item) => ({
+      title: item.title,
+      url: item.url,
+      method: item.method
+    }));
+    const synthesized = synthesizeAnswer({
+      evidence: result.evidence,
+      partial: result.decision.action !== 'answer',
+      caveatReasons: result.metadata?.caveatReasons as EvidenceCaveatReason[] | undefined
+    });
+
+    const shaped: WebExploreResponse = {
+      status: 'ok',
+      findings: synthesized.findings,
+      sources,
+      caveat: synthesized.caveat,
+      metadata: result.metadata
+    };
+
+    return {
+      ...shaped,
+      presentation: buildExplorePresentation(shaped)
+    };
+  };
+}

package/dist/extensions/pi-web-agent/src/tools/web-fetch-headless.ts

@@ -0,0 +1,31 @@
+import { headlessFetch } from '../fetch/headless-fetch.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
+import type { WebFetchHeadlessResponse } from '../types.js';
+
+export function createWebFetchHeadlessTool({
+  fetchPage = headlessFetch
+}: {
+  fetchPage?: (url: string) => Promise<WebFetchHeadlessResponse>;
+} = {}) {
+  return async function webFetchHeadless({ url }: { url: string }): Promise<WebFetchHeadlessResponse> {
+    if (!/^https?:\/\//.test(url)) {
+      const result: WebFetchHeadlessResponse = {
+        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)
+      };
+    }
+
+    const result = await fetchPage(url);
+    return {
+      ...result,
+      presentation: buildFetchPresentation(result)
+    };
+  };
+}

package/dist/extensions/pi-web-agent/src/tools/web-fetch.ts

@@ -0,0 +1,31 @@
+import { createHttpFetcher } from '../fetch/http-fetch.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
+import type { WebFetchResponse } from '../types.js';
+
+export function createWebFetchTool({
+  fetchPage = createHttpFetcher()
+}: {
+  fetchPage?: (url: string) => Promise<WebFetchResponse>;
+} = {}) {
+  return async function webFetch({ url }: { url: string }): Promise<WebFetchResponse> {
+    if (!/^https?:\/\//.test(url)) {
+      const result: WebFetchResponse = {
+        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)
+      };
+    }
+
+    const result = await fetchPage(url);
+    return {
+      ...result,
+      presentation: buildFetchPresentation(result)
+    };
+  };
+}

package/dist/extensions/pi-web-agent/src/tools/web-search.ts

@@ -0,0 +1,157 @@
+import { createCacheKey, createTtlCache } from '../cache/ttl-cache.js';
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import { fetchDuckDuckGoHtml, parseDuckDuckGoResults } from '../search/duckduckgo.js';
+import type { WebSearchResponse } from '../types.js';
+
+function classifySearchFailure(error: unknown) {
+  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: string) {
+  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<WebSearchResponse>({ ttlMs: 30_000 })
+}: {
+  searchHtml?: (query: string) => Promise<string>;
+  cache?: {
+    get(key: string): WebSearchResponse | undefined;
+    set(key: string, value: WebSearchResponse): void;
+  };
+} = {}) {
+  return async function webSearch({ query }: { query: string }): Promise<WebSearchResponse> {
+    const normalizedQuery = query.trim();
+
+    if (!normalizedQuery) {
+      const result: WebSearchResponse = {
+        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) {
+      const result: WebSearchResponse = {
+        ...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: WebSearchResponse = {
+          status: 'ok',
+          results: parsed.results,
+          metadata: { backend: 'duckduckgo', cacheHit: false }
+        };
+        cache.set(cacheKey, result);
+        return {
+          ...result,
+          presentation: buildSearchPresentation(result)
+        };
+      }
+
+      if (parsed.noResults) {
+        const result: WebSearchResponse = {
+          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: WebSearchResponse = {
+          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: WebSearchResponse = {
+        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)
+      };
+    } catch (error) {
+      const result: WebSearchResponse = {
+        status: 'error',
+        results: [],
+        metadata: { backend: 'duckduckgo', cacheHit: false },
+        error: classifySearchFailure(error)
+      };
+      return {
+        ...result,
+        presentation: buildSearchPresentation(result)
+      };
+    }
+  };
+}