pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/code-image-observation.js

@@ -0,0 +1,119 @@
+import { isRecord } from "../parsing.js";
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function size(value) {
+    if (!isRecord(value) || !finite(value.width) || !finite(value.height)) {
+        return undefined;
+    }
+    return { width: value.width, height: value.height };
+}
+function point(value) {
+    if (!isRecord(value) || !finite(value.x) || !finite(value.y)) {
+        return undefined;
+    }
+    return { x: value.x, y: value.y };
+}
+function rectangle(value) {
+    const dimensions = size(value);
+    const coordinates = point(value);
+    return dimensions && coordinates ? { ...dimensions, ...coordinates } : undefined;
+}
+function visualViewport(value) {
+    const coordinates = point(value);
+    if (!isRecord(value) || !coordinates || !finite(value.scale)) {
+        return undefined;
+    }
+    return { ...coordinates, scale: value.scale };
+}
+function rendering(value) {
+    return value === undefined || value === "text";
+}
+function sample(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const viewport = size(value.viewport);
+    const document = size(value.document);
+    const scroll = point(value.scroll);
+    const visual = visualViewport(value.visualViewport);
+    if (!viewport || !document || !scroll || !visual) {
+        return undefined;
+    }
+    const element = rectangle(value.element);
+    if (value.element !== undefined && element === undefined) {
+        return undefined;
+    }
+    if (!validSampleIdentity(value)) {
+        return undefined;
+    }
+    return {
+        url: value.url,
+        frame: value.frame,
+        childFrameCount: value.childFrameCount,
+        dpr: value.dpr,
+        rendering: value.rendering,
+        viewport,
+        document,
+        scroll,
+        visualViewport: visual,
+        element,
+    };
+}
+function validSampleIdentity(value) {
+    return (typeof value.url === "string" &&
+        (value.frame === "main" || value.frame === "child") &&
+        finite(value.childFrameCount) &&
+        finite(value.dpr) &&
+        rendering(value.rendering));
+}
+function geometry(value) {
+    if (!isRecord(value) || typeof value.reason !== "string") {
+        return undefined;
+    }
+    if (value.status !== "measured" && value.status !== "unknown") {
+        return undefined;
+    }
+    const before = sample(value.before);
+    const after = sample(value.after);
+    const crop = rectangle(value.crop);
+    const pixelsPerCssPixel = point(value.pixelsPerCssPixel);
+    const invalid = [
+        [value.before, before],
+        [value.after, after],
+        [value.crop, crop],
+        [value.pixelsPerCssPixel, pixelsPerCssPixel],
+    ].some(([supplied, parsed]) => supplied !== undefined && parsed === undefined);
+    if (invalid) {
+        return undefined;
+    }
+    return { status: value.status, reason: value.reason, before, after, crop, pixelsPerCssPixel };
+}
+export function parseCodeImageObservation(value) {
+    if (!isRecord(value) || typeof value.path !== "string" || typeof value.mimeType !== "string") {
+        return undefined;
+    }
+    const captures = [
+        "viewport",
+        "full-page",
+        "element",
+        "unknown",
+    ];
+    const capture = captures.find((candidate) => candidate === value.capture);
+    const measuredGeometry = geometry(value.geometry);
+    if (capture === undefined || !measuredGeometry || !rendering(value.rendering)) {
+        return undefined;
+    }
+    const pixels = size(value.pixels);
+    if (value.pixels !== undefined && pixels === undefined) {
+        return undefined;
+    }
+    return {
+        path: value.path,
+        mimeType: value.mimeType,
+        capture,
+        geometry: measuredGeometry,
+        pixels,
+        rendering: value.rendering,
+    };
+}

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

