pi-agent-browser-native 0.2.47 → 0.2.49

package/extensions/agent-browser/lib/config.ts

@@ -1,209 +0,0 @@
-/**
- * Purpose: Load pi-agent-browser-native package configuration from Pi-scoped global, project, or explicit paths.
- * Responsibilities: Resolve config layers, resolve secrets without exposing values, and provide redacted status for tools/CLIs.
- * Scope: Package-owned configuration only; canonical config policy lives in config-policy.js, browser command execution and web-search API calls live in focused modules.
- * Invariants/Assumptions: Raw project-local plaintext credentials are unsafe and rejected by the shared config policy; command credentials are resolved lazily at execution time.
- */
-
-import { exec as execCallback } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { promisify } from "node:util";
-
-import {
-	SECRET_COMMAND_TIMEOUT_MS,
-	buildAgentBrowserConfigState,
-	getAgentBrowserConfigPaths,
-	getWebSearchCredentialSource,
-	getWebSearchProviderOrder,
-	loadAgentBrowserConfigStateSync,
-	mergeAgentBrowserConfig,
-	parseAgentBrowserConfigLayer,
-	resolveEnvInterpolations,
-} from "./config-policy.js";
-import type {
-	AgentBrowserConfig,
-	AgentBrowserConfigLoadOptions,
-	AgentBrowserConfigScope,
-	AgentBrowserConfigState,
-	BrowserDefaultProfileConfig,
-	BrowserDefaultProfilePolicy,
-	ConfigLayer,
-	CredentialSource,
-	CredentialSourceKind,
-	WebSearchProvider,
-} from "./config-policy.js";
-
-export {
-	AGENT_BROWSER_CONFIG_ENV,
-	BRAVE_API_KEY_ENV,
-	CONFIG_RELATIVE_PATH,
-	DEFAULT_WEB_SEARCH_PROVIDER,
-	EXA_API_KEY_ENV,
-	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,
-	isPlaintextCredentialValue,
-	isProjectSafeCredentialValueForProvider,
-	isWebSearchProvider,
-	loadAgentBrowserConfigStateSync,
-	mergeAgentBrowserConfig,
-	parseAgentBrowserConfigLayer,
-	resolveEnvInterpolations,
-	summarizeConfigFiles,
-	validateAgentBrowserConfig,
-	validateWebSearchProvider,
-} from "./config-policy.js";
-export type {
-	AgentBrowserConfig,
-	AgentBrowserConfigLoadOptions,
-	AgentBrowserConfigScope,
-	AgentBrowserConfigState,
-	BrowserDefaultProfileConfig,
-	BrowserDefaultProfilePolicy,
-	ConfigLayer,
-	CredentialSource,
-	CredentialSourceKind,
-	WebSearchProvider,
-	WebSearchProviderDescriptor,
-} from "./config-policy.js";
-
-const exec = promisify(execCallback);
-
-export interface ResolvedCredential {
-	source: CredentialSource;
-	value: string;
-}
-
-async function readConfigLayer(path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): Promise<ConfigLayer | undefined> {
-	let raw: string;
-	try {
-		raw = await readFile(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);
-}
-
-export async function loadAgentBrowserConfig(options: AgentBrowserConfigLoadOptions = {}): Promise<AgentBrowserConfigState> {
-	const env = options.env ?? process.env;
-	const paths = getAgentBrowserConfigPaths({ cwd: options.cwd, env });
-	const includeProjectConfig = options.includeProjectConfig !== false;
-	const errors: string[] = [];
-	const warnings: string[] = [];
-	const layerCandidates = [
-		{ path: paths.global, scope: "global" as const },
-		...(includeProjectConfig ? [{ path: paths.project, scope: "project" as const }] : []),
-		...(paths.override ? [{ path: paths.override, scope: "override" as const }] : []),
-	];
-	const layers: ConfigLayer[] = [];
-	let mergedConfig: AgentBrowserConfig = {};
-	for (const candidate of layerCandidates) {
-		const layer = await readConfigLayer(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,
-	});
-}
-
-export function loadAgentBrowserConfigSync(options: AgentBrowserConfigLoadOptions = {}): AgentBrowserConfigState {
-	return loadAgentBrowserConfigStateSync(options);
-}
-
-async function resolveCommandCredential(rawValue: string, signal?: AbortSignal): Promise<string | undefined> {
-	const command = rawValue.slice(1).trim();
-	if (!command) return undefined;
-	try {
-		const result = await exec(command, {
-			signal,
-			timeout: SECRET_COMMAND_TIMEOUT_MS,
-			maxBuffer: 1024 * 1024,
-		});
-		const value = result.stdout.trim();
-		return value.length > 0 ? value : undefined;
-	} catch (error) {
-		if (signal?.aborted) throw 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.");
-	}
-}
-
-export async function resolveCredentialSource(
-	source: CredentialSource | undefined,
-	options: { env?: NodeJS.ProcessEnv; signal?: AbortSignal } = {},
-): Promise<ResolvedCredential | undefined> {
-	if (!source) return undefined;
-	let value: string | undefined;
-	if (source.kind === "command") {
-		value = await resolveCommandCredential(source.rawValue, options.signal);
-	} else if (source.kind === "env") {
-		value = resolveEnvInterpolations(source.rawValue, options.env ?? process.env)?.trim();
-	} else {
-		value = source.rawValue.trim();
-	}
-	return value ? { source, value } : undefined;
-}
-
-export async function resolveWebSearchCredential(
-	state: AgentBrowserConfigState,
-	provider: WebSearchProvider,
-	options: { env?: NodeJS.ProcessEnv; signal?: AbortSignal } = {},
-): Promise<ResolvedCredential | undefined> {
-	return resolveCredentialSource(getWebSearchCredentialSource(state, provider), options);
-}
-
-export async function resolvePreferredWebSearchCredential(
-	state: AgentBrowserConfigState,
-	options: { env?: NodeJS.ProcessEnv; provider?: WebSearchProvider | "auto"; signal?: AbortSignal } = {},
-): Promise<{ provider: WebSearchProvider; credential: ResolvedCredential } | undefined> {
-	for (const provider of getWebSearchProviderOrder(state, options.provider)) {
-		const credential = await resolveWebSearchCredential(state, provider, options);
-		if (credential) return { provider, credential };
-	}
-	return undefined;
-}
-
-export async function hasResolvableCredentialSource(
-	state: AgentBrowserConfigState,
-	options: { env?: NodeJS.ProcessEnv } = {},
-): Promise<boolean> {
-	if (!state.webSearchEnabled || state.errors.length > 0) return false;
-	for (const provider of getWebSearchProviderOrder(state)) {
-		const source = getWebSearchCredentialSource(state, provider);
-		if (!source) continue;
-		if (source.kind === "command") return true;
-		if ((await resolveCredentialSource(source, options))?.value) return true;
-	}
-	return false;
-}

package/extensions/agent-browser/lib/electron/cdp.ts

@@ -1,69 +0,0 @@
-/**
- * Purpose: Parse and fetch Chrome DevTools Protocol metadata for wrapper-owned Electron launches.
- * Responsibilities: Normalize CDP version/target JSON and perform bounded localhost CDP JSON fetches.
- * Scope: Tiny Electron CDP boundary helpers only; launch, status, cleanup, and target selection stay in their owning modules.
- * Usage: Imported by Electron launch and cleanup paths when polling `/json/version` and `/json/list`.
- * Invariants/Assumptions: Malformed or unavailable CDP endpoints return undefined/empty metadata rather than throwing, matching prior caller behavior.
- */
-
-import { isRecord } from "../parsing.js";
-
-const ELECTRON_CDP_FETCH_TIMEOUT_MS = 1_000;
-
-export interface ElectronCdpVersion {
-	browser?: string;
-	protocolVersion?: string;
-	userAgent?: string;
-	v8Version?: string;
-	webKitVersion?: string;
-	webSocketDebuggerUrl?: string;
-}
-
-export interface ElectronCdpTarget {
-	id?: string;
-	title?: string;
-	type?: string;
-	url?: string;
-	webSocketDebuggerUrl?: string;
-}
-
-function asString(value: unknown): string | undefined {
-	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
-}
-
-export function parseCdpVersion(value: unknown): ElectronCdpVersion | undefined {
-	if (!isRecord(value)) return undefined;
-	return {
-		browser: asString(value.Browser) ?? asString(value.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),
-		webKitVersion: asString(value["WebKit-Version"]) ?? asString(value.webKitVersion),
-		webSocketDebuggerUrl: asString(value.webSocketDebuggerUrl),
-	};
-}
-
-export function parseCdpTargets(value: unknown): ElectronCdpTarget[] {
-	if (!Array.isArray(value)) return [];
-	return value.filter(isRecord).map((target) => ({
-		id: asString(target.id),
-		title: asString(target.title),
-		type: asString(target.type),
-		url: asString(target.url),
-		webSocketDebuggerUrl: asString(target.webSocketDebuggerUrl),
-	}));
-}
-
-export async function fetchCdpJson(url: string): Promise<unknown | undefined> {
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), ELECTRON_CDP_FETCH_TIMEOUT_MS);
-	try {
-		const response = await fetch(url, { signal: controller.signal });
-		if (!response.ok) return undefined;
-		return await response.json() as unknown;
-	} catch {
-		return undefined;
-	} finally {
-		clearTimeout(timeout);
-	}
-}

