pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,86 @@
+import { buildOwnedManagedSessionRestoreContext, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
+import { withAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { normalizeProcessError } from "../../process-errors.js";
+import { collectElectronManagedSessionTarget } from "../browser-run/diagnostics.js";
+import { acquireOwnedManagedSessionDaemonPolicy, getRunningHeadedAutosavePolicyChangeError, } from "../browser-run/managed-session-daemon-policy.js";
+export class ElectronManagedSessionPolicyError extends Error {
+}
+async function acquireElectronPolicy(options, context) {
+    try {
+        return await acquireOwnedManagedSessionDaemonPolicy({
+            context,
+            electronLaunchRecord: options.electronLaunchRecord,
+            electronVerificationTimeoutMs: options.timeoutMs,
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        throw new ElectronManagedSessionPolicyError(normalizeProcessError(error).message, {
+            cause: error,
+        });
+    }
+}
+function requirePolicyLock(policy, signal) {
+    if (policy.error !== undefined && policy.error.length > 0) {
+        throw new ElectronManagedSessionPolicyError(policy.error);
+    }
+    if (!policy.lock) {
+        throw new ElectronManagedSessionPolicyError(signal?.aborted === true
+            ? "Electron helper was aborted."
+            : "Electron helper could not acquire managed-session policy coordination.");
+    }
+    return policy.lock;
+}
+export async function withOwnedElectronManagedSessionPolicy(options, run) {
+    return withAgentBrowserProcessEnvironment({ AGENT_BROWSER_CONFIRM_ACTIONS: options.confirmActions }, async () => {
+        const autosavePolicyChangeError = getRunningHeadedAutosavePolicyChangeError(options.headedManagedAutosaveInterval);
+        if (autosavePolicyChangeError !== undefined && autosavePolicyChangeError.length > 0) {
+            throw new ElectronManagedSessionPolicyError(autosavePolicyChangeError);
+        }
+        const context = buildOwnedManagedSessionRestoreContext({
+            args: [
+                "--namespace",
+                options.namespace ?? "",
+                "--session",
+                options.sessionName,
+                ...options.args,
+            ],
+            cwd: options.cwd,
+            headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+            headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
+            managedSessionName: options.sessionName,
+            namespace: options.namespace,
+            restoreState: options.restoreState,
+        });
+        if (!context) {
+            throw new ElectronManagedSessionPolicyError("Electron helper could not establish wrapper ownership for its managed session.");
+        }
+        const policy = await acquireElectronPolicy(options, context);
+        try {
+            requirePolicyLock(policy, options.signal);
+            return await withOwnedManagedSessionContext(context, run);
+        }
+        finally {
+            await policy.lock?.release();
+        }
+    });
+}
+export async function collectOwnedElectronManagedSessionTarget(options) {
+    try {
+        const target = (await withOwnedElectronManagedSessionPolicy({ ...options, args: ["get", "url"] }, () => collectElectronManagedSessionTarget({
+            cwd: options.cwd,
+            namespace: options.namespace,
+            sessionName: options.sessionName,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        }))) ?? { sessionName: options.sessionName };
+        return { ...target, namespace: options.namespace };
+    }
+    catch (error) {
+        return {
+            error: normalizeProcessError(error).message,
+            namespace: options.namespace,
+            sessionName: options.sessionName,
+        };
+    }
+}

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

@@ -0,0 +1,68 @@
+import { boundElectronProbeString } from "../../electron/cdp.js";
+import { normalizeProcessError } from "../../process-errors.js";
+import { extractStringResultField, runSessionCommandData } from "../browser-run/session-state.js";
+import { ELECTRON_FOCUSED_ELEMENT_EVAL, extractElectronFocusedElement, extractElectronProbeTabs, summarizeElectronProbeSnapshot, getElectronProbeSummary, } from "./probe-data.js";
+async function runElectronProbeCommandData(options) {
+    try {
+        return {
+            data: await runSessionCommandData({ ...options, pinNamespace: true, throwOnFailure: true }),
+        };
+    }
+    catch (error) {
+        return { error: normalizeProcessError(error).message };
+    }
+}
+function probeCommandError(result, label) {
+    return result.error !== undefined && result.error.length > 0
+        ? `${label}: ${result.error}`
+        : undefined;
+}
+export async function collectElectronProbe(options) {
+    // Each read completes before the next: native session commands share a pending
+    // slot, and the final snapshot owns the refs published by this probe.
+    const urlResult = await runElectronProbeCommandData({ ...options, args: ["get", "url"] });
+    const urlError = probeCommandError(urlResult, "get url");
+    if (urlError !== undefined) {
+        throw new Error(urlError);
+    }
+    const url = extractStringResultField(urlResult.data, "result") ??
+        extractStringResultField(urlResult.data, "url");
+    if (url === undefined || url.trim().length === 0) {
+        throw new Error("get url returned no active page URL.");
+    }
+    const titleResult = await runElectronProbeCommandData({ ...options, args: ["get", "title"] });
+    const focusedResult = await runElectronProbeCommandData({
+        ...options,
+        args: ["eval", "--stdin"],
+        stdin: ELECTRON_FOCUSED_ELEMENT_EVAL,
+    });
+    const tabsResult = await runElectronProbeCommandData({ ...options, args: ["tab", "list"] });
+    const snapshotResult = await runElectronProbeCommandData({
+        ...options,
+        args: ["snapshot", "-i"],
+    });
+    const errors = [
+        probeCommandError(titleResult, "get title"),
+        probeCommandError(focusedResult, "focused element"),
+        probeCommandError(tabsResult, "tab list"),
+        probeCommandError(snapshotResult, "snapshot"),
+    ]
+        .filter((item) => item !== undefined)
+        .map((error) => boundElectronProbeString(error, 240) ?? "probe command failed");
+    const { activeTab, tabs } = extractElectronProbeTabs(tabsResult.data);
+    const { refSnapshot, snapshot } = summarizeElectronProbeSnapshot(snapshotResult.data);
+    const probe = {
+        activeTab,
+        focusedElement: extractElectronFocusedElement(focusedResult.data),
+        errors: errors.length > 0 ? errors : undefined,
+        refSnapshot,
+        sessionName: options.sessionName,
+        snapshot,
+        status: errors.length === 0 ? "succeeded" : "partial",
+        tabs,
+        title: boundElectronProbeString(extractStringResultField(titleResult.data, "result") ??
+            extractStringResultField(titleResult.data, "title"), 160),
+        url,
+    };
+    return { ...probe, summary: getElectronProbeSummary(probe) };
+}

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

@@ -0,0 +1,169 @@
+import { boundElectronProbeString } from "../../electron/cdp.js";
+import { isRecord } from "../../parsing.js";
+import { extractRefSnapshotFromData } from "../../session-page-state.js";
+export 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) };
+})()`;
+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 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 focusedElementPayload(data) {
+    const payload = isRecord(data) && isRecord(data.result) ? data.result : data;
+    if (!isRecord(payload)) {
+        return;
+    }
+    return isRecord(payload.focusedElement) ? payload.focusedElement : payload;
+}
+export function extractElectronFocusedElement(data) {
+    const raw = focusedElementPayload(data);
+    if (!raw) {
+        return;
+    }
+    const focusedElement = {
+        ariaLabel: getTrimmedString(raw.ariaLabel),
+        id: getTrimmedString(raw.id),
+        isContentEditable: getOptionalBoolean(raw.isContentEditable),
+        name: getTrimmedString(raw.name),
+        placeholder: getTrimmedString(raw.placeholder),
+        role: getTrimmedString(raw.role),
+        tagName: getTrimmedString(raw.tagName),
+        textLength: getOptionalNumber(raw.textLength),
+        textPreview: getTrimmedString(raw.textPreview),
+        title: getTrimmedString(raw.title),
+        type: getTrimmedString(raw.type),
+        valueLength: getOptionalNumber(raw.valueLength),
+    };
+    return Object.values(focusedElement).some((value) => value !== undefined)
+        ? focusedElement
+        : undefined;
+}
+function rawProbeTabs(data) {
+    if (isRecord(data) && Array.isArray(data.tabs)) {
+        return data.tabs;
+    }
+    return Array.isArray(data) ? data : [];
+}
+export function extractElectronProbeTabs(data) {
+    const allTabs = rawProbeTabs(data)
+        .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: typeof tab.url === "string" ? tab.url : undefined,
+    }));
+    if (allTabs.length === 0) {
+        return {};
+    }
+    const shown = allTabs.slice(0, ELECTRON_PROBE_MAX_TABS);
+    return {
+        activeTab: allTabs.find((tab) => tab.active === true) ?? allTabs[0],
+        tabs: {
+            omittedCount: allTabs.length > shown.length ? allTabs.length - shown.length : undefined,
+            shown,
+            total: allTabs.length,
+        },
+    };
+}
+function truncateElectronProbeSnapshotText(snapshotText) {
+    if (snapshotText === undefined || snapshotText.length === 0) {
+        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,
+    };
+}
+export function summarizeElectronProbeSnapshot(data) {
+    const refSnapshot = extractRefSnapshotFromData(data);
+    const rawSnapshotText = isRecord(data) ? getTrimmedString(data.snapshot) : undefined;
+    const truncated = truncateElectronProbeSnapshotText(rawSnapshotText);
+    const refIds = refSnapshot?.refIds ?? [];
+    const shownRefIds = refIds.slice(0, ELECTRON_PROBE_MAX_REF_IDS);
+    const hasSnapshot = refSnapshot !== undefined || (truncated.text !== undefined && truncated.text.length > 0);
+    const snapshot = hasSnapshot
+        ? {
+            lineCount: truncated.lineCount,
+            omittedLineCount: truncated.omittedLineCount,
+            omittedRefCount: refIds.length > shownRefIds.length ? refIds.length - shownRefIds.length : undefined,
+            refCount: refIds.length,
+            refIds: shownRefIds,
+            text: truncated.text,
+        }
+        : undefined;
+    return { refSnapshot, snapshot };
+}
+export function getElectronProbeSummary(probe) {
+    const parts = [
+        probe.title !== undefined && probe.title.length > 0 ? `title "${probe.title}"` : undefined,
+        probe.url !== undefined && probe.url.length > 0
+            ? `url ${boundElectronProbeString(probe.url, 300) ?? ""}`
+            : 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.";
+}

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

@@ -0,0 +1,182 @@
+import { boundElectronProbeString } from "../../electron/cdp.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { appendUniqueAgentBrowserNextActions } from "../../results/next-actions.js";
+import { redactSensitiveText } from "../../runtime-redaction.js";
+import { isAboutBlankUrl } from "../../session-page-state.js";
+import { redactToolDetails } from "../browser-run/final-result.js";
+import { buildElectronIdentifiers, buildElectronMismatchNextActions, formatElectronSessionMismatchText, getLiveElectronRendererTargets, } from "../browser-run/session-state.js";
+function presentProbeTab(tab) {
+    return { ...tab, url: boundElectronProbeString(tab.url) };
+}
+function presentProbe(probe) {
+    return {
+        ...probe,
+        activeTab: probe.activeTab ? presentProbeTab(probe.activeTab) : undefined,
+        tabs: probe.tabs ? { ...probe.tabs, shown: probe.tabs.shown.map(presentProbeTab) } : undefined,
+        url: boundElectronProbeString(probe.url, 300),
+    };
+}
+function presentStrings(values) {
+    return values.filter((value) => value !== undefined && value.length > 0);
+}
+function formatFocusedElementAttributes(element) {
+    return presentStrings([
+        element.id !== undefined && element.id.length > 0 ? `#${element.id}` : undefined,
+        element.type !== undefined && element.type.length > 0 ? `type=${element.type}` : undefined,
+        element.valueLength !== undefined ? `valueLength=${element.valueLength}` : undefined,
+        element.textLength !== undefined ? `textLength=${element.textLength}` : undefined,
+    ]).join(", ");
+}
+function focusedElementLabel(element) {
+    return (element.name ?? element.textPreview ?? element.placeholder ?? element.ariaLabel ?? element.title);
+}
+function formatElectronProbeFocusedElement(element) {
+    if (!element) {
+        return;
+    }
+    const label = focusedElementLabel(element);
+    const descriptorText = presentStrings([element.role, element.tagName]).join("/");
+    const descriptor = descriptorText.length > 0 ? descriptorText : "element";
+    const suffix = formatFocusedElementAttributes(element);
+    return `Focused: ${descriptor}${label !== undefined && label.length > 0 ? ` "${label}"` : ""}${suffix.length > 0 ? ` (${suffix})` : ""}`;
+}
+function formatElectronProbeContextText(context) {
+    if (context.mode === "launchId") {
+        return `Probe context: wrapper launch ${context.launchId ?? "undefined"} session ${context.sessionName}.`;
+    }
+    if (context.note !== undefined && context.note.length > 0) {
+        return `Probe context: current managed session ${context.sessionName}; ${context.note}`;
+    }
+    if (context.launchId !== undefined && context.launchId.length > 0) {
+        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;
+    }
+    let pidText = "";
+    if (status.pidAlive !== undefined) {
+        pidText = status.pidAlive ? ", pid alive" : ", pid dead";
+    }
+    const lines = [
+        `Launch status: ${status.portAlive ? "debug port alive" : "debug port dead"}${pidText}; ${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 formatProbeTabs(probe) {
+    if (!probe.tabs) {
+        return;
+    }
+    const omitted = (probe.tabs.omittedCount ?? 0) !== 0 ? ` (${probe.tabs.omittedCount ?? 0} omitted)` : "";
+    const active = probe.activeTab;
+    const activeText = active
+        ? `; active ${active.index ?? "?"}: ${presentStrings([presentStrings([active.title, active.url]).join(" — "), active.tabId])[0] ?? "tab"}`
+        : "";
+    return `Tabs: ${probe.tabs.total} total${omitted}${activeText}`;
+}
+function formatProbeSnapshot(probe) {
+    const snapshot = probe.snapshot;
+    if (!snapshot) {
+        return [];
+    }
+    const omitted = (snapshot.omittedRefCount ?? 0) !== 0
+        ? ` (${snapshot.omittedRefCount ?? 0} ref id(s) omitted)`
+        : "";
+    const lines = [`Snapshot: ${snapshot.refCount} interactive ref(s)${omitted}.`];
+    if (snapshot.text !== undefined && snapshot.text.length > 0) {
+        lines.push(snapshot.text);
+    }
+    if ((snapshot.omittedLineCount ?? 0) !== 0) {
+        lines.push(`... ${snapshot.omittedLineCount ?? 0} snapshot line(s) omitted`);
+    }
+    return lines;
+}
+function formatElectronProbeVisibleText(options) {
+    const probe = options.probe;
+    const page = presentStrings([probe.title, probe.url]).join(" — ");
+    const lines = [
+        `Electron probe: ${page.length > 0 ? page : probe.sessionName}`,
+        formatElectronProbeContextText(options.probeContext),
+        ...presentStrings([
+            formatElectronProbeLaunchStatusText(options.status, probe),
+            options.mismatch ? formatElectronSessionMismatchText(options.mismatch) : undefined,
+            formatElectronProbeFocusedElement(probe.focusedElement),
+            formatProbeTabs(probe),
+        ]),
+        ...formatProbeSnapshot(probe),
+    ];
+    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 probeNextActions(options) {
+    const base = options.record
+        ? (buildAgentBrowserNextActions({
+            electron: {
+                launchId: options.record.launchId,
+                sessionName: options.record.sessionName,
+                status: options.record.cleanupState,
+            },
+            resultCategory: "success",
+            successCategory: "completed",
+        }) ?? [])
+        : [];
+    const mismatch = options.mismatch && options.record
+        ? buildElectronMismatchNextActions(options.record, options.mismatch.liveTarget)
+        : [];
+    return options.mismatch
+        ? appendUniqueAgentBrowserNextActions([...mismatch], base)
+        : appendUniqueAgentBrowserNextActions([...base], mismatch);
+}
+export function buildElectronProbeResult(options) {
+    const probe = presentProbe(options.probe);
+    const { refSnapshot: _refSnapshot, ...boundedProbe } = probe;
+    const nextActions = probeNextActions(options);
+    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 }),
+        managedSessionHeadedAutosaveDisabled: options.headedManagedAutosaveDisabled === true ? true : undefined,
+        managedSessionHeadedAutosaveInterval: options.headedManagedAutosaveInterval,
+        namespace: options.namespace,
+        refSnapshot: options.probe.refSnapshot,
+        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({ ...options, probe })),
+            },
+        ],
+        details: redactToolDetails(details, []),
+        isError: false,
+    };
+}

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

@@ -0,0 +1,161 @@
+import { inspectElectronLaunchStatus } from "../../electron/cleanup.js";
+import { getPageTargetValidationError } from "../../page-target-validation.js";
+import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { normalizeProcessError } from "../../process-errors.js";
+import { getSessionPageStateKey, normalizeSessionTabTarget, } from "../../session-page-state.js";
+import { buildElectronHostFailureResult } from "../browser-run/final-result.js";
+import { buildElectronSessionMismatch, findElectronLaunchRecordForSession, } from "../browser-run/session-state.js";
+import { ElectronManagedSessionPolicyError, withOwnedElectronManagedSessionPolicy, } from "./policy.js";
+import { collectElectronProbe } from "./probe-collection.js";
+import { buildElectronProbeResult } from "./probe-presentation.js";
+function resolveLaunchProbe(record, launchId) {
+    if (!record) {
+        return { error: `No wrapper-tracked Electron launch found for launchId ${launchId}.` };
+    }
+    if (record.sessionName === undefined || record.sessionName.length === 0) {
+        return {
+            error: `electron.probe launchId ${launchId} has no attached managed sessionName; reattach with connect or run electron.launch again.`,
+        };
+    }
+    return { record, namespace: record.namespace, sessionName: record.sessionName };
+}
+function resolveProbeIdentity(options, input) {
+    if (input.launchId !== undefined && input.launchId.length > 0) {
+        return resolveLaunchProbe(options.electronLaunchRecords.get(input.launchId), input.launchId);
+    }
+    const record = findElectronLaunchRecordForSession(options.managedSessionName, options.electronLaunchRecords, options.managedSessionNamespace);
+    if (!options.managedSessionActive) {
+        return {
+            error: "electron.probe requires an active attached session. Run electron.launch or connect to an Electron debug port first.",
+        };
+    }
+    if (options.managedSessionName.length === 0) {
+        return { error: "electron.probe could not resolve a managed session to inspect." };
+    }
+    return {
+        record,
+        namespace: options.managedSessionNamespace,
+        sessionName: options.managedSessionName,
+    };
+}
+function probeContext(identity, input, probe) {
+    const explicit = input.launchId !== undefined && input.launchId.length > 0;
+    let note;
+    if (!identity.record) {
+        note = "No wrapper-tracked Electron launch matched this current managed session.";
+    }
+    else if (!explicit &&
+        identity.record.sessionName !== undefined &&
+        identity.record.sessionName.length > 0 &&
+        identity.record.sessionName !== probe.sessionName) {
+        note = `single active Electron launch ${identity.record.launchId} uses wrapper session ${identity.record.sessionName}; pass electron.probe.launchId to inspect that launch session directly.`;
+    }
+    return {
+        launchId: identity.record?.launchId,
+        mode: explicit ? "launchId" : "current-managed-session",
+        note,
+        sessionName: probe.sessionName,
+    };
+}
+function probePageTarget(probe) {
+    const { title, url, activeTab, refSnapshot } = probe;
+    const snapshotTarget = refSnapshot?.target;
+    return normalizeSessionTabTarget({
+        title: title ?? activeTab?.title ?? snapshotTarget?.title,
+        url: url ?? activeTab?.url ?? snapshotTarget?.url,
+    });
+}
+function publishProbePageState(state, probe, namespace) {
+    const target = probePageTarget(probe);
+    const update = state.beginUpdate();
+    const key = getSessionPageStateKey(probe.sessionName, namespace) ?? probe.sessionName;
+    if (target) {
+        state.applyTabTarget({ sessionName: key, target, update });
+    }
+    if (probe.refSnapshot) {
+        state.applyRefSnapshot({
+            fallbackTarget: target,
+            sessionName: key,
+            snapshot: probe.refSnapshot,
+            update,
+        });
+    }
+    return target;
+}
+function resolveProbePolicy(options, identity, timeoutMs) {
+    const key = getSessionPageStateKey(identity.sessionName, identity.namespace) ?? identity.sessionName;
+    const pageState = options.sessionPageState.get(key);
+    const targetError = getPageTargetValidationError({
+        args: ["snapshot", "-i"],
+        currentPageUrl: pageState.tabTarget?.url,
+        pageUrlUnknown: pageState.tabTargetUnknown === true,
+    });
+    if (targetError !== undefined && targetError.length > 0) {
+        throw new ElectronManagedSessionPolicyError(targetError);
+    }
+    const owner = options.ownedManagedSessions.get(key);
+    return {
+        cwd: options.cwd,
+        namespace: identity.namespace,
+        sessionName: identity.sessionName,
+        signal: options.signal,
+        timeoutMs,
+        confirmActions: pageState.confirmActions ?? getAgentBrowserProcessEnvironment().AGENT_BROWSER_CONFIRM_ACTIONS,
+        electronLaunchRecord: identity.record,
+        headedManagedAutosaveDisabled: owner?.headedManagedAutosaveDisabled === true,
+        headedManagedAutosaveInterval: owner?.headedManagedAutosaveInterval,
+        restoreState: options.managedSessionRestoreState,
+    };
+}
+async function inspectProbeIdentity(options, identity, input, visibleInput) {
+    const status = identity.record ? await inspectElectronLaunchStatus(identity.record) : undefined;
+    const policy = resolveProbePolicy(options, identity, input.timeoutMs);
+    const probe = await withOwnedElectronManagedSessionPolicy({ ...policy, args: ["snapshot", "-i"] }, () => collectElectronProbe(policy));
+    const managedSession = {
+        sessionName: probe.sessionName,
+        title: probe.title ?? probe.activeTab?.title,
+        url: probe.url ?? probe.activeTab?.url,
+    };
+    const mismatch = identity.record && status
+        ? buildElectronSessionMismatch({
+            managedSession,
+            record: identity.record,
+            statusTargets: status.targets,
+        })
+        : undefined;
+    const context = probeContext(identity, input, probe);
+    const target = publishProbePageState(options.sessionPageState, probe, identity.namespace);
+    return buildElectronProbeResult({
+        compiledElectron: visibleInput,
+        headedManagedAutosaveDisabled: policy.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: policy.headedManagedAutosaveInterval,
+        mismatch,
+        namespace: identity.namespace,
+        probe,
+        probeContext: context,
+        record: identity.record,
+        sessionTabTarget: target,
+        status,
+    });
+}
+export async function probeElectronHost(options, compiledElectron, visibleInput) {
+    const identity = resolveProbeIdentity(options, compiledElectron);
+    if ("error" in identity) {
+        return buildElectronHostFailureResult({
+            compiledElectron: visibleInput,
+            errorText: identity.error,
+            failureCategory: "validation-error",
+        });
+    }
+    try {
+        return await inspectProbeIdentity(options, identity, compiledElectron, visibleInput);
+    }
+    catch (error) {
+        const errorText = normalizeProcessError(error).message;
+        return buildElectronHostFailureResult({
+            compiledElectron: visibleInput,
+            errorText: `Electron probe failed: ${errorText}`,
+            failureCategory: error instanceof ElectronManagedSessionPolicyError ? "validation-error" : "upstream-error",
+        });
+    }
+}