@f5-sales-demo/xcsh 19.51.2

package/src/autoresearch/types.ts

@@ -0,0 +1,114 @@
+import type { AgentToolResult } from "@f5xc-salesdemos/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "../extensibility/extensions";
+import type { TruncationResult } from "../session/streaming-output";
+
+export type MetricDirection = "lower" | "higher";
+export type ExperimentStatus = "keep" | "discard" | "crash" | "checks_failed";
+export type ASIValue = string | number | boolean | null | ASIValue[] | { [key: string]: ASIValue };
+export type ASIData = Record<string, ASIValue>;
+export type NumericMetricMap = Record<string, number>;
+export type MetricDef = { name: string; unit: string };
+
+export interface AutoresearchContract {
+	benchmark: {
+		command: string | null;
+		primaryMetric: string | null;
+		metricUnit: string;
+		direction: MetricDirection | null;
+		secondaryMetrics: string[];
+	};
+	scopePaths: string[];
+	offLimits: string[];
+	constraints: string[];
+}
+export interface ExperimentResult {
+	runNumber: number | null;
+	commit: string;
+	metric: number;
+	metrics: NumericMetricMap;
+	status: ExperimentStatus;
+	description: string;
+	timestamp: number;
+	segment: number;
+	confidence: number | null;
+	asi?: ASIData;
+}
+export interface ExperimentState {
+	results: ExperimentResult[];
+	bestMetric: number | null;
+	bestDirection: MetricDirection;
+	metricName: string;
+	metricUnit: string;
+	secondaryMetrics: MetricDef[];
+	name: string | null;
+	currentSegment: number;
+	maxExperiments: number | null;
+	confidence: number | null;
+	benchmarkCommand: string | null;
+	scopePaths: string[];
+	offLimits: string[];
+	constraints: string[];
+}
+export interface RunExperimentProgressDetails {
+	phase: "running";
+	elapsed: string;
+	truncation?: TruncationResult;
+	fullOutputPath?: string;
+	runDirectory?: string;
+}
+interface RunDataBase {
+	checksPass: boolean | null;
+	checksTimedOut: boolean;
+	command: string;
+	parsedAsi: ASIData | null;
+	parsedMetrics: NumericMetricMap | null;
+	parsedPrimary: number | null;
+	passed: boolean;
+	preRunDirtyPaths: string[];
+	runDirectory: string;
+	runNumber: number;
+}
+export interface RunDetails extends RunDataBase {
+	benchmarkLogPath: string;
+	checksLogPath?: string;
+	exitCode: number | null;
+	durationSeconds: number;
+	crashed: boolean;
+	timedOut: boolean;
+	tailOutput: string;
+	checksOutput: string;
+	checksDuration: number;
+	metricName: string;
+	metricUnit: string;
+	truncation?: TruncationResult;
+	fullOutputPath?: string;
+}
+export type LogDetails = { experiment: ExperimentResult; state: ExperimentState; wallClockSeconds: number | null };
+export type PendingRunSummary = RunDataBase & { checksDurationSeconds: number | null; durationSeconds: number | null };
+export interface AutoresearchRuntime {
+	autoresearchMode: boolean;
+	autoResumeArmed: boolean;
+	dashboardExpanded: boolean;
+	lastAutoResumePendingRunNumber: number | null;
+	lastRunChecks: { pass: boolean; output: string; duration: number } | null;
+	lastRunDuration: number | null;
+	lastRunAsi: ASIData | null;
+	lastRunArtifactDir: string | null;
+	lastRunNumber: number | null;
+	lastRunSummary: PendingRunSummary | null;
+	runningExperiment: { startedAt: number; command: string; runDirectory: string; runNumber: number } | null;
+	state: ExperimentState;
+	goal: string | null;
+}
+export interface DashboardController {
+	clear(ctx: ExtensionContext): void;
+	requestRender(): void;
+	showOverlay(ctx: ExtensionContext, runtime: AutoresearchRuntime): Promise<void>;
+	updateWidget(ctx: ExtensionContext, runtime: AutoresearchRuntime): void;
+}
+export interface AutoresearchToolFactoryOptions {
+	dashboard: DashboardController;
+	getRuntime(ctx: ExtensionContext): AutoresearchRuntime;
+	pi: ExtensionAPI;
+}
+export type AutoresearchToolResult<TDetails> = AgentToolResult<TDetails>;

package/src/browser/acquire.ts

