pi-agent-browser-native 0.2.48 → 0.2.50

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

@@ -1,257 +0,0 @@
-/*
- * Purpose: Render parsed agent-browser results into concise pi-facing summaries, text content, and optional inline image attachments.
- * Responsibilities: Orchestrate specialized presentation modules, attach inline images within size limits, and keep generic record formatting distinct from envelope parsing.
- * Scope: Presentation shaping only; upstream stdout parsing and snapshot compaction internals live in separate modules.
- */
-
-import type { CompiledAgentBrowserSemanticAction } from "../input-modes/types.js";
-import { isRecord } from "../parsing.js";
-import type { CommandInfo } from "../runtime.js";
-import type { PersistentSessionArtifactStore } from "../temp.js";
-import { buildAgentBrowserNextActions } from "./action-recommendations.js";
-import { buildAgentBrowserResultCategoryDetails } from "./categories.js";
-import { detectConfirmationRequired } from "./confirmation.js";
-import type {
-	AgentBrowserEnvelope,
-	AgentBrowserNextAction,
-	NetworkRouteDiagnostic,
-	SessionArtifactManifest,
-	ToolPresentation,
-} from "./contracts.js";
-import { buildSnapshotPresentation } from "./snapshot.js";
-import { parseJsonPreviewString, redactModelFacingText, stringifyModelFacing } from "./presentation/common.js";
-import {
-	applyArtifactManifest,
-	attachInlineImage,
-	buildArtifactVerificationSummary,
-	buildManifestEntriesForFileArtifacts,
-	classifyPresentationSuccessCategory,
-	extractFileArtifacts,
-	extractImagePath,
-	formatArtifactMetadataLines,
-	formatArtifactSummary,
-	formatMissingArtifactFailureText,
-	getSavedFileDetails,
-	hasMissingFileArtifact,
-	isManifestFileArtifact,
-	type ArtifactRequestContext,
-} from "./presentation/artifacts.js";
-import { buildBatchPresentation, isAgentBrowserBatchResultArray } from "./presentation/batch.js";
-import { getPresentationPaths } from "./presentation/content.js";
-import {
-	buildNetworkRequestsNextActions,
-	buildStreamNextActions,
-	enrichStreamStatusData,
-	formatNetworkRouteDiagnosticsText,
-	redactPresentationData,
-} from "./presentation/diagnostics.js";
-import { buildErrorPresentation } from "./presentation/errors.js";
-import { compactLargePresentationOutput } from "./presentation/large-output.js";
-import { buildPageChangeSummary } from "./presentation/navigation.js";
-import { formatPresentationContentText, formatPresentationSummary } from "./presentation/registry.js";
-import { resolvePresentationCommandInfo } from "./presentation/semantic-action.js";
-
-function sanitizeModelFacingPresentation(presentation: ToolPresentation): ToolPresentation {
-	presentation.content = presentation.content.map((item) => {
-		if (item.type !== "text") return item;
-		const parsed = parseJsonPreviewString(item.text);
-		return parsed === item.text ? item : { ...item, text: stringifyModelFacing(parsed) };
-	});
-	presentation.summary = redactModelFacingText(presentation.summary);
-	return presentation;
-}
-
-function mergeNextActions(...groups: Array<AgentBrowserNextAction[] | undefined>): AgentBrowserNextAction[] | undefined {
-	const merged = groups.flatMap((group) => group ?? []);
-	return merged.length > 0 ? merged : undefined;
-}
-
-function shouldAddAnnotatedScreenshotGuidance(commandInfo: CommandInfo, args: string[] | undefined): boolean {
-	return commandInfo.command === "screenshot" && (args?.includes("--annotate") ?? false);
-}
-
-export async function buildToolPresentation(options: {
-	artifactManifest?: SessionArtifactManifest;
-	args?: string[];
-	artifactRequest?: ArtifactRequestContext;
-	batchArtifactRequests?: Array<ArtifactRequestContext | undefined>;
-	commandInfo: CommandInfo;
-	compiledSemanticAction?: CompiledAgentBrowserSemanticAction;
-	cwd: string;
-	envelope?: AgentBrowserEnvelope;
-	errorText?: string;
-	networkRouteDiagnostics?: NetworkRouteDiagnostic[];
-	networkRoutes?: import("./contracts.js").NetworkRouteRecord[];
-	persistentArtifactStore?: PersistentSessionArtifactStore;
-	sessionName?: string;
-}): Promise<ToolPresentation> {
-	const {
-		args,
-		artifactManifest,
-		artifactRequest,
-		commandInfo,
-		compiledSemanticAction,
-		cwd,
-		envelope,
-		errorText,
-		networkRouteDiagnostics,
-		networkRoutes,
-		persistentArtifactStore,
-		sessionName,
-	} = options;
-	const presentationCommandInfo = resolvePresentationCommandInfo(commandInfo, compiledSemanticAction);
-
-	if (errorText) {
-		return buildErrorPresentation({ args, commandInfo, errorText, sessionName });
-	}
-
-	const data = enrichStreamStatusData(commandInfo, envelope?.data);
-	const presentationData = redactPresentationData(commandInfo, data);
-	const artifacts = await extractFileArtifacts({ artifactManifest, artifactRequest, commandInfo: presentationCommandInfo, cwd, data, sessionName });
-	const artifactVerification = buildArtifactVerificationSummary(artifacts);
-	const artifactSummary = formatArtifactSummary(artifacts);
-	const summary = artifactSummary ?? formatPresentationSummary(commandInfo, data, compiledSemanticAction);
-	const artifactText = artifacts.length > 0 ? formatArtifactMetadataLines(artifacts).join("\n") : undefined;
-
-	let presentation: ToolPresentation;
-	if (commandInfo.command === "batch" && isAgentBrowserBatchResultArray(data)) {
-		presentation = await buildBatchPresentation({
-			artifactManifest,
-			artifactRequests: options.batchArtifactRequests,
-			buildNestedToolPresentation: buildToolPresentation,
-			cwd,
-			data,
-			networkRoutes,
-			persistentArtifactStore,
-			sessionName,
-			summary,
-		});
-	} else if (commandInfo.command === "snapshot" && isRecord(data)) {
-		presentation = await buildSnapshotPresentation(data, persistentArtifactStore, artifactManifest);
-	} else {
-		presentation = {
-			artifactVerification,
-			artifacts: artifacts.length > 0 ? artifacts : undefined,
-			content: [{ type: "text", text: artifactText ?? formatPresentationContentText(commandInfo, data, compiledSemanticAction) }],
-			data: presentationData,
-			summary,
-		};
-	}
-
-	if (networkRouteDiagnostics && networkRouteDiagnostics.length > 0 && presentation.content[0]?.type === "text") {
-		const diagnosticText = formatNetworkRouteDiagnosticsText(networkRouteDiagnostics);
-		if (diagnosticText) presentation.content[0] = { ...presentation.content[0], text: `${diagnosticText}\n\n${presentation.content[0].text}` };
-		presentation.networkRouteDiagnostics = networkRouteDiagnostics;
-	}
-	if (artifacts.length > 0 && !presentation.artifacts) {
-		presentation.artifacts = artifacts;
-	}
-	presentation.artifactVerification = presentation.artifactVerification ?? artifactVerification;
-	if (isRecord(data)) {
-		const savedFile = getSavedFileDetails(commandInfo, data);
-		if (savedFile) {
-			presentation.savedFile = savedFile;
-			presentation.savedFilePath = savedFile.path;
-		}
-	}
-
-	if (shouldAddAnnotatedScreenshotGuidance(commandInfo, args) && presentation.content[0]?.type === "text") {
-		const guidance = "Annotated screenshot note: dense pages can produce overlapping labels. If the labels are noisy, capture a scoped element screenshot, take a non-annotated screenshot, or use snapshot -i high-value refs as the machine-readable map.";
-		presentation.content[0] = { ...presentation.content[0], text: `${presentation.content[0].text}\n\n${guidance}` };
-	}
-
-	const imagePath = artifactRequest?.absolutePath ?? extractImagePath(commandInfo, cwd, data);
-	const presentationWithImage = imagePath ? await attachInlineImage(presentation, imagePath) : presentation;
-	const compactedPresentation = await compactLargePresentationOutput({
-		artifactManifest,
-		commandInfo,
-		data: presentationData,
-		persistentArtifactStore,
-		presentation: presentationWithImage,
-	});
-	const presentationWithManifest = applyArtifactManifest(
-		compactedPresentation,
-		compactedPresentation.artifactManifest ?? artifactManifest,
-		buildManifestEntriesForFileArtifacts(artifacts.filter(isManifestFileArtifact)),
-	);
-	const currentSpillPaths = new Set(getPresentationPaths({
-		primaryPath: presentationWithManifest.fullOutputPath,
-		secondaryPaths: presentationWithManifest.fullOutputPaths,
-	}));
-	presentationWithManifest.artifactVerification = buildArtifactVerificationSummary(
-		artifacts,
-		presentationWithManifest.artifactManifest,
-		currentSpillPaths,
-	) ?? presentationWithManifest.artifactVerification;
-
-	const confirmationRequired = detectConfirmationRequired(data);
-	const missingArtifactFailureText = formatMissingArtifactFailureText(presentationWithManifest.artifacts);
-	if (missingArtifactFailureText && hasMissingFileArtifact(presentationWithManifest.artifacts)) {
-		presentationWithManifest.resultCategory = "failure";
-		presentationWithManifest.failureCategory = "artifact-missing";
-		presentationWithManifest.successCategory = undefined;
-		presentationWithManifest.summary = missingArtifactFailureText;
-		if (presentationWithManifest.content[0]?.type === "text") {
-			presentationWithManifest.content[0] = { ...presentationWithManifest.content[0], text: `${missingArtifactFailureText}\n\n${presentationWithManifest.content[0].text}` };
-		} else {
-			presentationWithManifest.content.unshift({ type: "text", text: missingArtifactFailureText });
-		}
-	}
-
-	if (!presentationWithManifest.resultCategory) {
-		const categoryDetails = buildAgentBrowserResultCategoryDetails({
-			artifacts: presentationWithManifest.artifacts,
-			command: presentationCommandInfo.command,
-			confirmationRequired: confirmationRequired !== undefined,
-			errorText: envelope?.success === false ? presentationWithManifest.summary : undefined,
-			savedFile: presentationWithManifest.savedFile,
-			succeeded: envelope?.success !== false,
-		});
-		presentationWithManifest.resultCategory = categoryDetails.resultCategory;
-		presentationWithManifest.successCategory = categoryDetails.resultCategory === "success"
-			? classifyPresentationSuccessCategory({
-				artifactVerification: presentationWithManifest.artifactVerification,
-				artifacts: presentationWithManifest.artifacts,
-				savedFile: presentationWithManifest.savedFile,
-			})
-			: categoryDetails.successCategory;
-		presentationWithManifest.failureCategory = categoryDetails.failureCategory;
-	}
-	if (presentationWithManifest.resultCategory === "success") {
-		presentationWithManifest.successCategory = classifyPresentationSuccessCategory({
-			artifactVerification: presentationWithManifest.artifactVerification,
-			artifacts: presentationWithManifest.artifacts,
-			savedFile: presentationWithManifest.savedFile,
-		});
-	}
-
-	const genericNextActions = presentationWithManifest.nextActions ? undefined : buildAgentBrowserNextActions({
-		artifacts: presentationWithManifest.artifacts,
-		args,
-		command: presentationCommandInfo.command,
-		confirmationId: confirmationRequired?.id,
-		failureCategory: presentationWithManifest.failureCategory,
-		resultCategory: presentationWithManifest.resultCategory ?? "success",
-		savedFilePath: presentationWithManifest.savedFilePath,
-		successCategory: presentationWithManifest.successCategory,
-	});
-	const networkNextActions = commandInfo.command === "network" && commandInfo.subcommand === "requests" && presentationWithManifest.resultCategory === "success"
-		? buildNetworkRequestsNextActions(data, sessionName, presentationWithManifest.networkRouteDiagnostics)
-		: undefined;
-	const streamNextActions = presentationWithManifest.resultCategory === "success" ? buildStreamNextActions(commandInfo, data, sessionName) : undefined;
-	presentationWithManifest.nextActions = mergeNextActions(
-		presentationWithManifest.nextActions,
-		genericNextActions,
-		networkNextActions,
-		streamNextActions,
-	);
-	presentationWithManifest.pageChangeSummary = presentationWithManifest.pageChangeSummary ?? buildPageChangeSummary({
-		artifacts: presentationWithManifest.artifacts,
-		commandInfo: presentationCommandInfo,
-		data,
-		nextActions: presentationWithManifest.nextActions,
-		savedFilePath: presentationWithManifest.savedFilePath,
-		summary: presentationWithManifest.summary,
-	});
-	return sanitizeModelFacingPresentation(presentationWithManifest);
-}

