pi-agent-browser-native 0.9.3 → 0.9.5

package/dist/extensions/agent-browser/lib/config-providers.js

@@ -0,0 +1,71 @@
+// @ts-check
+/** @typedef {"exa" | "brave"} WebSearchProvider */
+/** @typedef {"auto" | "fast" | "instant" | "deep-lite" | "deep" | "deep-reasoning"} ExaSearchType */
+/** @typedef {"exaApiKey" | "braveApiKey"} WebSearchProviderConfigKey */
+/** @typedef {{ readonly provider: WebSearchProvider; readonly apiKeyEnv: string; readonly configKey: WebSearchProviderConfigKey; readonly label: string }} WebSearchProviderDescriptor */
+export const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
+export const EXA_API_KEY_ENV = "EXA_API_KEY";
+/** @type {Readonly<Record<WebSearchProvider, WebSearchProviderDescriptor>>} */
+export const WEB_SEARCH_PROVIDER_DESCRIPTORS = Object.freeze({
+    exa: Object.freeze({
+        provider: "exa",
+        apiKeyEnv: EXA_API_KEY_ENV,
+        configKey: "exaApiKey",
+        label: "Exa",
+    }),
+    brave: Object.freeze({
+        provider: "brave",
+        apiKeyEnv: BRAVE_API_KEY_ENV,
+        configKey: "braveApiKey",
+        label: "Brave Search",
+    }),
+});
+/** @type {readonly WebSearchProvider[]} */
+export const WEB_SEARCH_PROVIDERS = Object.freeze(["exa", "brave"]);
+/** @type {WebSearchProvider} */
+export const DEFAULT_WEB_SEARCH_PROVIDER = "exa";
+/** @type {readonly ExaSearchType[]} */
+export const EXA_SEARCH_TYPES = Object.freeze([
+    "auto",
+    "fast",
+    "instant",
+    "deep-lite",
+    "deep",
+    "deep-reasoning",
+]);
+/** @type {Readonly<Record<WebSearchProvider, WebSearchProviderConfigKey>>} */
+export const WEB_SEARCH_PROVIDER_CONFIG_KEYS = Object.freeze({
+    exa: WEB_SEARCH_PROVIDER_DESCRIPTORS.exa.configKey,
+    brave: WEB_SEARCH_PROVIDER_DESCRIPTORS.brave.configKey,
+});
+/** @type {Readonly<Record<WebSearchProvider, string>>} */
+export const WEB_SEARCH_PROVIDER_ENV_VARS = Object.freeze({
+    exa: WEB_SEARCH_PROVIDER_DESCRIPTORS.exa.apiKeyEnv,
+    brave: WEB_SEARCH_PROVIDER_DESCRIPTORS.brave.apiKeyEnv,
+});
+/** @param {unknown} value
+ * @returns {value is WebSearchProvider} */
+export function isWebSearchProvider(value) {
+    return value === "exa" || value === "brave";
+}
+/** @param {string} provider
+ * @returns {WebSearchProviderDescriptor} */
+export function getWebSearchProviderDescriptor(provider) {
+    if (!isWebSearchProvider(provider)) {
+        throw new Error(`Unknown web-search provider: ${provider}`);
+    }
+    return WEB_SEARCH_PROVIDER_DESCRIPTORS[provider];
+}
+/** @param {WebSearchProvider} provider */
+export function getWebSearchProviderLabel(provider) {
+    return getWebSearchProviderDescriptor(provider).label;
+}
+/** @param {WebSearchProvider} provider */
+export function getWebSearchProviderEnvVar(provider) {
+    return getWebSearchProviderDescriptor(provider).apiKeyEnv;
+}
+/** @param {WebSearchProvider} provider
+ * @returns {WebSearchProviderConfigKey} */
+export function getWebSearchProviderConfigKey(provider) {
+    return getWebSearchProviderDescriptor(provider).configKey;
+}

package/dist/extensions/agent-browser/lib/config-validation.js

