pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,180 @@
+import { isOpenNavigationCommand } from "../command-taxonomy.js";
+import { buildInspectOverlayStateAction, buildNextToolAction } from "./next-actions.js";
+import { AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS } from "./recovery-actions.js";
+import { buildMissingArtifactNextActions } from "./artifact-recommendations.js";
+function getExplicitDownloadWaitPath(args) {
+    const candidate = args.at(args.indexOf("--download") + 1);
+    return candidate !== undefined && candidate.length > 0 && !candidate.startsWith("-")
+        ? candidate
+        : undefined;
+}
+function getDownloadRetryPath(args, fallback) {
+    if (fallback !== undefined && fallback.length > 0) {
+        return fallback;
+    }
+    if (!args || args.length === 0) {
+        return undefined;
+    }
+    if (args.includes("--download")) {
+        return getExplicitDownloadWaitPath(args);
+    }
+    const downloadCommandIndex = args.indexOf("download");
+    return downloadCommandIndex >= 0 && args.length > downloadCommandIndex + 2
+        ? args.at(-1)
+        : undefined;
+}
+function buildConfirmationActions(id) {
+    if (id === undefined || id.length === 0) {
+        return [];
+    }
+    return [
+        buildNextToolAction({
+            args: ["confirm", id],
+            id: "approve-confirmation",
+            reason: "Approve the pending upstream confirmation when the requested action is safe.",
+            safety: "Only confirm after reviewing the guarded action shown in the result.",
+        }),
+        buildNextToolAction({
+            args: ["deny", id],
+            id: "deny-confirmation",
+            reason: "Deny the pending upstream confirmation when the guarded action is unsafe or unintended.",
+        }),
+    ];
+}
+function buildDownloadFailureActions(options) {
+    const path = getDownloadRetryPath(options.args, options.savedFilePath);
+    return [
+        buildNextToolAction({
+            args: path !== undefined && path.length > 0
+                ? ["wait", "--download", path]
+                : ["wait", "--download"],
+            id: "wait-for-download",
+            reason: "Wait for the browser download and let the wrapper verify saved-file metadata.",
+            safety: "Use an explicit wait timeout; if you set top-level timeoutMs, keep it above the wait duration plus a small grace window.",
+        }),
+    ];
+}
+function getTimeoutInspectionReason(command, textAssertion) {
+    if (textAssertion) {
+        return "Inspect the current page after the text assertion failed before concluding the expected text is absent.";
+    }
+    return command === "wait"
+        ? "Inspect the current page after the wait condition timed out before retrying with a different selector or timeout."
+        : "Inspect the current page after the timed-out browser operation.";
+}
+function buildTimeoutActions(options) {
+    if (options.command === "session" && options.subcommand === "info") {
+        return [
+            buildNextToolAction({
+                args: ["session", "info"],
+                id: "retry-session-info",
+                reason: "Retry the same session status check without opening a browser or inspecting its page.",
+            }),
+        ];
+    }
+    const textAssertion = options.command === "wait" && options.args?.includes("--text") === true;
+    const urlAssertion = options.command === "wait" && options.args?.includes("--url") === true;
+    const actions = [
+        buildNextToolAction({
+            args: ["snapshot", "-i"],
+            id: textAssertion ? "inspect-after-text-assertion-failure" : "inspect-after-timeout",
+            reason: getTimeoutInspectionReason(options.command, textAssertion),
+            safety: textAssertion
+                ? "Read-only snapshot; use current refs or visible text from this page before retrying the assertion."
+                : "Read-only snapshot; do not assume the timed-out interaction completed.",
+        }),
+    ];
+    if (urlAssertion) {
+        actions.push(buildNextToolAction({
+            args: ["open", "about:blank"],
+            id: "fresh-session-after-url-wait-timeout",
+            reason: "If a preceding click or form submit reported success but the page never navigated, upstream click dispatch may have silently missed (observed with agent-browser 0.34 after many spaced commands); replace about:blank with the target URL and replay the flow as one batch in a fresh session instead of retrying the wait.",
+            safety: "Abandons the current browser session; capture page evidence with the inspect action first, and only abandon when the wait target is not simply wrong or slow.",
+            sessionMode: "fresh",
+        }));
+    }
+    return actions;
+}
+function buildUpstreamFailureActions(options) {
+    if (options.overlayBlockedClick === true) {
+        return [buildInspectOverlayStateAction(options.sessionName)];
+    }
+    return isOpenNavigationCommand(options.command)
+        ? [
+            buildNextToolAction({
+                args: ["get", "url"],
+                id: "inspect-page-after-navigation-error",
+                reason: "Check which page, if any, remains active after the navigation or network error.",
+                safety: "Read-only URL inspection; verify connectivity and the target URL before retrying navigation.",
+            }),
+        ]
+        : [];
+}
+function buildTabGoneActions() {
+    return [
+        buildNextToolAction({
+            args: ["tab", "list"],
+            id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.tabGoneListTabs,
+            reason: "The pinned bound tab is gone; inspect remaining tabs before acting on a neighbor.",
+            safety: "Read-only. Prefer a listed tab id, label, or CDP targetId, or open a new tab to rebind.",
+        }),
+        buildNextToolAction({
+            args: ["tab", "new"],
+            id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.tabGoneNewTab,
+            reason: "Bind a fresh tab after tab_gone instead of continuing on another session's page.",
+            safety: "Opens a new tab in this session and rebinds the pin; pass a URL if you know the intended page.",
+        }),
+    ];
+}
+function buildTabDriftActions(options) {
+    if (options.recovery?.kind === "about-blank" || options.recovery?.kind === "tab-drift") {
+        return [];
+    }
+    return [
+        buildNextToolAction({
+            args: ["tab", "list"],
+            id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.genericTabDriftListTabs,
+            reason: "Inspect available tabs before selecting the intended target.",
+            safety: "Read-only. Retry snapshot only after selecting or confirming the intended stable tab.",
+        }),
+    ];
+}
+export function buildFailureNextActions(options) {
+    switch (options.failureCategory) {
+        case "artifact-missing":
+            return buildMissingArtifactNextActions(options.artifacts);
+        case "confirmation-required":
+            return buildConfirmationActions(options.confirmationId);
+        case "stale-ref":
+        case "selector-not-found":
+        case "selector-unsupported":
+            return [
+                buildNextToolAction({
+                    args: ["snapshot", "-i"],
+                    id: "refresh-interactive-refs",
+                    reason: "Get current interactive refs before retrying the element action.",
+                    safety: "Prefer a current @ref or a stable find locator; do not retry stale refs blindly.",
+                }),
+            ];
+        case "download-not-verified":
+            return buildDownloadFailureActions(options);
+        case "timeout":
+            return buildTimeoutActions(options);
+        case "upstream-error":
+            return buildUpstreamFailureActions(options);
+        case "tab-gone":
+            return buildTabGoneActions();
+        case "tab-drift":
+            return buildTabDriftActions(options);
+        case "aborted":
+        case "cleanup-failed":
+        case "missing-binary":
+        case "parse-failure":
+        case "policy-blocked":
+        case "qa-failure":
+        case "script-error":
+        case "validation-error":
+        case undefined:
+            return [];
+    }
+}

