pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/results/editable-ref-evidence.js

@@ -1,64 +1,99 @@
-const EDITABLE_REF_EVIDENCE_KEYS = ["editable", "contentEditable", "contenteditable", "isContentEditable"];
+const EDITABLE_REF_EVIDENCE_KEYS = [
+    "editable",
+    "contentEditable",
+    "contenteditable",
+    "isContentEditable",
+];
 const EDITABLE_FALSE_TEXT_PATTERN = /\b(?:contenteditable|editable)\s*=\s*["']?(?:false|0)["']?/i;
 const EDITABLE_ASSIGNMENT_TEXT_PATTERN = /\b(contenteditable|editable)\s*=\s*("[^"]*"|'[^']*'|[^\s,\]]+)/gi;
 const EDITABLE_BARE_TEXT_PATTERN = /\b(?:contenteditable|editable)\b(?!\s*=)/i;
 function parseEditableEvidenceValue(value) {
-    if (typeof value === "boolean")
+    if (typeof value === "boolean") {
         return value;
+    }
     if (typeof value === "number") {
-        if (value === 1)
+        if (value === 1) {
             return true;
-        if (value === 0)
+        }
+        if (value === 0) {
             return false;
+        }
         return undefined;
     }
-    if (typeof value !== "string")
+    if (typeof value !== "string") {
         return undefined;
-    const normalized = value.trim().replace(/^["']|["']$/g, "").toLowerCase();
-    if (["false", "0", "no"].includes(normalized))
+    }
+    const normalized = value
+        .trim()
+        .replace(/^["']|["']$/g, "")
+        .toLowerCase();
+    if (["false", "0", "no"].includes(normalized)) {
         return false;
-    if (["", "true", "1", "yes", "plaintext-only"].includes(normalized))
+    }
+    if (["", "true", "1", "yes", "plaintext-only"].includes(normalized)) {
         return true;
+    }
     return undefined;
 }
 function stripLeadingSnapshotAccessibleName(text) {
     return text.replace(/^(\s*[-*]\s+\S+\s+)(?:"[^"]*"|'[^']*')/, "$1");
 }
-function parseEditableEvidenceText(text) {
-    if (!text)
-        return undefined;
-    const markerText = stripLeadingSnapshotAccessibleName(text);
-    if (EDITABLE_FALSE_TEXT_PATTERN.test(markerText))
-        return false;
+function parseEditableAssignments(markerText) {
     let hasPositiveAssignment = false;
     for (const match of markerText.matchAll(EDITABLE_ASSIGNMENT_TEXT_PATTERN)) {
         const key = match[1]?.toLowerCase();
         const evidence = parseEditableEvidenceValue(match[2]);
-        if (evidence === false)
+        if (evidence === false) {
             return false;
+        }
         if (evidence === true && (key === "contenteditable" || key === "editable")) {
             hasPositiveAssignment = true;
         }
     }
-    if (hasPositiveAssignment)
-        return true;
+    return hasPositiveAssignment ? true : undefined;
+}
+function parseEditableEvidenceText(text) {
+    if (text === undefined || text.length === 0) {
+        return undefined;
+    }
+    const markerText = stripLeadingSnapshotAccessibleName(text);
+    if (EDITABLE_FALSE_TEXT_PATTERN.test(markerText)) {
+        return false;
+    }
+    const assignment = parseEditableAssignments(markerText);
+    if (assignment !== undefined) {
+        return assignment;
+    }
     return EDITABLE_BARE_TEXT_PATTERN.test(markerText) ? true : undefined;
 }
-export function getEditableRefEvidence(options) {
+function getStructuredEditableEvidence(ref) {
+    if (!ref) {
+        return undefined;
+    }
     let hasPositiveEvidence = false;
-    if (options.ref) {
-        for (const key of EDITABLE_REF_EVIDENCE_KEYS) {
-            const evidence = parseEditableEvidenceValue(options.ref[key]);
-            if (evidence === false)
-                return false;
-            if (evidence === true)
-                hasPositiveEvidence = true;
+    for (const key of EDITABLE_REF_EVIDENCE_KEYS) {
+        const evidence = parseEditableEvidenceValue(ref[key]);
+        if (evidence === false) {
+            return false;
         }
+        if (evidence === true) {
+            hasPositiveEvidence = true;
+        }
+    }
+    return hasPositiveEvidence ? true : undefined;
+}
+export function getEditableRefEvidence(options) {
+    const structuredEvidence = getStructuredEditableEvidence(options.ref);
+    if (structuredEvidence === false) {
+        return false;
     }
+    let hasPositiveEvidence = structuredEvidence === true;
     const textEvidence = parseEditableEvidenceText(options.text);
-    if (textEvidence === false)
+    if (textEvidence === false) {
         return false;
-    if (textEvidence === true)
+    }
+    if (textEvidence === true) {
         hasPositiveEvidence = true;
+    }
     return hasPositiveEvidence ? true : undefined;
 }

package/dist/extensions/agent-browser/lib/results/electron-recommendations.js

@@ -0,0 +1,83 @@
+import { buildNextToolAction } from "./next-actions.js";
+function buildElectronToolAction(options) {
+    return {
+        id: options.id,
+        params: { action: options.action, launchId: options.launchId },
+        reason: options.reason,
+        ...(options.safety !== undefined && options.safety.length > 0
+            ? { safety: options.safety }
+            : {}),
+        tool: "agent_browser_electron",
+    };
+}
+function buildActiveLaunchActions(launchId) {
+    return [
+        buildElectronToolAction({
+            action: "status",
+            id: "status-electron-launch",
+            launchId,
+            reason: "Check the wrapper-tracked Electron launch liveness and current CDP targets without mutating the app.",
+        }),
+        buildElectronToolAction({
+            action: "probe",
+            id: "probe-electron-launch",
+            launchId,
+            reason: "Probe the attached Electron managed session and carry the wrapper launchId for follow-up diagnostics.",
+        }),
+        buildElectronToolAction({
+            action: "cleanup",
+            id: "cleanup-electron-launch",
+            launchId,
+            reason: "Clean the wrapper-owned Electron process and isolated userDataDir when the run is complete.",
+            safety: "Only operates on the launchId created by electron.launch; explicit artifacts and manually launched apps remain host-owned.",
+        }),
+    ];
+}
+function buildElectronSessionActions(sessionName) {
+    if (sessionName === undefined || sessionName.length === 0) {
+        return [];
+    }
+    return [
+        buildNextToolAction({
+            args: ["--session", sessionName, "tab", "list"],
+            id: "list-electron-tabs",
+            reason: "Inspect attached Electron page/webview targets before choosing the active tab.",
+        }),
+        buildNextToolAction({
+            args: ["--session", sessionName, "snapshot", "-i"],
+            id: "snapshot-electron-session",
+            reason: "Refresh interactive refs for the attached Electron session.",
+            safety: "Use current Electron refs only after a fresh snapshot for this session.",
+        }),
+    ];
+}
+export function buildElectronNextActions(options) {
+    const launchId = options.electron?.launchId;
+    if (launchId === undefined || launchId.length === 0) {
+        return [];
+    }
+    if (options.resultCategory === "success" && options.electron?.status !== "cleaned") {
+        return [
+            ...buildActiveLaunchActions(launchId),
+            ...buildElectronSessionActions(options.electron?.sessionName),
+        ];
+    }
+    if (options.resultCategory === "failure" && options.failureCategory === "cleanup-failed") {
+        return [
+            buildElectronToolAction({
+                action: "status",
+                id: "status-electron-launch",
+                launchId,
+                reason: "Inspect which wrapper-tracked Electron resources remain after partial cleanup.",
+            }),
+            buildElectronToolAction({
+                action: "cleanup",
+                id: "retry-electron-cleanup",
+                launchId,
+                reason: "Retry cleanup for the same wrapper-owned Electron launch after reviewing remaining resources.",
+                safety: "Only retry for the same launchId; do not use cleanup for manually launched Electron apps.",
+            }),
+        ];
+    }
+    return [];
+}

package/dist/extensions/agent-browser/lib/results/envelope-decoding.js

@@ -0,0 +1,48 @@
+import { isRecord } from "../parsing.js";
+function decodePluginList(value) {
+    const keys = Object.keys(value);
+    if (keys.length !== 1) {
+        return undefined;
+    }
+    if (keys[0] === "plugins" && Array.isArray(value.plugins)) {
+        return { success: true, data: { plugins: value.plugins } };
+    }
+    if (keys[0] === "plugin" && isRecord(value.plugin) && !Array.isArray(value.plugin)) {
+        return { success: true, data: { plugin: value.plugin } };
+    }
+    return undefined;
+}
+export function decodeAgentBrowserEnvelope(value) {
+    if (Array.isArray(value)) {
+        return {
+            envelope: {
+                success: value.every((item) => !isRecord(item) || item.success !== false),
+                data: value,
+            },
+        };
+    }
+    if (!isRecord(value)) {
+        return { parseError: "agent-browser returned JSON, but it was not an object envelope." };
+    }
+    const plugin = decodePluginList(value);
+    if (plugin) {
+        return { envelope: plugin };
+    }
+    if (!("success" in value)) {
+        return {
+            parseError: "agent-browser returned an invalid JSON envelope: missing boolean success field.",
+        };
+    }
+    if (typeof value.success !== "boolean") {
+        return {
+            parseError: "agent-browser returned an invalid JSON envelope: success field must be boolean.",
+        };
+    }
+    if (!Object.hasOwn(value, "data")) {
+        const { success, error, ...topLevelData } = value;
+        if (Object.keys(topLevelData).length > 0) {
+            return { envelope: { error, success, data: topLevelData } };
+        }
+    }
+    return { envelope: { ...value, success: value.success } };
+}

package/dist/extensions/agent-browser/lib/results/envelope.js

@@ -1,90 +1,86 @@
 import { readFile } from "node:fs/promises";
 import { isRecord } from "../parsing.js";
 import { detectConfirmationRequired } from "./confirmation.js";
+import { decodeAgentBrowserEnvelope } from "./envelope-decoding.js";
 import { stringifyUnknown } from "./text.js";
 function hasStructuredBatchStepFailure(data) {
     return Array.isArray(data) && data.some((item) => isRecord(item) && item.success === false);
 }
 async function readEnvelopeSource(options) {
-    if (!options.stdoutPath) {
+    if (options.stdoutPath === undefined || options.stdoutPath.length === 0) {
         return options.stdout;
     }
     try {
         return await readFile(options.stdoutPath, "utf8");
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`agent-browser output spill file could not be read: ${message}`);
+        const message = error instanceof Error ? error.message : stringifyUnknown(error);
+        throw new Error(`agent-browser output spill file could not be read: ${message}`, {
+            cause: error,
+        });
     }
 }
 export function extractEnvelopeErrorText(error) {
     if (typeof error === "string") {
-        return error.trim() || undefined;
+        const trimmed = error.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
     }
     if (typeof error === "number" || typeof error === "boolean") {
         return String(error);
     }
     if (Array.isArray(error)) {
-        const parts = error.map((item) => extractEnvelopeErrorText(item) ?? stringifyUnknown(item)).filter((item) => item.length > 0);
+        const parts = error
+            .map((item) => extractEnvelopeErrorText(item) ?? stringifyUnknown(item))
+            .filter((item) => item.length > 0);
         return parts.length > 0 ? parts.join("\n") : undefined;
     }
     if (!isRecord(error)) {
-        return error == null ? undefined : stringifyUnknown(error);
+        return error === null || error === undefined ? undefined : stringifyUnknown(error);
     }
+    return extractStructuredEnvelopeErrorText(error);
+}
+function extractStructuredEnvelopeErrorText(error) {
     for (const key of ["message", "error", "details", "cause", "stderr"]) {
         const value = extractEnvelopeErrorText(error[key]);
-        if (value)
+        if ((value ?? "") !== "") {
             return value;
+        }
     }
     const fallback = stringifyUnknown(error).trim();
     return fallback.length > 0 && fallback !== "{}" ? fallback : undefined;
 }
+function getEnvelopeOutputMode(options) {
+    return typeof options === "string"
+        ? { plainText: false, textOutput: false }
+        : { plainText: options.plainText === true, textOutput: options.textOutput === true };
+}
 export async function parseAgentBrowserEnvelope(options) {
     let stdout;
     try {
         stdout = typeof options === "string" ? options : await readEnvelopeSource(options);
     }
     catch (error) {
-        return { parseError: error instanceof Error ? error.message : String(error) };
+        return { parseError: error instanceof Error ? error.message : stringifyUnknown(error) };
+    }
+    // ponytail: native text has no machine receipts; use JSON mode for structured evidence.
+    // JSON-looking page text must never become an envelope, confirmation, or batch row.
+    const { plainText, textOutput } = getEnvelopeOutputMode(options);
+    if (textOutput) {
+        return { envelope: { success: true, data: stdout } };
     }
     const trimmed = stdout.trim();
-    const plainText = typeof options !== "string" && options.plainText === true;
     if (trimmed.length === 0 && !plainText) {
         return { parseError: "agent-browser returned no JSON output." };
     }
     try {
         const parsed = JSON.parse(trimmed);
-        if (Array.isArray(parsed)) {
-            return { envelope: { success: parsed.every((item) => !isRecord(item) || item.success !== false), data: parsed } };
-        }
-        if (!isRecord(parsed)) {
-            return { parseError: "agent-browser returned JSON, but it was not an object envelope." };
-        }
-        const keys = Object.keys(parsed);
-        if (keys.length === 1 && keys[0] === "plugins" && Array.isArray(parsed.plugins)) {
-            return { envelope: { success: true, data: { plugins: parsed.plugins } } };
-        }
-        if (keys.length === 1 && keys[0] === "plugin" && isRecord(parsed.plugin) && !Array.isArray(parsed.plugin)) {
-            return { envelope: { success: true, data: { plugin: parsed.plugin } } };
-        }
-        if (!("success" in parsed)) {
-            return { parseError: "agent-browser returned an invalid JSON envelope: missing boolean success field." };
-        }
-        if (typeof parsed.success !== "boolean") {
-            return { parseError: "agent-browser returned an invalid JSON envelope: success field must be boolean." };
-        }
-        if (!Object.hasOwn(parsed, "data")) {
-            const { success, error, ...topLevelData } = parsed;
-            if (Object.keys(topLevelData).length > 0) {
-                return { envelope: { error, success, data: topLevelData } };
-            }
-        }
-        return { envelope: parsed };
+        return decodeAgentBrowserEnvelope(parsed);
     }
     catch (error) {
-        if (plainText)
+        if (plainText) {
             return { envelope: { success: true, data: trimmed } };
-        const message = error instanceof Error ? error.message : String(error);
+        }
+        const message = error instanceof Error ? error.message : stringifyUnknown(error);
         return { parseError: `agent-browser returned invalid JSON: ${message}` };
     }
 }
@@ -92,14 +88,14 @@ function buildInvocationLabel(options) {
     if (options.effectiveArgs && options.effectiveArgs.length > 0) {
         return `agent-browser ${options.effectiveArgs.join(" ")}`;
     }
-    if (options.command && options.command.trim().length > 0) {
+    if (options.command !== undefined && options.command.trim().length > 0) {
         return `agent-browser ${options.command.trim()}`;
     }
     return "agent-browser";
 }
 function appendWrapperRecoveryHint(message, wrapperRecoveryHint) {
     const hint = wrapperRecoveryHint?.trim();
-    return hint ? `${message}\n${hint}` : message;
+    return hint !== undefined && hint.length > 0 ? `${message}\n${hint}` : message;
 }
 function buildFailureFallback(options) {
     const invocation = buildInvocationLabel(options);
@@ -111,7 +107,9 @@ function buildExitCodeFallback(options) {
     return appendWrapperRecoveryHint(`${invocation} exited with code ${options.exitCode}.`, options.wrapperRecoveryHint);
 }
 function buildWatchdogTimeoutMessage(options) {
-    const timeoutText = options.timeoutMs === undefined ? "the wrapper watchdog" : `the ${options.timeoutMs}ms wrapper watchdog`;
+    const timeoutText = options.timeoutMs === undefined
+        ? "the wrapper watchdog"
+        : `the ${options.timeoutMs}ms wrapper watchdog`;
     const ipcTiming = options.timeoutMs !== undefined && options.timeoutMs <= 30_000
         ? "before the upstream CLI entered its 30s IPC retry path"
         : "after waiting beyond the upstream CLI's 30s IPC retry window";
@@ -126,7 +124,7 @@ function isUpstreamIpcReadTimeoutMessage(message) {
 function buildUpstreamIpcReadTimeoutMessage() {
     return [
         "agent-browser hit the upstream CLI 30s IPC read timeout while waiting for the daemon response.",
-        "The daemon may still be alive; do not blindly retry a non-idempotent command. Prefer a shorter command, split long waits, or retry with sessionMode: \"fresh\" after checking tab list.",
+        'The daemon may still be alive; do not blindly retry a non-idempotent command. Prefer a shorter command, split long waits, or retry with sessionMode: "fresh" after checking tab list.',
     ].join(" ");
 }
 function maybeAppendStaleRefHint(message, args) {
@@ -136,36 +134,65 @@ function maybeAppendStaleRefHint(message, args) {
     }
     return [
         message,
-        "This @ref may be stale after navigation, scrolling, or a DOM update. Run `agent_browser` with `{ \"args\": [\"snapshot\", \"-i\"] }` again and retry with a current ref, or use a stable `find` locator.",
+        'This @ref may be stale after navigation, scrolling, or a DOM update. Run `agent_browser` with `{ "args": ["snapshot", "-i"] }` again and retry with a current ref, or use a stable `find` locator.',
     ].join("\n");
 }
-export function getAgentBrowserErrorText(options) {
-    const { aborted, envelope, exitCode, parseError, plainTextInspection, spawnError, stderr, timedOut } = options;
-    if (plainTextInspection)
-        return undefined;
-    if (timedOut)
+function getTransportErrorText(options) {
+    if (options.timedOut === true) {
         return buildWatchdogTimeoutMessage(options);
-    if (aborted)
+    }
+    if (options.aborted) {
         return "agent-browser was aborted.";
-    if (spawnError)
-        return spawnError.message;
-    if (parseError)
-        return parseError;
-    if (envelope?.success === false) {
-        const explicitErrorText = extractEnvelopeErrorText(envelope.error);
-        if ((hasStructuredBatchStepFailure(envelope.data) || detectConfirmationRequired(envelope.data)) && explicitErrorText === undefined) {
-            return undefined;
-        }
-        const envelopeErrorText = explicitErrorText
-            ?? extractEnvelopeErrorText(typeof envelope.data === "string" ? envelope.data : isRecord(envelope.data) ? envelope.data.error : undefined);
-        if (envelopeErrorText && isUpstreamIpcReadTimeoutMessage(envelopeErrorText)) {
-            return buildUpstreamIpcReadTimeoutMessage();
-        }
-        const fallback = envelopeErrorText ?? (stderr.trim() || buildFailureFallback(options));
-        return maybeAppendStaleRefHint(fallback, options.staleRefArgs ?? options.effectiveArgs);
     }
-    if (exitCode !== 0) {
-        return stderr.trim() || buildExitCodeFallback(options);
+    if (options.spawnError) {
+        return options.spawnError.message;
+    }
+    if ((options.parseError ?? "") !== "") {
+        return options.exitCode !== 0 && options.stderr.trim().length > 0
+            ? options.stderr.trim()
+            : options.parseError;
+    }
+    return undefined;
+}
+function getEnvelopeDataError(data) {
+    if (typeof data === "string") {
+        return data;
+    }
+    return isRecord(data) ? data.error : undefined;
+}
+function getFailedEnvelopeFallback(options, errorText) {
+    const stderr = options.stderr.trim();
+    return errorText ?? (stderr.length > 0 ? stderr : buildFailureFallback(options));
+}
+function getFailedEnvelopeErrorText(options, envelope) {
+    const explicitErrorText = extractEnvelopeErrorText(envelope.error);
+    if ((hasStructuredBatchStepFailure(envelope.data) || detectConfirmationRequired(envelope.data)) &&
+        explicitErrorText === undefined) {
+        return undefined;
+    }
+    const envelopeErrorText = explicitErrorText ?? extractEnvelopeErrorText(getEnvelopeDataError(envelope.data));
+    if (envelopeErrorText !== undefined &&
+        envelopeErrorText.length > 0 &&
+        isUpstreamIpcReadTimeoutMessage(envelopeErrorText)) {
+        return buildUpstreamIpcReadTimeoutMessage();
+    }
+    const fallback = getFailedEnvelopeFallback(options, envelopeErrorText);
+    return maybeAppendStaleRefHint(fallback, options.staleRefArgs ?? options.effectiveArgs);
+}
+export function getAgentBrowserErrorText(options) {
+    if (options.plainTextInspection) {
+        return undefined;
+    }
+    const transportErrorText = getTransportErrorText(options);
+    if (transportErrorText !== undefined) {
+        return transportErrorText;
+    }
+    if (options.envelope?.success === false) {
+        return getFailedEnvelopeErrorText(options, options.envelope);
+    }
+    if (options.exitCode !== 0) {
+        const stderr = options.stderr.trim();
+        return stderr.length > 0 ? stderr : buildExitCodeFallback(options);
     }
     return undefined;
 }

package/dist/extensions/agent-browser/lib/results/evidence-contracts.js

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