pi-agent-browser-native 0.2.30 → 0.2.32

package/extensions/agent-browser/lib/results/presentation.ts

@@ -96,6 +96,10 @@ const DIAGNOSTIC_REQUEST_PREVIEW_LIMIT = 40;
 const DIAGNOSTIC_LOG_PREVIEW_LIMIT = 80;
 const NETWORK_BODY_PREVIEW_MAX_CHARS = 280;
 const NETWORK_ERROR_PREVIEW_MAX_CHARS = 220;
+const NETWORK_NEXT_ACTION_LIMIT = 4;
+const NETWORK_FILTER_MAX_CHARS = 160;
+const NETWORK_FILTER_SENSITIVE_SEGMENT_TERMS = ["apikey", "api-key", "api_key", "authentication", "authorization", "bearer", "credential", "credentials", "jwt", "passwd", "password", "reset", "secret", "session", "token"] as const;
+const NETWORK_FILTER_OPAQUE_SEGMENT_PATTERN = /^(?:[A-Fa-f0-9]{16,}|(?=.*[A-Za-z])(?=.*\d)[A-Za-z0-9_-]{16,})$/;
 const NETWORK_PREVIEW_FIELD_CANDIDATES = {
 	request: ["postData"] as const,
 	response: ["responseBody"] as const,
@@ -641,6 +645,145 @@ function formatNetworkRequestText(data: Record<string, unknown>): string | undef
 	return formatNetworkRequestLine(data, 0).join("\n");
 }
 