package/dist/extensions/agent-browser/lib/results/network-routes.js

@@ -1,13 +1,14 @@
 import { isRecord } from "../parsing.js";
-import { redactSensitiveText } from "../runtime.js";
+import { redactSensitiveText } from "../runtime-redaction.js";
 import { getStringRecordField, isApiLikeNetworkRequest } from "./network.js";
 function getArrayField(data, key) {
     const value = data[key];
     return Array.isArray(value) ? value : undefined;
 }
 function networkRoutePatternMatchesUrl(pattern, url) {
-    if (pattern === url)
+    if (pattern === url) {
         return true;
+    }
     if (pattern.includes("*")) {
         const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
         return new RegExp(`^${escaped}$`).test(url);
@@ -16,77 +17,117 @@ function networkRoutePatternMatchesUrl(pattern, url) {
 }
 function getSafeRequestId(item) {
     const requestId = getStringRecordField(item, "requestId") ?? getStringRecordField(item, "id");
-    if (!requestId || redactSensitiveText(requestId) !== requestId)
+    if (requestId === undefined ||
+        requestId.length === 0 ||
+        redactSensitiveText(requestId) !== requestId) {
         return undefined;
+    }
     return requestId;
 }
+function routedRequestFailed(item, error) {
+    return ((typeof item.status === "number" && item.status >= 400) ||
+        item.failed === true ||
+        error !== undefined);
+}
 function getRouteDiagnosticReason(item, route) {
     const statusMissing = typeof item.status !== "number";
-    const error = getStringRecordField(item, "error") ?? getStringRecordField(item, "failureText") ?? getStringRecordField(item, "errorText");
-    if (error && /(?:cors|cross-origin|preflight|access-control-allow-origin)/i.test(error))
+    const error = getStringRecordField(item, "error") ??
+        getStringRecordField(item, "failureText") ??
+        getStringRecordField(item, "errorText");
+    if (error !== undefined &&
+        /(?:cors|cross-origin|preflight|access-control-allow-origin)/i.test(error)) {
         return "cors-likely-routed-request";
-    if (statusMissing && isApiLikeNetworkRequest(item))
+    }
+    if (statusMissing && isApiLikeNetworkRequest(item)) {
         return "pending-routed-request";
-    if (route.mode !== "abort" && ((typeof item.status === "number" && item.status >= 400) || item.failed === true || typeof error === "string"))
+    }
+    if (route.mode !== "abort" && routedRequestFailed(item, error)) {
         return "unfulfilled-routed-request";
+    }
     return undefined;
 }
 function getNetworkRouteMode(args) {
-    if (args.includes("--abort"))
+    if (args.includes("--abort")) {
         return "abort";
-    if (args.includes("--body"))
+    }
+    if (args.includes("--body")) {
         return "body";
+    }
     return "handler";
 }
 export function applyNetworkRouteRecords(routes, commandTokens, succeeded) {
-    if (!succeeded || commandTokens?.[0] !== "network")
+    if (!succeeded || commandTokens?.[0] !== "network") {
         return routes;
+    }
     const subcommand = commandTokens[1];
-    if (subcommand !== "route" && subcommand !== "unroute")
+    if (subcommand !== "route" && subcommand !== "unroute") {
         return routes;
+    }
+    return updateNetworkRoutes(routes, commandTokens);
+}
+function updateNetworkRoutes(routes, commandTokens) {
     const existing = routes ?? [];
-    const pattern = commandTokens[2];
-    if (subcommand === "route" && pattern)
-        return [...existing.filter((route) => route.pattern !== pattern), { mode: getNetworkRouteMode(commandTokens), pattern }];
-    if (!pattern)
+    const pattern = commandTokens.at(2);
+    if (commandTokens[1] === "route" && pattern !== undefined && pattern.length > 0) {
+        return [
+            ...existing.filter((route) => route.pattern !== pattern),
+            { mode: getNetworkRouteMode(commandTokens), pattern },
+        ];
+    }
+    if (pattern === undefined || pattern.length === 0) {
         return undefined;
+    }
     const next = existing.filter((route) => route.pattern !== pattern);
     return next.length > 0 ? next : undefined;
 }
+function formatNetworkRouteDiagnosticSummary(reason, request, pattern) {
+    switch (reason) {
+        case "cors-likely-routed-request":
+            return `Routed request ${request} looks CORS/preflight-related for route ${pattern}.`;
+        case "unfulfilled-routed-request":
+            return `Routed request ${request} failed instead of returning the configured route ${pattern}.`;
+        case "pending-routed-request":
+            return `Routed request ${request} is still pending/no-status for route ${pattern}.`;
+    }
+}
+function buildRoutedRequestDiagnostic(item, routes) {
+    if (!isRecord(item)) {
+        return undefined;
+    }
+    const url = getStringRecordField(item, "url");
+    if (url === undefined) {
+        return undefined;
+    }
+    const route = routes.find((candidate) => networkRoutePatternMatchesUrl(candidate.pattern, url));
+    if (!route) {
+        return undefined;
+    }
+    const reason = getRouteDiagnosticReason(item, route);
+    if (reason === undefined) {
+        return undefined;
+    }
+    const requestId = getSafeRequestId(item);
+    const requestUrl = redactSensitiveText(url);
+    const routePattern = redactSensitiveText(route.pattern);
+    return {
+        mode: route.mode,
+        reason,
+        ...(requestId !== undefined ? { requestId } : {}),
+        requestUrl,
+        routePattern,
+        summary: formatNetworkRouteDiagnosticSummary(reason, requestId ?? requestUrl, routePattern),
+    };
+}
 export function buildNetworkRouteDiagnostics(data, routes) {
-    if (!routes || routes.length === 0 || !isRecord(data))
+    if (!routes || routes.length === 0 || !isRecord(data)) {
         return undefined;
+    }
     const requests = getArrayField(data, "requests");
-    if (!requests)
+    if (!requests) {
         return undefined;
-    const diagnostics = [];
-    for (const item of requests) {
-        if (!isRecord(item))
-            continue;
-        const url = getStringRecordField(item, "url");
-        if (!url)
-            continue;
-        const route = routes.find((candidate) => networkRoutePatternMatchesUrl(candidate.pattern, url));
-        if (!route)
-            continue;
-        const reason = getRouteDiagnosticReason(item, route);
-        if (!reason)
-            continue;
-        const requestId = getSafeRequestId(item);
-        const requestUrl = redactSensitiveText(url);
-        const routePattern = redactSensitiveText(route.pattern);
-        diagnostics.push({
-            mode: route.mode,
-            reason,
-            ...(requestId ? { requestId } : {}),
-            requestUrl,
-            routePattern,
-            summary: reason === "cors-likely-routed-request"
-                ? `Routed request ${requestId ?? requestUrl} looks CORS/preflight-related for route ${routePattern}.`
-                : reason === "unfulfilled-routed-request"
-                    ? `Routed request ${requestId ?? requestUrl} failed instead of returning the configured route ${routePattern}.`
-                    : `Routed request ${requestId ?? requestUrl} is still pending/no-status for route ${routePattern}.`,
-        });
     }
+    const diagnostics = requests
+        .map((item) => buildRoutedRequestDiagnostic(item, routes))
+        .filter((item) => item !== undefined);
     return diagnostics.length > 0 ? diagnostics.slice(0, 5) : undefined;
 }

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

@@ -4,8 +4,9 @@ export function getStringRecordField(value, key) {
     return typeof field === "string" && field.trim().length > 0 ? field.trim() : undefined;
 }
 function getNetworkRequestUrlPath(url) {
-    if (!url)
+    if (url === undefined || url.length === 0) {
         return undefined;
+    }
     try {
         return new URL(url).pathname;
     }
@@ -15,44 +16,66 @@ function getNetworkRequestUrlPath(url) {
     }
 }
 function isFailedNetworkRequest(request) {
-    return (typeof request.status === "number" && request.status >= 400) || request.failed === true || typeof request.error === "string";
+    return ((typeof request.status === "number" && request.status >= 400) ||
+        request.failed === true ||
+        typeof request.error === "string");
 }
 export function isNetworkArtifactNoiseRequest(request) {
     const url = getStringRecordField(request, "url") ?? "";
-    const resourceType = (getStringRecordField(request, "resourceType") ?? getStringRecordField(request, "mimeType") ?? "").toLowerCase();
+    const resourceType = (getStringRecordField(request, "resourceType") ??
+        getStringRecordField(request, "mimeType") ??
+        "").toLowerCase();
     return /^data:image\//i.test(url) || (url.startsWith("data:") && resourceType.includes("image"));
 }
+function isIconResourceType(resourceType) {
+    const normalized = resourceType?.toLowerCase() ?? "";
+    return (normalized.length === 0 ||
+        ["image", "img", "other"].includes(normalized) ||
+        normalized.startsWith("image/"));
+}
 function isBenignAssetFailure(request, url, resourceType) {
     const path = getNetworkRequestUrlPath(url);
-    if (!path)
+    if (path === undefined || path.length === 0) {
         return false;
-    const normalizedResourceType = resourceType?.toLowerCase();
-    return /(?:^|\/)(?:favicon(?:[-.\w]*)?\.(?:ico|png|svg)|apple-touch-icon(?:[-.\w]*)?\.png)$/i.test(path)
-        && (request.status === 404 || request.failed === true || typeof request.error === "string")
-        && (!normalizedResourceType || ["image", "img", "other"].includes(normalizedResourceType) || normalizedResourceType.startsWith("image/"));
+    }
+    return (/(?:^|\/)(?:favicon(?:[-.\w]*)?\.(?:ico|png|svg)|apple-touch-icon(?:[-.\w]*)?\.png)$/i.test(path) &&
+        (request.status === 404 || request.failed === true || typeof request.error === "string") &&
+        isIconResourceType(resourceType));
 }
 export function isApiLikeNetworkRequest(request) {
     const method = (getStringRecordField(request, "method") ?? "GET").toUpperCase();
     const resourceType = (getStringRecordField(request, "resourceType") ?? "").toLowerCase();
     const mimeType = (getStringRecordField(request, "mimeType") ?? "").toLowerCase();
     const path = getNetworkRequestUrlPath(getStringRecordField(request, "url")) ?? "";
-    return resourceType === "fetch" || resourceType === "xhr" || mimeType.includes("json") || /\/(?:api|graphql|rpc)(?:\/|$)/i.test(path) || !["GET", "HEAD"].includes(method);
+    return (resourceType === "fetch" ||
+        resourceType === "xhr" ||
+        mimeType.includes("json") ||
+        /\/(?:api|graphql|rpc)(?:\/|$)/i.test(path) ||
+        !["GET", "HEAD"].includes(method));
 }
 export function classifyNetworkRequestFailure(request) {
-    if (!isFailedNetworkRequest(request))
+    if (!isFailedNetworkRequest(request)) {
         return undefined;
+    }
     const url = getStringRecordField(request, "url");
     const resourceType = getStringRecordField(request, "resourceType") ?? getStringRecordField(request, "mimeType");
     const status = typeof request.status === "number" ? request.status : undefined;
     if (isBenignAssetFailure(request, url, resourceType)) {
         return { impact: "benign", reason: "low-impact browser icon asset", resourceType, status, url };
     }
-    return { impact: "actionable", reason: "document, script, API, or non-benign request failure", resourceType, status, url };
+    return {
+        impact: "actionable",
+        reason: "document, script, API, or non-benign request failure",
+        resourceType,
+        status,
+        url,
+    };
 }
 export function summarizeNetworkFailures(requests) {
     const failures = requests.flatMap((request) => {
-        if (!isRecord(request) || isNetworkArtifactNoiseRequest(request))
+        if (!isRecord(request) || isNetworkArtifactNoiseRequest(request)) {
             return [];
+        }
         const classification = classifyNetworkRequestFailure(request);
         return classification ? [classification] : [];
     });

package/dist/extensions/agent-browser/lib/results/next-actions.js

@@ -1,33 +1,54 @@
 export function withOptionalNamespaceArgs(namespace, args) {
-    return namespace !== undefined && args[0] !== "--namespace" ? ["--namespace", namespace, ...args] : args;
+    return namespace !== undefined && args[0] !== "--namespace"
+        ? ["--namespace", namespace, ...args]
+        : args;
 }
 export function withOptionalSessionArgs(sessionName, args) {
-    if (!sessionName || args[0] === "--session" || (args[0] === "--namespace" && args[2] === "--session"))
+    if (sessionName === undefined ||
+        sessionName.length === 0 ||
+        args[0] === "--session" ||
+        (args[0] === "--namespace" && args[2] === "--session")) {
         return args;
-    if (args[0] === "--namespace" && args.length >= 2)
+    }
+    if (args[0] === "--namespace" && args.length >= 2) {
         return [args[0], args[1], "--session", sessionName, ...args.slice(2)];
+    }
     return ["--session", sessionName, ...args];
 }
 export function applyNamespaceToNextActions(actions, namespace) {
-    if (namespace === undefined || !actions)
+    if (namespace === undefined || !actions) {
         return actions;
+    }
     return actions.map((action) => {
         const args = action.params?.args;
-        if (args)
-            return { ...action, params: { ...action.params, args: withOptionalNamespaceArgs(namespace, args) } };
-        return action.tool === "agent_browser_network_source" ? { ...action, params: { ...action.params, namespace } } : action;
+        if (args) {
+            return {
+                ...action,
+                params: { ...action.params, args: withOptionalNamespaceArgs(namespace, args) },
+            };
+        }
+        return action.tool === "agent_browser_network_source"
+            ? { ...action, params: { ...action.params, namespace } }
+            : action;
     });
 }
 export function applySessionToNextActions(actions, sessionName) {
-    if (!sessionName || !actions)
+    if (sessionName === undefined || sessionName.length === 0 || !actions) {
         return actions;
+    }
     return actions.map((action) => {
         // Fresh-session actions deliberately target a new session; the planner ignores sessionMode when an
         // explicit --session is present, so prefixing one here would silently downgrade them to reuse.
-        if (action.params?.sessionMode === "fresh")
+        if (action.params?.sessionMode === "fresh") {
             return action;
+        }
         const args = action.params?.args;
-        return args ? { ...action, params: { ...action.params, args: withOptionalSessionArgs(sessionName, args) } } : action;
+        return args
+            ? {
+                ...action,
+                params: { ...action.params, args: withOptionalSessionArgs(sessionName, args) },
+            }
+            : action;
     });
 }
 export function buildNextToolAction(options) {
@@ -35,11 +56,13 @@ export function buildNextToolAction(options) {
         id: options.id,
         params: {
             args: options.args,
-            ...(options.sessionMode ? { sessionMode: options.sessionMode } : {}),
-            ...(options.stdin ? { stdin: options.stdin } : {}),
+            ...(options.sessionMode !== undefined ? { sessionMode: options.sessionMode } : {}),
+            ...(options.stdin !== undefined && options.stdin.length > 0 ? { stdin: options.stdin } : {}),
         },
         reason: options.reason,
-        ...(options.safety ? { safety: options.safety } : {}),
+        ...(options.safety !== undefined && options.safety.length > 0
+            ? { safety: options.safety }
+            : {}),
         tool: "agent_browser",
     };
 }
@@ -52,12 +75,14 @@ export function buildInspectOverlayStateAction(sessionName) {
     });
 }
 export function appendUniqueAgentBrowserNextActions(target, additions) {
-    if (!additions || additions.length === 0)
+    if (!additions || additions.length === 0) {
         return target;
+    }
     const existingIds = new Set(target.map((action) => action.id));
     for (const action of additions) {
-        if (existingIds.has(action.id))
+        if (existingIds.has(action.id)) {
             continue;
+        }
         target.push(action);
         existingIds.add(action.id);
     }
@@ -65,17 +90,22 @@ export function appendUniqueAgentBrowserNextActions(target, additions) {
 }
 export function isStandaloneSnapshotNextAction(action) {
     const args = action.params?.args;
-    if (!args || action.params?.stdin)
+    if (!args || (action.params.stdin !== undefined && action.params.stdin.length > 0)) {
         return false;
+    }
     let commandIndex = args[0] === "--namespace" ? 2 : 0;
-    if (args[commandIndex] === "--session")
+    if (args[commandIndex] === "--session") {
         commandIndex += 2;
+    }
     return args[commandIndex] === "snapshot";
 }
 export function alignPageChangeSummaryNextActionIds(summary, nextActions) {
-    if (!summary?.nextActionIds || !nextActions)
+    if (!summary?.nextActionIds || !nextActions) {
         return summary;
+    }
     const nextActionIds = new Set(nextActions.map((action) => action.id));
     const alignedIds = summary.nextActionIds.filter((id) => nextActionIds.has(id));
-    return alignedIds.length > 0 ? { ...summary, nextActionIds: alignedIds } : { ...summary, nextActionIds: undefined };
+    return alignedIds.length > 0
+        ? { ...summary, nextActionIds: alignedIds }
+        : { ...summary, nextActionIds: undefined };
 }