pi-agent-browser-native 0.2.48 → 0.2.50

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

@@ -0,0 +1,669 @@
+// @ts-check
+/**
+ * Purpose: Canonical pi-agent-browser-native config policy shared by runtime and setup CLI.
+ * Responsibilities: Own config paths, provider descriptors, credential source parsing, layer validation/merge, status projection, and redacted summaries.
+ * Scope: Pure configuration policy plus synchronous status loading; secret command execution and browser/web-search runtime calls live elsewhere.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/** @typedef {"explicit-only" | "authenticated-only" | "always"} BrowserDefaultProfilePolicy */
+/** @typedef {"global" | "project" | "override" | "env-fallback"} AgentBrowserConfigScope */
+/** @typedef {"global" | "project" | "override"} ConfigLayerScope */
+/** @typedef {"literal" | "env" | "command"} CredentialSourceKind */
+/** @typedef {"exa" | "brave"} WebSearchProvider */
+/** @typedef {"exaApiKey" | "braveApiKey"} WebSearchProviderConfigKey */
+/** @typedef {{ provider: WebSearchProvider; apiKeyEnv: string; configKey: WebSearchProviderConfigKey; label: string }} WebSearchProviderDescriptor */
+/** @typedef {{ name: string; policy?: BrowserDefaultProfilePolicy }} BrowserDefaultProfileConfig */
+/** @typedef {{ enabled?: boolean; preferredProvider?: WebSearchProvider; braveApiKey?: string; exaApiKey?: string }} WebSearchConfig */
+/** @typedef {{ defaultProfile?: BrowserDefaultProfileConfig; executablePath?: string; defaultLaunchArgs?: string[] }} BrowserConfig */
+/** @typedef {{ version?: 1; webSearch?: WebSearchConfig; browser?: BrowserConfig }} AgentBrowserConfig */
+/** @typedef {{ config: AgentBrowserConfig; path: string; scope: ConfigLayerScope }} ConfigLayer */
+/** @typedef {{ kind: CredentialSourceKind; provider?: WebSearchProvider; rawValue: string; scope: AgentBrowserConfigScope }} CredentialSource */
+/** @typedef {{ global: string; project: string; override?: string }} AgentBrowserConfigPaths */
+/** @typedef {{ cwd?: string; env?: NodeJS.ProcessEnv; includeProjectConfig?: boolean }} AgentBrowserConfigLoadOptions */
+/** @typedef {{ browserDefaultProfile?: Required<BrowserDefaultProfileConfig>; browserDefaultProfileScope?: ConfigLayerScope; browserExecutablePath?: string; browserExecutablePathScope?: ConfigLayerScope; trustedBrowserDefaultProfile?: Required<BrowserDefaultProfileConfig>; trustedBrowserDefaultProfileScope?: ConfigLayerScope; trustedBrowserExecutablePath?: string; trustedBrowserExecutablePathScope?: ConfigLayerScope; config: AgentBrowserConfig; webSearchCredentialSources: Partial<Record<WebSearchProvider, CredentialSource>>; webSearchEnabled: boolean; webSearchPreferredProvider: WebSearchProvider; errors: string[]; layers: ConfigLayer[]; paths: AgentBrowserConfigPaths; projectConfigIncluded: boolean; warnings: string[] }} AgentBrowserConfigState */
+/** @typedef {{ scope: string; path: string; exists: boolean }} ConfigFileSummary */
+export const AGENT_BROWSER_CONFIG_ENV = "PI_AGENT_BROWSER_CONFIG";
+export const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
+export const EXA_API_KEY_ENV = "EXA_API_KEY";
+export const CONFIG_RELATIVE_PATH = /** @type {const} */ ([".pi", "config", "pi-agent-browser-native", "config.json"]);
+export const GLOBAL_CONFIG_RELATIVE_PATH = /** @type {const} */ ([".pi", "config", "pi-agent-browser-native", "config.json"]);
+export const SECRET_COMMAND_TIMEOUT_MS = 15_000;
+/** @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<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 typeof value === "string" && WEB_SEARCH_PROVIDERS.includes(/** @type {WebSearchProvider} */ (value));
+}
+/**
+ * @param {WebSearchProvider} provider
+ * @returns {WebSearchProviderDescriptor}
+ */
+export function getWebSearchProviderDescriptor(provider) {
+    const descriptor = WEB_SEARCH_PROVIDER_DESCRIPTORS[provider];
+    if (!descriptor)
+        throw new Error(`Unknown web-search provider: ${String(provider)}`);
+    return descriptor;
+}
+/** @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;
+}
+/** @param {NodeJS.ProcessEnv} [env] */
+export function getGlobalAgentBrowserConfigPath(env = process.env) {
+    const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
+    return join(home, ...GLOBAL_CONFIG_RELATIVE_PATH);
+}
+/** @param {string} [cwd] */
+export function getProjectAgentBrowserConfigPath(cwd = process.cwd()) {
+    return resolve(cwd, ...CONFIG_RELATIVE_PATH);
+}
+/**
+ * @param {{ cwd?: string; env?: NodeJS.ProcessEnv }} [options]
+ * @returns {AgentBrowserConfigPaths}
+ */
+export function getAgentBrowserConfigPaths(options = {}) {
+    const env = options.env ?? process.env;
+    const override = env[AGENT_BROWSER_CONFIG_ENV]?.trim();
+    return {
+        global: getGlobalAgentBrowserConfigPath(env),
+        project: getProjectAgentBrowserConfigPath(options.cwd),
+        ...(override ? { override: resolve(override) } : {}),
+    };
+}
+/**
+ * @param {AgentBrowserConfig} base
+ * @param {AgentBrowserConfig} override
+ * @returns {AgentBrowserConfig}
+ */
+export function mergeAgentBrowserConfig(base, override) {
+    return {
+        ...base,
+        ...override,
+        browser: {
+            ...(base.browser ?? {}),
+            ...(override.browser ?? {}),
+            defaultProfile: override.browser?.defaultProfile ?? base.browser?.defaultProfile,
+        },
+        webSearch: {
+            ...(base.webSearch ?? {}),
+            ...(override.webSearch ?? {}),
+        },
+    };
+}
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * @param {unknown} value
+ * @param {string} path
+ * @param {string[]} errors
+ */
+function validateString(value, path, errors) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        errors.push(`${path} must be a string.`);
+        return undefined;
+    }
+    return value;
+}
+/**
+ * @param {unknown} value
+ * @param {string} path
+ * @param {string[]} errors
+ * @returns {string[] | undefined}
+ */
+function validateStringArray(value, path, errors) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        errors.push(`${path} must be an array of strings.`);
+        return undefined;
+    }
+    return value;
+}
+/**
+ * @param {unknown} value
+ * @param {string} path
+ * @param {string[]} errors
+ */
+function validateBoolean(value, path, errors) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean") {
+        errors.push(`${path} must be a boolean.`);
+        return undefined;
+    }
+    return value;
+}
+/**
+ * @param {unknown} value
+ * @param {string} path
+ * @param {string[]} errors
+ * @returns {WebSearchProvider | undefined}
+ */
+export function validateWebSearchProvider(value, path, errors) {
+    if (value === undefined)
+        return undefined;
+    const provider = validateString(value, path, errors)?.trim();
+    if (provider === undefined)
+        return undefined;
+    if (!isWebSearchProvider(provider)) {
+        errors.push(`${path} must be one of ${WEB_SEARCH_PROVIDERS.join(", ")}.`);
+        return undefined;
+    }
+    return provider;
+}
+/**
+ * @param {unknown} value
+ * @param {string} path
+ * @param {string[]} errors
+ * @returns {BrowserDefaultProfileConfig | undefined}
+ */
+function validateBrowserDefaultProfile(value, path, errors) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value)) {
+        errors.push(`${path} must be an object.`);
+        return undefined;
+    }
+    const name = validateString(value.name, `${path}.name`, errors)?.trim();
+    if (!name) {
+        errors.push(`${path}.name must not be blank.`);
+        return undefined;
+    }
+    const rawPolicy = validateString(value.policy, `${path}.policy`, errors);
+    const policy = rawPolicy ?? "authenticated-only";
+    if (!["explicit-only", "authenticated-only", "always"].includes(policy)) {
+        errors.push(`${path}.policy must be one of explicit-only, authenticated-only, always.`);
+        return undefined;
+    }
+    return { name, policy: /** @type {BrowserDefaultProfilePolicy} */ (policy) };
+}
+/** @param {string} rawValue */
+export function isPlaintextCredentialValue(rawValue) {
+    const trimmed = rawValue.trim();
+    return Boolean(trimmed) && !trimmed.startsWith("!") && !trimmed.startsWith("$");
+}
+/**
+ * @param {string} rawValue
+ * @param {WebSearchProvider} provider
+ */
+export function isProjectSafeCredentialValueForProvider(rawValue, provider) {
+    void provider;
+    return rawValue.trim().length > 0;
+}
+/**
+ * @param {unknown} value
+ * @param {string} path
+ * @param {ConfigLayerScope} scope
+ * @param {string[]} errors
+ * @param {string[]} warnings
+ * @returns {AgentBrowserConfig | undefined}
+ */
+export function validateAgentBrowserConfig(value, path, scope, errors, warnings) {
+    if (!isRecord(value)) {
+        errors.push(`${path} must contain a JSON object.`);
+        return undefined;
+    }
+    if (value.version !== undefined && value.version !== 1) {
+        errors.push(`${path}.version must be 1 when present.`);
+    }
+    /** @type {AgentBrowserConfig} */
+    const config = value.version === 1 ? { version: 1 } : {};
+    if (value.webSearch !== undefined) {
+        if (!isRecord(value.webSearch)) {
+            errors.push(`${path}.webSearch must be an object.`);
+        }
+        else {
+            /** @type {NonNullable<AgentBrowserConfig["webSearch"]>} */
+            const webSearch = {};
+            const enabled = validateBoolean(value.webSearch.enabled, `${path}.webSearch.enabled`, errors);
+            if (enabled !== undefined)
+                webSearch.enabled = enabled;
+            const preferredProvider = validateWebSearchProvider(value.webSearch.preferredProvider, `${path}.webSearch.preferredProvider`, errors);
+            if (preferredProvider)
+                webSearch.preferredProvider = preferredProvider;
+            for (const provider of WEB_SEARCH_PROVIDERS) {
+                const descriptor = getWebSearchProviderDescriptor(provider);
+                const apiKey = validateString(value.webSearch[descriptor.configKey], `${path}.webSearch.${descriptor.configKey}`, errors);
+                if (apiKey !== undefined) {
+                    webSearch[descriptor.configKey] = apiKey;
+                }
+            }
+            if (Object.keys(webSearch).length > 0)
+                config.webSearch = webSearch;
+        }
+    }
+    if (value.browser !== undefined) {
+        if (!isRecord(value.browser)) {
+            errors.push(`${path}.browser must be an object.`);
+        }
+        else {
+            config.browser = {};
+            const defaultProfile = validateBrowserDefaultProfile(value.browser.defaultProfile, `${path}.browser.defaultProfile`, errors);
+            if (defaultProfile) {
+                config.browser.defaultProfile = defaultProfile;
+            }
+            const executablePath = validateString(value.browser.executablePath, `${path}.browser.executablePath`, errors)?.trim();
+            if (executablePath) {
+                config.browser.executablePath = executablePath;
+            }
+            const defaultLaunchArgs = validateStringArray(value.browser.defaultLaunchArgs, `${path}.browser.defaultLaunchArgs`, errors);
+            if (defaultLaunchArgs) {
+                config.browser.defaultLaunchArgs = defaultLaunchArgs;
+                warnings.push(`${path}.browser.defaultLaunchArgs is recorded for future use; current releases do not auto-inject default launch args.`);
+            }
+        }
+    }
+    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 config;
+}
+/**
+ * @param {string} raw
+ * @param {string} path
+ * @param {ConfigLayerScope} scope
+ * @param {string[]} errors
+ * @param {string[]} warnings
+ * @returns {ConfigLayer | undefined}
+ */
+export function parseAgentBrowserConfigLayer(raw, path, scope, errors, warnings) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        errors.push(`Could not parse ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    const config = validateAgentBrowserConfig(parsed, path, scope, errors, warnings);
+    return config ? { config, path, scope } : undefined;
+}
+/**
+ * @param {string} rawValue
+ * @param {AgentBrowserConfigScope} scope
+ * @param {WebSearchProvider} [provider]
+ * @returns {CredentialSource | undefined}
+ */
+export function classifyCredentialSource(rawValue, scope, provider) {
+    const trimmed = rawValue.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith("!"))
+        return { kind: "command", provider, rawValue: trimmed, scope };
+    if (trimmed.includes("$"))
+        return { kind: "env", provider, rawValue: trimmed, scope };
+    return { kind: "literal", provider, rawValue: trimmed, scope };
+}
+/**
+ * @param {AgentBrowserConfig} config
+ * @returns {Required<BrowserDefaultProfileConfig> | undefined}
+ */
+function getBrowserDefaultProfile(config) {
+    const profile = config.browser?.defaultProfile;
+    if (!profile?.name.trim())
+        return undefined;
+    return { name: profile.name.trim(), policy: profile.policy ?? "authenticated-only" };
+}
+/** @param {AgentBrowserConfig} config */
+function getBrowserExecutablePath(config) {
+    const executablePath = config.browser?.executablePath?.trim();
+    return executablePath || undefined;
+}
+/**
+ * @param {ConfigLayer[]} layers
+ * @returns {ConfigLayerScope | undefined}
+ */
+function getBrowserDefaultProfileScope(layers) {
+    for (let index = layers.length - 1; index >= 0; index -= 1) {
+        const layer = layers[index];
+        if (layer?.config.browser?.defaultProfile !== undefined)
+            return layer.scope;
+    }
+    return undefined;
+}
+/**
+ * @param {ConfigLayer[]} layers
+ * @returns {ConfigLayerScope | undefined}
+ */
+function getBrowserExecutablePathScope(layers) {
+    for (let index = layers.length - 1; index >= 0; index -= 1) {
+        const layer = layers[index];
+        if (layer?.config.browser?.executablePath !== undefined)
+            return layer.scope;
+    }
+    return undefined;
+}
+/**
+ * @param {ConfigLayer[]} layers
+ * @returns {{ profile: Required<BrowserDefaultProfileConfig>; scope: ConfigLayerScope } | undefined}
+ */
+function getTrustedBrowserDefaultProfile(layers) {
+    for (let index = layers.length - 1; index >= 0; index -= 1) {
+        const layer = layers[index];
+        if (!layer)
+            continue;
+        const profile = getBrowserDefaultProfile(layer.config);
+        if (profile)
+            return { profile, scope: layer.scope };
+    }
+    return undefined;
+}
+/**
+ * @param {ConfigLayer[]} layers
+ * @returns {{ executablePath: string; scope: ConfigLayerScope } | undefined}
+ */
+function getTrustedBrowserExecutablePath(layers) {
+    for (let index = layers.length - 1; index >= 0; index -= 1) {
+        const layer = layers[index];
+        if (!layer)
+            continue;
+        const executablePath = getBrowserExecutablePath(layer.config);
+        if (executablePath)
+            return { executablePath, scope: layer.scope };
+    }
+    return undefined;
+}
+/**
+ * @param {ConfigLayer[]} layers
+ * @param {WebSearchProviderConfigKey} key
+ * @returns {AgentBrowserConfigScope}
+ */
+function getWebSearchCredentialScope(layers, key) {
+    for (let index = layers.length - 1; index >= 0; index -= 1) {
+        const layer = layers[index];
+        if (layer?.config.webSearch?.[key] !== undefined)
+            return layer.scope;
+    }
+    return "global";
+}
+/**
+ * @param {{ env: NodeJS.ProcessEnv; layers: ConfigLayer[]; mergedConfig: AgentBrowserConfig }} options
+ * @returns {Partial<Record<WebSearchProvider, CredentialSource>>}
+ */
+export function buildWebSearchCredentialSources(options) {
+    /** @type {Partial<Record<WebSearchProvider, CredentialSource>>} */
+    const sources = {};
+    for (const provider of WEB_SEARCH_PROVIDERS) {
+        const descriptor = getWebSearchProviderDescriptor(provider);
+        const apiKey = options.mergedConfig.webSearch?.[descriptor.configKey];
+        if (apiKey !== undefined) {
+            sources[provider] = classifyCredentialSource(apiKey, getWebSearchCredentialScope(options.layers, descriptor.configKey), provider);
+        }
+        if (!sources[provider] && options.env[descriptor.apiKeyEnv]?.trim()) {
+            sources[provider] = { kind: "literal", provider, rawValue: options.env[descriptor.apiKeyEnv] ?? "", scope: "env-fallback" };
+        }
+    }
+    return sources;
+}
+/**
+ * @param {{ env: NodeJS.ProcessEnv; layers: ConfigLayer[]; mergedConfig: AgentBrowserConfig; paths: AgentBrowserConfigPaths; errors: string[]; warnings: string[]; projectConfigIncluded?: boolean }} options
+ * @returns {AgentBrowserConfigState}
+ */
+export function buildAgentBrowserConfigState(options) {
+    const webSearchCredentialSources = buildWebSearchCredentialSources(options);
+    const trustedBrowserDefaultProfile = getTrustedBrowserDefaultProfile(options.layers);
+    const trustedBrowserExecutablePath = getTrustedBrowserExecutablePath(options.layers);
+    return {
+        browserDefaultProfile: getBrowserDefaultProfile(options.mergedConfig),
+        browserDefaultProfileScope: getBrowserDefaultProfileScope(options.layers),
+        browserExecutablePath: getBrowserExecutablePath(options.mergedConfig),
+        browserExecutablePathScope: getBrowserExecutablePathScope(options.layers),
+        trustedBrowserDefaultProfile: trustedBrowserDefaultProfile?.profile,
+        trustedBrowserDefaultProfileScope: trustedBrowserDefaultProfile?.scope,
+        trustedBrowserExecutablePath: trustedBrowserExecutablePath?.executablePath,
+        trustedBrowserExecutablePathScope: trustedBrowserExecutablePath?.scope,
+        config: options.mergedConfig,
+        webSearchCredentialSources,
+        webSearchEnabled: options.mergedConfig.webSearch?.enabled !== false,
+        webSearchPreferredProvider: options.mergedConfig.webSearch?.preferredProvider ?? DEFAULT_WEB_SEARCH_PROVIDER,
+        errors: options.errors,
+        layers: options.layers,
+        paths: options.paths,
+        projectConfigIncluded: options.projectConfigIncluded ?? options.layers.some((layer) => layer.scope === "project"),
+        warnings: options.warnings,
+    };
+}
+/**
+ * @param {string} path
+ * @param {ConfigLayerScope} scope
+ * @param {string[]} errors
+ * @param {string[]} warnings
+ * @returns {ConfigLayer | undefined}
+ */
+function readConfigLayerSync(path, scope, errors, warnings) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+            return undefined;
+        errors.push(`Could not read ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    return parseAgentBrowserConfigLayer(raw, path, scope, errors, warnings);
+}
+/**
+ * @param {AgentBrowserConfigLoadOptions} [options]
+ * @returns {AgentBrowserConfigState}
+ */
+export function loadAgentBrowserConfigStateSync(options = {}) {
+    const env = options.env ?? process.env;
+    const paths = getAgentBrowserConfigPaths({ cwd: options.cwd, env });
+    const includeProjectConfig = options.includeProjectConfig !== false;
+    /** @type {string[]} */
+    const errors = [];
+    /** @type {string[]} */
+    const warnings = [];
+    /** @type {Array<{ path: string; scope: ConfigLayerScope }>} */
+    const layerCandidates = [
+        { path: paths.global, scope: "global" },
+        ...(includeProjectConfig ? [{ path: paths.project, scope: /** @type {ConfigLayerScope} */ ("project") }] : []),
+        ...(paths.override ? [{ path: paths.override, scope: /** @type {ConfigLayerScope} */ ("override") }] : []),
+    ];
+    /** @type {ConfigLayer[]} */
+    const layers = [];
+    /** @type {AgentBrowserConfig} */
+    let mergedConfig = {};
+    for (const candidate of layerCandidates) {
+        const layer = readConfigLayerSync(candidate.path, candidate.scope, errors, warnings);
+        if (!layer)
+            continue;
+        layers.push(layer);
+        mergedConfig = mergeAgentBrowserConfig(mergedConfig, layer.config);
+    }
+    return buildAgentBrowserConfigState({
+        env,
+        errors,
+        layers,
+        mergedConfig,
+        paths,
+        projectConfigIncluded: includeProjectConfig,
+        warnings,
+    });
+}
+/**
+ * @param {string} rawValue
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function resolveEnvInterpolations(rawValue, env) {
+    let output = "";
+    for (let index = 0; index < rawValue.length; index += 1) {
+        const char = rawValue[index];
+        if (char !== "$") {
+            output += char;
+            continue;
+        }
+        const next = rawValue[index + 1];
+        if (next === "$") {
+            output += "$";
+            index += 1;
+            continue;
+        }
+        if (next === "!") {
+            output += "!";
+            index += 1;
+            continue;
+        }
+        let name = "";
+        if (next === "{") {
+            const end = rawValue.indexOf("}", index + 2);
+            if (end === -1)
+                return undefined;
+            name = rawValue.slice(index + 2, end);
+            index = end;
+        }
+        else {
+            const match = rawValue.slice(index + 1).match(/^([A-Za-z_][A-Za-z0-9_]*)/);
+            if (!match) {
+                output += "$";
+                continue;
+            }
+            name = match[1] ?? "";
+            index += name.length;
+        }
+        if (!name)
+            return undefined;
+        const value = env[name];
+        if (value === undefined)
+            return undefined;
+        output += value;
+    }
+    return output;
+}
+/**
+ * @param {AgentBrowserConfigState} state
+ * @param {WebSearchProvider | "auto"} [requestedProvider]
+ * @returns {WebSearchProvider[]}
+ */
+export function getWebSearchProviderOrder(state, requestedProvider) {
+    if (requestedProvider && requestedProvider !== "auto")
+        return [requestedProvider];
+    const preferred = state.webSearchPreferredProvider;
+    return [preferred, ...WEB_SEARCH_PROVIDERS.filter((provider) => provider !== preferred)];
+}
+/**
+ * @param {AgentBrowserConfigState} state
+ * @param {WebSearchProvider} provider
+ */
+export function getWebSearchCredentialSource(state, provider) {
+    return state.webSearchCredentialSources[provider];
+}
+/**
+ * @param {CredentialSource | undefined} source
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function hasPotentialCredentialSource(source, env) {
+    if (!source)
+        return false;
+    if (source.kind === "command")
+        return true;
+    if (source.kind === "env")
+        return Boolean(resolveEnvInterpolations(source.rawValue, env)?.trim());
+    return Boolean(source.rawValue.trim());
+}
+/**
+ * @param {AgentBrowserConfigState} state
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function canRegisterWebSearchTool(state, env = process.env) {
+    if (!state.webSearchEnabled || state.errors.length > 0)
+        return false;
+    return WEB_SEARCH_PROVIDERS.some((provider) => hasPotentialCredentialSource(state.webSearchCredentialSources[provider], env));
+}
+/**
+ * @param {CredentialSource | undefined} source
+ * @param {WebSearchProvider} [provider]
+ */
+export function getCredentialSourceSummary(source, provider) {
+    if (!source)
+        return "not configured";
+    if (source.kind === "command")
+        return `configured via command (${source.scope})`;
+    if (source.kind === "env")
+        return `configured via environment interpolation (${source.scope})`;
+    if (source.scope === "env-fallback") {
+        return `configured via ${getWebSearchProviderEnvVar(provider ?? source.provider ?? DEFAULT_WEB_SEARCH_PROVIDER)} environment fallback`;
+    }
+    return `configured as plaintext ${source.scope} value [redacted]`;
+}
+/** @param {AgentBrowserConfigState} state */
+export function formatBrowserProfileStatus(state) {
+    const profile = state.browserDefaultProfile;
+    if (!profile)
+        return "not configured";
+    const scope = state.browserDefaultProfileScope ?? "unknown";
+    return `${profile.name} (policy: ${profile.policy}; ${scope})`;
+}
+/** @param {AgentBrowserConfigState} state */
+export function formatBrowserExecutableStatus(state) {
+    const executablePath = state.browserExecutablePath;
+    if (!executablePath)
+        return "not configured";
+    const scope = state.browserExecutablePathScope ?? "unknown";
+    return `${executablePath} (${scope})`;
+}
+/**
+ * @param {AgentBrowserConfigState} state
+ * @param {(path: string) => boolean} [exists]
+ * @returns {ConfigFileSummary[]}
+ */
+export function summarizeConfigFiles(state, exists = existsSync) {
+    return [
+        ["global", state.paths.global],
+        ["project", state.paths.project],
+        ...(state.paths.override ? [["override", state.paths.override]] : []),
+    ].map(([scope, path]) => ({ scope, path, exists: exists(path) }));
+}