@@ -0,0 +1,249 @@
+import { execFileSync } from "node:child_process";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Browser, Page } from "puppeteer";
+import { assertLoopbackBrowserUrl, pickCoDrivePage, resolveBrowserConnectUrl } from "../tools/browser";
+import { locateChrome } from "./chrome-locate";
+
+export type AcquireMode = "attached" | "launched-default" | "launched-dedicated" | "relaunched-default";
+
+const DEFAULT_DEBUG_PORT = 9222;
+
+export function dedicatedProfileDir(home: string = os.homedir()): string {
+	return path.join(home, ".xcsh", "chrome-profile");
+}
+
+export function defaultProfileDir(opts?: {
+	platform?: NodeJS.Platform;
+	env?: NodeJS.ProcessEnv;
+	home?: string;
+}): string | null {
+	const platform = opts?.platform ?? process.platform;
+	const env = opts?.env ?? process.env;
+	const home = opts?.home ?? os.homedir();
+	switch (platform) {
+		case "darwin":
+			return path.join(home, "Library", "Application Support", "Google", "Chrome");
+		case "linux":
+			return path.join(home, ".config", "google-chrome");
+		case "win32": {
+			const localAppData = env.LOCALAPPDATA;
+			if (!localAppData) return null;
+			return path.join(localAppData, "Google", "Chrome", "User Data");
+		}
+		default:
+			return null;
+	}
+}
+
+async function withLaunchTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<never>((_resolve, reject) => {
+		timer = setTimeout(() => reject(new Error("launch timed out")), ms);
+	});
+	try {
+		return await Promise.race([p, timeout]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+export function buildLaunchArgs(opts: { profileDir?: string; debugPort: number }): string[] {
+	const args = [
+		`--remote-debugging-port=${opts.debugPort}`,
+		"--remote-debugging-address=127.0.0.1",
+		"--no-first-run",
+		"--no-default-browser-check",
+	];
+	if (opts.profileDir) args.push(`--user-data-dir=${opts.profileDir}`);
+	return args;
+}
+
+export type AcquireAction = "attach" | "launch" | "relaunch" | "dedicated" | "no-chrome";
+
+export function decideAcquireAction(state: {
+	debuggableNow: boolean;
+	chromeRunning: boolean;
+	chromeInstalled: boolean;
+	allowRelaunch: boolean;
+}): AcquireAction {
+	if (!state.chromeInstalled) return "no-chrome";
+	if (state.debuggableNow) return "attach";
+	if (!state.chromeRunning) return "launch";
+	return state.allowRelaunch ? "relaunch" : "dedicated";
+}
+
+/** Graceful (never force) quit command for the user's Chrome, per OS. */
+export function quitChromeCommand(
+	platform: NodeJS.Platform = process.platform,
+): { cmd: string; args: string[] } | null {
+	switch (platform) {
+		case "darwin":
+			return { cmd: "osascript", args: ["-e", 'quit app "Google Chrome"'] };
+		case "linux":
+			return { cmd: "pkill", args: ["-TERM", "-x", "chrome"] };
+		case "win32":
+			return { cmd: "taskkill", args: ["/IM", "chrome.exe"] };
+		default:
+			return null;
+	}
+}
+
+export function isProfileLockError(message: string): boolean {
+	// Chrome's own SingletonLock messages, plus Puppeteer's message when an
+	// explicit --user-data-dir is already held by a running browser
+	// ("The browser is already running for <dir>. Use a different `userDataDir` …").
+	return /singletonlock|processsingleton|profile appears to be in use|create a processsingleton|already running for|use a different\s+`?userdatadir/i.test(
+		message,
+	);
+}
+
+function defaultExec(cmd: string, args: string[]): { code: number } {
+	try {
+		execFileSync(cmd, args, { stdio: "ignore" });
+		return { code: 0 };
+	} catch (e) {
+		const code = (e as { status?: number }).status;
+		return { code: typeof code === "number" ? code : 1 };
+	}
+}
+
+export function isChromeRunning(
+	opts: { platform?: NodeJS.Platform; exec?: (cmd: string, args: string[]) => { code: number } } = {},
+): boolean {
+	const platform = opts.platform ?? process.platform;
+	const exec = opts.exec ?? defaultExec;
+	if (platform === "win32") {
+		// tasklist always exits 0; use FILTER so a no-match is a non-zero/empty result.
+		return exec("tasklist", ["/FI", "IMAGENAME eq chrome.exe", "/NH"]).code === 0;
+	}
+	// darwin/linux: pgrep exits 0 when a match exists, 1 otherwise.
+	const pattern = platform === "darwin" ? "Google Chrome" : "chrome";
+	return exec("pgrep", ["-x", pattern]).code === 0;
+}
+
+async function waitForChromeExit(timeoutMs = 8000, pollMs = 300): Promise<boolean> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (!isChromeRunning()) return true;
+		await new Promise(r => setTimeout(r, pollMs));
+	}
+	return false;
+}
+
+async function tryAttach(browserURL: string): Promise<{ browser: Browser; page: Page } | null> {
+	const puppeteer = (await import("puppeteer")).default;
+	try {
+		const browser = await puppeteer.connect({ browserURL });
+		const pages = await browser.pages();
+		const page = pages.length ? pages[pickCoDrivePage(pages)]! : await browser.newPage();
+		return { browser, page };
+	} catch {
+		return null;
+	}
+}
+
+async function launch(executablePath: string, args: string[]): Promise<Browser> {
+	const puppeteer = (await import("puppeteer")).default;
+	return puppeteer.launch({ headless: false, executablePath, args, defaultViewport: null });
+}
+
+export async function acquirePage(opts: {
+	settings: { get(key: string): unknown };
+	debugPort?: number;
+	allowRelaunch?: boolean;
+}): Promise<{ browser: Browser; page: Page; mode: AcquireMode }> {
+	const debugPort = opts.debugPort ?? DEFAULT_DEBUG_PORT;
+	const configuredUrl = resolveBrowserConnectUrl(opts.settings);
+	const attachUrl = configuredUrl ?? `http://127.0.0.1:${debugPort}`;
+	assertLoopbackBrowserUrl(attachUrl);
+
+	// 1) Attach to a Chrome already exposing the debug port.
+	const attached = await tryAttach(attachUrl);
+	if (attached) return { ...attached, mode: "attached" };
+
+	// If the user explicitly configured connectUrl but nothing is there, that is an error
+	// (do not silently launch a different browser than they asked to attach to).
+	if (configuredUrl) {
+		throw new Error(
+			`Could not attach to Chrome at ${configuredUrl}. Start Chrome with --remote-debugging-port=${debugPort} and retry, or unset browser.connectUrl to let xcsh launch Chrome.`,
+		);
+	}
+
+	const located = locateChrome({ settings: opts.settings });
+	if (!located) {
+		throw new Error(
+			"Google Chrome not found. Install Google Chrome, or set the browser.chromePath setting to your Chrome/Chromium executable.",
+		);
+	}
+
+	// 2) Launch the user's installed Chrome with their DEFAULT profile + debug port.
+	// We pass --user-data-dir EXPLICITLY (Chrome's implicit default profile would hand off
+	// to an already-running Chrome and exit, leaving puppeteer.launch hanging on a debug
+	// endpoint that never appears). A timeout guards against that handoff case so we can
+	// fall through to a dedicated profile instead of hanging.
+	const defaultDir = defaultProfileDir();
+	if (defaultDir) {
+		try {
+			const browser = await withLaunchTimeout(
+				launch(located.path, buildLaunchArgs({ debugPort, profileDir: defaultDir })),
+				12_000,
+			);
+			const pages = await browser.pages();
+			const page = pages.length ? pages[0]! : await browser.newPage();
+			return { browser, page, mode: "launched-default" };
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			// Profile locked (Chrome already running) or the launch timed out (handoff to a
+			// running instance) → fall through to a dedicated, xcsh-owned profile.
+			if (!isProfileLockError(msg) && !msg.includes("launch timed out")) throw err;
+
+			// Resolve relaunch consent: explicit opt, else the setting.
+			const allowRelaunch = opts.allowRelaunch ?? opts.settings.get("browser.allowChromeRelaunch") === true;
+			// 3) Chrome running without the port → consented quit + relaunch on the real profile.
+			if (allowRelaunch) {
+				const quit = quitChromeCommand();
+				if (quit) {
+					try {
+						execFileSync(quit.cmd, quit.args, { stdio: "ignore" });
+					} catch {
+						/* ignore quit errors; verify via waitForChromeExit */
+					}
+					const exited = await waitForChromeExit();
+					if (exited) {
+						const browser = await withLaunchTimeout(
+							launch(located.path, buildLaunchArgs({ debugPort, profileDir: defaultDir })),
+							12_000,
+						);
+						const pages = await browser.pages();
+						const page = pages.length ? pages[0]! : await browser.newPage();
+						return { browser, page, mode: "relaunched-default" };
+					}
+					// quit timed out → DO NOT relaunch (avoid two instances / data loss); fall through to dedicated.
+				}
+			}
+		}
+	}
+
+	// 4) Default profile unavailable (locked / handoff / unsupported platform) → dedicated
+	// xcsh-owned profile. A previous xcsh-launched Chrome on this profile may still be
+	// running (close() only disconnects, never terminates), so this launch can hit the
+	// same SingletonLock/handoff and hang. Guard it with a timeout; there is no further
+	// fallback, so a timeout/lock error is fatal.
+	const profileDir = dedicatedProfileDir();
+	let browser: Browser;
+	try {
+		browser = await withLaunchTimeout(launch(located.path, buildLaunchArgs({ debugPort, profileDir })), 12_000);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (msg.includes("launch timed out") || isProfileLockError(msg)) {
+			throw new Error(
+				"Could not launch Chrome on the dedicated xcsh profile (it may already be in use); close other xcsh-launched Chrome windows and retry.",
+			);
+		}
+		throw err;
+	}
+	const pages = await browser.pages();
+	const page = pages.length ? pages[0]! : await browser.newPage();
+	return { browser, page, mode: "launched-dedicated" };
+}

package/src/browser/actions.ts

@@ -0,0 +1,126 @@
+import type { Page } from "puppeteer";
+import { commitInputValue } from "./input-commit";
+import { resolve } from "./resolver";
+
+/** Delay after a fill to let blur-triggered framework revalidation complete. */
+const SETTLE_AFTER_FILL_MS = 600;
+
+/** Resolve after `ms` milliseconds (a small, explicit settle for SPA timing). */
+function settle(ms: number): Promise<void> {
+	return new Promise(resolveSettle => setTimeout(resolveSettle, ms));
+}
+
+/** XC-SPA-aware: wait until the console's loading/spinner indicators clear. */
+export async function waitForXcSettled(page: Page, timeoutMs = 15000): Promise<void> {
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) {
+		const busy = await page
+			.evaluate((): boolean => {
+				const sel = '[aria-busy="true"], .ant-spin-spinning, [role="progressbar"], .loading-indicator';
+				const doc = (globalThis as unknown as { document: { querySelector(s: string): unknown } }).document;
+				return doc.querySelector(sel) != null;
+			})
+			.catch(() => false);
+		if (!busy) return;
+		await Bun.sleep(150);
+	}
+}
+
+async function withRetry<T>(fn: () => Promise<T>, timeoutMs = 15000): Promise<T> {
+	const start = Date.now();
+	let last: unknown;
+	while (Date.now() - start < timeoutMs) {
+		try {
+			return await fn();
+		} catch (e) {
+			last = e;
+			await Bun.sleep(150);
+		}
+	}
+	throw last instanceof Error ? last : new Error(String(last));
+}
+
+export async function click(page: Page, selector: string, context?: string): Promise<void> {
+	await waitForXcSettled(page);
+	await withRetry(async () => {
+		const h = await resolve(page, selector, context);
+		try {
+			await h.scrollIntoView().catch(() => {});
+			try {
+				await h.click();
+			} catch {
+				// sticky/offscreen elements: synthetic DOM click fallback
+				await h.evaluate(el => (el as unknown as { click(): void }).click());
+			}
+		} finally {
+			await h.dispose().catch(() => {});
+		}
+	});
+}
+
+export async function fill(page: Page, selector: string, value: string, context?: string): Promise<void> {
+	await waitForXcSettled(page);
+	await withRetry(async () => {
+		const h = await resolve(page, selector, context);
+		try {
+			await h.focus().catch(() => {});
+			// Set the value through the native value setter + framework events
+			// (input/change/blur/focusout). This replaces any existing value and is
+			// the robust path for framework-bound controls — including the console's
+			// vsui-input over ngx-datatable, whose patched value descriptor swallows
+			// plain keystrokes so they never reach the Angular model. (Use the `type`
+			// action for fields that must observe individual keystrokes.)
+			await h.evaluate(commitInputValue, value);
+		} finally {
+			await h.dispose().catch(() => {});
+		}
+	});
+	// Let the framework's blur-triggered revalidation run before the next action
+	// (Angular `updateOn: 'blur'` controls update validity asynchronously, so an
+	// immediate Save would otherwise still see the field as invalid).
+	await settle(SETTLE_AFTER_FILL_MS);
+}
+
+export async function selectOption(page: Page, selector: string, value: string, context?: string): Promise<void> {
+	await click(page, selector, context); // open the listbox/combobox
+	await click(page, `option:text('${value}')`); // pick the option by role+name
+}
+
+export async function scrollIntoView(page: Page, selector: string, context?: string): Promise<void> {
+	await waitForXcSettled(page);
+	const h = await resolve(page, selector, context);
+	try {
+		await h.scrollIntoView();
+	} finally {
+		await h.dispose().catch(() => {});
+	}
+}
+
+export async function pressKey(page: Page, key: string): Promise<void> {
+	await page.keyboard.press(key as Parameters<Page["keyboard"]["press"]>[0]);
+}
+
+export async function assertText(page: Page, selector: string, expected: string, context?: string): Promise<void> {
+	await waitForXcSettled(page);
+	const h = await resolve(page, selector, context);
+	try {
+		const txt = (await h.evaluate(el => (el as unknown as { innerText: string }).innerText)) as string;
+		if (!txt.includes(expected)) throw new Error(`assert failed: "${expected}" not in "${txt.slice(0, 200)}"`);
+	} finally {
+		await h.dispose().catch(() => {});
+	}
+}
+
+export async function waitFor(page: Page, selector: string, context?: string, timeoutMs = 30000): Promise<void> {
+	await withRetry(async () => {
+		const h = await resolve(page, selector, context);
+		await h.dispose().catch(() => {});
+	}, timeoutMs);
+}
+
+export async function screenshot(page: Page, file: string): Promise<void> {
+	if (!file.endsWith(".png") || file.includes("..") || file.includes("\0")) {
+		throw new Error(`Invalid screenshot path: ${file}`);
+	}
+	await page.screenshot({ path: file as `${string}.png`, type: "png" });
+}

package/src/browser/auth.ts

@@ -0,0 +1,176 @@
+/**
+ * Auth preflight for the F5 XC console.
+ *
+ * Pure predicates (`isLoginWall` / `isAuthenticated`) classify a document as a
+ * login wall or an authenticated console shell. They work over a minimal
+ * structural Document so they run both under linkedom in tests and against the
+ * live `document` (via page.evaluate) in the browser. `ensureAuthenticated` is
+ * the browser-bound orchestrator: on a login wall it triggers saved-password
+ * autofill + submit, then falls back to a co-drive poll until the operator logs
+ * in. It is verified at a later live gate (no unit test drives a real browser).
+ *
+ * No Puppeteer imports leak into the pure predicates; only `ensureAuthenticated`
+ * references the `Page` type.
+ */
+
+import type { Page } from "puppeteer";
+
+/** Minimal structural interface matching both linkedom and browser Document. */
+export interface AuthDocument {
+	querySelector(sel: string): unknown;
+	querySelectorAll(sel: string): ArrayLike<unknown>;
+}
+
+/**
+ * Selectors that identify a login form. The real XC login wall is a Keycloak
+ * page with `#username`, `#password`, and a `#kc-login` submit; the id/name/type
+ * alternatives keep this robust across Keycloak theme variations.
+ */
+export const LOGIN_SELECTOR = "#username, #password, input[name='username'], input[type='password']";
+
+/**
+ * Selector that identifies the authenticated console shell. The XC console
+ * decorates its chrome with `ves-`-prefixed component classes; the login wall
+ * has none (the only `ves-` strings there live in URL query params, not class
+ * attributes).
+ */
+export const CONSOLE_SHELL_SELECTOR = "[class*='ves-']";
+
+/** True when the document presents a login form (Keycloak login wall). */
+export function isLoginWall(doc: AuthDocument): boolean {
+	return doc.querySelector(LOGIN_SELECTOR) != null;
+}
+
+/**
+ * True when the document is the authenticated console shell: it carries
+ * `ves-`-classed chrome and is NOT showing a login form.
+ */
+export function isAuthenticated(doc: AuthDocument): boolean {
+	return doc.querySelector(CONSOLE_SHELL_SELECTOR) != null && !isLoginWall(doc);
+}
+
+/**
+ * Source for an injected IIFE that nudges the browser's saved-password manager
+ * to autofill the login form and then submits it.
+ *
+ * It focuses the username/password fields and dispatches synthetic input events
+ * so Chrome's credential manager offers its saved entry, then clicks the submit
+ * control (`#kc-login`) or, failing that, submits the enclosing form. Returns
+ * `true` when a form was found and a submit was attempted.
+ *
+ * Built as a string (rather than a function reference) so the caller can pass it
+ * straight to `page.evaluate`.
+ */
+export function triggerSavedPasswordExpr(): string {
+	return `(() => {
+  const username = document.querySelector("#username, input[name='username']");
+  const password = document.querySelector("#password, input[type='password']");
+  if (!username && !password) return false;
+  const nudge = (el) => {
+    if (!el) return;
+    el.focus();
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    el.dispatchEvent(new Event("change", { bubbles: true }));
+  };
+  nudge(username);
+  nudge(password);
+  const submit = document.querySelector("#kc-login, button[type='submit'], input[type='submit']");
+  if (submit) { submit.click(); return true; }
+  const form = (password || username || {}).form;
+  if (form && typeof form.requestSubmit === "function") { form.requestSubmit(); return true; }
+  if (form && typeof form.submit === "function") { form.submit(); return true; }
+  return false;
+})()`;
+}
+
+export interface EnsureAuthenticatedOptions {
+	/** Co-drive poll interval in ms (default 1000). */
+	pollIntervalMs?: number;
+	/** Total time to wait for the operator to complete login in ms (default 300000 = 5 min). */
+	timeoutMs?: number;
+	/** Optional callback invoked once when login is required, so callers can surface a co-drive prompt. */
+	onLoginRequired?: () => void;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+function sleep(ms: number): Promise<void> {
+	return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Compute the auth state against the live document inside the page.
+ *
+ * Self-contained: the selectors are passed as `page.evaluate` ARGS so nothing
+ * relies on closure or sibling-function scope (those identifiers do not exist in
+ * the page realm). Mirrors the pure `isLoginWall` / `isAuthenticated` predicates,
+ * which remain the documented logic over the same two selector consts.
+ */
+async function evalAuthState(page: Page): Promise<{ loginWall: boolean; authed: boolean }> {
+	return page.evaluate(
+		(loginSel, shellSel) => {
+			const doc = (globalThis as unknown as { document: { querySelector(s: string): unknown } }).document;
+			const loginWall = doc.querySelector(loginSel) != null;
+			const authed = doc.querySelector(shellSel) != null && !loginWall;
+			return { loginWall, authed };
+		},
+		LOGIN_SELECTOR,
+		CONSOLE_SHELL_SELECTOR,
+	);
+}
+
+/**
+ * Ensure the console at `consoleUrl` is authenticated.
+ *
+ * 1. Navigate to `consoleUrl`.
+ * 2. If already authenticated, return immediately.
+ * 3. If on a login wall, trigger saved-password autofill + submit once.
+ * 4. Poll until authenticated (operator co-drive) or the timeout elapses.
+ *
+ * Throws if the timeout elapses before authentication succeeds.
+ */
+export async function ensureAuthenticated(
+	page: Page,
+	consoleUrl: string,
+	opts: EnsureAuthenticatedOptions = {},
+): Promise<void> {
+	const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+	await page.goto(consoleUrl, { waitUntil: "domcontentloaded" });
+
+	{
+		const { authed } = await evalAuthState(page);
+		if (authed) return;
+	}
+
+	let nudged = false;
+	let loginAnnounced = false;
+	const deadline = Date.now() + timeoutMs;
+
+	while (Date.now() < deadline) {
+		const { loginWall, authed } = await evalAuthState(page);
+		if (authed) return;
+
+		if (loginWall) {
+			if (!loginAnnounced) {
+				opts.onLoginRequired?.();
+				loginAnnounced = true;
+			}
+			if (!nudged) {
+				// Try saved-password autofill + submit exactly once; subsequent
+				// passes fall through to co-drive polling so we don't fight the
+				// operator if autofill failed or no credential was saved.
+				await page.evaluate(triggerSavedPasswordExpr());
+				nudged = true;
+			}
+		}
+
+		await sleep(pollIntervalMs);
+	}
+
+	throw new Error(
+		`Timed out after ${timeoutMs}ms waiting for authentication at ${consoleUrl}; the console is still showing a login wall.`,
+	);
+}