pi-agent-browser-native 0.2.47 → 0.2.49

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

@@ -0,0 +1,166 @@
+/**
+ * Purpose: Parse upstream agent-browser output and turn failure envelopes into actionable error text.
+ * Responsibilities: Read inline or spilled stdout, parse observed JSON envelope shapes, normalize batch arrays, and extract the most useful error text from nested upstream failures.
+ * Scope: Envelope parsing and error derivation only; content rendering and snapshot compaction live in separate modules.
+ * Usage: Imported by the public `lib/results.ts` facade and by tests through that facade.
+ * Invariants/Assumptions: Upstream `agent-browser --json` responses follow the observed `{ success, data, error }` envelope shape or the array shape returned by `batch --json`.
+ */
+import { readFile } from "node:fs/promises";
+import { isRecord } from "../parsing.js";
+import { detectConfirmationRequired } from "./confirmation.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) {
+        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}`);
+    }
+}
+function extractEnvelopeErrorText(error) {
+    if (typeof error === "string") {
+        return error.trim() || 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);
+        return parts.length > 0 ? parts.join("\n") : undefined;
+    }
+    if (!isRecord(error)) {
+        return error == null ? undefined : stringifyUnknown(error);
+    }
+    for (const key of ["message", "error", "details", "cause", "stderr"]) {
+        const value = extractEnvelopeErrorText(error[key]);
+        if (value)
+            return value;
+    }
+    const fallback = stringifyUnknown(error).trim();
+    return fallback.length > 0 && fallback !== "{}" ? fallback : undefined;
+}
+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) };
+    }
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        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." };
+        }
+        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 };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { parseError: `agent-browser returned invalid JSON: ${message}` };
+    }
+}
+function buildInvocationLabel(options) {
+    if (options.effectiveArgs && options.effectiveArgs.length > 0) {
+        return `agent-browser ${options.effectiveArgs.join(" ")}`;
+    }
+    if (options.command && 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;
+}
+function buildFailureFallback(options) {
+    const invocation = buildInvocationLabel(options);
+    const exitSuffix = options.exitCode !== 0 ? ` (exit code ${options.exitCode})` : "";
+    return appendWrapperRecoveryHint(`${invocation} reported failure${exitSuffix}.`, options.wrapperRecoveryHint);
+}
+function buildExitCodeFallback(options) {
+    const invocation = buildInvocationLabel(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 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";
+    return [
+        `agent-browser exceeded ${timeoutText} and was stopped ${ipcTiming}.`,
+        "Prefer a condition wait or split long work into shorter calls; for legitimately long opens or captures, pass agent_browser timeoutMs with a bounded higher value and inspect details.timeoutPartialProgress before retrying.",
+    ].join(" ");
+}
+function isUpstreamIpcReadTimeoutMessage(message) {
+    return /Failed to read: Resource temporarily unavailable(?: \(os error \d+\))?.*daemon may be busy or unresponsive/i.test(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.",
+    ].join(" ");
+}
+function maybeAppendStaleRefHint(message, args) {
+    const usedRef = args?.some((arg) => /^@e\d+\b/.test(arg)) ?? false;
+    if (!usedRef || !/could not locate element|element not found|no element/i.test(message)) {
+        return message;
+    }
+    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.",
+    ].join("\n");
+}
+export function getAgentBrowserErrorText(options) {
+    const { aborted, envelope, exitCode, parseError, plainTextInspection, spawnError, stderr, timedOut } = options;
+    if (plainTextInspection)
+        return undefined;
+    if (timedOut)
+        return buildWatchdogTimeoutMessage(options);
+    if (aborted)
+        return "agent-browser was aborted.";
+    if (spawnError)
+        return spawnError.message;
+    if (parseError)
+        return parseError;
+    if (envelope?.success === false) {
+        if ((hasStructuredBatchStepFailure(envelope.data) || detectConfirmationRequired(envelope.data)) && envelope.error === undefined) {
+            return undefined;
+        }
+        const envelopeErrorText = extractEnvelopeErrorText(envelope.error);
+        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);
+    }
+    return undefined;
+}

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

@@ -0,0 +1,92 @@
+import { isRecord } from "../parsing.js";
+import { redactSensitiveText } from "../runtime.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)
+        return true;
+    if (pattern.includes("*")) {
+        const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+        return new RegExp(`^${escaped}$`).test(url);
+    }
+    return pattern.length >= 4 && url.includes(pattern);
+}
+function getSafeRequestId(item) {
+    const requestId = getStringRecordField(item, "requestId") ?? getStringRecordField(item, "id");
+    if (!requestId || redactSensitiveText(requestId) !== requestId)
+        return undefined;
+    return requestId;
+}
+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))
+        return "cors-likely-routed-request";
+    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"))
+        return "unfulfilled-routed-request";
+    return undefined;
+}
+export function getNetworkRouteMode(args) {
+    if (args.includes("--abort"))
+        return "abort";
+    if (args.includes("--body"))
+        return "body";
+    return "handler";
+}
+export function applyNetworkRouteRecords(routes, commandTokens, succeeded) {
+    if (!succeeded || commandTokens?.[0] !== "network")
+        return routes;
+    const subcommand = commandTokens[1];
+    if (subcommand !== "route" && subcommand !== "unroute")
+        return routes;
+    const existing = routes ?? [];
+    const pattern = commandTokens[2];
+    if (subcommand === "route" && pattern)
+        return [...existing.filter((route) => route.pattern !== pattern), { mode: getNetworkRouteMode(commandTokens), pattern }];
+    if (!pattern)
+        return undefined;
+    const next = existing.filter((route) => route.pattern !== pattern);
+    return next.length > 0 ? next : undefined;
+}
+export function buildNetworkRouteDiagnostics(data, routes) {
+    if (!routes || routes.length === 0 || !isRecord(data))
+        return undefined;
+    const requests = getArrayField(data, "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}.`,
+        });
+    }
+    return diagnostics.length > 0 ? diagnostics.slice(0, 5) : undefined;
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Purpose: Classify failed network requests into actionable vs benign diagnostics.
+ * Responsibilities: Recognize failed request rows, de-prioritize browser icon misses, and summarize failure counts.
+ * Scope: Network diagnostic classification only.
+ * Usage: QA preset analysis and presentation network summaries.
+ * Invariants/Assumptions: Browser favicon/apple-touch icon misses are warnings; API/document/script failures are actionable.
+ */
+import { isRecord } from "../parsing.js";
+export function getStringRecordField(value, key) {
+    const field = value[key];
+    return typeof field === "string" && field.trim().length > 0 ? field.trim() : undefined;
+}
+export function getNetworkRequestUrlPath(url) {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        const withoutQuery = url.split(/[?#]/, 1)[0];
+        return withoutQuery.length > 0 ? withoutQuery : undefined;
+    }
+}
+function isFailedNetworkRequest(request) {
+    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();
+    return /^data:image\//i.test(url) || (url.startsWith("data:") && resourceType.includes("image"));
+}
+function isBenignAssetFailure(request, url, resourceType) {
+    const path = getNetworkRequestUrlPath(url);
+    if (!path)
+        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/"));
+}
+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);
+}
+export function classifyNetworkRequestFailure(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 };
+}
+export function summarizeNetworkFailures(requests) {
+    const failures = requests.flatMap((request) => {
+        if (!isRecord(request) || isNetworkArtifactNoiseRequest(request))
+            return [];
+        const classification = classifyNetworkRequestFailure(request);
+        return classification ? [classification] : [];
+    });
+    const benignCount = failures.filter((failure) => failure.impact === "benign").length;
+    return {
+        actionableCount: failures.length - benignCount,
+        benignCount,
+        failures,
+        totalCount: failures.length,
+    };
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Purpose: Own machine-readable agent_browser next-action contracts and merge policy.
+ * Responsibilities: Define the stable nextAction shape, build basic argv follow-ups, and provide deterministic action-list collection helpers.
+ * Scope: Result follow-up action mechanics only; command-specific recovery and artifact policies live in neighboring modules.
+ * Usage: Imported by result presentation helpers and the extension entrypoint when attaching details.nextActions.
+ * Invariants/Assumptions: Action ids are stable machine-readable contracts; dedupe preserves first occurrence order.
+ */
+export function withOptionalSessionArgs(sessionName, args) {
+    return sessionName && args[0] !== "--session" ? ["--session", sessionName, ...args] : args;
+}
+export function buildNextToolAction(options) {
+    return {
+        id: options.id,
+        params: {
+            args: options.args,
+            ...(options.sessionMode ? { sessionMode: options.sessionMode } : {}),
+            ...(options.stdin ? { stdin: options.stdin } : {}),
+        },
+        reason: options.reason,
+        ...(options.safety ? { safety: options.safety } : {}),
+        tool: "agent_browser",
+    };
+}
+export function appendUniqueAgentBrowserNextActions(target, additions) {
+    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))
+            continue;
+        target.push(action);
+        existingIds.add(action.id);
+    }
+    return target;
+}
+export function isStandaloneSnapshotNextAction(action) {
+    const args = action.params?.args;
+    if (!args || action.params?.stdin)
+        return false;
+    const commandIndex = args[0] === "--session" ? 2 : 0;
+    return args[commandIndex] === "snapshot";
+}
+export function alignPageChangeSummaryNextActionIds(summary, 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 };
+}
+export class AgentBrowserNextActionCollector {
+    actions;
+    constructor(initialActions = undefined) {
+        this.actions = initialActions ? [...initialActions] : [];
+    }
+    append(actions) {
+        if (!actions || actions.length === 0)
+            return;
+        this.actions.push(...actions);
+    }
+    appendUnique(actions) {
+        appendUniqueAgentBrowserNextActions(this.actions, actions);
+    }
+    replace(actions) {
+        this.actions = actions ? [...actions] : [];
+    }
+    removeWhere(predicate) {
+        this.actions = this.actions.filter((action) => !predicate(action));
+    }
+    toArray() {
+        return this.actions.length > 0 ? [...this.actions] : undefined;
+    }
+}