@@ -0,0 +1,92 @@
+import { getBrowserResultMessage } from "../../browser-transcript.js";
+import { isRecord } from "../../parsing.js";
+import { getActiveElectronRecords } from "../browser-run/session-state.js";
+function isLaunchIdentity(value) {
+    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");
+}
+function hasValidOptionalFields(value) {
+    const strings = [
+        "ownerSessionId",
+        "appPath",
+        "bundleId",
+        "desktopId",
+        "namespace",
+        "packageSource",
+        "platform",
+        "sessionName",
+        "webSocketDebuggerUrl",
+    ];
+    return (strings.every((field) => value[field] === undefined || typeof value[field] === "string") &&
+        ["pid", "processGroupId"].every((field) => value[field] === undefined || typeof value[field] === "number"));
+}
+function isCleanupState(value) {
+    return (typeof value === "string" && ["active", "cleaned", "dead", "failed", "partial"].includes(value));
+}
+function isTargetType(value) {
+    return value === undefined || value === "any" || value === "page" || value === "webview";
+}
+function isElectronLaunchRecord(value) {
+    if (!isRecord(value) || !isLaunchIdentity(value) || !hasValidOptionalFields(value)) {
+        return false;
+    }
+    return isCleanupState(value.cleanupState) && isTargetType(value.targetType);
+}
+function cleanupLaunchRecords(electron) {
+    return isRecord(electron.cleanup) && Array.isArray(electron.cleanup.records)
+        ? electron.cleanup.records
+        : [];
+}
+function restoredRecords(entry) {
+    const message = getBrowserResultMessage(entry);
+    if (!message) {
+        return [];
+    }
+    const details = isRecord(message.details) ? message.details : undefined;
+    const electron = isRecord(details?.electron) ? details.electron : undefined;
+    if (!electron) {
+        return [];
+    }
+    const namespace = typeof details?.namespace === "string" ? details.namespace : undefined;
+    const cleanupRecords = cleanupLaunchRecords(electron);
+    const records = [];
+    for (const record of [electron.launch, ...cleanupRecords].filter(isElectronLaunchRecord)) {
+        records.push({ ...record, namespace: record.namespace ?? namespace });
+    }
+    return records;
+}
+export function restoreElectronLaunchRecordsFromBranch(branch) {
+    const records = new Map();
+    for (const entry of branch) {
+        for (const record of restoredRecords(entry)) {
+            records.set(record.launchId, record);
+        }
+    }
+    return records;
+}
+export function selectElectronRecords(compiledElectron, records) {
+    if (compiledElectron.launchId !== undefined && compiledElectron.launchId.length > 0) {
+        const record = records.get(compiledElectron.launchId);
+        return record
+            ? { records: [record] }
+            : {
+                error: `No wrapper-tracked Electron launch found for launchId ${compiledElectron.launchId}.`,
+            };
+    }
+    if (compiledElectron.all === true) {
+        return { records: getActiveElectronRecords(records) };
+    }
+    const activeRecords = getActiveElectronRecords(records);
+    if (activeRecords.length > 1) {
+        return {
+            error: "Multiple wrapper-tracked Electron launches are active; pass electron.launchId or electron.all.",
+        };
+    }
+    return { records: activeRecords };
+}

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