+interface NetworkRequestActionCandidate {
+	filter?: string;
+	item: Record<string, unknown>;
+	kind: "actionable" | "api" | "benign" | "request";
+	requestId: string;
+}
+
+function getSafeNetworkActionValue(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0 || redactSensitiveText(trimmed) !== trimmed) return undefined;
+	return trimmed;
+}
+
+function getNetworkRequestId(item: Record<string, unknown>): string | undefined {
+	return getSafeNetworkActionValue(getStringField(item, "requestId") ?? getStringField(item, "id"));
+}
+
+function isSensitiveNetworkPathSegment(segment: string): boolean {
+	const normalized = segment.toLowerCase();
+	return normalized === "auth" || NETWORK_FILTER_SENSITIVE_SEGMENT_TERMS.some((term) => normalized.includes(term));
+}
+
+function pathFilterMayExposeSensitiveSegment(filter: string): boolean {
+	const decoded = (() => {
+		try {
+			return decodeURIComponent(filter);
+		} catch {
+			return filter;
+		}
+	})();
+	return decoded.split("/").some((segment) => isSensitiveNetworkPathSegment(segment) || NETWORK_FILTER_OPAQUE_SEGMENT_PATTERN.test(segment));
+}
+
+function getNetworkRequestPathFilter(item: Record<string, unknown>): string | undefined {
+	const url = getStringField(item, "url");
+	if (!url) return undefined;
+	let filter: string | undefined;
+	try {
+		filter = new URL(url).pathname;
+	} catch {
+		filter = url.split(/[?#]/, 1)[0];
+	}
+	filter = filter?.trim();
+	if (!filter || filter === "/" || filter.length > NETWORK_FILTER_MAX_CHARS || pathFilterMayExposeSensitiveSegment(filter)) return undefined;
+	return getSafeNetworkActionValue(filter);
+}
+
+function isApiLikeNetworkRequest(item: Record<string, unknown>): boolean {
+	const method = (getStringField(item, "method") ?? "GET").toUpperCase();
+	const resourceType = (getStringField(item, "resourceType") ?? "").toLowerCase();
+	const mimeType = (getStringField(item, "mimeType") ?? "").toLowerCase();
+	const filter = getNetworkRequestPathFilter(item) ?? "";
+	return resourceType === "fetch" || resourceType === "xhr" || mimeType.includes("json") || /\/(?:api|graphql|rpc)(?:\/|$)/i.test(filter) || !["GET", "HEAD"].includes(method);
+}
+
+function getNetworkRequestActionCandidate(item: Record<string, unknown>): NetworkRequestActionCandidate | undefined {
+	const requestId = getNetworkRequestId(item);
+	if (!requestId) return undefined;
+	const classification = classifyNetworkRequestFailure(item);
+	const kind: NetworkRequestActionCandidate["kind"] = classification?.impact === "actionable"
+		? "actionable"
+		: classification?.impact === "benign"
+			? "benign"
+			: isApiLikeNetworkRequest(item)
+				? "api"
+				: "request";
+	return { filter: getNetworkRequestPathFilter(item), item, kind, requestId };
+}
+
+function chooseNetworkRequestActionCandidate(candidates: NetworkRequestActionCandidate[]): NetworkRequestActionCandidate | undefined {
+	return candidates.find((candidate) => candidate.kind === "actionable")
+		?? candidates.find((candidate) => candidate.kind === "api")
+		?? candidates.find((candidate) => candidate.kind === "benign")
+		?? candidates[0];
+}
+
+function formatNetworkRequestActionDescriptor(candidate: NetworkRequestActionCandidate): string {
+	const method = getStringField(candidate.item, "method") ?? "GET";
+	const status = typeof candidate.item.status === "number" ? String(candidate.item.status) : "pending";
+	const target = candidate.filter ? ` ${candidate.filter}` : "";
+	return `${status} ${method}${target} [${candidate.requestId}]`;
+}
+
+function getNetworkRequestDetailActionId(candidate: NetworkRequestActionCandidate): string {
+	if (candidate.kind === "actionable") return "inspect-actionable-network-request";
+	if (candidate.kind === "benign") return "inspect-benign-network-request";
+	return "inspect-network-request";
+}
+
+function buildNetworkRequestsNextActions(data: unknown, sessionName: string | undefined): AgentBrowserNextAction[] | undefined {
+	if (!isRecord(data)) return undefined;
+	const requests = getArrayField(data, "requests");
+	if (!requests) return undefined;
+	const candidates = requests.flatMap((item) => {
+		if (!isRecord(item)) return [];
+		const candidate = getNetworkRequestActionCandidate(item);
+		return candidate ? [candidate] : [];
+	});
+	const selected = chooseNetworkRequestActionCandidate(candidates);
+	if (!selected) return undefined;
+	const descriptor = formatNetworkRequestActionDescriptor(selected);
+	const actions: AgentBrowserNextAction[] = [
+		{
+			id: getNetworkRequestDetailActionId(selected),
+			params: { args: withSessionPrefix(sessionName, ["network", "request", selected.requestId]) },
+			reason: `Inspect full request details for ${descriptor}.`,
+			safety: "Read-only network diagnostic; request inspection must not replace the active page/ref context.",
+			tool: "agent_browser",
+		},
+	];
+	if (selected.kind === "actionable") {
+		actions.push({
+			id: "trace-actionable-network-source",
+			params: { networkSourceLookup: { requestId: selected.requestId, ...(sessionName ? { session: sessionName } : {}) } },
+			reason: `Look for local source candidates related to ${descriptor}.`,
+			safety: "Read-only experimental helper; it reports bounded candidates and may miss bundled or dynamic call sites.",
+			tool: "agent_browser",
+		});
+	}
+	if (selected.filter) {
+		actions.push({
+			id: "filter-network-requests-by-path",
+			params: { args: withSessionPrefix(sessionName, ["network", "requests", "--filter", selected.filter]) },
+			reason: `List captured requests matching ${selected.filter}.`,
+			safety: "Read-only request-list filter; absence from a compact preview is not proof the request did not happen.",
+			tool: "agent_browser",
+		});
+	}
+	actions.push({
+		id: "start-network-har-capture",
+		params: { args: withSessionPrefix(sessionName, ["network", "har", "start"]) },
+		reason: "Start HAR capture before reproducing the network behavior again.",
+		safety: "HARs can contain URLs and headers; stop to an explicit path, inspect metadata, and avoid sharing sensitive captures.",
+		tool: "agent_browser",
+	});
+	return actions.slice(0, NETWORK_NEXT_ACTION_LIMIT);
+}
+
 function formatConsoleText(data: Record<string, unknown>): string | undefined {
 	const messages = getArrayField(data, "messages");
 	if (!messages) return undefined;
@@ -1561,6 +1704,33 @@ function buildUnknownCommandSuggestionActions(suggestions: CommandSuggestion[],
 	return actions.length > 0 ? actions : undefined;
 }
 
+function isWaitTextAssertionCommand(command: string[] | undefined): boolean {
+	return command?.[0] === "wait" && command.includes("--text");
+}
+
+function buildWaitTextAssertionFailureNextAction(sessionName: string | undefined): AgentBrowserNextAction {
+	return {
+		id: "inspect-after-text-assertion-failure",
+		params: { args: withSessionPrefix(sessionName, ["snapshot", "-i"]) },
+		reason: "Inspect the current page after the text assertion failed before concluding the expected text is absent.",
+		safety: "Read-only snapshot; use current refs or visible text from this page before retrying the assertion.",
+		tool: "agent_browser",
+	};
+}
+
+function mergePresentationNextActions(...groups: Array<AgentBrowserNextAction[] | undefined>): AgentBrowserNextAction[] | undefined {
+	const actions: AgentBrowserNextAction[] = [];
+	const seen = new Set<string>();
+	for (const group of groups) {
+		for (const action of group ?? []) {
+			if (seen.has(action.id)) continue;
+			actions.push(action);
+			seen.add(action.id);
+		}
+	}
+	return actions.length > 0 ? actions : undefined;
+}
+
 function appendSelectorRecoveryHint(errorText: string): string {
 	const hint = getSelectorRecoveryHint(errorText);
 	if (!hint || errorText.includes("Agent-browser hint:")) {
@@ -1642,13 +1812,16 @@ async function buildBatchStepPresentation(options: {
 			errorText,
 		});
 		const confirmationRequired = detectConfirmationRequired(item.error);
-		const nextActions = buildAgentBrowserNextActions({
-			args: command,
-			command: command?.[0],
-			confirmationId: confirmationRequired?.id,
-			failureCategory,
-			resultCategory: "failure",
-		});
+		const nextActions = mergePresentationNextActions(
+			buildAgentBrowserNextActions({
+				args: command,
+				command: command?.[0],
+				confirmationId: confirmationRequired?.id,
+				failureCategory,
+				resultCategory: "failure",
+			}),
+			isWaitTextAssertionCommand(command) ? [buildWaitTextAssertionFailureNextAction(sessionName)] : undefined,
+		);
 		const presentation: ToolPresentation = {
 			content: [{ type: "text", text: errorText }],
 			failureCategory,
@@ -1694,7 +1867,7 @@ async function buildBatchStepPresentation(options: {
 		secondaryPaths: presentation.imagePaths,
 	});
 	const text = getPresentationText(presentation) || presentation.summary;
-	const nextActions = buildAgentBrowserNextActions({
+	const nextActions = presentation.nextActions ?? buildAgentBrowserNextActions({
 		artifacts: presentation.artifacts,
 		args: command,
 		command: command?.[0],
@@ -2129,6 +2302,11 @@ function buildSpillArtifactEntries(options: {
 	];
 }
 
+function mergeNextActions(...groups: Array<AgentBrowserNextAction[] | undefined>): AgentBrowserNextAction[] | undefined {
+	const merged = groups.flatMap((group) => group ?? []);
+	return merged.length > 0 ? merged : undefined;
+}
+
 async function compactLargePresentationOutput(options: {
 	artifactManifest?: SessionArtifactManifest;
 	commandInfo: CommandInfo;
@@ -2321,7 +2499,7 @@ export async function buildToolPresentation(options: {
 			savedFile: presentationWithManifest.savedFile,
 		});
 	}
-	presentationWithManifest.nextActions = presentationWithManifest.nextActions ?? buildAgentBrowserNextActions({
+	const genericNextActions = presentationWithManifest.nextActions ? undefined : buildAgentBrowserNextActions({
 		artifacts: presentationWithManifest.artifacts,
 		args,
 		command: commandInfo.command,
@@ -2331,6 +2509,10 @@ export async function buildToolPresentation(options: {
 		savedFilePath: presentationWithManifest.savedFilePath,
 		successCategory: presentationWithManifest.successCategory,
 	});
+	const networkNextActions = commandInfo.command === "network" && commandInfo.subcommand === "requests" && presentationWithManifest.resultCategory === "success"
+		? buildNetworkRequestsNextActions(data, sessionName)
+		: undefined;
+	presentationWithManifest.nextActions = mergeNextActions(presentationWithManifest.nextActions, genericNextActions, networkNextActions);
 	presentationWithManifest.pageChangeSummary = presentationWithManifest.pageChangeSummary ?? buildPageChangeSummary({
 		artifacts: presentationWithManifest.artifacts,
 		commandInfo,

package/extensions/agent-browser/lib/results/shared.ts

@@ -25,10 +25,12 @@ export type AgentBrowserSuccessCategory = "artifact-saved" | "artifact-unverifie
 
 export type AgentBrowserFailureCategory =
 	| "aborted"
+	| "cleanup-failed"
 	| "confirmation-required"
 	| "download-not-verified"
 	| "missing-binary"
 	| "parse-failure"
+	| "policy-blocked"
 	| "qa-failure"
 	| "selector-not-found"
 	| "selector-unsupported"
@@ -59,7 +61,19 @@ export interface AgentBrowserNextAction {
 	artifactPath?: string;
 	id: string;
 	params?: {
-		args: string[];
+		args?: string[];
+		electron?: {
+			action: "cleanup" | "list" | "launch" | "probe" | "status";
+			all?: boolean;
+			handoff?: "connect" | "snapshot" | "tabs";
+			launchId?: string;
+		};
+		networkSourceLookup?: {
+			filter?: string;
+			requestId?: string;
+			session?: string;
+			url?: string;
+		};
 		sessionMode?: "auto" | "fresh";
 		stdin?: string;
 	};
@@ -353,6 +367,8 @@ export function classifyAgentBrowserFailureCategory(options: {
 	if (/ENOENT|not found on PATH|could not find.*agent-browser|agent-browser is required but was not found/i.test(text)) return "missing-binary";
 	if (options.parseError || /invalid JSON|missing boolean success|success field must be boolean|returned no JSON output/i.test(text)) return "parse-failure";
 	if (/aborted/i.test(text)) return "aborted";
+	if (/policy[- ]blocked|blocked by caller policy|caller deny policy|caller allow policy/i.test(text)) return "policy-blocked";
+	if (/cleanup failed|cleanup.*partial|partial cleanup|remaining resources/i.test(text)) return "cleanup-failed";
 	if (options.tabDrift || /could not re-select the intended tab|about:blank|selected tab looks wrong|tab drift|tab.*wrong/i.test(text)) return "tab-drift";
 	if (/\bUnknown ref\b|\bstale ref\b|@ref may be stale|\bref\b.*\b(?:not found|missing|expired)\b/i.test(text)) return "stale-ref";
 	if (usedRef && /could not locate element|element not found|no element/i.test(text)) return "stale-ref";
@@ -418,6 +434,22 @@ function buildArtifactVerificationAction(artifact: FileArtifactMetadata): AgentB
 	};
 }
 
+function buildElectronToolAction(options: {
+	action: "cleanup" | "probe" | "status";
+	id: string;
+	launchId: string;
+	reason: string;
+	safety?: string;
+}): AgentBrowserNextAction {
+	return {
+		id: options.id,
+		params: { electron: { action: options.action, launchId: options.launchId } },
+		reason: options.reason,
+		...(options.safety ? { safety: options.safety } : {}),
+		tool: "agent_browser",
+	};
+}
+
 const MUTATING_COMMANDS = new Set([
 	"back",
 	"check",
@@ -459,12 +491,74 @@ export function buildAgentBrowserNextActions(options: {
 	args?: string[];
 	command?: string;
 	confirmationId?: string;
+	electron?: {
+		launchId?: string;
+		sessionName?: string;
+		status?: "active" | "cleaned" | "dead" | "failed" | "partial" | "succeeded";
+	};
 	failureCategory?: AgentBrowserFailureCategory;
 	resultCategory: AgentBrowserResultCategory;
 	savedFilePath?: string;
 	successCategory?: AgentBrowserSuccessCategory;
 }): AgentBrowserNextAction[] | undefined {
 	const actions: AgentBrowserNextAction[] = [];
+	if (options.electron?.launchId) {
+		const { launchId, sessionName, status } = options.electron;
+		if (options.resultCategory === "success" && status !== "cleaned") {
+			actions.push(
+				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.",
+				}),
+			);
+			if (sessionName) {
+				actions.push(
+					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.",
+					}),
+				);
+			}
+		} else if (options.resultCategory === "failure" && options.failureCategory === "cleanup-failed") {
+			actions.push(
+				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.",
+				}),
+			);
+		}
+	}
 	if (options.resultCategory === "success") {
 		if (options.command === "open") {
 			actions.push(buildNextToolAction({

package/extensions/agent-browser/lib/temp.ts

@@ -390,6 +390,32 @@ export async function writeSecureTempFile(options: {
 	return path;
 }
 
+export async function createSecureTempDirectory(prefix: string): Promise<string> {
+	const tempRoot = await getSessionTempRoot();
+	await assertSecureTempRootBudget(tempRoot, 0);
+	const directory = await mkdtemp(join(tempRoot, prefix));
+	await chmod(directory, 0o700).catch(() => undefined);
+	await refreshSecureTempRootLease(tempRoot).catch(() => undefined);
+	return directory;
+}
+
+export async function getSecureTempChildDirectoryValidationError(path: string, childPrefix: string): Promise<string | undefined> {
+	const parentDirectory = dirname(path);
+	const childName = path.slice(parentDirectory.length + 1);
+	if (!childName.startsWith(childPrefix)) {
+		return `Refusing to remove ${path}; expected wrapper temp child prefix ${childPrefix}.`;
+	}
+	const ownershipMarker = await readTempRootOwnershipMarker(parentDirectory);
+	if (!ownershipMarker) {
+		return `Refusing to remove ${path}; parent directory is not a pi-agent-browser owned temp root.`;
+	}
+	const currentUid = getCurrentProcessUid();
+	if (currentUid !== undefined && ownershipMarker.ownerUid !== undefined && ownershipMarker.ownerUid !== currentUid) {
+		return `Refusing to remove ${path}; parent temp root is owned by uid ${ownershipMarker.ownerUid}, not current uid ${currentUid}.`;
+	}
+	return undefined;
+}
+
 export async function writePersistentSessionArtifactFile(options: {
 	content: string | Uint8Array;
 	prefix: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -38,6 +38,7 @@
     "LICENSE",
     "docs/ARCHITECTURE.md",
     "docs/COMMAND_REFERENCE.md",
+    "docs/ELECTRON.md",
     "docs/RELEASE.md",
     "docs/REQUIREMENTS.md",
     "docs/SUPPORT_MATRIX.md",
@@ -55,9 +56,9 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.75.3",
-    "@earendil-works/pi-coding-agent": "^0.75.3",
-    "@earendil-works/pi-tui": "^0.75.3",
+    "@earendil-works/pi-ai": "^0.75.4",
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@earendil-works/pi-tui": "^0.75.4",
     "@types/node": "^25.6.1",
     "tsx": "^4.21.0",
     "typebox": "^1.1.38",