pi-agent-browser-native 0.2.43 → 0.2.45

package/extensions/agent-browser/lib/orchestration/browser-run/process-output.ts

@@ -7,6 +7,7 @@ import { getAllowedDomainsViolation, parseAllowedDomainsPolicyFromArgs } from ".
 import {
 	analyzeNetworkSourceLookupResults,
 	analyzeQaPresetResults,
+	analyzeQaPresetTimeout,
 	analyzeSourceLookupResults,
 	buildQaCompactPassText,
 	extractQaPageContext,
@@ -78,6 +79,7 @@ import {
 	collectNavigationSummary,
 	collectOverlayBlockerDiagnostic,
 	collectQaAttachedTarget,
+	collectSnapshotOverlayBlockerDiagnostic,
 	collectRecordingDependencyWarning,
 	collectScrollPositionSnapshot,
 	collectSelectorTextVisibilityDiagnostics,
@@ -159,6 +161,15 @@ function isStreamEnableAlreadyEnabledNoop(options: { command: string | undefined
 	return message === "streaming is already enabled for this session" || message === "streaming is already enabled" || message === "stream already enabled";
 }
 
+function batchStartedManagedBrowser(data: unknown): boolean {
+	if (!Array.isArray(data)) return false;
+	return data.some((entry) => {
+		if (!isRecord(entry) || entry.success !== true || !Array.isArray(entry.command)) return false;
+		const command = typeof entry.command[0] === "string" ? entry.command[0] : undefined;
+		return command === "connect" || command === "goto" || command === "navigate" || isOpenNavigationCommand(command);
+	});
+}
+
 function setNetworkRouteState(options: { routes?: NetworkRouteRecord[]; routesBySession: Map<string, NetworkRouteRecord[]>; sessionName: string | undefined }): Map<string, NetworkRouteRecord[]> {
 	if (!options.sessionName) return options.routesBySession;
 	const previousRoutes = options.routesBySession.get(options.sessionName);
@@ -351,11 +362,17 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		let selectorTextVisibilityDiagnostics: Awaited<ReturnType<typeof collectSelectorTextVisibilityDiagnostics>> = [];
 		let electronBroadGetTextScopeDiagnostics: ReturnType<typeof collectElectronBroadGetTextScopeDiagnostics> = [];
 		const timeoutPartialProgress = processResult.timedOut ? await collectTimeoutPartialProgress({ command: prepared.executionPlan.commandInfo.command, compiledJob: prepared.compiledJob, cwd, sessionName: prepared.executionPlan.sessionName, stdin: prepared.runtimeToolStdin }) : undefined;
+		if (succeeded) {
+			const fillRefSnapshot = prepared.resolvedSemanticActionRefSnapshot ?? prepared.priorRefSnapshotState;
+			fillVerificationDiagnostic = await collectFillVerificationDiagnostic({ commandTokens: prepared.commandTokens, cwd, forceValueVerification: electronRecordForCommand !== undefined, refSnapshot: fillRefSnapshot, sessionName: prepared.executionPlan.sessionName, signal });
+		}
 		if (succeeded && electronRecordForCommand) {
-			fillVerificationDiagnostic = await collectFillVerificationDiagnostic({ commandTokens: prepared.commandTokens, cwd, sessionName: prepared.executionPlan.sessionName, signal });
 			electronRefFreshnessDiagnostic = buildElectronRefFreshnessDiagnostic({ command: prepared.executionPlan.commandInfo.command, commandTokens: prepared.commandTokens, record: electronRecordForCommand, sessionName: prepared.executionPlan.sessionName, stdin: prepared.runtimeToolStdin });
 		}
-		if (succeeded && !sessionTabCorrection && !aboutBlankSessionMismatch && !electronRecordForCommand && !clickDispatchDiagnostic) overlayBlockerDiagnostic = await collectOverlayBlockerDiagnostic({ command: prepared.executionPlan.commandInfo.command, cwd, data: presentationEnvelope?.data, navigationSummary, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName, signal });
+		if (succeeded && prepared.executionPlan.commandInfo.command === "snapshot") {
+			overlayBlockerDiagnostic = collectSnapshotOverlayBlockerDiagnostic(presentationEnvelope?.data);
+		}
+		if (succeeded && !overlayBlockerDiagnostic && !sessionTabCorrection && !aboutBlankSessionMismatch && !electronRecordForCommand && !clickDispatchDiagnostic) overlayBlockerDiagnostic = await collectOverlayBlockerDiagnostic({ command: prepared.executionPlan.commandInfo.command, cwd, data: presentationEnvelope?.data, navigationSummary, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName, signal });
 		if (succeeded) {
 			selectorTextVisibilityDiagnostics = await collectSelectorTextVisibilityDiagnostics({ commandInfo: prepared.executionPlan.commandInfo, commandTokens: prepared.commandTokens, cwd, data: presentationEnvelope?.data, sessionName: prepared.executionPlan.sessionName, signal });
 			if (electronRecordForCommand) electronBroadGetTextScopeDiagnostics = collectElectronBroadGetTextScopeDiagnostics({ commandInfo: prepared.executionPlan.commandInfo, commandTokens: prepared.commandTokens, currentTarget: currentSessionTabTarget, data: presentationEnvelope?.data, electronLaunchRecords, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName });
@@ -403,7 +420,9 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 			? prepared.executionPlan.sessionName
 			: prepared.executionPlan.managedSessionName;
 		const policyBlockedFreshManagedSession = allowedDomainsViolation !== undefined && prepared.sessionMode === "fresh" && prepared.executionPlan.managedSessionName === prepared.executionPlan.sessionName;
-		const managedTransitionSucceeded = succeeded || policyBlockedFreshManagedSession;
+		const postLaunchBatchFailure = !succeeded && processSucceeded && parseSucceeded && prepared.sessionMode === "fresh" && prepared.executionPlan.commandInfo.command === "batch" && batchStartedManagedBrowser(presentationEnvelope?.data);
+		const postLaunchTimeoutWithPage = !succeeded && processResult.timedOut && prepared.sessionMode === "fresh" && prepared.executionPlan.commandInfo.command === "batch" && timeoutPartialProgress?.liveUrlRecovered === true;
+		const managedTransitionSucceeded = succeeded || policyBlockedFreshManagedSession || postLaunchBatchFailure || postLaunchTimeoutWithPage;
 		const managedSessionState = resolveManagedSessionState({ command: prepared.executionPlan.commandInfo.command, managedSessionName: managedCloseSessionName, priorActive: priorManagedSessionActive, priorSessionName: priorManagedSessionName, succeeded: managedTransitionSucceeded });
 		const replacedManagedSessionName = managedSessionState.replacedSessionName;
 		managedSessionActive = managedSessionState.active;
@@ -462,10 +481,16 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		}
 		const presentation = plainTextInspection ? { artifacts: undefined, batchFailure: undefined, batchSteps: undefined, content: [{ type: "text" as const, text: inspectionText ?? "" }], data: undefined, fullOutputPath: undefined, fullOutputPaths: undefined, imagePath: undefined, imagePaths: undefined, savedFile: undefined, savedFilePath: undefined, summary: `${prepared.redactedArgs.join(" ")} completed` } : await buildToolPresentation({ args: prepared.redactedProcessArgs, artifactManifest, artifactRequest: screenshotArtifactRequest, batchArtifactRequests: batchScreenshotArtifactRequests, commandInfo: prepared.executionPlan.commandInfo, compiledSemanticAction: prepared.compiledSemanticAction, cwd, envelope: presentationEnvelope, errorText, networkRouteDiagnostics, networkRoutes: activeNetworkRoutes, persistentArtifactStore, sessionName: prepared.executionPlan.sessionName });
 		networkRoutesBySession = applyBatchNetworkRouteState({ data: presentationEnvelope?.data, routesBySession: networkRoutesBySession, sessionName: prepared.executionPlan.sessionName, succeeded });
-		if (presentation.failureCategory === "artifact-missing") {
+		if (presentation.resultCategory === "failure" && succeeded) {
 			succeeded = false;
 			presentationEnvelope = { ...(presentationEnvelope ?? {}), error: presentation.summary, success: false };
 		}
+		if (scrollNoopDiagnostic) {
+			presentation.summary = "Scroll completed with no observed movement.";
+			if (isRecord(presentation.data)) presentation.data = { ...presentation.data, noMovement: true, scrolled: false };
+			if (presentation.content[0]?.type === "text") presentation.content[0] = { ...presentation.content[0], text: `Scroll completed with no observed movement.\n\n${presentation.content[0].text}` };
+			else presentation.content.unshift({ type: "text", text: "Scroll completed with no observed movement." });
+		}
 		if (parseFailureOutput.artifactManifest) { presentation.artifactManifest = parseFailureOutput.artifactManifest; presentation.artifactRetentionSummary = parseFailureOutput.artifactRetentionSummary; }
 		if (parseFailureOutput.fullOutputPath || parseFailureOutput.fullOutputUnavailable) {
 			const existingText = presentation.content[0]?.type === "text" ? presentation.content[0].text : "";
@@ -474,7 +499,9 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 			presentation.content[0] = { type: "text", text: existingText.length > 0 ? `${existingText}\n\n${notice}` : notice };
 		}
 		if (presentation.artifactManifest) artifactManifest = presentation.artifactManifest;
-		const qaPreset = prepared.compiledQaPreset ? analyzeQaPresetResults(presentationEnvelope?.data) : undefined;
+		const qaPreset = prepared.compiledQaPreset
+			? (processResult.timedOut ? analyzeQaPresetTimeout(prepared.compiledQaPreset) ?? analyzeQaPresetResults(presentationEnvelope?.data, prepared.compiledQaPreset) : analyzeQaPresetResults(presentationEnvelope?.data, prepared.compiledQaPreset))
+			: undefined;
 		let qaAttachedTarget = prepared.compiledQaPreset?.checks.attached
 			? await collectQaAttachedTarget({ currentTarget: currentSessionTabTarget ?? prepared.priorSessionTabTarget, cwd, sessionName: prepared.executionPlan.sessionName, signal })
 			: undefined;
@@ -508,9 +535,13 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 			presentation.content = [{ type: "text", text: compactText }, ...nonTextContent];
 		}
 		const qaAttachedTargetText = formatQaAttachedTargetText(qaAttachedTarget);
+		const qaAttachedDiagnosticsText = prepared.compiledQaPreset?.checks.attached && prepared.compiledQaPreset.checks.diagnosticsResetAtStart === false && (prepared.compiledQaPreset.checks.checkNetwork || prepared.compiledQaPreset.checks.checkConsole || prepared.compiledQaPreset.checks.checkErrors)
+			? "Attached diagnostics: existing upstream session console/network/error buffers were preserved; rows may include events from before qa.attached started."
+			: undefined;
+		const qaAttachedBannerText = [qaAttachedTargetText, qaAttachedDiagnosticsText].filter((part): part is string => typeof part === "string" && part.length > 0).join("\n");
 		const skipAttachedTargetBanner = qaPreset?.passed && prepared.compiledQaPreset?.checks.attached;
-		if (!skipAttachedTargetBanner && qaAttachedTargetText && presentation.content[0]?.type === "text") presentation.content[0] = { ...presentation.content[0], text: `${qaAttachedTargetText}\n\n${presentation.content[0].text}` };
-		else if (!skipAttachedTargetBanner && qaAttachedTargetText) presentation.content.unshift({ type: "text", text: qaAttachedTargetText });
+		if (!skipAttachedTargetBanner && qaAttachedBannerText && presentation.content[0]?.type === "text") presentation.content[0] = { ...presentation.content[0], text: `${qaAttachedBannerText}\n\n${presentation.content[0].text}` };
+		else if (!skipAttachedTargetBanner && qaAttachedBannerText) presentation.content.unshift({ type: "text", text: qaAttachedBannerText });
 		if (managedSessionOutcome && managedSessionOutcome.succeeded !== succeeded) managedSessionOutcome = { ...managedSessionOutcome, succeeded };
 		const evalNavigationSummary = navigationSummary ?? extractNavigationSummaryFromData(presentationEnvelope?.data);
 		const evalSessionTabUrl = prepared.executionPlan.sessionName ? sessionPageState.get(prepared.executionPlan.sessionName).tabTarget?.url : undefined;

package/extensions/agent-browser/lib/orchestration/browser-run/prompt-guards.ts

@@ -4,17 +4,6 @@ import { isCloseCommand } from "../../command-taxonomy.js";
 import { executableExistsOnPath } from "../../executable-path.js";
 import type { SessionArtifactManifest } from "../../results/contracts.js";
 import type { PromptPolicy, PromptRequestedArtifact } from "../../prompt-policy.js";
-import type { SessionRefSnapshot } from "../../session-page-state.js";
-import { findBlockedFinalizingAction, STOP_BOUNDARY_GUARD_SCOPE, type BrowserFinalizingAction } from "./browser-action-model.js";
-
-export interface StopBoundaryViolation {
-	action: BrowserFinalizingAction;
-	command: string[];
-	message: string;
-	reason: "explicit-user-stop-boundary";
-	stepIndex?: number;
-	target?: string;
-}
 
 export interface RequestedArtifactCloseViolation {
 	message: string;
@@ -22,41 +11,6 @@ export interface RequestedArtifactCloseViolation {
 	reason: "requested-artifacts-missing-before-close";
 }
 
-function formatStopBoundaryActionPhrase(action: BrowserFinalizingAction): string {
-	if (action.kind === "keyboard-submit") return "keyboard submit (Enter/Return)";
-	return "click-like action";
-}
-
-export function findStopBoundaryViolation(options: { commandTokens: string[]; promptPolicy: PromptPolicy; refSnapshot?: SessionRefSnapshot; stdin?: string }): StopBoundaryViolation | undefined {
-	if (!options.promptPolicy.stopBoundary) return undefined;
-	const blocked = findBlockedFinalizingAction({
-		commandTokens: options.commandTokens,
-		refSnapshot: options.refSnapshot,
-		stdin: options.stdin,
-	});
-	if (!blocked) return undefined;
-	const target = blocked.targetLabel;
-	const actionPhrase = formatStopBoundaryActionPhrase(blocked);
-	const scopeNote = `Best-effort guard scope covers ${STOP_BOUNDARY_GUARD_SCOPE.covered.join(", ")}; it does not block ${STOP_BOUNDARY_GUARD_SCOPE.excluded.join(", ")}.`;
-	if (blocked.stepIndex === undefined) {
-		return {
-			action: blocked,
-			command: blocked.command,
-			message: `Blocked likely final submit/order ${actionPhrase} (${target}) because the latest user prompt set an explicit stop boundary. Gather evidence on the current page instead of activating the final action. ${scopeNote}`,
-			reason: "explicit-user-stop-boundary",
-			target,
-		};
-	}
-	return {
-		action: blocked,
-		command: blocked.command,
-		message: `Blocked likely final submit/order ${actionPhrase} in batch step ${blocked.stepIndex + 1} (${target}) because the latest user prompt set an explicit stop boundary. Gather evidence on the current page instead of activating the final action. ${scopeNote}`,
-		reason: "explicit-user-stop-boundary",
-		stepIndex: blocked.stepIndex,
-		target,
-	};
-}
-
 function resolveArtifactPath(cwd: string, path: string): string {
 	return isAbsolute(path) ? path : resolve(cwd, path);
 }

package/extensions/agent-browser/lib/orchestration/browser-run/session-state.ts

@@ -157,7 +157,15 @@ function formatManagedSessionOutcomeRecoveryGuidance(outcome: ManagedSessionOutc
 }
 
 export function formatManagedSessionOutcomeText(outcome: ManagedSessionOutcome | undefined): string | undefined {
-	if (!outcome || outcome.succeeded || outcome.sessionMode !== "fresh") return undefined;
+	if (!outcome) return undefined;
+	if (outcome.status === "closed" && outcome.succeeded) {
+		return [
+			"Managed session outcome: The current wrapper-managed browser session was closed.",
+			"Next sessionMode auto call will start or attach a managed session as needed. If upstream session list still shows rows, they are separate saved/upstream sessions; use close --all only when full cleanup is intended.",
+			"Full session names and transition details remain in details.managedSessionOutcome.",
+		].join("\n");
+	}
+	if (outcome.succeeded || outcome.sessionMode !== "fresh") return undefined;
 	return [formatManagedSessionOutcomeHeadline(outcome), formatManagedSessionOutcomeRecoveryGuidance(outcome)].join("\n");
 }
 
@@ -334,6 +342,7 @@ function isSafeSameSnapshotFormBatchStep(step: string[], refSnapshot: SessionRef
 	const roles = refIds.map((refId) => getSnapshotRefRole(refSnapshot, refId));
 	if (roles.some((role) => role === undefined)) return false;
 	if (command === "check" || command === "uncheck") return roles.every((role) => role === "checkbox" || role === "radio");
+	if (command === "click" || command === "tap") return roles.every((role) => role === "checkbox" || role === "radio");
 	if (command === "select") return roles.every((role) => role === "combobox");
 	return false;
 }

package/extensions/agent-browser/lib/orchestration/browser-run/types.ts

@@ -150,9 +150,17 @@ export interface ClickDispatchProbe {
 	target: ClickDispatchProbeTarget;
 }
 
+export interface ClickDispatchScrollContainerDiagnostic {
+	selector?: string;
+	summary: string;
+	targetOutsideContainer?: boolean;
+	targetOutsideViewport?: boolean;
+}
+
 export interface ClickDispatchDiagnostic {
 	nativeEventCount: number;
 	reason: "native-click-produced-no-target-dom-event";
+	scrollContainer?: ClickDispatchScrollContainerDiagnostic;
 	status: "no-native-event-observed";
 	summary: string;
 	target: ClickDispatchProbeTarget;
@@ -202,16 +210,32 @@ export interface TimeoutArtifactEvidence {
 	exists: boolean;
 	path: string;
 	sizeBytes?: number;
+	state: "missing" | "verified";
 	stepIndex: number;
 }
 
+export type TimeoutProgressStepStatus = "completed" | "failed" | "pending" | "unknown";
+
+export interface TimeoutProgressStep {
+	args: string[];
+	generatedFrom?: string;
+	index: number;
+	reason?: string;
+	retry?: { args: string[] };
+	status: TimeoutProgressStepStatus;
+}
+
 export interface TimeoutPartialProgress {
 	artifacts: TimeoutArtifactEvidence[];
 	currentPage?: {
+		source?: "live" | "planned";
 		title?: string;
 		url?: string;
 	};
-	steps?: Array<{ args: string[]; index: number }>;
+	liveUrlRecovered?: boolean;
+	openedButPostOpenTimedOut?: boolean;
+	retryStep?: TimeoutProgressStep;
+	steps?: TimeoutProgressStep[];
 	summary: string;
 }
 
@@ -374,7 +398,9 @@ export interface ElectronPostCommandHealthDiagnostic {
 export interface FillVerificationDiagnostic {
 	actual?: string;
 	expected: string;
+	method: "text" | "value";
 	nextActionIds: string[];
+	reason: "contenteditable-fill-mismatch" | "value-fill-mismatch";
 	selector: string;
 	status: "mismatch";
 	summary: string;
@@ -411,6 +437,7 @@ export interface PreparedBrowserRun {
 	priorSessionTabTarget?: SessionTabTarget;
 	processArgs: string[];
 	processStdin?: string;
+	processTimeoutMs?: number;
 	redactedArgs: string[];
 	redactedCompiledElectron?: CompiledAgentBrowserElectron;
 	redactedCompiledJob?: CompiledAgentBrowserJob;

package/extensions/agent-browser/lib/orchestration/electron-host/index.ts

@@ -9,6 +9,7 @@ import type { ChildProcess } from "node:child_process";
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus, type ElectronCleanupResult, type ElectronLaunchStatus } from "../../electron/cleanup.js";
 import { discoverElectronApps, type ElectronDiscoveryResult } from "../../electron/discovery.js";
 import type { ElectronCdpTarget, ElectronLaunchRecord } from "../../electron/launch.js";
+import { boundElectronProbeString } from "../../electron/text.js";
 import type { CompiledAgentBrowserElectron } from "../../input-modes.js";
 import { isRecord } from "../../parsing.js";
 import { buildAgentBrowserNextActions, buildAgentBrowserResultCategoryDetails } from "../../results.js";
@@ -368,12 +369,6 @@ const ELECTRON_FOCUSED_ELEMENT_EVAL = `(() => {
 	return { focusedElement: describeElement(document.activeElement) };
 })()`;
 
-function boundElectronProbeString(value: string | undefined, maxLength = 240): string | undefined {
-	const trimmed = value?.trim();
-	if (!trimmed) return undefined;
-	return trimmed.length > maxLength ? `${trimmed.slice(0, Math.max(0, maxLength - 3))}...` : trimmed;
-}
-
 function getTrimmedString(value: unknown): string | undefined {
 	return typeof value === "string" ? boundElectronProbeString(value) : undefined;
 }

package/extensions/agent-browser/lib/orchestration/input-plan.ts

@@ -23,11 +23,13 @@ export interface AgentBrowserExecuteParams {
 	electron?: unknown;
 	job?: unknown;
 	networkSourceLookup?: unknown;
+	outputPath?: string;
 	qa?: unknown;
 	semanticAction?: unknown;
 	sessionMode?: "auto" | "fresh";
 	sourceLookup?: unknown;
 	stdin?: string;
+	timeoutMs?: number;
 }
 
 export type ResolvedAgentBrowserInputKind = "args" | "electron" | "job" | "networkSourceLookup" | "qa" | "semanticAction" | "sourceLookup";
@@ -175,11 +177,11 @@ function normalizeExplicitEvalStdinArgs(args: string[], stdin: string | undefine
 }
 
 export function resolveAgentBrowserInput(options: {
-	getBatchAnnotateValidationError: (args: string[], stdin: string | undefined) => string | undefined;
+	getBatchPreflightValidationError: (args: string[], stdin: string | undefined) => string | undefined;
 	managedSessionActive: boolean;
 	params: AgentBrowserExecuteParams;
 }): ResolvedAgentBrowserInput {
-	const { getBatchAnnotateValidationError, managedSessionActive, params } = options;
+	const { getBatchPreflightValidationError, managedSessionActive, params } = options;
 	const semanticActionResult = params.semanticAction === undefined ? {} : compileAgentBrowserSemanticAction(params.semanticAction);
 	const jobResult = params.job === undefined ? {} : compileAgentBrowserJob(params.job);
 	const qaResult = params.qa === undefined ? {} : compileAgentBrowserQaPreset(params.qa);
@@ -219,6 +221,14 @@ export function resolveAgentBrowserInput(options: {
 				? "Do not provide stdin with electron; electron mode is host-only or manages its own input."
 				: undefined
 		: undefined;
+	const outputPathError = params.outputPath !== undefined && (typeof params.outputPath !== "string" || params.outputPath.trim().length === 0)
+		? "outputPath must be a non-empty string when provided."
+		: undefined;
+	const timeoutMsError = params.timeoutMs !== undefined && (typeof params.timeoutMs !== "number" || !Number.isSafeInteger(params.timeoutMs) || params.timeoutMs <= 0)
+		? "timeoutMs must be a positive integer when provided."
+		: compiledElectron && params.timeoutMs !== undefined
+			? "Use electron.timeoutMs for electron actions; top-level timeoutMs applies only to browser CLI subprocess calls."
+			: undefined;
 	const attachedQaSessionError = compiledQaPreset?.checks.attached
 		? params.sessionMode === "fresh"
 			? "qa.attached cannot be used with sessionMode=fresh; attach or launch a session first, then run qa.attached with the current session."
@@ -234,8 +244,10 @@ export function resolveAgentBrowserInput(options: {
 		?? electronResult.error
 		?? inputModeError
 		?? generatedStdinError
+		?? outputPathError
+		?? timeoutMsError
 		?? attachedQaSessionError
-		?? (compiledElectron ? undefined : validateToolArgs(toolArgs) ?? getBatchAnnotateValidationError(toolArgs, toolStdin));
+		?? (compiledElectron ? undefined : validateToolArgs(toolArgs) ?? getBatchPreflightValidationError(toolArgs, toolStdin));
 	const redactedCompiledJob = redactCompiledJob(compiledJob);
 	const redactedCompiledSemanticAction = compiledSemanticAction
 		? { ...compiledSemanticAction, args: redactInvocationArgs(compiledSemanticAction.args) }

package/extensions/agent-browser/lib/orchestration/output-file.ts

@@ -0,0 +1,86 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+import { isRecord } from "../parsing.js";
+import type { AgentBrowserToolResult } from "./browser-run/types.js";
+
+export interface AgentBrowserOutputFileDetails {
+	absolutePath: string;
+	bytes?: number;
+	error?: string;
+	path: string;
+	source: "content.text" | "details.data";
+	status: "failed" | "saved";
+}
+
+function normalizeRequestedOutputPath(path: string): string {
+	return path.startsWith("@") ? path.slice(1) : path;
+}
+
+function getTextContent(result: AgentBrowserToolResult): string {
+	return result.content
+		?.filter((item): item is { text: string; type: "text" } => item.type === "text")
+		.map((item) => item.text)
+		.join("\n\n") ?? "";
+}
+
+function getOutputPayload(result: AgentBrowserToolResult): { source: AgentBrowserOutputFileDetails["source"]; value: unknown } {
+	const details = isRecord(result.details) ? result.details : undefined;
+	if (details && details.data !== undefined) return { source: "details.data", value: details.data };
+	return { source: "content.text", value: getTextContent(result) };
+}
+
+function serializeOutputPayload(value: unknown): string {
+	return typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function appendOutputFileNotice(result: AgentBrowserToolResult, message: string): AgentBrowserToolResult["content"] {
+	const content = [...(result.content ?? [])] as AgentBrowserToolResult["content"];
+	if (content[0]?.type === "text") {
+		content[0] = { ...content[0], text: `${content[0].text}\n\n${message}` };
+		return content;
+	}
+	return [{ type: "text", text: message }, ...content];
+}
+
+export async function applyAgentBrowserOutputPath(options: {
+	cwd: string;
+	outputPath?: string;
+	preserveTextContent?: boolean;
+	result: AgentBrowserToolResult;
+}): Promise<AgentBrowserToolResult> {
+	if (!options.outputPath) return options.result;
+	if (options.result.isError || (isRecord(options.result.details) && options.result.details.resultCategory === "failure")) return options.result;
+	const requestedPath = normalizeRequestedOutputPath(options.outputPath);
+	const absolutePath = isAbsolute(requestedPath) ? requestedPath : resolve(options.cwd, requestedPath);
+	const payload = getOutputPayload(options.result);
+	try {
+		const serialized = serializeOutputPayload(payload.value);
+		await mkdir(dirname(absolutePath), { recursive: true });
+		await writeFile(absolutePath, serialized, "utf8");
+		const bytes = Buffer.byteLength(serialized, "utf8");
+		const outputFile: AgentBrowserOutputFileDetails = { absolutePath, bytes, path: requestedPath, source: payload.source, status: "saved" };
+		const details = isRecord(options.result.details) ? { ...options.result.details, outputFile } : { outputFile };
+		return {
+			...options.result,
+			content: options.preserveTextContent ? options.result.content : appendOutputFileNotice(options.result, `Output file: ${requestedPath} (${bytes} bytes from ${payload.source}).`),
+			details,
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const outputFile: AgentBrowserOutputFileDetails = { absolutePath, error: message, path: requestedPath, source: payload.source, status: "failed" };
+		const details = isRecord(options.result.details)
+			? (() => {
+				const rest = { ...options.result.details };
+				delete rest.successCategory;
+				return { ...rest, failureCategory: rest.failureCategory ?? "upstream-error", outputFile, resultCategory: "failure" };
+			})()
+			: { failureCategory: "upstream-error", outputFile, resultCategory: "failure" };
+		return {
+			...options.result,
+			content: options.preserveTextContent ? options.result.content : appendOutputFileNotice(options.result, `Output file failed: ${requestedPath} (${message}).`),
+			details,
+			isError: true,
+		};
+	}
+}

package/extensions/agent-browser/lib/pi-tool-rendering.ts

@@ -0,0 +1,231 @@
+import type { AgentToolResult, Theme, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import { highlightCode, keyHint } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+
+import {
+	compileAgentBrowserElectron,
+	compileAgentBrowserJob,
+	compileAgentBrowserNetworkSourceLookup,
+	compileAgentBrowserQaPreset,
+	compileAgentBrowserSemanticAction,
+	compileAgentBrowserSourceLookup,
+} from "./input-modes.js";
+import { isRecord } from "./parsing.js";
+import { redactInvocationArgs } from "./runtime.js";
+
+const TUI_INVOCATION_PREVIEW_MAX_CHARS = 160;
+const TUI_COLLAPSED_OUTPUT_MAX_LINES = 12;
+const ANSI_CONTROL_SEQUENCE_PATTERN = /\x1B(?:\][^\x07\x1B]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|P[^\x1B]*(?:\x1B\\)|_[^\x1B]*(?:\x1B\\)|\^[^\x1B]*(?:\x1B\\)|[@-Z\\-_])/g;
+const UNSAFE_DISPLAY_CONTROL_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\x80-\x9F]/g;
+
+function sanitizeDisplayText(value: string): string {
+	return value
+		.replace(ANSI_CONTROL_SEQUENCE_PATTERN, "")
+		.replace(/\r/g, "")
+		.replace(UNSAFE_DISPLAY_CONTROL_PATTERN, "�");
+}
+
+function replaceTabsForDisplay(value: string): string {
+	return value.replaceAll("\t", "    ");
+}
+
+function trimTrailingBlankLines(lines: string[]): string[] {
+	let end = lines.length;
+	while (end > 0 && lines[end - 1].trim().length === 0) {
+		end -= 1;
+	}
+	return lines.slice(0, end);
+}
+
+function isJsonDocumentText(value: string): boolean {
+	const trimmed = value.trim();
+	if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return false;
+	try {
+		JSON.parse(trimmed);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function getPrimaryTextContent(result: AgentToolResult<unknown>): string {
+	const textContent = result.content.find((item) => item.type === "text");
+	return textContent?.type === "text" ? textContent.text : "";
+}
+
+function colorizeToolOutputLines(outputText: string, theme: Theme, isError: boolean): string[] {
+	const normalizedLines = trimTrailingBlankLines(replaceTabsForDisplay(sanitizeDisplayText(outputText)).split("\n"));
+	const normalizedText = normalizedLines.join("\n");
+	if (normalizedText.length === 0) return [];
+	if (isJsonDocumentText(normalizedText)) {
+		return highlightCode(normalizedText, "json");
+	}
+	return normalizedLines.map((line) => {
+		if (line.length === 0) {
+			return "";
+		}
+		return isError ? theme.fg("error", line) : theme.fg("toolOutput", line);
+	});
+}
+
+function formatExpandHint(theme: Theme): string {
+	try {
+		return keyHint("app.tools.expand", "to expand");
+	} catch {
+		return `${theme.fg("dim", "ctrl+o")} ${theme.fg("muted", "to expand")}`;
+	}
+}
+
+function formatVisualTruncationNotice(remainingLines: number, totalLines: number, theme: Theme, width: number): string {
+	const notice = `${theme.fg("muted", `... (${remainingLines} more lines, ${totalLines} total, `)}${formatExpandHint(theme)}${theme.fg("muted", ")")}`;
+	return truncateToWidth(notice, Math.max(0, width));
+}
+
+export function formatAgentBrowserRenderCall(args: unknown, theme: Theme): string {
+	const input = isRecord(args) ? args : {};
+	const semanticAction = compileAgentBrowserSemanticAction(input.semanticAction);
+	const job = compileAgentBrowserJob(input.job);
+	const qa = compileAgentBrowserQaPreset(input.qa);
+	const sourceLookup = compileAgentBrowserSourceLookup(input.sourceLookup);
+	const networkSourceLookup = compileAgentBrowserNetworkSourceLookup(input.networkSourceLookup);
+	const electron = compileAgentBrowserElectron(input.electron);
+	const generatedBatch = networkSourceLookup.compiled ?? sourceLookup.compiled ?? job.compiled ?? qa.compiled;
+	const rawArgs = Array.isArray(input.args)
+		? input.args.filter((value): value is string => typeof value === "string")
+		: electron.compiled
+			? ["electron", electron.compiled.action]
+			: (semanticAction.compiled?.args ?? generatedBatch?.args ?? []);
+	const redactedArgs = redactInvocationArgs(rawArgs);
+	const invocation = sanitizeDisplayText(redactedArgs.join(" ")).replace(/\s+/g, " ").trim();
+	const invocationPreview =
+		invocation.length > TUI_INVOCATION_PREVIEW_MAX_CHARS
+			? `${invocation.slice(0, TUI_INVOCATION_PREVIEW_MAX_CHARS - 3)}...`
+			: invocation;
+	let text = theme.fg("toolTitle", theme.bold("agent_browser"));
+	if (invocationPreview.length > 0) {
+		text += ` ${theme.fg("accent", invocationPreview)}`;
+	}
+	if (input.sessionMode === "fresh") {
+		text += theme.fg("dim", " sessionMode=fresh");
+	}
+	if (typeof input.stdin === "string") {
+		text += theme.fg("dim", " + stdin");
+	}
+	return text;
+}
+
+export function formatAgentBrowserRenderResult(
+	result: AgentToolResult<unknown>,
+	options: { expanded: boolean; isPartial: boolean },
+	theme: Theme,
+	isError: boolean,
+): string {
+	if (options.isPartial) {
+		return theme.fg("warning", "Running agent-browser...");
+	}
+
+	const outputText = getPrimaryTextContent(result);
+	const outputLines = colorizeToolOutputLines(outputText, theme, isError);
+	if (outputLines.length === 0) {
+		const details = isRecord(result.details) ? result.details : undefined;
+		const rawSummary = typeof details?.summary === "string" ? details.summary : isError ? "agent-browser failed" : "Done";
+		const sanitizedSummary = sanitizeDisplayText(rawSummary).trim();
+		const summary = sanitizedSummary.length > 0 ? sanitizedSummary : isError ? "agent-browser failed" : "Done";
+		return isError ? theme.fg("error", summary) : theme.fg("success", summary);
+	}
+
+	return `\n${outputLines.join("\n")}`;
+}
+
+function formatModelVisibleFailureCategoryNotice(details: unknown): string | undefined {
+	if (!isRecord(details) || details.resultCategory !== "failure") return undefined;
+	const failureCategory = typeof details.failureCategory === "string" && details.failureCategory.length > 0
+		? details.failureCategory
+		: undefined;
+	return `Result category: failure${failureCategory ? `; failureCategory: ${failureCategory}` : ""}; Pi tool isError: true.`;
+}
+
+type AgentBrowserToolContent = AgentToolResult<unknown>["content"];
+type AgentBrowserToolContentItem = AgentBrowserToolContent[number];
+
+export type AgentBrowserToolResultPatch = {
+	content?: AgentBrowserToolContent;
+	isError?: boolean;
+};
+
+function agentBrowserToolResultRequestedJson(event: ToolResultEvent): boolean {
+	const details = isRecord(event.details) ? event.details : undefined;
+	const detailArgs = Array.isArray(details?.args) ? details.args : undefined;
+	const inputArgs = isRecord(event.input) && Array.isArray(event.input.args) ? event.input.args : undefined;
+	return detailArgs?.includes("--json") === true || inputArgs?.includes("--json") === true;
+}
+
+function agentBrowserToolResultHasParseableJsonContent(content: AgentBrowserToolContent): boolean {
+	return content.some((item) => {
+		if (item.type !== "text" || typeof item.text !== "string") return false;
+		const text = item.text.trim();
+		if (text.length === 0) return false;
+		try {
+			JSON.parse(text);
+			return true;
+		} catch {
+			return false;
+		}
+	});
+}
+
+function appendModelVisibleFailureCategoryNotice(content: AgentBrowserToolContent, notice: string): AgentBrowserToolContent | undefined {
+	const noticeContent: AgentBrowserToolContentItem = { type: "text", text: notice };
+	const textIndex = content.findIndex((item) => item.type === "text" && typeof item.text === "string");
+	if (textIndex === -1) return [noticeContent, ...content];
+	const textItem = content[textIndex];
+	if (textItem.type !== "text" || typeof textItem.text !== "string" || textItem.text.includes(notice)) return undefined;
+	return content.map((item, index) => index === textIndex
+		? { ...item, text: `${textItem.text}\n\n${notice}` }
+		: item);
+}
+
+export function buildAgentBrowserToolResultPatch(event: ToolResultEvent): AgentBrowserToolResultPatch | undefined {
+	if (event.toolName !== "agent_browser") return undefined;
+	const preservesParseableJson = agentBrowserToolResultRequestedJson(event) && agentBrowserToolResultHasParseableJsonContent(event.content);
+	const notice = preservesParseableJson ? undefined : formatModelVisibleFailureCategoryNotice(event.details);
+	const content = notice ? appendModelVisibleFailureCategoryNotice(event.content, notice) : undefined;
+	const shouldMarkError = isRecord(event.details) && event.details.resultCategory === "failure" && event.isError !== true;
+	if (!shouldMarkError && !content) return undefined;
+	return {
+		...(content ? { content } : {}),
+		...(shouldMarkError ? { isError: true } : {}),
+	};
+}
+
+export class AgentBrowserResultComponent {
+	private expanded = false;
+	private theme: Theme | undefined;
+	private readonly text = new Text("", 0, 0);
+
+	setState(value: string, expanded: boolean, theme: Theme): void {
+		this.text.setText(value);
+		this.expanded = expanded;
+		this.theme = theme;
+	}
+
+	render(width: number): string[] {
+		const lines = this.text.render(width);
+		if (this.expanded || lines.length <= TUI_COLLAPSED_OUTPUT_MAX_LINES) {
+			return lines;
+		}
+		const theme = this.theme;
+		if (!theme) {
+			return lines.slice(0, TUI_COLLAPSED_OUTPUT_MAX_LINES);
+		}
+		const hiddenLineCount = lines.length - TUI_COLLAPSED_OUTPUT_MAX_LINES;
+		return [
+			...lines.slice(0, TUI_COLLAPSED_OUTPUT_MAX_LINES),
+			formatVisualTruncationNotice(hiddenLineCount, lines.length, theme, width),
+		];
+	}
+
+	invalidate(): void {
+		this.text.invalidate();
+	}
+}