@@ -0,0 +1,231 @@
+// @ts-check
+import { EXA_SEARCH_TYPES, WEB_SEARCH_PROVIDERS, getWebSearchProviderDescriptor, isWebSearchProvider, } from "./config-providers.js";
+/** @typedef {import("./config-providers.js").WebSearchProvider} WebSearchProvider */
+/** @typedef {import("./config-providers.js").ExaSearchType} ExaSearchType */
+/** @typedef {"explicit-only" | "authenticated-only" | "always"} BrowserDefaultProfilePolicy */
+/** @typedef {"global" | "project" | "override"} ConfigLayerScope */
+/** @typedef {{ readonly name: string; readonly policy?: BrowserDefaultProfilePolicy }} BrowserDefaultProfileConfig */
+/** @typedef {{ readonly enabled?: boolean; readonly preferredProvider?: WebSearchProvider; readonly defaultSearchType?: ExaSearchType; readonly braveApiKey?: string; readonly exaApiKey?: string }} WebSearchConfig */
+/** @typedef {{ readonly defaultProfile?: BrowserDefaultProfileConfig; readonly executablePath?: string }} BrowserConfig */
+/** @typedef {{ readonly version?: 1; readonly webSearch?: WebSearchConfig; readonly browser?: BrowserConfig }} AgentBrowserConfig */
+/** @typedef {{ readonly config: AgentBrowserConfig; readonly path: string; readonly scope: ConfigLayerScope }} ConfigLayer */
+/** Validation deliberately appends diagnostics to the caller's collectors.
+ * @typedef {string[]} ConfigDiagnostics */
+/** @param {unknown} value
+ * @returns {value is Readonly<Record<string, unknown>>} */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** @param {unknown} value
+ * @param {string} path
+ * @param {ConfigDiagnostics} errors */
+function validateString(value, path, errors) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== "string") {
+        errors.push(`${path} must be a string.`);
+        return;
+    }
+    return value;
+}
+/** @param {unknown} value
+ * @param {string} path
+ * @param {ConfigDiagnostics} errors */
+function validateBoolean(value, path, errors) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== "boolean") {
+        errors.push(`${path} must be a boolean.`);
+        return;
+    }
+    return value;
+}
+/** @param {unknown} value
+ * @param {string} path
+ * @param {ConfigDiagnostics} errors
+ * @returns {WebSearchProvider | undefined} */
+export function validateWebSearchProvider(value, path, errors) {
+    if (value === undefined) {
+        return;
+    }
+    const provider = validateString(value, path, errors)?.trim();
+    if (provider === undefined) {
+        return;
+    }
+    if (!isWebSearchProvider(provider)) {
+        errors.push(`${path} must be one of ${WEB_SEARCH_PROVIDERS.join(", ")}.`);
+        return;
+    }
+    return provider;
+}
+/** @param {unknown} value
+ * @param {string} path
+ * @param {ConfigDiagnostics} errors
+ * @returns {ExaSearchType | undefined} */
+function validateExaSearchType(value, path, errors) {
+    if (value === undefined) {
+        return;
+    }
+    const searchType = validateString(value, path, errors)?.trim();
+    if (searchType === undefined) {
+        return;
+    }
+    const supported = EXA_SEARCH_TYPES.find((candidate) => candidate === searchType);
+    if (supported === undefined) {
+        errors.push(`${path} must be one of ${EXA_SEARCH_TYPES.join(", ")}.`);
+    }
+    return supported;
+}
+/** @param {unknown} value
+ * @param {string} path
+ * @param {ConfigDiagnostics} errors
+ * @returns {BrowserDefaultProfileConfig | undefined} */
+function validateBrowserDefaultProfile(value, path, errors) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isRecord(value)) {
+        errors.push(`${path} must be an object.`);
+        return;
+    }
+    const name = validateString(value.name, `${path}.name`, errors)?.trim();
+    if (name === undefined || name.length === 0) {
+        errors.push(`${path}.name must not be blank.`);
+        return;
+    }
+    const policy = validateString(value.policy, `${path}.policy`, errors) ?? "authenticated-only";
+    if (policy !== "explicit-only" && policy !== "authenticated-only" && policy !== "always") {
+        errors.push(`${path}.policy must be one of explicit-only, authenticated-only, always.`);
+        return;
+    }
+    return { name, policy };
+}
+/** @param {unknown} value
+ * @param {string} path
+ * @param {ConfigDiagnostics} errors
+ * @returns {WebSearchConfig | undefined} */
+function validateWebSearchConfig(value, path, errors) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isRecord(value)) {
+        errors.push(`${path} must be an object.`);
+        return;
+    }
+    const enabled = validateBoolean(value.enabled, `${path}.enabled`, errors);
+    const preferredProvider = validateWebSearchProvider(value.preferredProvider, `${path}.preferredProvider`, errors);
+    const defaultSearchType = validateExaSearchType(value.defaultSearchType, `${path}.defaultSearchType`, errors);
+    /** @type {Partial<Record<import("./config-providers.js").WebSearchProviderConfigKey, string>>} */
+    const keys = {};
+    for (const provider of WEB_SEARCH_PROVIDERS) {
+        const { configKey } = getWebSearchProviderDescriptor(provider);
+        const apiKey = validateString(value[configKey], `${path}.${configKey}`, errors);
+        if (apiKey !== undefined) {
+            keys[configKey] = apiKey;
+        }
+    }
+    const config = {
+        ...(enabled !== undefined ? { enabled } : {}),
+        ...(preferredProvider !== undefined ? { preferredProvider } : {}),
+        ...(defaultSearchType !== undefined ? { defaultSearchType } : {}),
+        ...keys,
+    };
+    return Object.keys(config).length > 0 ? config : undefined;
+}
+/** @param {unknown} value
+ * @param {string} path
+ * @param {ConfigDiagnostics} errors
+ * @returns {BrowserConfig | undefined} */
+function validateBrowserConfig(value, path, errors) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isRecord(value)) {
+        errors.push(`${path} must be an object.`);
+        return;
+    }
+    const defaultProfile = validateBrowserDefaultProfile(value.defaultProfile, `${path}.defaultProfile`, errors);
+    const executablePath = validateString(value.executablePath, `${path}.executablePath`, errors)?.trim();
+    return {
+        ...(defaultProfile !== undefined ? { defaultProfile } : {}),
+        ...(executablePath !== undefined && executablePath.length > 0 ? { executablePath } : {}),
+    };
+}
+/** @param {unknown} value
+ * @param {string} path
+ * @param {ConfigDiagnostics} errors
+ * @param {ConfigDiagnostics} warnings
+ * @returns {AgentBrowserConfig | undefined} */
+export function validateAgentBrowserConfig(value, path, errors, warnings) {
+    if (!isRecord(value)) {
+        errors.push(`${path} must contain a JSON object.`);
+        return;
+    }
+    if (value.version !== undefined && value.version !== 1) {
+        errors.push(`${path}.version must be 1 when present.`);
+    }
+    const webSearch = validateWebSearchConfig(value.webSearch, `${path}.webSearch`, errors);
+    const browser = validateBrowserConfig(value.browser, `${path}.browser`, errors);
+    for (const key of Object.keys(value)) {
+        if (!["version", "webSearch", "browser"].includes(key)) {
+            warnings.push(`${path}.${key} is not a recognized pi-agent-browser-native config field and was ignored.`);
+        }
+    }
+    return {
+        ...(value.version === 1 ? { version: 1 } : {}),
+        ...(webSearch !== undefined ? { webSearch } : {}),
+        ...(browser !== undefined ? { browser } : {}),
+    };
+}
+/** Parse config without retaining native token previews or source-bearing error causes.
+ * @param {string} raw
+ * @returns {{ readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly error: string }} */
+export function parseAgentBrowserConfigJson(raw) {
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch (error) {
+        const location = error instanceof Error
+            ? error.message.match(/at position \d+(?: \(line \d+ column \d+\))?/)?.[0]
+            : undefined;
+        return {
+            ok: false,
+            error: location === undefined ? "Invalid JSON." : `Invalid JSON ${location}.`,
+        };
+    }
+}
+/** @param {string} raw
+ * @param {string} path
+ * @param {ConfigLayerScope} scope
+ * @param {ConfigDiagnostics} errors
+ * @param {ConfigDiagnostics} warnings
+ * @returns {ConfigLayer | undefined} */
+export function parseAgentBrowserConfigLayer(raw, path, scope, errors, warnings) {
+    const parsed = parseAgentBrowserConfigJson(raw);
+    if (!parsed.ok) {
+        errors.push(`Could not parse ${scope} config ${path}: ${parsed.error}`);
+        return;
+    }
+    const config = validateAgentBrowserConfig(parsed.value, path, errors, warnings);
+    return config ? { config, path, scope } : undefined;
+}
+/** @param {unknown} value */
+export function describeUnknownError(value) {
+    switch (typeof value) {
+        case "string":
+            return value;
+        case "number":
+        case "bigint":
+        case "boolean":
+        case "symbol":
+            return String(value);
+        case "undefined":
+            return "undefined";
+        case "object":
+            return value === null ? "null" : Object.prototype.toString.call(value);
+        case "function":
+            return value.toString();
+    }
+}

