pi-agent-browser-native 0.9.3 → 0.9.4

package/dist/extensions/agent-browser/lib/web-search-results.js

@@ -0,0 +1,281 @@
+import { isRecord } from "./parsing.js";
+const HTML_ENTITY_REPLACEMENTS = {
+    amp: "&",
+    apos: "'",
+    gt: ">",
+    lt: "<",
+    nbsp: " ",
+    quot: '"',
+};
+const HTML_TAG_NAMES_TO_STRIP = new Set([
+    "a",
+    "abbr",
+    "address",
+    "article",
+    "aside",
+    "audio",
+    "b",
+    "base",
+    "blockquote",
+    "body",
+    "br",
+    "button",
+    "canvas",
+    "code",
+    "div",
+    "em",
+    "embed",
+    "footer",
+    "form",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "head",
+    "header",
+    "html",
+    "i",
+    "iframe",
+    "img",
+    "input",
+    "li",
+    "link",
+    "main",
+    "mark",
+    "math",
+    "meta",
+    "nav",
+    "object",
+    "ol",
+    "option",
+    "p",
+    "pre",
+    "script",
+    "section",
+    "select",
+    "source",
+    "span",
+    "strong",
+    "style",
+    "svg",
+    "table",
+    "tbody",
+    "td",
+    "textarea",
+    "tfoot",
+    "th",
+    "thead",
+    "tr",
+    "u",
+    "ul",
+    "video",
+]);
+function decodeHtmlEntity(entity) {
+    const named = HTML_ENTITY_REPLACEMENTS[entity.toLowerCase()];
+    if (named !== undefined) {
+        return named;
+    }
+    const decimalMatch = /^#(\d+)$/.exec(entity);
+    const hexMatch = /^#x([0-9a-f]+)$/i.exec(entity);
+    let codePoint;
+    if (decimalMatch) {
+        codePoint = Number.parseInt(decimalMatch[1], 10);
+    }
+    else if (hexMatch) {
+        codePoint = Number.parseInt(hexMatch[1], 16);
+    }
+    if (codePoint === undefined || !Number.isFinite(codePoint)) {
+        return `&${entity};`;
+    }
+    try {
+        return String.fromCodePoint(codePoint);
+    }
+    catch {
+        return `&${entity};`;
+    }
+}
+export function decodeHtmlEntities(value) {
+    return value.replace(/&([a-z][a-z0-9]+|#\d+|#x[0-9a-f]+);/gi, (_match, entity) => decodeHtmlEntity(entity));
+}
+function stripDecodedHtmlTags(value) {
+    return value
+        .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<\/?([a-z][a-z0-9-]*)(\s[^>]*)?>/gi, (match, tagName, attributes) => {
+        if ((attributes !== undefined && attributes.length > 0) ||
+            match.startsWith("</") ||
+            HTML_TAG_NAMES_TO_STRIP.has(tagName.toLowerCase())) {
+            return " ";
+        }
+        return match;
+    });
+}
+export function cleanSearchText(value, maxLength = 500) {
+    if (typeof value !== "string") {
+        return;
+    }
+    const cleaned = stripDecodedHtmlTags(decodeHtmlEntities(value.replace(/<[^>]*>/g, " ")))
+        .replace(/\s+/g, " ")
+        .trim();
+    if (cleaned.length === 0) {
+        return;
+    }
+    if (cleaned.length <= maxLength) {
+        return cleaned;
+    }
+    return `${cleaned.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+function normalizeSearchUrl(value) {
+    if (typeof value !== "string") {
+        return;
+    }
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            return;
+        }
+        return url.toString();
+    }
+    catch {
+        return;
+    }
+}
+function getHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return;
+    }
+}
+function normalizeHighlightList(value) {
+    if (!Array.isArray(value)) {
+        return;
+    }
+    const highlights = value
+        .map((entry) => cleanSearchText(entry, 320))
+        .filter((entry) => entry !== undefined)
+        .slice(0, 3);
+    return highlights.length > 0 ? highlights : undefined;
+}
+export function normalizeBraveSearchResult(result) {
+    const title = cleanSearchText(result.title, 180);
+    const url = normalizeSearchUrl(result.url);
+    if (title === undefined || url === undefined) {
+        return;
+    }
+    const pageDate = cleanSearchText(result.page_age, 80);
+    return {
+        title,
+        url,
+        description: cleanSearchText(result.description, 320),
+        source: cleanSearchText(result.profile?.name, 120) ?? cleanSearchText(result.meta_url?.hostname, 120),
+        age: cleanSearchText(result.age, 80),
+        ...(pageDate !== undefined ? { pageDate } : {}),
+        language: cleanSearchText(result.language, 40),
+    };
+}
+export function normalizeExaSearchResult(result) {
+    const title = cleanSearchText(result.title, 180);
+    const url = normalizeSearchUrl(result.url);
+    if (title === undefined || url === undefined) {
+        return;
+    }
+    const highlights = normalizeHighlightList(result.highlights);
+    const pageDate = cleanSearchText(result.publishedDate, 80);
+    return {
+        title,
+        url,
+        description: cleanSearchText(result.summary, 320) ?? highlights?.[0] ?? cleanSearchText(result.text, 320),
+        highlights,
+        source: cleanSearchText(result.author, 120) ?? cleanSearchText(getHostname(url), 120),
+        ...(pageDate !== undefined ? { pageDate } : {}),
+    };
+}
+export function getProviderLabel(provider) {
+    return provider === "exa" ? "Exa" : "Brave";
+}
+function formatResultLines(result, index, provider) {
+    const lines = [`${index + 1}. ${result.title}`, `   URL: ${result.url}`];
+    if (result.source !== undefined) {
+        lines.push(`   Source: ${result.source}`);
+    }
+    if (result.pageDate !== undefined) {
+        lines.push(`   ${provider === "exa" ? "Published" : "Page date"}: ${result.pageDate}`);
+    }
+    if (result.age !== undefined) {
+        lines.push(`   Age: ${result.age}`);
+    }
+    if (result.description !== undefined) {
+        lines.push(`   Summary: ${result.description}`);
+    }
+    if (result.highlights && result.highlights.length > 1) {
+        lines.push("   Highlights:", ...result.highlights.map((highlight) => `   - ${highlight}`));
+    }
+    lines.push("");
+    return lines;
+}
+export function formatSearchResults(provider, query, results) {
+    const providerLabel = getProviderLabel(provider);
+    if (results.length === 0) {
+        return `No ${providerLabel} web results found for: ${query}`;
+    }
+    return [
+        `${providerLabel} web search results for: ${query}`,
+        "",
+        ...results.flatMap((result, index) => formatResultLines(result, index, provider)),
+    ]
+        .join("\n")
+        .trimEnd();
+}
+export function dedupeSearchResults(results) {
+    const seen = new Set();
+    return results.filter((result) => {
+        if (seen.has(result.url)) {
+            return false;
+        }
+        seen.add(result.url);
+        return true;
+    });
+}
+function isJsonObject(value) {
+    return isRecord(value) && !Array.isArray(value);
+}
+function isOptionalRecord(value) {
+    return value === undefined || value === null || isJsonObject(value);
+}
+function isBraveSearchResult(value) {
+    return isJsonObject(value) && isOptionalRecord(value.profile) && isOptionalRecord(value.meta_url);
+}
+function isBraveSearchResponse(value) {
+    if (!isJsonObject(value) || !isOptionalRecord(value.query) || !isOptionalRecord(value.web)) {
+        return false;
+    }
+    const results = value.web?.results;
+    return (results === undefined ||
+        results === null ||
+        (Array.isArray(results) && results.every(isBraveSearchResult)));
+}
+function isExaSearchResponse(value) {
+    if (!isJsonObject(value)) {
+        return false;
+    }
+    const results = value.results;
+    return (results === undefined ||
+        results === null ||
+        (Array.isArray(results) && results.every((result) => isJsonObject(result))));
+}
+/** Validate every consumed container while retaining extension fields and loose leaf values. */
+export function parseBraveSearchResponse(value) {
+    if (!isBraveSearchResponse(value)) {
+        throw new Error("Brave search response has invalid result structure");
+    }
+    return value;
+}
+export function parseExaSearchResponse(value) {
+    if (!isExaSearchResponse(value)) {
+        throw new Error("Exa search response has invalid result structure");
+    }
+    return value;
+}

package/dist/extensions/agent-browser/lib/web-search-schema.js

@@ -0,0 +1,82 @@
+import { JsonSchema } from "./json-schema.js";
+import { StringEnum as localStringEnum } from "./string-enum-schema.js";
+import { DEFAULT_WEB_SEARCH_PROVIDER, EXA_SEARCH_TYPES, WEB_SEARCH_PROVIDERS, } from "./config.js";
+export const DEFAULT_SEARCH_RESULT_COUNT = 5;
+export const MAX_SEARCH_RESULT_COUNT = 10;
+const WEB_SEARCH_PROVIDER_PARAM_VALUES = ["auto", ...WEB_SEARCH_PROVIDERS];
+const EXA_SEARCH_CATEGORIES = [
+    "company",
+    "people",
+    "publication",
+    "news",
+    "personal site",
+    "financial report",
+];
+const MAX_EXA_DOMAIN_FILTERS = 20;
+const MAX_EXA_ADDITIONAL_QUERIES = 10;
+function createExaFilterProperties(Type, StringEnum) {
+    return {
+        includeDomains: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+            minItems: 1,
+            maxItems: MAX_EXA_DOMAIN_FILTERS,
+            description: `Exa only. Limit results to 1–${MAX_EXA_DOMAIN_FILTERS} hostnames, path prefixes (exa.ai/docs), or wildcard subdomains (*.substack.com).`,
+        })),
+        excludeDomains: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+            minItems: 1,
+            maxItems: MAX_EXA_DOMAIN_FILTERS,
+            description: `Exa only. Exclude 1–${MAX_EXA_DOMAIN_FILTERS} hostnames, path prefixes, or wildcard subdomains. Not compatible with category company or people.`,
+        })),
+        category: Type.Optional(StringEnum(EXA_SEARCH_CATEGORIES, {
+            description: "Exa-only result category. company and people cannot be combined with freshness or excludeDomains.",
+        })),
+        additionalQueries: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+            minItems: 1,
+            maxItems: MAX_EXA_ADDITIONAL_QUERIES,
+            description: `Exa only. Add 1–${MAX_EXA_ADDITIONAL_QUERIES} query variations when the effective searchType is deep-lite, deep, or deep-reasoning.`,
+        })),
+        highlightsDynamic: Type.Optional(Type.Boolean({
+            description: "Exa-only research preview. Allocate one highlight budget across all results; the wrapper sends the required Exa-Beta header. Regular per-page highlights remain the default.",
+        })),
+    };
+}
+export function createAgentBrowserWebSearchParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
+    return Type.Object({
+        query: Type.String({
+            minLength: 1,
+            description: "Search query to run with the configured Exa or Brave web search provider.",
+        }),
+        provider: Type.Optional(StringEnum(WEB_SEARCH_PROVIDER_PARAM_VALUES, {
+            description: `Optional provider override. auto uses configured keys and preferredProvider; when both Exa and Brave are available, the default preferred provider is ${DEFAULT_WEB_SEARCH_PROVIDER}.`,
+        })),
+        searchType: Type.Optional(StringEnum(EXA_SEARCH_TYPES, {
+            description: "Exa mode; omitted uses webSearch.defaultSearchType, then auto. instant (~250ms) is only for trivial lookups; fast (~450ms) favors latency; auto (~1s) is balanced. Pass searchType: deep-lite (~4s) for research before implementation unless config already defaults it; do not assume auto is deep enough. deep (4–15s) handles hard multi-source research; deep-reasoning (12–40s) is only for the hardest work. Brave ignores this field.",
+        })),
+        ...createExaFilterProperties(Type, StringEnum),
+        count: Type.Optional(Type.Integer({
+            minimum: 1,
+            maximum: MAX_SEARCH_RESULT_COUNT,
+            description: `Number of web results to return. Defaults to ${DEFAULT_SEARCH_RESULT_COUNT}; max ${MAX_SEARCH_RESULT_COUNT}.`,
+        })),
+        offset: Type.Optional(Type.Integer({
+            minimum: 0,
+            maximum: 9,
+            description: "Zero-based result offset for pagination. Defaults to 0.",
+        })),
+        country: Type.Optional(Type.String({
+            pattern: "^[A-Za-z]{2}$",
+            description: "Optional 2-letter country code, such as US or GB.",
+        })),
+        searchLang: Type.Optional(Type.String({
+            minLength: 2,
+            maxLength: 8,
+            description: "Optional Brave search language code, such as en or en-US.",
+        })),
+        safesearch: Type.Optional(StringEnum(["off", "moderate", "strict"], {
+            description: "Optional search safety setting. Brave forwards this as safesearch; Exa maps moderate/strict to moderation=true.",
+        })),
+        freshness: Type.Optional(StringEnum(["pd", "pw", "pm", "py"], {
+            description: "Optional freshness window: pd=past day, pw=past week, pm=past month, py=past year.",
+        })),
+    }, { additionalProperties: false });
+}
+export const AgentBrowserWebSearchParams = createAgentBrowserWebSearchParamsSchema();