package/extensions/agent-browser/lib/electron/cleanup.ts

@@ -1,235 +0,0 @@
-/**
- * Purpose: Inspect and clean wrapper-owned Electron launch resources.
- * Responsibilities: Report CDP liveness/targets without mutation and remove only tracked process/profile resources during explicit or shutdown cleanup.
- * Scope: Host-side Electron status and resource cleanup only; upstream managed-session close remains in the extension entrypoint.
- * Usage: Called by electron.status, electron.cleanup, and session_shutdown handling.
- * Invariants/Assumptions: Cleanup operates only on launch records produced by this wrapper and prefers partial cleanup reporting over killing or deleting untracked resources.
- */
-
-import { execFile, type ChildProcess } from "node:child_process";
-import { rm } from "node:fs/promises";
-import { promisify } from "node:util";
-
-import { fetchCdpJson, parseCdpTargets, parseCdpVersion } from "./cdp.js";
-import { ELECTRON_PROFILE_DIR_PREFIX, type ElectronCdpTarget, type ElectronCdpVersion, type ElectronLaunchRecord } from "./launch.js";
-import { pathExists } from "../fs-utils.js";
-import { getSecureTempChildDirectoryValidationError } from "../temp.js";
-
-const ELECTRON_CLEANUP_DEFAULT_TIMEOUT_MS = 5_000;
-const ELECTRON_CLEANUP_POLL_INTERVAL_MS = 100;
-const RESTORED_PROCESS_COMMAND_TIMEOUT_MS = 1_000;
-const execFileAsync = promisify(execFile);
-
-export interface ElectronLaunchStatus {
-	cleanupState: ElectronLaunchRecord["cleanupState"];
-	launchId: string;
-	pid?: number;
-	pidAlive?: boolean;
-	port: number;
-	portAlive: boolean;
-	targets: ElectronCdpTarget[];
-	version?: ElectronCdpVersion;
-}
-
-export interface ElectronCleanupStep {
-	error?: string;
-	resource: "debug-port" | "managed-session" | "process" | "user-data-dir";
-	sessionName?: string;
-	state: "already-gone" | "failed" | "removed" | "skipped";
-}
-
-export interface ElectronCleanupResult {
-	launchId: string;
-	partial: boolean;
-	record: ElectronLaunchRecord;
-	remainingResources: string[];
-	steps: ElectronCleanupStep[];
-	summary: string;
-}
-
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function isPidAlive(pid: number | undefined): boolean | undefined {
-	if (!pid || !Number.isSafeInteger(pid) || pid <= 0) return undefined;
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		const code = (error as NodeJS.ErrnoException).code;
-		return code === "EPERM" ? true : false;
-	}
-}
-
-async function isPortAlive(port: number): Promise<{ targets: ElectronCdpTarget[]; version?: ElectronCdpVersion }> {
-	const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`));
-	if (!version) return { targets: [] };
-	const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`));
-	return { targets, version };
-}
-
-export async function inspectElectronLaunchStatus(record: ElectronLaunchRecord): Promise<ElectronLaunchStatus> {
-	const cdp = await isPortAlive(record.port);
-	return {
-		cleanupState: record.cleanupState,
-		launchId: record.launchId,
-		pid: record.pid,
-		pidAlive: isPidAlive(record.pid),
-		port: record.port,
-		portAlive: cdp.version !== undefined,
-		targets: cdp.targets,
-		version: cdp.version,
-	};
-}
-
-async function waitForProcessExit(child: ChildProcess | undefined, pid: number | undefined, deadlineMs: number): Promise<boolean> {
-	while (Date.now() <= deadlineMs) {
-		if (child && (child.exitCode !== null || child.signalCode !== null)) return true;
-		if (isPidAlive(pid) === false) return true;
-		await sleep(ELECTRON_CLEANUP_POLL_INTERVAL_MS);
-	}
-	return isPidAlive(pid) === false;
-}
-
-async function readPidCommandLine(pid: number | undefined): Promise<string | undefined> {
-	if (!pid || !Number.isSafeInteger(pid) || pid <= 0) return undefined;
-	try {
-		const { stdout } = await execFileAsync("ps", ["-ww", "-p", String(pid), "-o", "command="], {
-			timeout: RESTORED_PROCESS_COMMAND_TIMEOUT_MS,
-		});
-		return stdout.trim() || undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-function restoredLaunchCommandMatchesRecord(record: ElectronLaunchRecord, commandLine: string | undefined): boolean {
-	return commandLine?.includes(`--user-data-dir=${record.userDataDir}`) === true;
-}
-
-async function getRestoredProcessVerificationError(record: ElectronLaunchRecord): Promise<string | undefined> {
-	const commandLine = await readPidCommandLine(record.pid);
-	if (!commandLine) {
-		return `PID ${record.pid} is alive, but this session has no tracked child handle and its command line could not be inspected; refusing to signal a restored PID that may have been reused.`;
-	}
-	if (!restoredLaunchCommandMatchesRecord(record, commandLine)) {
-		return `PID ${record.pid} is alive, but this session has no tracked child handle and its command line does not include wrapper-owned user data dir ${record.userDataDir}; refusing to signal a restored PID that may have been reused.`;
-	}
-	return undefined;
-}
-
-function killPid(pid: number | undefined, signal: NodeJS.Signals): boolean {
-	if (!pid || !Number.isSafeInteger(pid) || pid <= 0) return false;
-	try {
-		process.kill(pid, signal);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function killProcessGroup(processGroupId: number | undefined, signal: NodeJS.Signals): boolean {
-	if (process.platform === "win32" || !processGroupId || !Number.isSafeInteger(processGroupId) || processGroupId <= 0) return false;
-	try {
-		process.kill(-processGroupId, signal);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function signalRestoredLaunchProcess(record: ElectronLaunchRecord, signal: NodeJS.Signals): boolean {
-	return killProcessGroup(record.processGroupId, signal) || killPid(record.pid, signal);
-}
-
-async function cleanupProcess(record: ElectronLaunchRecord, child: ChildProcess | undefined, deadlineMs: number): Promise<ElectronCleanupStep> {
-	if (!record.pid) return { resource: "process", state: "skipped" };
-	if (isPidAlive(record.pid) === false) return { resource: "process", state: "already-gone" };
-	if (!child) {
-		const verificationError = await getRestoredProcessVerificationError(record);
-		if (verificationError) return { error: verificationError, resource: "process", state: "failed" };
-		if (!signalRestoredLaunchProcess(record, "SIGTERM")) {
-			return { error: `PID ${record.pid} matched wrapper launch metadata but could not be signaled.`, resource: "process", state: "failed" };
-		}
-		if (await waitForProcessExit(undefined, record.pid, deadlineMs)) return { resource: "process", state: "removed" };
-		signalRestoredLaunchProcess(record, "SIGKILL");
-		if (await waitForProcessExit(undefined, record.pid, Date.now() + 1_000)) return { resource: "process", state: "removed" };
-		return { error: `PID ${record.pid} remained alive after SIGTERM/SIGKILL.`, resource: "process", state: "failed" };
-	}
-	if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
-	else killPid(record.pid, "SIGTERM");
-	if (await waitForProcessExit(child, record.pid, deadlineMs)) return { resource: "process", state: "removed" };
-	if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
-	else killPid(record.pid, "SIGKILL");
-	if (await waitForProcessExit(child, record.pid, Date.now() + 1_000)) return { resource: "process", state: "removed" };
-	return { error: `PID ${record.pid} remained alive after SIGTERM/SIGKILL.`, resource: "process", state: "failed" };
-}
-
-async function cleanupUserDataDir(record: ElectronLaunchRecord): Promise<ElectronCleanupStep> {
-	if (!record.userDataDir) return { resource: "user-data-dir", state: "skipped" };
-	if (!await pathExists(record.userDataDir)) return { resource: "user-data-dir", state: "already-gone" };
-	const validationError = await getSecureTempChildDirectoryValidationError(record.userDataDir, ELECTRON_PROFILE_DIR_PREFIX);
-	if (validationError) return { error: validationError, resource: "user-data-dir", state: "failed" };
-	try {
-		await rm(record.userDataDir, { force: true, recursive: true });
-		return { resource: "user-data-dir", state: await pathExists(record.userDataDir) ? "failed" : "removed" };
-	} catch (error) {
-		return { error: error instanceof Error ? error.message : String(error), resource: "user-data-dir", state: "failed" };
-	}
-}
-
-function shouldSkipUserDataDirCleanup(processStep: ElectronCleanupStep, debugPortStep: ElectronCleanupStep): string | undefined {
-	if (processStep.state === "failed") return `Skipped because process cleanup failed: ${processStep.error ?? "process state could not be verified"}.`;
-	if (debugPortStep.state === "failed") return `Skipped because debug port cleanup is incomplete: ${debugPortStep.error ?? "debug port still responds"}.`;
-	return undefined;
-}
-
-async function cleanupDebugPort(record: ElectronLaunchRecord): Promise<ElectronCleanupStep> {
-	const cdp = await isPortAlive(record.port);
-	return cdp.version ? { resource: "debug-port", state: "failed", error: `/json/version still responds on port ${record.port}.` } : { resource: "debug-port", state: "already-gone" };
-}
-
-function summarizeCleanup(launchId: string, steps: ElectronCleanupStep[]): { partial: boolean; remainingResources: string[]; summary: string } {
-	const remainingResources = steps
-		.filter((step) => step.state === "failed" || (step.resource === "user-data-dir" && step.state === "skipped" && step.error))
-		.map((step) => step.resource);
-	const partial = remainingResources.length > 0;
-	return {
-		partial,
-		remainingResources,
-		summary: partial
-			? `Electron cleanup for ${launchId} is partial; remaining resources: ${remainingResources.join(", ")}.`
-			: `Electron cleanup for ${launchId} completed.`,
-	};
-}
-
-export async function cleanupElectronLaunchResources(options: {
-	child?: ChildProcess;
-	record: ElectronLaunchRecord;
-	timeoutMs?: number;
-}): Promise<ElectronCleanupResult> {
-	const timeoutMs = Number.isSafeInteger(options.timeoutMs) && (options.timeoutMs ?? 0) > 0
-		? options.timeoutMs as number
-		: ELECTRON_CLEANUP_DEFAULT_TIMEOUT_MS;
-	const deadlineMs = Date.now() + timeoutMs;
-	const processStep = await cleanupProcess(options.record, options.child, deadlineMs);
-	const debugPortStep = await cleanupDebugPort(options.record);
-	const userDataDirSkipReason = shouldSkipUserDataDirCleanup(processStep, debugPortStep);
-	const userDataDirStep = userDataDirSkipReason
-		? { error: userDataDirSkipReason, resource: "user-data-dir" as const, state: "skipped" as const }
-		: await cleanupUserDataDir(options.record);
-	const steps = [processStep, debugPortStep, userDataDirStep];
-	const summary = summarizeCleanup(options.record.launchId, steps);
-	return {
-		launchId: options.record.launchId,
-		partial: summary.partial,
-		record: {
-			...options.record,
-			cleanupState: summary.partial ? "partial" : "cleaned",
-		},
-		remainingResources: summary.remainingResources,
-		steps,
-		summary: summary.summary,
-	};
-}