import type { ChromeOptions } from './types.js';
import type { BrowserType } from './types.js';
/**
 * True when `binaryPath` is a shebang script rather than a native browser
 * executable. The Linux distro launchers (`/usr/bin/brave-browser`, …) are such
 * scripts; `launchBrowser` can't drive one over `--remote-debugging-pipe` (see
 * resolveBrowserBinary). `profiles doctor` uses this to flag a profile whose
 * binary resolves to a wrapper we couldn't unwrap. Shebang scripts are a
 * Linux/Unix concept — returns false on Windows/macOS app bundles.
 */
export declare function isLauncherScript(binaryPath: string): boolean;
export declare function resolveBrowserBinary(binaryPath: string): string;
export declare function findBrowserPath(browserType: BrowserType, customBinary?: string): string;
/**
 * Walk the per-platform priority list and return the first browser that's
 * actually installed on disk. Returns null if none of them are present.
 *
 * This is the auto-pick the `agents browser start` command uses when the user
 * doesn't pass `--profile`. The intent matches "use whatever's preinstalled,"
 * but constrained to Chromium-family binaries so CDP works without a new
 * driver layer.
 */
export declare function findFirstInstalledBrowser(platform?: string): {
    browserType: BrowserType;
    binary: string;
} | null;
/**
 * List every installed Chromium-family browser on this machine, in the platform
 * priority order. Used by `agents setup browser` to offer a pick when more than
 * one is present. Returns [] if none are installed.
 */
export declare function listInstalledBrowsers(platform?: string): {
    browserType: BrowserType;
    binary: string;
}[];
export interface LaunchResult {
    pid: number;
    port: number;
    wsUrl: string;
}
/**
 * Resolve a browser-profile secrets bundle into an env map for the child, or an
 * EMPTY map when the bundle is absent, locked, or otherwise unreadable — never a
 * throw and never a prompt. Injecting profile secrets on launch is a BACKGROUND
 * read (the agent is spawning the browser, not a human at a Touch ID sheet), so
 * the read is `agentOnly` (SEC-13: never pop biometry on its own): a `never`/no-ACL
 * or broker-held bundle resolves silently; a locked `hold`/`always` bundle throws,
 * and we swallow it so the launch proceeds without those secrets (an agent that
 * needs them can `agents secrets unlock <bundle>`). Exported so the no-prompt
 * behavior is testable on the real keychain path without spawning a browser.
 */
export declare function resolveProfileSecretsEnv(secrets?: string): Record<string, string>;
export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string, customBinary?: string, isElectron?: boolean): Promise<LaunchResult>;
export declare function attachToChrome(port: number): Promise<string>;
export declare function killChrome(pid: number): void;
export declare function getRunningChromeInfo(profileName: string): {
    pid: number;
    port: number;
} | null;
/**
 * Prepare `<userDataDir>/Default/Preferences` before launch.
 *
 * Two concerns, one write:
 *  - First launch (file absent): stamp the agents-cli profile name so
 *    Chromium's UI shows "<profile>" instead of its default "Person 1".
 *    Cosmetic; existing files keep whatever Chrome wrote in the meantime.
 *  - Every launch (when `persistSessionCookies`): pin
 *    `session.restore_on_startup: 1` ("continue where you left off").
 *    Chromium purges memory-only session cookies at startup UNLESS this
 *    preference says the session will be restored — it keys the purge off
 *    the pref, not off tabs actually reopening. Sites like idealista issue
 *    login cookies with `expires=-1`, so without this every browser restart
 *    silently logs the profile out. The visible tab-restore side effect is
 *    suppressed separately via `--no-startup-window` (see launchBrowser).
 *
 * Runs only while the browser is down (called before spawn), so Chromium
 * can't overwrite the patch on exit. Best-effort: a malformed existing file
 * is left untouched (Chromium recovers its own state better than we can),
 * and any I/O hiccup is silently ignored.
 */
export declare function ensureProfilePreferences(userDataDir: string, profileName: string, persistSessionCookies: boolean): void;
/**
 * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
 * (lsof doesn't exist there). Returns false on any tooling error so port
 * allocation degrades to "assume free" rather than throwing.
 *
 * Exported as the canonical cross-platform probe — `findFreeProfilePort`
 * (profiles.ts) must use this rather than shelling out to lsof directly,
 * or every port scans as free on Windows.
 */
export declare function isPortInUse(port: number): boolean;
export declare function allocatePort(): number;
/**
 * Read the `--user-data-dir` a running browser process was launched with, by
 * inspecting its command line (PHNX-3967). This is the ownership signal the
 * attach-only guard uses to tell the credentialed canonical browser apart from a
 * foreign port-squatter serving CDP on the same port (e.g. a logged-out
 * `/tmp/...` Comet). Returns null when the pid is gone, exposes no
 * `--user-data-dir`, or the platform probe fails.
 *
 * POSIX: `ps -ww -o command=` (full, un-truncated argv). Windows: the
 * `CommandLine` from `Win32_Process` via PowerShell. The value is captured up to
 * the next ` --<flag>` (or end of line) so a data dir that itself contains a
 * space is not truncated at the space.
 */
export declare function getProcessUserDataDir(pid: number): string | null;
/**
 * Extract the `--user-data-dir` value from a browser command line. Handles both
 * `--user-data-dir=<path>` and `--user-data-dir <path>` and stops the value at
 * the next ` --<flag>` so a path containing spaces survives. Exported for unit
 * testing without a live process.
 */
export declare function parseUserDataDirFromCommandLine(cmdline: string): string | null;
export interface PortOccupant {
    pid: number;
    command: string;
}
/**
 * Identify the process listening on a TCP port. Returns null when nothing is bound.
 * Used for clearer error messages when a profile's configured port is taken by a
 * non-debug process (e.g. Comet running without --remote-debugging-port).
 * `lsof` on POSIX; `netstat -ano` + `tasklist` on Windows.
 */
export declare function getPortOccupant(port: number): PortOccupant | null;
