pi-agent-browser-native 0.2.44 → 0.2.46

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,
+		};
+	}
+}