package/extensions/agent-browser/lib/results/recovery-actions.ts

@@ -1,139 +0,0 @@
-/**
- * Purpose: Centralize recovery-oriented nextAction ids and action construction.
- * Responsibilities: Build tab/about:blank/no-active-page/connected-session follow-ups and rich-input recovery ids.
- * Scope: Recovery action contracts only; result category classification and artifact follow-ups live elsewhere.
- * Usage: Imported by shared result action builders and the extension entrypoint.
- * Invariants/Assumptions: Ids are public machine-readable contracts mirrored by docs and tests.
- */
-
-import { buildNextToolAction, type AgentBrowserNextAction, withOptionalSessionArgs } from "./next-actions.js";
-
-export type AgentBrowserRecoveryKind = "about-blank" | "connected-session" | "no-active-page" | "tab-drift";
-
-export interface AgentBrowserRecoveryContext {
-	kind: AgentBrowserRecoveryKind;
-	recoveryApplied?: boolean;
-	selectedTab?: string;
-	sessionName?: string;
-	targetTitle?: string;
-	targetUrl?: string;
-}
-
-export const AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS = {
-	aboutBlankListTabs: "list-tabs-for-about-blank-recovery",
-	connectedSessionListTabs: "list-connected-session-tabs",
-	genericTabDriftListTabs: "list-tabs-for-recovery",
-	noActivePageListTabs: "list-tabs-after-no-active-page",
-	selectIntendedTabAfterDrift: "select-intended-tab-after-drift",
-	snapshotAfterTabRecovery: "snapshot-after-tab-recovery",
-	tabDriftListTabs: "list-tabs-for-tab-drift-recovery",
-} as const;
-
-export const AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS = {
-	click: "click-current-editable-ref",
-	focus: "focus-current-editable-ref",
-} as const;
-
-export type AgentBrowserRichInputRecoveryNextActionKind = keyof typeof AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS;
-
-function getNumberedAgentBrowserNextActionId(baseId: string, index: number, total: number): string {
-	return total > 1 ? `${baseId}-${index + 1}` : baseId;
-}
-
-export function getAgentBrowserRichInputRecoveryNextActionId(kind: AgentBrowserRichInputRecoveryNextActionKind, index: number, candidateCount: number): string {
-	return getNumberedAgentBrowserNextActionId(AGENT_BROWSER_RICH_INPUT_RECOVERY_NEXT_ACTION_IDS[kind], index, candidateCount);
-}
-
-export function getAgentBrowserRichInputRecoveryNextActionIds(candidateCount: number): string[] {
-	const ids: string[] = [];
-	for (let index = 0; index < candidateCount; index += 1) {
-		ids.push(
-			getAgentBrowserRichInputRecoveryNextActionId("focus", index, candidateCount),
-			getAgentBrowserRichInputRecoveryNextActionId("click", index, candidateCount),
-		);
-	}
-	return ids;
-}
-
-function getRecoveryTargetDescription(recovery: AgentBrowserRecoveryContext): string {
-	const target = [recovery.targetTitle, recovery.targetUrl].filter((item): item is string => item !== undefined && item.length > 0).join(" at ");
-	return target.length > 0 ? target : "the intended tab";
-}
-
-function isStableTabId(tab: string | undefined): tab is string {
-	return /^t\d+$/.test(tab ?? "");
-}
-
-function buildTabSnapshotRecoveryAction(options: {
-	id: string;
-	reason: string;
-	recovery: AgentBrowserRecoveryContext;
-	safety: string;
-	sessionArgs: (args: string[]) => string[];
-	tabId: string;
-}): AgentBrowserNextAction {
-	if (options.recovery.recoveryApplied === true) {
-		return buildNextToolAction({
-			args: options.sessionArgs(["snapshot", "-i"]),
-			id: options.id,
-			reason: options.reason,
-			safety: options.safety,
-		});
-	}
-	return buildNextToolAction({
-		args: options.sessionArgs(["batch"]),
-		id: options.id,
-		reason: `${options.reason} The batch selects the stable tab before snapshotting.`,
-		safety: `${options.safety} The snapshot retry is atomic with tab selection, so it does not assume the intended tab is already active.`,
-		stdin: JSON.stringify([["tab", options.tabId], ["snapshot", "-i"]]),
-	});
-}
-
-export function buildRecoveryNextActions(recovery: AgentBrowserRecoveryContext): AgentBrowserNextAction[] {
-	const sessionArgs = (args: string[]) => withOptionalSessionArgs(recovery.sessionName, args);
-	if (recovery.kind === "connected-session") {
-		return [
-			buildNextToolAction({
-				args: sessionArgs(["tab", "list"]),
-				id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.connectedSessionListTabs,
-				reason: "Inspect tabs exposed by the connected CDP endpoint before assuming the app surface is active.",
-				safety: "Read-only. Raw connect can succeed before the desktop app has an active rendered page.",
-			}),
-		];
-	}
-	if (recovery.kind === "no-active-page") {
-		return [
-			buildNextToolAction({
-				args: sessionArgs(["tab", "list"]),
-				id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.noActivePageListTabs,
-				reason: "The snapshot found no active page; inspect the session tabs before retrying refs.",
-				safety: "Read-only tab listing for the same connected session.",
-			}),
-		];
-	}
-	const targetDescription = getRecoveryTargetDescription(recovery);
-	const listAction = buildNextToolAction({
-		args: sessionArgs(["tab", "list"]),
-		id: recovery.kind === "about-blank" ? AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.aboutBlankListTabs : AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.tabDriftListTabs,
-		reason: `Inspect tabs for ${targetDescription} before continuing after tab drift.`,
-		safety: "Read-only tab listing; prefer stable tN tab ids over positional tab guesses.",
-	});
-	if (!isStableTabId(recovery.selectedTab)) return [listAction];
-	return [
-		listAction,
-		buildNextToolAction({
-			args: sessionArgs(["tab", recovery.selectedTab]),
-			id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.selectIntendedTabAfterDrift,
-			reason: `Re-select ${targetDescription} with the stable tab id already observed by the wrapper.`,
-			safety: "Switches only the active tab in this browser session; it does not mutate page content.",
-		}),
-		buildTabSnapshotRecoveryAction({
-			id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.snapshotAfterTabRecovery,
-			reason: "Refresh interactive refs on the recovered tab before using @e refs again.",
-			recovery,
-			safety: "Read-only snapshot. Treat previous refs as stale until this succeeds.",
-			sessionArgs,
-			tabId: recovery.selectedTab,
-		}),
-	];
-}