package/dist/extensions/agent-browser/lib/config.js

@@ -1,15 +1,18 @@
 import { exec as execCallback } from "node:child_process";
 import { promisify } from "node:util";
 import { SECRET_COMMAND_TIMEOUT_MS, getWebSearchCredentialSource, getWebSearchProviderOrder, loadAgentBrowserConfigStateSync, resolveEnvInterpolations, } from "./config-policy.js";
-export { AGENT_BROWSER_CONFIG_ENV, BRAVE_API_KEY_ENV, CONFIG_RELATIVE_PATH, DEFAULT_WEB_SEARCH_PROVIDER, EXA_API_KEY_ENV, EXA_SEARCH_TYPES, GLOBAL_CONFIG_RELATIVE_PATH, SECRET_COMMAND_TIMEOUT_MS, WEB_SEARCH_PROVIDER_CONFIG_KEYS, WEB_SEARCH_PROVIDER_DESCRIPTORS, WEB_SEARCH_PROVIDER_ENV_VARS, WEB_SEARCH_PROVIDERS, buildAgentBrowserConfigState, buildWebSearchCredentialSources, canRegisterWebSearchTool, classifyCredentialSource, formatBrowserExecutableStatus, formatBrowserProfileStatus, getAgentBrowserConfigPaths, getCredentialSourceSummary, getGlobalAgentBrowserConfigPath, getProjectAgentBrowserConfigPath, getWebSearchCredentialSource, getWebSearchProviderConfigKey, getWebSearchProviderDescriptor, getWebSearchProviderEnvVar, getWebSearchProviderLabel, getWebSearchProviderOrder, hasPotentialCredentialSource, isWebSearchProvider, loadAgentBrowserConfigStateSync, mergeAgentBrowserConfig, parseAgentBrowserConfigLayer, resolveEnvInterpolations, summarizeConfigFiles, validateAgentBrowserConfig, validateWebSearchProvider, } from "./config-policy.js";
+export { AGENT_BROWSER_CONFIG_ENV, BRAVE_API_KEY_ENV, CONFIG_RELATIVE_PATH, DEFAULT_WEB_SEARCH_PROVIDER, EXA_API_KEY_ENV, EXA_SEARCH_TYPES, GLOBAL_CONFIG_RELATIVE_PATH, SECRET_COMMAND_TIMEOUT_MS, WEB_SEARCH_PROVIDER_CONFIG_KEYS, WEB_SEARCH_PROVIDER_ENV_VARS, WEB_SEARCH_PROVIDERS, buildAgentBrowserConfigState, buildWebSearchCredentialSources, canRegisterWebSearchTool, classifyCredentialSource, formatBrowserExecutableStatus, formatBrowserProfileStatus, getAgentBrowserConfigPaths, getCredentialSourceSummary, getGlobalAgentBrowserConfigPath, getProjectAgentBrowserConfigPath, getWebSearchCredentialSource, getWebSearchProviderDescriptor, getWebSearchProviderLabel, getWebSearchProviderOrder, hasPotentialCredentialSource, isWebSearchProvider, loadAgentBrowserConfigStateSync, mergeAgentBrowserConfig, parseAgentBrowserConfigJson, parseAgentBrowserConfigLayer, resolveEnvInterpolations, summarizeConfigFiles, validateAgentBrowserConfig, validateWebSearchProvider, } from "./config-policy.js";
+// Node's callback-oriented exec returns ChildProcess; promisify intentionally ignores that return.
+// oxlint-disable-next-line typescript/strict-void-return
 const exec = promisify(execCallback);
 export function loadAgentBrowserConfigSync(options = {}) {
     return loadAgentBrowserConfigStateSync(options);
 }
 async function resolveCommandCredential(rawValue, signal) {
     const command = rawValue.slice(1).trim();
-    if (!command)
+    if (command.length === 0) {
         return undefined;
+    }
     try {
         const result = await exec(command, {
             signal,
@@ -20,14 +23,18 @@ async function resolveCommandCredential(rawValue, signal) {
         return value.length > 0 ? value : undefined;
     }
     catch (error) {
-        if (signal?.aborted)
+        if (signal?.aborted === true) {
             throw error;
+        }
+        // The native exec error contains the secret command/stdout/stderr; never expose it as a cause.
+        // oxlint-disable-next-line eslint/preserve-caught-error
         throw new Error("Credential command failed without exposing command output. Check pi-agent-browser-config web-search status and the configured secret manager command.");
     }
 }
 async function resolveCredentialSource(source, options = {}) {
-    if (!source)
+    if (!source) {
         return undefined;
+    }
     let value;
     if (source.kind === "command") {
         value = await resolveCommandCredential(source.rawValue, options.signal);
@@ -38,20 +45,25 @@ async function resolveCredentialSource(source, options = {}) {
     else {
         value = source.rawValue.trim();
     }
-    return value ? { source, value } : undefined;
+    return value !== undefined && value.length > 0 ? { source, value } : undefined;
 }
 export async function resolveWebSearchCredential(state, provider, options = {}) {
-    if (!state.webSearchEnabled || state.errors.length > 0)
+    if (!state.webSearchEnabled || state.errors.length > 0) {
         return undefined;
+    }
     return resolveCredentialSource(getWebSearchCredentialSource(state, provider), options);
 }
 export async function resolvePreferredWebSearchCredential(state, options = {}) {
-    if (!state.webSearchEnabled || state.errors.length > 0)
+    if (!state.webSearchEnabled || state.errors.length > 0) {
         return undefined;
+    }
     for (const provider of getWebSearchProviderOrder(state, options.provider)) {
+        // Resolve in configured preference order; later secret commands must not run once a key resolves.
+        // oxlint-disable-next-line no-await-in-loop
         const credential = await resolveWebSearchCredential(state, provider, options);
-        if (credential)
+        if (credential) {
             return { provider, credential };
+        }
     }
     return undefined;
 }

package/dist/extensions/agent-browser/lib/electron/cdp.js

@@ -4,10 +4,15 @@ function asString(value) {
     return typeof value === "string" && value.trim().length > 0 ? value : undefined;
 }
 export function parseCdpVersion(value) {
-    if (!isRecord(value))
+    if (!isRecord(value)) {
         return undefined;
+    }
+    const browser = asString(value.Browser) ?? asString(value.browser);
+    if (browser === undefined) {
+        return undefined;
+    }
     return {
-        browser: asString(value.Browser) ?? asString(value.browser),
+        browser,
         protocolVersion: asString(value["Protocol-Version"]) ?? asString(value.protocolVersion),
         userAgent: asString(value["User-Agent"]) ?? asString(value.userAgent),
         v8Version: asString(value["V8-Version"]) ?? asString(value.v8Version),
@@ -16,8 +21,9 @@ export function parseCdpVersion(value) {
     };
 }
 export function parseCdpTargets(value) {
-    if (!Array.isArray(value))
+    if (!Array.isArray(value)) {
         return [];
+    }
     return value.filter(isRecord).map((target) => ({
         id: asString(target.id),
         title: asString(target.title),
@@ -30,10 +36,13 @@ export async function fetchCdpJson(url, signal) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), ELECTRON_CDP_FETCH_TIMEOUT_MS);
     try {
-        const response = await fetch(url, { signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal });
-        if (!response.ok)
+        const response = await fetch(url, {
+            signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal,
+        });
+        if (!response.ok) {
             return undefined;
-        return await response.json();
+        }
+        return (await response.json());
     }
     catch {
         return undefined;
@@ -44,7 +53,10 @@ export async function fetchCdpJson(url, signal) {
 }
 export function boundElectronProbeString(value, maxLength = 240) {
     const trimmed = value?.trim();
-    if (!trimmed)
+    if (trimmed === undefined || trimmed.length === 0) {
         return undefined;
-    return trimmed.length > maxLength ? `${trimmed.slice(0, Math.max(0, maxLength - 3))}...` : trimmed;
+    }
+    return trimmed.length > maxLength
+        ? `${trimmed.slice(0, Math.max(0, maxLength - 3))}...`
+        : trimmed;
 }