pi-agent-browser-native 0.2.47 → 0.2.49

package/dist/extensions/agent-browser/lib/orchestration/electron-host/index.js

@@ -0,0 +1,718 @@
+/**
+ * Purpose: Own wrapper-side Electron host orchestration for agent_browser structured electron input.
+ * Responsibilities: Discover Electron apps, inspect/probe/cleanup wrapper-tracked Electron launches, and build Pi-facing Electron host results.
+ * Scope: Electron host actions that do not spawn the main upstream browser command; generic agent_browser execution stays in browser-run.
+ */
+import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
+import { discoverElectronApps } from "../../electron/discovery.js";
+import { boundElectronProbeString } from "../../electron/text.js";
+import { isRecord } from "../../parsing.js";
+import { buildAgentBrowserNextActions, buildAgentBrowserResultCategoryDetails } from "../../results.js";
+import { appendUniqueAgentBrowserNextActions } from "../../results/next-actions.js";
+import { extractRefSnapshotFromData, isAboutBlankUrl, normalizeSessionTabTarget } from "../../session-page-state.js";
+import { redactSensitiveText } from "../../runtime.js";
+import { collectElectronManagedSessionTarget } from "../browser-run/diagnostics.js";
+import { buildElectronHostFailureResult, formatElectronTargetLines, redactToolDetails } from "../browser-run/final-result.js";
+import { buildElectronIdentifiers, buildElectronMismatchNextActions, buildElectronSessionMismatch, closeManagedSession, extractStringResultField, findElectronLaunchRecordForSession, formatElectronSessionMismatchText, getActiveElectronRecords, getLiveElectronRendererTargets, runSessionCommandData, } from "../browser-run/session-state.js";
+const ELECTRON_PROFILE_ISOLATION_NOTE = "Profile note: electron.launch starts an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app.";
+const ELECTRON_EXISTING_AUTH_GUIDANCE = "For already-authenticated desktop app content, do not stop here: if host tools are allowed and the app is not running, launch the normal app with --remote-debugging-port=<port>, verify the port, then run agent_browser connect <port>; if it is already running without a debug port, ask before relaunching it.";
+export const ELECTRON_PROFILE_ISOLATION_DETAILS = {
+    attachesToAlreadyRunningApp: false,
+    existingAuthenticatedAppGuidance: ELECTRON_EXISTING_AUTH_GUIDANCE,
+    hostDebugLaunchExample: "macOS: open -a <App Name> --args --remote-debugging-port=9222 --remote-allow-origins='*'; then agent_browser connect 9222 with sessionMode=fresh",
+    isolatedLaunch: true,
+    note: ELECTRON_PROFILE_ISOLATION_NOTE,
+    reusesExistingSignedInProfile: false,
+};
+export const ELECTRON_POST_COMMAND_STATUS_SETTLE_MS = 250;
+const ELECTRON_PROBE_MAX_TABS = 6;
+const ELECTRON_PROBE_MAX_REF_IDS = 20;
+const ELECTRON_PROBE_MAX_SNAPSHOT_LINES = 12;
+const ELECTRON_PROBE_MAX_SNAPSHOT_CHARS = 1_600;
+function formatElectronListVisibleText(result) {
+    const visibleApps = result.apps.slice(0, 10);
+    const visibleOmittedCount = Math.max(0, result.apps.length - visibleApps.length);
+    const header = result.omittedCount > 0
+        ? `Electron apps (${result.apps.length} shown, ${result.omittedCount} omitted):`
+        : `Electron apps (${result.apps.length} found):`;
+    const lines = [header];
+    if (visibleApps.length === 0) {
+        lines.push(result.query ? `No Electron apps matched query "${result.query}".` : "No Electron apps found in the supported scan locations.");
+    }
+    else {
+        for (const app of visibleApps) {
+            const identifier = app.bundleId ?? app.desktopId;
+            const path = app.appPath ?? app.executablePath;
+            const sensitivity = app.sensitivity ? ` [likely sensitive: ${app.sensitivity.categories.join(", ")}]` : "";
+            lines.push(`- ${app.name}${identifier ? ` (${identifier})` : ""}${sensitivity} — ${path}`);
+        }
+    }
+    if (visibleOmittedCount > 0) {
+        lines.push(`${visibleOmittedCount} additional app(s) omitted from visible output; see details.electron.apps.`);
+    }
+    if (result.omittedCount > 0) {
+        lines.push(`${result.omittedCount} app(s) omitted by maxResults=${result.maxResults}.`);
+    }
+    if (result.apps.some((app) => app.sensitivity?.level === "likely-sensitive")) {
+        lines.push("Review likely-sensitive apps and use caller-owned allow/deny policy before launch.");
+        lines.push(ELECTRON_PROFILE_ISOLATION_NOTE);
+        lines.push(ELECTRON_EXISTING_AUTH_GUIDANCE);
+    }
+    return lines.join("\n");
+}
+function buildElectronListSuccessResult(compiledElectron, discovery) {
+    const text = redactSensitiveText(formatElectronListVisibleText(discovery));
+    const sensitiveAppCount = discovery.apps.filter((app) => app.sensitivity?.level === "likely-sensitive").length;
+    const details = {
+        args: [],
+        compiledElectron,
+        electron: {
+            action: "list",
+            apps: discovery.apps,
+            maxResults: discovery.maxResults,
+            omittedCount: discovery.omittedCount || undefined,
+            platform: discovery.platform,
+            profileIsolation: ELECTRON_PROFILE_ISOLATION_DETAILS,
+            query: discovery.query,
+            sensitiveAppCount: sensitiveAppCount || undefined,
+            skippedCount: discovery.skippedCount,
+            status: "succeeded",
+        },
+        ...buildAgentBrowserResultCategoryDetails({ args: [], succeeded: true }),
+        summary: discovery.omittedCount > 0
+            ? `Electron app discovery found ${discovery.apps.length} app(s) and omitted ${discovery.omittedCount}.`
+            : `Electron app discovery found ${discovery.apps.length} app(s).`,
+    };
+    return {
+        content: [{ type: "text", text }],
+        details: redactToolDetails(details, []),
+        isError: false,
+    };
+}
+function buildElectronListFailureResult(compiledElectron, error) {
+    const errorText = error instanceof Error ? error.message : String(error);
+    const text = redactSensitiveText(`Electron app discovery failed: ${errorText}`);
+    const details = {
+        args: [],
+        compiledElectron,
+        electron: {
+            action: "list",
+            error: errorText,
+            status: "failed",
+        },
+        ...buildAgentBrowserResultCategoryDetails({ args: [], errorText, succeeded: false }),
+        summary: "Electron app discovery failed.",
+    };
+    return {
+        content: [{ type: "text", text }],
+        details: redactToolDetails(details, []),
+        isError: true,
+    };
+}
+function isElectronLaunchRecord(value) {
+    if (!isRecord(value))
+        return false;
+    return value.version === 1 &&
+        value.launchedByWrapper === true &&
+        typeof value.launchId === "string" &&
+        typeof value.appName === "string" &&
+        typeof value.executablePath === "string" &&
+        typeof value.userDataDir === "string" &&
+        typeof value.port === "number" &&
+        typeof value.createdAtMs === "number";
+}
+export function restoreElectronLaunchRecordsFromBranch(branch) {
+    const records = new Map();
+    for (const entry of branch) {
+        if (!isRecord(entry) || entry.type !== "message")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        if (!message || message.toolName !== "agent_browser")
+            continue;
+        const details = isRecord(message.details) ? message.details : undefined;
+        const electron = isRecord(details?.electron) ? details.electron : undefined;
+        if (!electron)
+            continue;
+        const launch = isElectronLaunchRecord(electron.launch) ? electron.launch : undefined;
+        if (launch)
+            records.set(launch.launchId, launch);
+        const cleanupRecords = isRecord(electron.cleanup) && Array.isArray(electron.cleanup.records) ? electron.cleanup.records : [];
+        for (const cleanupRecord of cleanupRecords) {
+            if (isElectronLaunchRecord(cleanupRecord))
+                records.set(cleanupRecord.launchId, cleanupRecord);
+        }
+    }
+    return records;
+}
+function selectElectronRecords(compiledElectron, records) {
+    if (compiledElectron.launchId) {
+        const record = records.get(compiledElectron.launchId);
+        return record ? { records: [record] } : { error: `No wrapper-tracked Electron launch found for launchId ${compiledElectron.launchId}.` };
+    }
+    if (compiledElectron.all)
+        return { records: getActiveElectronRecords(records) };
+    const activeRecords = getActiveElectronRecords(records);
+    if (activeRecords.length === 0)
+        return { records: [] };
+    if (activeRecords.length > 1)
+        return { error: "Multiple wrapper-tracked Electron launches are active; pass electron.launchId or electron.all." };
+    return { records: activeRecords };
+}
+function extractTargetsFromStatus(statuses) {
+    return statuses.flatMap((status) => status.targets);
+}
+function formatElectronStatusVisibleText(statuses, records, mismatches = [], managedSessions = []) {
+    if (statuses.length === 0)
+        return "Electron status: no active wrapper-tracked launches.";
+    const recordsByLaunchId = new Map(records.map((record) => [record.launchId, record]));
+    const managedSessionsByName = new Map(managedSessions.map((managedSession) => [managedSession.sessionName, managedSession]));
+    const lines = [`Electron status: ${statuses.length} wrapper-tracked launch(es).`];
+    for (const status of statuses) {
+        const record = recordsByLaunchId.get(status.launchId);
+        const sessionName = record?.sessionName;
+        const appName = record?.appName ?? "Electron launch";
+        const sessionText = sessionName ? `, sessionName ${sessionName}` : "";
+        lines.push(`- ${status.launchId}: ${appName}${sessionText}; ${status.portAlive ? "debug port alive" : "debug port dead"}${status.pidAlive === undefined ? "" : status.pidAlive ? ", pid alive" : ", pid dead"} (port ${status.port})`);
+        lines.push(`  Identifiers: launchId ${status.launchId}; sessionName ${sessionName ?? "not attached"}.`);
+        for (const targetLine of formatElectronTargetLines(status.targets, 4))
+            lines.push(`  ${targetLine}`);
+        const managedSession = sessionName ? managedSessionsByName.get(sessionName) : undefined;
+        if (managedSession?.error)
+            lines.push(`  Managed session warning: ${managedSession.error}`);
+    }
+    for (const mismatch of mismatches)
+        lines.push("", formatElectronSessionMismatchText(mismatch));
+    return lines.join("\n");
+}
+function buildElectronStatusResult(options) {
+    const baseNextActions = options.records.flatMap((record) => buildAgentBrowserNextActions({
+        electron: { launchId: record.launchId, sessionName: record.sessionName, status: record.cleanupState },
+        resultCategory: "success",
+        successCategory: "completed",
+    }) ?? []);
+    const mismatchNextActions = (options.mismatches ?? []).flatMap((mismatch) => {
+        const record = options.records.find((candidate) => candidate.launchId === mismatch.launchId);
+        return record ? buildElectronMismatchNextActions(record, mismatch.liveTarget) : [];
+    });
+    const nextActions = options.mismatches?.length
+        ? appendUniqueAgentBrowserNextActions([...mismatchNextActions], baseNextActions)
+        : appendUniqueAgentBrowserNextActions([...baseNextActions], mismatchNextActions);
+    const details = {
+        args: [],
+        compiledElectron: options.compiledElectron,
+        electron: {
+            action: "status",
+            identifierList: options.records.length > 1 ? options.records.map(buildElectronIdentifiers) : undefined,
+            identifiers: options.records.length === 1 && options.records[0] ? buildElectronIdentifiers(options.records[0]) : undefined,
+            launches: options.records,
+            managedSession: options.managedSessions?.length === 1 ? options.managedSessions[0] : undefined,
+            managedSessions: options.managedSessions && options.managedSessions.length > 0 ? options.managedSessions : undefined,
+            sessionMismatch: options.mismatches?.length === 1 ? options.mismatches[0] : undefined,
+            sessionMismatches: options.mismatches && options.mismatches.length > 1 ? options.mismatches : undefined,
+            status: "succeeded",
+            statuses: options.statuses,
+            targets: extractTargetsFromStatus(options.statuses),
+        },
+        nextActions: nextActions.length > 0 ? nextActions : undefined,
+        ...buildAgentBrowserResultCategoryDetails({ args: [], succeeded: true }),
+        summary: options.statuses.length === 0 ? "Electron status found no active wrapper-tracked launches." : `Electron status inspected ${options.statuses.length} launch(es).`,
+    };
+    return { content: [{ type: "text", text: redactSensitiveText(formatElectronStatusVisibleText(options.statuses, options.records, options.mismatches, options.managedSessions)) }], details: redactToolDetails(details, []), isError: false };
+}
+function formatElectronCleanupVisibleText(results) {
+    if (results.length === 0)
+        return "Electron cleanup: no active wrapper-tracked launches.";
+    const lines = [`Electron cleanup: ${results.filter((result) => !result.partial).length}/${results.length} launch(es) fully cleaned.`];
+    for (const result of results) {
+        lines.push(`- ${result.summary}`);
+        for (const step of result.steps)
+            lines.push(`  - ${step.resource}: ${step.state}${step.error ? ` (${step.error})` : ""}`);
+    }
+    return lines.join("\n");
+}
+function buildElectronCleanupResult(compiledElectron, cleanupResults) {
+    const partial = cleanupResults.some((result) => result.partial);
+    const records = cleanupResults.map((result) => result.record);
+    const nextActions = cleanupResults.flatMap((result) => buildAgentBrowserNextActions({
+        electron: { launchId: result.launchId, sessionName: result.record.sessionName, status: result.record.cleanupState },
+        failureCategory: partial ? "cleanup-failed" : undefined,
+        resultCategory: partial ? "failure" : "success",
+        successCategory: partial ? undefined : "completed",
+    }) ?? []);
+    const errorText = partial ? cleanupResults.map((result) => result.summary).join("\n") : undefined;
+    const details = {
+        args: [],
+        compiledElectron,
+        electron: {
+            action: "cleanup",
+            cleanup: { partial, records, results: cleanupResults },
+            status: partial ? "partial" : "succeeded",
+        },
+        nextActions: nextActions.length > 0 ? nextActions : undefined,
+        ...buildAgentBrowserResultCategoryDetails({ args: [], errorText, failureCategory: partial ? "cleanup-failed" : undefined, succeeded: !partial }),
+        summary: partial ? "Electron cleanup was partial." : "Electron cleanup completed.",
+    };
+    return { content: [{ type: "text", text: redactSensitiveText(formatElectronCleanupVisibleText(cleanupResults)) }], details: redactToolDetails(details, []), isError: partial };
+}
+const ELECTRON_FOCUSED_ELEMENT_EVAL = `(() => {
+	const clean = (value, max = 80) => {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.replace(/\\s+/g, " ").trim();
+	if (!normalized) return undefined;
+	return normalized.length > max ? normalized.slice(0, max - 3) + "..." : normalized;
+	};
+	const describeElement = (element) => {
+	if (!element || !(element instanceof Element)) return undefined;
+	const tagName = element.tagName.toLowerCase();
+	const inputLike = element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement;
+	const contentEditable = element instanceof HTMLElement && element.isContentEditable;
+	const containerLike = tagName === "body" || tagName === "html";
+	const rawText = element.textContent || "";
+	const exposeText = !inputLike && !contentEditable && !containerLike;
+	const text = exposeText ? clean(rawText) : undefined;
+	return {
+		tagName: clean(tagName, 40),
+		role: clean(element.getAttribute("role") || "", 60),
+		name: clean(element.getAttribute("aria-label") || element.getAttribute("title") || text || "", 80),
+		id: clean(element.id || "", 80),
+		type: clean(element.getAttribute("type") || "", 40),
+		placeholder: clean(element.getAttribute("placeholder") || "", 80),
+		ariaLabel: clean(element.getAttribute("aria-label") || "", 80),
+		title: clean(element.getAttribute("title") || "", 80),
+		textLength: !exposeText && rawText ? rawText.length : undefined,
+		textPreview: text,
+		valueLength: inputLike && typeof element.value === "string" ? element.value.length : undefined,
+		isContentEditable: contentEditable || undefined,
+	};
+	};
+	return { focusedElement: describeElement(document.activeElement) };
+})()`;
+function getTrimmedString(value) {
+    return typeof value === "string" ? boundElectronProbeString(value) : undefined;
+}
+function getOptionalBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function getOptionalNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function extractElectronFocusedElement(data) {
+    const payload = isRecord(data) && isRecord(data.result) ? data.result : data;
+    const rawFocusedElement = isRecord(payload) && isRecord(payload.focusedElement) ? payload.focusedElement : isRecord(payload) ? payload : undefined;
+    if (!rawFocusedElement)
+        return undefined;
+    const focusedElement = {
+        ariaLabel: getTrimmedString(rawFocusedElement.ariaLabel),
+        id: getTrimmedString(rawFocusedElement.id),
+        isContentEditable: getOptionalBoolean(rawFocusedElement.isContentEditable),
+        name: getTrimmedString(rawFocusedElement.name),
+        placeholder: getTrimmedString(rawFocusedElement.placeholder),
+        role: getTrimmedString(rawFocusedElement.role),
+        tagName: getTrimmedString(rawFocusedElement.tagName),
+        textLength: getOptionalNumber(rawFocusedElement.textLength),
+        textPreview: getTrimmedString(rawFocusedElement.textPreview),
+        title: getTrimmedString(rawFocusedElement.title),
+        type: getTrimmedString(rawFocusedElement.type),
+        valueLength: getOptionalNumber(rawFocusedElement.valueLength),
+    };
+    return Object.values(focusedElement).some((value) => value !== undefined) ? focusedElement : undefined;
+}
+function extractElectronProbeTabs(data) {
+    const rawTabs = isRecord(data) && Array.isArray(data.tabs) ? data.tabs : Array.isArray(data) ? data : [];
+    const allTabs = rawTabs.filter(isRecord).map((tab, index) => ({
+        active: getOptionalBoolean(tab.active),
+        index: typeof tab.index === "number" && Number.isInteger(tab.index) ? tab.index : index,
+        tabId: getTrimmedString(tab.tabId) ?? getTrimmedString(tab.id),
+        title: getTrimmedString(tab.title) ?? getTrimmedString(tab.label),
+        type: getTrimmedString(tab.type),
+        url: getTrimmedString(tab.url),
+    }));
+    if (allTabs.length === 0)
+        return {};
+    const shown = allTabs.slice(0, ELECTRON_PROBE_MAX_TABS);
+    return {
+        activeTab: allTabs.find((tab) => tab.active) ?? allTabs[0],
+        tabs: {
+            omittedCount: allTabs.length > shown.length ? allTabs.length - shown.length : undefined,
+            shown,
+            total: allTabs.length,
+        },
+    };
+}
+function truncateElectronProbeSnapshotText(snapshotText) {
+    if (!snapshotText)
+        return { lineCount: 0 };
+    const lines = snapshotText.split(/\r?\n/);
+    const shownLines = [];
+    let usedChars = 0;
+    for (const line of lines) {
+        if (shownLines.length >= ELECTRON_PROBE_MAX_SNAPSHOT_LINES)
+            break;
+        const nextLength = usedChars + line.length + (shownLines.length > 0 ? 1 : 0);
+        if (nextLength > ELECTRON_PROBE_MAX_SNAPSHOT_CHARS) {
+            if (shownLines.length === 0)
+                shownLines.push(`${line.slice(0, ELECTRON_PROBE_MAX_SNAPSHOT_CHARS - 3)}...`);
+            break;
+        }
+        shownLines.push(line);
+        usedChars = nextLength;
+    }
+    return {
+        lineCount: lines.length,
+        omittedLineCount: lines.length > shownLines.length ? lines.length - shownLines.length : undefined,
+        text: shownLines.length > 0 ? shownLines.join("\n") : undefined,
+    };
+}
+function summarizeElectronProbeSnapshot(data) {
+    const refSnapshot = extractRefSnapshotFromData(data);
+    const rawSnapshotText = isRecord(data) ? getTrimmedString(data.snapshot) : undefined;
+    const truncatedText = truncateElectronProbeSnapshotText(rawSnapshotText);
+    const refIds = refSnapshot?.refIds ?? [];
+    const shownRefIds = refIds.slice(0, ELECTRON_PROBE_MAX_REF_IDS);
+    const snapshot = refSnapshot || truncatedText.text
+        ? {
+            lineCount: truncatedText.lineCount,
+            omittedLineCount: truncatedText.omittedLineCount,
+            omittedRefCount: refIds.length > shownRefIds.length ? refIds.length - shownRefIds.length : undefined,
+            refCount: refIds.length,
+            refIds: shownRefIds,
+            text: truncatedText.text,
+        }
+        : undefined;
+    return { refSnapshot, snapshot };
+}
+function getElectronProbeSummary(probe) {
+    const parts = [
+        probe.title ? `title "${probe.title}"` : undefined,
+        probe.url ? `url ${probe.url}` : undefined,
+        probe.focusedElement ? "focused element" : undefined,
+        probe.tabs ? `${probe.tabs.total} tab(s)` : undefined,
+        probe.snapshot ? `${probe.snapshot.refCount} ref(s)` : undefined,
+    ].filter((item) => item !== undefined);
+    return parts.length > 0 ? `Electron probe collected ${parts.join(", ")}.` : "Electron probe did not return current session state.";
+}
+async function runElectronProbeCommandData(options) {
+    try {
+        return { data: await runSessionCommandData(options) };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function collectElectronProbe(options) {
+    const titleResult = await runElectronProbeCommandData({ args: ["get", "title"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs });
+    const urlResult = await runElectronProbeCommandData({ args: ["get", "url"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs });
+    const focusedResult = await runElectronProbeCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, stdin: ELECTRON_FOCUSED_ELEMENT_EVAL, timeoutMs: options.timeoutMs });
+    const tabsResult = await runElectronProbeCommandData({ args: ["tab", "list"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs });
+    const snapshotResult = await runElectronProbeCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs });
+    const errors = [
+        titleResult.error ? `get title: ${titleResult.error}` : undefined,
+        urlResult.error ? `get url: ${urlResult.error}` : undefined,
+        focusedResult.error ? `focused element: ${focusedResult.error}` : undefined,
+        tabsResult.error ? `tab list: ${tabsResult.error}` : undefined,
+        snapshotResult.error ? `snapshot: ${snapshotResult.error}` : undefined,
+    ].filter((item) => item !== undefined).map((error) => boundElectronProbeString(error, 240) ?? "probe command failed");
+    const title = boundElectronProbeString(extractStringResultField(titleResult.data, "result") ?? extractStringResultField(titleResult.data, "title"), 160);
+    const url = boundElectronProbeString(extractStringResultField(urlResult.data, "result") ?? extractStringResultField(urlResult.data, "url"), 300);
+    const focusedElement = extractElectronFocusedElement(focusedResult.data);
+    const { activeTab, tabs } = extractElectronProbeTabs(tabsResult.data);
+    const { refSnapshot, snapshot } = summarizeElectronProbeSnapshot(snapshotResult.data);
+    const probeWithoutSummary = {
+        activeTab,
+        focusedElement,
+        errors: errors.length > 0 ? errors : undefined,
+        refSnapshot,
+        sessionName: options.sessionName,
+        snapshot,
+        status: errors.length === 0 && (title || url || focusedElement || tabs || snapshot) ? "succeeded" : "partial",
+        tabs,
+        title,
+        url,
+    };
+    return { ...probeWithoutSummary, summary: getElectronProbeSummary(probeWithoutSummary) };
+}
+function formatElectronProbeFocusedElement(focusedElement) {
+    if (!focusedElement)
+        return undefined;
+    const label = focusedElement.name ?? focusedElement.textPreview ?? focusedElement.placeholder ?? focusedElement.ariaLabel ?? focusedElement.title;
+    const descriptor = [focusedElement.role, focusedElement.tagName].filter(Boolean).join("/") || "element";
+    const suffix = [
+        focusedElement.id ? `#${focusedElement.id}` : undefined,
+        focusedElement.type ? `type=${focusedElement.type}` : undefined,
+        focusedElement.valueLength !== undefined ? `valueLength=${focusedElement.valueLength}` : undefined,
+        focusedElement.textLength !== undefined ? `textLength=${focusedElement.textLength}` : undefined,
+    ].filter((item) => item !== undefined).join(", ");
+    return `Focused: ${descriptor}${label ? ` "${label}"` : ""}${suffix ? ` (${suffix})` : ""}`;
+}
+function formatElectronProbeContextText(context) {
+    if (context.mode === "launchId") {
+        return `Probe context: wrapper launch ${context.launchId} session ${context.sessionName}.`;
+    }
+    if (context.note) {
+        return `Probe context: current managed session ${context.sessionName}; ${context.note}`;
+    }
+    if (context.launchId) {
+        return `Probe context: current managed session ${context.sessionName} maps to Electron launch ${context.launchId}.`;
+    }
+    return `Probe context: current managed session ${context.sessionName} only; pass electron.probe.launchId to compare wrapper-tracked launch status.`;
+}
+function formatElectronProbeLaunchStatusText(status, probe) {
+    if (!status)
+        return undefined;
+    const lines = [`Launch status: ${status.portAlive ? "debug port alive" : "debug port dead"}${status.pidAlive === undefined ? "" : status.pidAlive ? ", pid alive" : ", pid dead"}; ${status.targets.length} CDP target(s).`];
+    if (isAboutBlankUrl(probe.url) && (!status.portAlive || status.pidAlive === false || getLiveElectronRendererTargets(status.targets).length === 0)) {
+        lines.push("Electron lifecycle warning: the browser session is on about:blank and the wrapper launch has no live renderer target to reattach. Run electron.status, cleanup if dead, or relaunch the app.");
+    }
+    return lines.join("\n");
+}
+function formatElectronProbeVisibleText(options) {
+    const { context, mismatch, probe, status } = options;
+    const page = [probe.title, probe.url].filter(Boolean).join(" — ");
+    const lines = [`Electron probe: ${page || probe.sessionName}`];
+    if (context)
+        lines.push(formatElectronProbeContextText(context));
+    const launchStatusText = formatElectronProbeLaunchStatusText(status, probe);
+    if (launchStatusText)
+        lines.push(launchStatusText);
+    if (mismatch)
+        lines.push(formatElectronSessionMismatchText(mismatch));
+    const focusedLine = formatElectronProbeFocusedElement(probe.focusedElement);
+    if (focusedLine)
+        lines.push(focusedLine);
+    if (probe.tabs) {
+        const active = probe.activeTab;
+        lines.push(`Tabs: ${probe.tabs.total} total${probe.tabs.omittedCount ? ` (${probe.tabs.omittedCount} omitted)` : ""}${active ? `; active ${active.index ?? "?"}: ${[active.title, active.url].filter(Boolean).join(" — ") || active.tabId || "tab"}` : ""}`);
+    }
+    if (probe.snapshot) {
+        lines.push(`Snapshot: ${probe.snapshot.refCount} interactive ref(s)${probe.snapshot.omittedRefCount ? ` (${probe.snapshot.omittedRefCount} ref id(s) omitted)` : ""}.`);
+        if (probe.snapshot.text)
+            lines.push(probe.snapshot.text);
+        if (probe.snapshot.omittedLineCount)
+            lines.push(`... ${probe.snapshot.omittedLineCount} snapshot line(s) omitted`);
+    }
+    if (probe.status === "partial")
+        lines.push("Some probe commands did not return data; use raw agent_browser commands for deeper diagnostics.");
+    if (probe.errors && probe.errors.length > 0)
+        lines.push(`Probe warning: ${probe.errors.slice(0, 2).join("; ")}${probe.errors.length > 2 ? "; ..." : ""}`);
+    return lines.join("\n");
+}
+function buildElectronProbeResult(options) {
+    const { refSnapshot: _refSnapshot, ...boundedProbe } = options.probe;
+    const baseNextActions = options.record ? buildAgentBrowserNextActions({
+        electron: { launchId: options.record.launchId, sessionName: options.record.sessionName, status: options.record.cleanupState },
+        resultCategory: "success",
+        successCategory: "completed",
+    }) ?? [] : [];
+    const mismatchNextActions = options.mismatch && options.record ? buildElectronMismatchNextActions(options.record, options.mismatch.liveTarget) : [];
+    const nextActions = options.mismatch
+        ? appendUniqueAgentBrowserNextActions([...mismatchNextActions], baseNextActions)
+        : appendUniqueAgentBrowserNextActions([...baseNextActions], mismatchNextActions);
+    const details = {
+        args: [],
+        compiledElectron: options.compiledElectron,
+        electron: {
+            action: "probe",
+            identifiers: options.record ? buildElectronIdentifiers(options.record) : undefined,
+            probe: boundedProbe,
+            probeContext: options.probeContext,
+            sessionMismatch: options.mismatch,
+            status: options.probe.status,
+            statusTargets: options.status?.targets,
+            launchStatus: options.status,
+        },
+        nextActions: nextActions.length > 0 ? nextActions : undefined,
+        ...buildAgentBrowserResultCategoryDetails({ args: [], succeeded: true }),
+        sessionName: options.probe.sessionName,
+        sessionTabTarget: options.sessionTabTarget,
+        summary: options.mismatch?.summary ?? options.probe.summary,
+        usedImplicitSession: options.probeContext.mode === "current-managed-session",
+    };
+    return {
+        content: [{ type: "text", text: redactSensitiveText(formatElectronProbeVisibleText({ context: options.probeContext, mismatch: options.mismatch, probe: options.probe, status: options.status })) }],
+        details: redactToolDetails(details, []),
+        isError: false,
+    };
+}
+export async function cleanupTrackedElectronHostLaunches(options) {
+    const results = [];
+    for (const record of options.records) {
+        const managedSessionCloseError = record.sessionName
+            ? await closeManagedSession({ cwd: options.cwd, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
+            : undefined;
+        const managedSessionStep = record.sessionName
+            ? managedSessionCloseError
+                ? { error: managedSessionCloseError, resource: "managed-session", sessionName: record.sessionName, state: "failed" }
+                : { resource: "managed-session", sessionName: record.sessionName, state: "removed" }
+            : undefined;
+        const cleanupResult = await cleanupElectronLaunchResources({
+            child: options.electronChildProcesses.get(record.launchId),
+            record,
+            timeoutMs: options.timeoutMs,
+        });
+        const cleanupRecord = record.sessionName && !managedSessionCloseError
+            ? { ...cleanupResult.record, sessionName: undefined }
+            : cleanupResult.record;
+        const result = managedSessionCloseError
+            ? {
+                ...cleanupResult,
+                partial: true,
+                record: { ...cleanupResult.record, cleanupState: "partial" },
+                remainingResources: [...new Set(["managed-session", ...cleanupResult.remainingResources])],
+                steps: [managedSessionStep, ...cleanupResult.steps].filter((step) => step !== undefined),
+                summary: `Electron cleanup for ${record.launchId} is partial; managed session close failed.`,
+            }
+            : {
+                ...cleanupResult,
+                record: cleanupRecord,
+                steps: [managedSessionStep, ...cleanupResult.steps].filter((step) => step !== undefined),
+            };
+        results.push(result);
+        options.electronLaunchRecords.set(record.launchId, result.record);
+        if (!result.partial)
+            options.electronChildProcesses.delete(record.launchId);
+    }
+    return results;
+}
+export async function cleanupActiveElectronHostLaunches(options) {
+    const activeRecords = getActiveElectronRecords(options.electronLaunchRecords);
+    return activeRecords.length > 0
+        ? cleanupTrackedElectronHostLaunches({ ...options, records: activeRecords })
+        : [];
+}
+export async function handleElectronHostInput(options) {
+    const { compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, redactedCompiledElectron, sessionPageState, signal, } = options;
+    if (compiledElectron?.action === "list") {
+        try {
+            const discovery = await discoverElectronApps({ maxResults: compiledElectron.maxResults, query: compiledElectron.query });
+            return buildElectronListSuccessResult(redactedCompiledElectron ?? compiledElectron, discovery);
+        }
+        catch (error) {
+            return buildElectronListFailureResult(redactedCompiledElectron ?? compiledElectron, error);
+        }
+    }
+    if (compiledElectron?.action === "status") {
+        const selection = selectElectronRecords(compiledElectron, electronLaunchRecords);
+        if (selection.error)
+            return buildElectronHostFailureResult({ compiledElectron: redactedCompiledElectron ?? compiledElectron, errorText: selection.error, failureCategory: "validation-error" });
+        const records = selection.records ?? [];
+        const statuses = await Promise.all(records.map((record) => inspectElectronLaunchStatus(record)));
+        const managedSessions = (await Promise.all(records.map((record) => collectElectronManagedSessionTarget({
+            cwd,
+            sessionName: record.sessionName,
+            signal,
+            timeoutMs: compiledElectron.timeoutMs,
+        })))).filter((managedSession) => managedSession !== undefined);
+        const mismatches = managedSessions
+            .map((managedSession) => {
+            const record = records.find((candidate) => candidate.sessionName === managedSession.sessionName);
+            const status = record ? statuses.find((candidate) => candidate.launchId === record.launchId) : undefined;
+            return record && status ? buildElectronSessionMismatch({ managedSession, record, statusTargets: status.targets }) : undefined;
+        })
+            .filter((mismatch) => mismatch !== undefined);
+        return buildElectronStatusResult({
+            compiledElectron: redactedCompiledElectron ?? compiledElectron,
+            managedSessions,
+            mismatches,
+            records,
+            statuses,
+        });
+    }
+    if (compiledElectron?.action === "probe") {
+        const launchRecord = compiledElectron.launchId
+            ? electronLaunchRecords.get(compiledElectron.launchId)
+            : findElectronLaunchRecordForSession(managedSessionName, electronLaunchRecords);
+        if (compiledElectron.launchId && !launchRecord) {
+            return buildElectronHostFailureResult({
+                compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                errorText: `No wrapper-tracked Electron launch found for launchId ${compiledElectron.launchId}.`,
+                failureCategory: "validation-error",
+            });
+        }
+        if (compiledElectron.launchId && !launchRecord?.sessionName) {
+            return buildElectronHostFailureResult({
+                compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                errorText: `electron.probe launchId ${compiledElectron.launchId} has no attached managed sessionName; reattach with connect or run electron.launch again.`,
+                failureCategory: "validation-error",
+            });
+        }
+        if (!compiledElectron.launchId && !managedSessionActive) {
+            return buildElectronHostFailureResult({
+                compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                errorText: "electron.probe requires an active attached session. Run electron.launch or connect to an Electron debug port first.",
+                failureCategory: "validation-error",
+            });
+        }
+        const probeSessionName = compiledElectron.launchId ? launchRecord?.sessionName : managedSessionName;
+        if (!probeSessionName) {
+            return buildElectronHostFailureResult({
+                compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                errorText: "electron.probe could not resolve a managed session to inspect.",
+                failureCategory: "validation-error",
+            });
+        }
+        try {
+            const status = launchRecord ? await inspectElectronLaunchStatus(launchRecord) : undefined;
+            const probe = await collectElectronProbe({ cwd, sessionName: probeSessionName, signal, timeoutMs: compiledElectron.timeoutMs });
+            const managedSession = {
+                sessionName: probe.sessionName,
+                title: probe.title ?? probe.activeTab?.title,
+                url: probe.url ?? probe.activeTab?.url,
+            };
+            const sessionMismatch = launchRecord && status
+                ? buildElectronSessionMismatch({ managedSession, record: launchRecord, statusTargets: status.targets })
+                : undefined;
+            const probeContextNote = !launchRecord
+                ? "No wrapper-tracked Electron launch matched this current managed session."
+                : !compiledElectron.launchId && launchRecord.sessionName && launchRecord.sessionName !== probe.sessionName
+                    ? `single active Electron launch ${launchRecord.launchId} uses wrapper session ${launchRecord.sessionName}; pass electron.probe.launchId to inspect that launch session directly.`
+                    : undefined;
+            const probeContext = {
+                launchId: launchRecord?.launchId,
+                mode: compiledElectron.launchId ? "launchId" : "current-managed-session",
+                note: probeContextNote,
+                sessionName: probe.sessionName,
+            };
+            const sessionTabTarget = normalizeSessionTabTarget({
+                title: probe.title ?? probe.activeTab?.title ?? probe.refSnapshot?.target?.title,
+                url: probe.url ?? probe.activeTab?.url ?? probe.refSnapshot?.target?.url,
+            });
+            const pageStateUpdate = sessionPageState.beginUpdate();
+            if (sessionTabTarget) {
+                sessionPageState.applyTabTarget({ sessionName: probe.sessionName, target: sessionTabTarget, update: pageStateUpdate });
+            }
+            if (probe.refSnapshot) {
+                sessionPageState.applyRefSnapshot({
+                    fallbackTarget: sessionTabTarget,
+                    sessionName: probe.sessionName,
+                    snapshot: probe.refSnapshot,
+                    update: pageStateUpdate,
+                });
+            }
+            return buildElectronProbeResult({
+                compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                mismatch: sessionMismatch,
+                probe,
+                probeContext,
+                record: launchRecord,
+                sessionTabTarget,
+                status,
+            });
+        }
+        catch (error) {
+            const errorText = error instanceof Error ? error.message : String(error);
+            return buildElectronHostFailureResult({
+                compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                errorText: `Electron probe failed: ${errorText}`,
+                failureCategory: "upstream-error",
+            });
+        }
+    }
+    if (compiledElectron?.action === "cleanup") {
+        const selection = selectElectronRecords(compiledElectron, electronLaunchRecords);
+        if (selection.error)
+            return buildElectronHostFailureResult({ compiledElectron: redactedCompiledElectron ?? compiledElectron, errorText: selection.error, failureCategory: "validation-error" });
+        const cleanupResults = await cleanupTrackedElectronHostLaunches({ cwd, electronChildProcesses, electronLaunchRecords, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
+        return buildElectronCleanupResult(redactedCompiledElectron ?? compiledElectron, cleanupResults);
+    }
+    return undefined;
+}