@@ -0,0 +1,58 @@
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { redactSensitiveText } from "../../runtime-redaction.js";
+import { redactToolDetails } from "../browser-run/final-result-redaction.js";
+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 !== undefined && step.error.length > 0 ? ` (${step.error})` : ""}`);
+        }
+    }
+    return lines.join("\n");
+}
+export 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,
+    };
+}

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

@@ -0,0 +1,78 @@
+import { cleanupElectronLaunchResources, } from "../../electron/cleanup.js";
+import { getSessionPageStateKey } from "../../session-page-state.js";
+import { closeManagedSession } from "../browser-run/managed-session-daemon-policy.js";
+import { getActiveElectronRecords } from "../browser-run/session-state.js";
+async function closeElectronManagedSession(options, record) {
+    if (record.sessionName === undefined || record.sessionName.length === 0) {
+        return;
+    }
+    const sessionKey = getSessionPageStateKey(record.sessionName, record.namespace) ?? record.sessionName;
+    const owner = options.ownedManagedSessions.get(sessionKey);
+    return closeManagedSession({
+        confirmActions: options.sessionPageState.get(sessionKey).confirmActions ??
+            process.env.AGENT_BROWSER_CONFIRM_ACTIONS,
+        cwd: options.cwd,
+        headedManagedAutosaveInterval: owner?.headedManagedAutosaveInterval,
+        namespace: record.namespace,
+        preserveAttachedBrowserSession: options.attachedSessionKeys.has(sessionKey),
+        restoreState: options.managedSessionRestoreState,
+        sessionName: record.sessionName,
+        socketDir: owner?.socketDir,
+        timeoutMs: options.timeoutMs,
+    });
+}
+function managedSessionStep(record, error) {
+    if (record.sessionName === undefined || record.sessionName.length === 0) {
+        return;
+    }
+    return error !== undefined && error.length > 0
+        ? { error, resource: "managed-session", sessionName: record.sessionName, state: "failed" }
+        : { resource: "managed-session", sessionName: record.sessionName, state: "removed" };
+}
+async function cleanupTrackedLaunch(options, record) {
+    const closeError = await closeElectronManagedSession(options, record);
+    const step = managedSessionStep(record, closeError);
+    const cleanup = await cleanupElectronLaunchResources({
+        child: options.electronChildProcesses.get(record.launchId),
+        record,
+        timeoutMs: options.timeoutMs,
+    });
+    const steps = step ? [step, ...cleanup.steps] : [...cleanup.steps];
+    if (closeError !== undefined && closeError.length > 0) {
+        return {
+            ...cleanup,
+            partial: true,
+            record: { ...cleanup.record, cleanupState: "partial" },
+            remainingResources: [...new Set(["managed-session", ...cleanup.remainingResources])],
+            steps,
+            summary: `Electron cleanup for ${record.launchId} is partial; managed session close failed.`,
+        };
+    }
+    const clearedSession = record.sessionName !== undefined && record.sessionName.length > 0;
+    return {
+        ...cleanup,
+        record: clearedSession ? { ...cleanup.record, sessionName: undefined } : cleanup.record,
+        steps,
+    };
+}
+export async function cleanupTrackedElectronHostLaunches(options) {
+    const results = [];
+    for (const record of options.records) {
+        // Close the managed connection before its process/profile, and publish each
+        // terminal record before proceeding to the next owned launch.
+        // oxlint-disable-next-line no-await-in-loop
+        const result = await cleanupTrackedLaunch(options, record);
+        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 })
+        : [];
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,106 @@
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { redactSensitiveText } from "../../runtime-redaction.js";
+import { normalizeProcessError } from "../../process-errors.js";
+import { redactToolDetails } from "../browser-run/final-result-redaction.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,
+};
+function formatApp(app) {
+    const identifier = app.bundleId ?? app.desktopId;
+    const path = app.appPath ?? app.executablePath;
+    const sensitivity = app.sensitivity
+        ? ` [likely sensitive: ${app.sensitivity.categories.join(", ")}]`
+        : "";
+    return `- ${app.name}${identifier !== undefined && identifier.length > 0 ? ` (${identifier})` : ""}${sensitivity} — ${path}`;
+}
+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 !== undefined && result.query.length > 0
+            ? `No Electron apps matched query "${result.query}".`
+            : "No Electron apps found in the supported scan locations.");
+    }
+    else {
+        lines.push(...visibleApps.map(formatApp));
+    }
+    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.", ELECTRON_PROFILE_ISOLATION_NOTE, 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 === 0 ? undefined : discovery.omittedCount,
+            platform: discovery.platform,
+            profileIsolation: ELECTRON_PROFILE_ISOLATION_DETAILS,
+            query: discovery.query,
+            sensitiveAppCount: sensitiveAppCount === 0 ? undefined : sensitiveAppCount,
+            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 = normalizeProcessError(error).message;
+    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,
+    };
+}
+export async function discoverElectronHostApps(compiledElectron, visibleInput) {
+    try {
+        const { discoverElectronApps } = await import("../../electron/discovery.js");
+        const discovery = await discoverElectronApps({
+            maxResults: compiledElectron.maxResults,
+            query: compiledElectron.query,
+        });
+        return buildElectronListSuccessResult(visibleInput, discovery);
+    }
+    catch (error) {
+        return buildElectronListFailureResult(visibleInput, error);
+    }
+}