package/extensions/agent-browser/lib/results/recovery-next-actions.ts

@@ -1,71 +0,0 @@
-/**
- * Purpose: Build session-aware recovery nextActions that combine result category policy with known session/tab context.
- * Responsibilities: Prefix recovery argv with the active session and adapt tab/about:blank/no-active/stale-ref contexts into stable nextAction lists.
- * Scope: Recovery nextAction assembly only; diagnostic detection and action-list merge ordering stay in the extension entrypoint.
- * Usage: Imported by the extension entrypoint when adding recovery nextActions to tool details.
- * Invariants/Assumptions: Action ids and argv ordering are public contracts; session prefixing must not double-prefix explicit --session args.
- */
-
-import { buildAgentBrowserNextActions } from "./action-recommendations.js";
-import { type AgentBrowserNextAction, withOptionalSessionArgs } from "./next-actions.js";
-
-export interface TabRecoveryCorrection {
-	selectedTab?: string;
-	targetTitle?: string;
-	targetUrl?: string;
-}
-
-export interface TabRecoveryTarget {
-	title?: string;
-	url?: string;
-}
-
-export function buildConnectedSessionNextActions(sessionName: string | undefined): AgentBrowserNextAction[] {
-	if (!sessionName) return [];
-	return buildAgentBrowserNextActions({
-		recovery: { kind: "connected-session", sessionName },
-		resultCategory: "success",
-		successCategory: "completed",
-	}) ?? [];
-}
-
-export function buildNoActivePageNextActions(sessionName: string | undefined): AgentBrowserNextAction[] {
-	if (!sessionName) return [];
-	return buildAgentBrowserNextActions({
-		recovery: { kind: "no-active-page", sessionName },
-		resultCategory: "failure",
-	}) ?? [];
-}
-
-export function buildSessionTabRecoveryNextActions(options: {
-	kind: "about-blank" | "tab-drift";
-	recoveryApplied?: boolean;
-	resultCategory?: "failure" | "success";
-	sessionName?: string;
-	tabCorrection?: TabRecoveryCorrection;
-	target?: TabRecoveryTarget;
-}): AgentBrowserNextAction[] {
-	const resultCategory = options.resultCategory ?? "success";
-	return buildAgentBrowserNextActions({
-		recovery: {
-			kind: options.kind,
-			recoveryApplied: options.recoveryApplied,
-			selectedTab: options.tabCorrection?.selectedTab,
-			sessionName: options.sessionName,
-			targetTitle: options.tabCorrection?.targetTitle ?? options.target?.title,
-			targetUrl: options.tabCorrection?.targetUrl ?? options.target?.url,
-		},
-		resultCategory,
-		successCategory: resultCategory === "success" ? "completed" : undefined,
-	}) ?? [];
-}
-
-export function buildSessionAwareStaleRefNextActions(sessionName: string | undefined): AgentBrowserNextAction[] {
-	return (buildAgentBrowserNextActions({ failureCategory: "stale-ref", resultCategory: "failure" }) ?? []).map((action) => {
-		const actionArgs = action.params?.args;
-		return {
-			...action,
-			params: action.params && actionArgs ? { ...action.params, args: withOptionalSessionArgs(sessionName, actionArgs) } : action.params,
-		};
-	});
-}