pi-agent-browser-native 0.2.32 → 0.2.34

package/extensions/agent-browser/lib/input-modes/electron.ts

@@ -0,0 +1,170 @@
+/**
+ * Purpose: Compile top-level Electron wrapper inputs into validated Electron actions.
+ * Responsibilities: Enforce action-specific fields, launch-target rules, and wrapper-owned flag safety.
+ * Scope: Electron input-mode validation only; launch/probe/cleanup execution stays in the extension entrypoint.
+ */
+
+import { isRecord } from "../parsing.js";
+import {
+	AGENT_BROWSER_ELECTRON_ACTIONS,
+	AGENT_BROWSER_ELECTRON_HANDOFFS,
+	AGENT_BROWSER_ELECTRON_LIST_FIELDS,
+	AGENT_BROWSER_ELECTRON_PROBE_FIELDS,
+	AGENT_BROWSER_ELECTRON_RESERVED_APP_ARGS,
+	AGENT_BROWSER_ELECTRON_TARGET_TYPES,
+	type AgentBrowserElectronAction,
+	type CompiledAgentBrowserElectron,
+} from "./types.js";
+
+function validateOptionalNonEmptyString(input: Record<string, unknown>, fieldName: string): { value?: string; error?: string } {
+	const value = input[fieldName];
+	if (value === undefined) return {};
+	if (typeof value !== "string" || value.trim().length === 0) {
+		return { error: `electron.${fieldName} must be a non-empty string when provided.` };
+	}
+	return { value: value.trim() };
+}
+
+function validateOptionalElectronStringArray(input: Record<string, unknown>, fieldName: "allow" | "appArgs" | "deny"): string | undefined {
+	const value = input[fieldName];
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim().length === 0)) {
+		return `electron.${fieldName} must be an array of non-empty strings when provided.`;
+	}
+	return undefined;
+}
+
+function validateOptionalElectronEnum<T extends string>(input: Record<string, unknown>, fieldName: string, values: readonly T[]): string | undefined {
+	const value = input[fieldName];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || !values.includes(value as T)) {
+		return `electron.${fieldName} must be one of: ${values.join(", ")}.`;
+	}
+	return undefined;
+}
+
+function getReservedElectronAppArg(appArgs: string[] | undefined): string | undefined {
+	return appArgs?.find((arg) => {
+		const trimmed = arg.trim();
+		return trimmed === "--" || AGENT_BROWSER_ELECTRON_RESERVED_APP_ARGS.some((reserved) => trimmed === reserved || trimmed.startsWith(`${reserved}=`));
+	});
+}
+
+function validateElectronLaunchAppArgs(appArgs: string[] | undefined): string | undefined {
+	const reservedArg = getReservedElectronAppArg(appArgs);
+	return reservedArg
+		? `electron.appArgs must not include wrapper-owned launch flag ${reservedArg}.`
+		: undefined;
+}
+
+function validateOptionalElectronPositiveInteger(input: Record<string, unknown>, fieldName: "maxResults" | "timeoutMs"): { value?: number; error?: string } {
+	const value = input[fieldName];
+	if (value === undefined) return {};
+	if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+		return { error: `electron.${fieldName} must be a positive integer when provided.` };
+	}
+	return { value };
+}
+
+function onlyAllowedElectronFields(input: Record<string, unknown>, action: string, allowedFields: ReadonlySet<string>): string | undefined {
+	return Object.keys(input).find((fieldName) => !allowedFields.has(fieldName))
+		? `electron.${action} does not support electron.${Object.keys(input).find((fieldName) => !allowedFields.has(fieldName))}.`
+		: undefined;
+}
+
+export function compileAgentBrowserElectron(input: unknown): { compiled?: CompiledAgentBrowserElectron; error?: string } {
+	if (!isRecord(input)) return { error: "electron must be an object." };
+	const action = input.action;
+	if (typeof action !== "string" || !AGENT_BROWSER_ELECTRON_ACTIONS.includes(action as AgentBrowserElectronAction)) {
+		return { error: `electron.action must be one of: ${AGENT_BROWSER_ELECTRON_ACTIONS.join(", ")}.` };
+	}
+	for (const fieldName of ["query", "appPath", "appName", "bundleId", "executablePath", "launchId"] as const) {
+		const validation = validateOptionalNonEmptyString(input, fieldName);
+		if (validation.error) return { error: validation.error };
+	}
+	for (const fieldName of ["appArgs", "allow", "deny"] as const) {
+		const error = validateOptionalElectronStringArray(input, fieldName);
+		if (error) return { error };
+	}
+	const handoffError = validateOptionalElectronEnum(input, "handoff", AGENT_BROWSER_ELECTRON_HANDOFFS);
+	if (handoffError) return { error: handoffError };
+	const targetTypeError = validateOptionalElectronEnum(input, "targetType", AGENT_BROWSER_ELECTRON_TARGET_TYPES);
+	if (targetTypeError) return { error: targetTypeError };
+	for (const fieldName of ["maxResults", "timeoutMs"] as const) {
+		const validation = validateOptionalElectronPositiveInteger(input, fieldName);
+		if (validation.error) return { error: validation.error };
+	}
+	if (input.all !== undefined && input.all !== true) {
+		return { error: "electron.all must be true when provided." };
+	}
+	if (action === "list") {
+		const unsupportedListField = Object.keys(input).find((fieldName) => !AGENT_BROWSER_ELECTRON_LIST_FIELDS.has(fieldName));
+		if (unsupportedListField) {
+			return { error: `electron.list only supports query and maxResults; remove electron.${unsupportedListField}.` };
+		}
+		return {
+			compiled: {
+				action: "list",
+				maxResults: validateOptionalElectronPositiveInteger(input, "maxResults").value,
+				query: validateOptionalNonEmptyString(input, "query").value,
+			},
+		};
+	}
+	if (action === "probe") {
+		const unsupportedProbeField = Object.keys(input).find((fieldName) => !AGENT_BROWSER_ELECTRON_PROBE_FIELDS.has(fieldName));
+		if (unsupportedProbeField) {
+			return { error: `electron.probe only supports action, launchId, and timeoutMs; remove electron.${unsupportedProbeField}.` };
+		}
+		const launchId = validateOptionalNonEmptyString(input, "launchId").value;
+		const timeoutMs = validateOptionalElectronPositiveInteger(input, "timeoutMs").value;
+		return {
+			compiled: {
+				action: "probe",
+				...(launchId ? { launchId } : {}),
+				...(timeoutMs ? { timeoutMs } : {}),
+			},
+		};
+	}
+	if (action === "launch") {
+		const allowedFields = new Set(["action", "allow", "appArgs", "appName", "appPath", "bundleId", "deny", "executablePath", "handoff", "targetType", "timeoutMs"]);
+		const unsupportedFieldError = onlyAllowedElectronFields(input, action, allowedFields);
+		if (unsupportedFieldError) return { error: unsupportedFieldError };
+		const appArgs = (input.appArgs as string[] | undefined)?.map((item) => item.trim());
+		const appArgsError = validateElectronLaunchAppArgs(appArgs);
+		if (appArgsError) return { error: appArgsError };
+		const targetFields = ["appPath", "appName", "bundleId", "executablePath"] as const;
+		const providedTargets = targetFields.filter((fieldName) => input[fieldName] !== undefined);
+		if (providedTargets.length !== 1) {
+			return { error: "electron.launch requires exactly one of appPath, appName, bundleId, or executablePath." };
+		}
+		return {
+			compiled: {
+				action: "launch",
+				allow: (input.allow as string[] | undefined)?.map((item) => item.trim()),
+				appArgs,
+				deny: (input.deny as string[] | undefined)?.map((item) => item.trim()),
+				appName: validateOptionalNonEmptyString(input, "appName").value,
+				appPath: validateOptionalNonEmptyString(input, "appPath").value,
+				bundleId: validateOptionalNonEmptyString(input, "bundleId").value,
+				executablePath: validateOptionalNonEmptyString(input, "executablePath").value,
+				handoff: (input.handoff as "connect" | "snapshot" | "tabs" | undefined) ?? "snapshot",
+				targetType: (input.targetType as "any" | "page" | "webview" | undefined) ?? "page",
+				timeoutMs: validateOptionalElectronPositiveInteger(input, "timeoutMs").value,
+			},
+		};
+	}
+	const allowedFields = new Set(["action", "all", "launchId", "timeoutMs"]);
+	const unsupportedFieldError = onlyAllowedElectronFields(input, action, allowedFields);
+	if (unsupportedFieldError) return { error: unsupportedFieldError };
+	if (input.all === true && input.launchId !== undefined) {
+		return { error: `electron.${action} accepts launchId or all, not both.` };
+	}
+	return {
+		compiled: {
+			action: action as "cleanup" | "status",
+			all: input.all === true || undefined,
+			launchId: validateOptionalNonEmptyString(input, "launchId").value,
+			timeoutMs: validateOptionalElectronPositiveInteger(input, "timeoutMs").value,
+		},
+	};
+}

package/extensions/agent-browser/lib/input-modes/job.ts

@@ -0,0 +1,265 @@
+/**
+ * Purpose: Compile constrained job and lightweight QA wrapper inputs to upstream batch commands.
+ * Responsibilities: Validate job/QA fields, produce argv/stdin, and summarize QA diagnostic results.
+ * Scope: Job and QA modes only.
+ */
+
+import type { ArtifactVerificationSummary } from "../results/contracts.js";
+import { isRecord } from "../parsing.js";
+import { summarizeNetworkFailures } from "../results/network.js";
+import { getBatchResultItems, getCommandNameFromBatchItem, getSelectValues } from "./shared.js";
+import {
+	AGENT_BROWSER_JOB_STEP_ACTIONS,
+	AGENT_BROWSER_QA_LOAD_STATES,
+	type AgentBrowserJobStepAction,
+	type AgentBrowserQaLoadState,
+	type AgentBrowserQaPresetAnalysis,
+	type CompiledAgentBrowserJob,
+	type CompiledAgentBrowserJobStep,
+	type CompiledAgentBrowserQaPreset,
+} from "./types.js";
+
+function getRequiredJobString(step: Record<string, unknown>, field: "path" | "selector" | "text" | "url", action: AgentBrowserJobStepAction): { value?: string; error?: string } {
+	const value = step[field];
+	if (typeof value !== "string" || value.trim().length === 0) {
+		return { error: `job step ${action} requires a non-empty ${field} string.` };
+	}
+	return { value };
+}
+
+export function compileAgentBrowserJob(input: unknown): { compiled?: CompiledAgentBrowserJob; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "job must be an object." };
+	}
+	const rawSteps = input.steps;
+	if (!Array.isArray(rawSteps) || rawSteps.length === 0) {
+		return { error: "job.steps must be a non-empty array." };
+	}
+	const steps: CompiledAgentBrowserJobStep[] = [];
+	for (const [index, rawStep] of rawSteps.entries()) {
+		if (!isRecord(rawStep)) {
+			return { error: `job.steps[${index}] must be an object.` };
+		}
+		const action = rawStep.action;
+		if (typeof action !== "string" || !AGENT_BROWSER_JOB_STEP_ACTIONS.includes(action as AgentBrowserJobStepAction)) {
+			return { error: `job.steps[${index}].action must be one of: ${AGENT_BROWSER_JOB_STEP_ACTIONS.join(", ")}.` };
+		}
+		const jobAction = action as AgentBrowserJobStepAction;
+		let args: string[];
+		if (jobAction === "open") {
+			const result = getRequiredJobString(rawStep, "url", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["open", result.value as string];
+		} else if (jobAction === "click") {
+			const result = getRequiredJobString(rawStep, "selector", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["click", result.value as string];
+		} else if (jobAction === "fill") {
+			const selector = getRequiredJobString(rawStep, "selector", jobAction);
+			if (selector.error) return { error: `job.steps[${index}]: ${selector.error}` };
+			const text = getRequiredJobString(rawStep, "text", jobAction);
+			if (text.error) return { error: `job.steps[${index}]: ${text.error}` };
+			args = ["fill", selector.value as string, text.value as string];
+		} else if (jobAction === "select") {
+			const selector = getRequiredJobString(rawStep, "selector", jobAction);
+			if (selector.error) return { error: `job.steps[${index}]: ${selector.error}` };
+			const values = getSelectValues(rawStep, `job.steps[${index}]`);
+			if (values.error) return { error: values.error };
+			args = ["select", selector.value as string, ...(values.values as string[])];
+		} else if (jobAction === "wait") {
+			const milliseconds = rawStep.milliseconds;
+			if (typeof milliseconds !== "number" || !Number.isInteger(milliseconds) || milliseconds <= 0) {
+				return { error: `job.steps[${index}]: job step wait requires a positive integer milliseconds value.` };
+			}
+			args = ["wait", String(milliseconds)];
+		} else if (jobAction === "assertText") {
+			const result = getRequiredJobString(rawStep, "text", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--text", result.value as string];
+		} else if (jobAction === "assertUrl") {
+			const result = getRequiredJobString(rawStep, "url", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--url", result.value as string];
+		} else if (jobAction === "waitForDownload") {
+			const result = getRequiredJobString(rawStep, "path", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["wait", "--download", result.value as string];
+		} else {
+			const result = getRequiredJobString(rawStep, "path", jobAction);
+			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
+			args = ["screenshot", result.value as string];
+		}
+		steps.push({ action: jobAction, args });
+	}
+	return { compiled: { args: ["batch"], stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
+}
+
+export function isHttpOrHttpsUrl(url: string): boolean {
+	try {
+		const protocol = new URL(url).protocol;
+		return protocol === "http:" || protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+
+function describeQaChecksRun(checks: CompiledAgentBrowserQaPreset["checks"]): string {
+	const parts = [`load:${checks.loadState}`];
+	if (checks.expectedText.length > 0) parts.push(`text×${checks.expectedText.length}`);
+	if (checks.expectedSelector) parts.push("selector");
+	if (checks.checkNetwork) parts.push("network");
+	if (checks.checkConsole) parts.push("console");
+	if (checks.checkErrors) parts.push("errors");
+	if (checks.screenshotPath) parts.push("screenshot");
+	return parts.join(", ");
+}
+
+export function extractQaPageContext(options: {
+	attachedTarget?: { title?: string; url?: string };
+	batchData?: unknown;
+	compiled?: CompiledAgentBrowserQaPreset;
+}): { title?: string; url?: string } {
+	if (options.attachedTarget?.title || options.attachedTarget?.url) {
+		return { title: options.attachedTarget.title, url: options.attachedTarget.url };
+	}
+	for (const item of getBatchResultItems(options.batchData)) {
+		if (getCommandNameFromBatchItem(item) !== "open" || !isRecord(item.result)) continue;
+		const url = typeof item.result.url === "string" ? item.result.url : undefined;
+		const title = typeof item.result.title === "string" ? item.result.title : undefined;
+		if (url || title) return { title, url };
+	}
+	if (options.compiled?.checks.url) {
+		return { url: options.compiled.checks.url };
+	}
+	return {};
+}
+
+export function buildQaCompactPassText(options: {
+	artifactVerification?: ArtifactVerificationSummary;
+	batchStepCount: number;
+	checks: CompiledAgentBrowserQaPreset["checks"];
+	page?: { title?: string; url?: string };
+	qaPreset: AgentBrowserQaPresetAnalysis;
+}): string {
+	const lines = [options.qaPreset.summary];
+	const pageParts = [options.page?.title, options.page?.url].filter((part): part is string => typeof part === "string" && part.length > 0);
+	if (pageParts.length > 0) lines.push(`Page: ${pageParts.join(" — ")}`);
+	lines.push(`Checks run: ${describeQaChecksRun(options.checks)} (${options.batchStepCount} batch step${options.batchStepCount === 1 ? "" : "s"})`);
+	if (options.checks.screenshotPath) {
+		const verification = options.artifactVerification;
+		lines.push(verification
+			? `Screenshot: ${options.checks.screenshotPath} (${verification.verifiedCount}/${verification.artifacts.length} verified on disk)`
+			: `Screenshot: ${options.checks.screenshotPath}`);
+	}
+	lines.push("Full diagnostic matrix: see details.qaPreset and details.batchSteps.");
+	return lines.join("\n");
+}
+
+export function analyzeQaPresetResults(data: unknown): AgentBrowserQaPresetAnalysis | undefined {
+	const items = getBatchResultItems(data);
+	if (items.length === 0) return undefined;
+	const failedChecks: string[] = [];
+	const warnings: string[] = [];
+	for (const item of items) {
+		if (item.success === false) {
+			failedChecks.push(`${getCommandNameFromBatchItem(item) ?? "step"} failed`);
+		}
+		const result = isRecord(item.result) ? item.result : undefined;
+		const commandName = getCommandNameFromBatchItem(item);
+		if (commandName === "errors" && Array.isArray(result?.errors) && result.errors.length > 0) {
+			failedChecks.push(`${result.errors.length} page error(s)`);
+		}
+		if (commandName === "console" && Array.isArray(result?.messages)) {
+			const errorCount = result.messages.filter((message) => isRecord(message) && /error/i.test(String(message.type ?? message.level ?? ""))).length;
+			if (errorCount > 0) failedChecks.push(`${errorCount} console error message(s)`);
+		}
+		if (commandName === "network" && Array.isArray(result?.requests)) {
+			const networkFailures = summarizeNetworkFailures(result.requests);
+			if (networkFailures.actionableCount > 0) failedChecks.push(`${networkFailures.actionableCount} actionable failed network request(s)`);
+			if (networkFailures.benignCount > 0) warnings.push(`${networkFailures.benignCount} benign network request failure(s) ignored`);
+		}
+	}
+	const uniqueFailures = [...new Set(failedChecks)];
+	const uniqueWarnings = [...new Set(warnings)];
+	return {
+		failedChecks: uniqueFailures,
+		passed: uniqueFailures.length === 0,
+		summary: uniqueFailures.length === 0
+			? uniqueWarnings.length === 0 ? "QA preset passed." : `QA preset passed with warnings: ${uniqueWarnings.join("; ")}.`
+			: `QA preset failed: ${uniqueFailures.join("; ")}.`,
+		warnings: uniqueWarnings,
+	};
+}
+
+export function compileAgentBrowserQaPreset(input: unknown): { compiled?: CompiledAgentBrowserQaPreset; error?: string } {
+	if (!isRecord(input)) {
+		return { error: "qa must be an object." };
+	}
+	const attached = input.attached === true;
+	if (input.attached !== undefined && typeof input.attached !== "boolean") {
+		return { error: "qa.attached must be a boolean when provided." };
+	}
+	const url = input.url;
+	if (attached && url !== undefined) {
+		return { error: "qa.url must be omitted when qa.attached is true." };
+	}
+	if (!attached && (typeof url !== "string" || url.trim().length === 0)) {
+		return { error: "qa.url must be a non-empty string." };
+	}
+	const normalizedUrl = typeof url === "string" ? url.trim() : undefined;
+	const expectedText = input.expectedText === undefined
+		? []
+		: typeof input.expectedText === "string"
+			? [input.expectedText]
+			: Array.isArray(input.expectedText)
+				? input.expectedText
+				: undefined;
+	if (!expectedText || expectedText.some((text) => typeof text !== "string" || text.trim().length === 0)) {
+		return { error: "qa.expectedText must be a non-empty string or array of non-empty strings when provided." };
+	}
+	const expectedSelector = input.expectedSelector;
+	if (expectedSelector !== undefined && (typeof expectedSelector !== "string" || expectedSelector.trim().length === 0)) {
+		return { error: "qa.expectedSelector must be a non-empty string when provided." };
+	}
+	const screenshotPath = input.screenshotPath;
+	if (screenshotPath !== undefined && (typeof screenshotPath !== "string" || screenshotPath.trim().length === 0)) {
+		return { error: "qa.screenshotPath must be a non-empty string when provided." };
+	}
+	for (const field of ["checkConsole", "checkErrors", "checkNetwork"] as const) {
+		if (input[field] !== undefined && typeof input[field] !== "boolean") {
+			return { error: `qa.${field} must be a boolean when provided.` };
+		}
+	}
+	const rawLoadState = input.loadState;
+	if (rawLoadState !== undefined && (typeof rawLoadState !== "string" || !AGENT_BROWSER_QA_LOAD_STATES.includes(rawLoadState as AgentBrowserQaLoadState))) {
+		return { error: `qa.loadState must be one of: ${AGENT_BROWSER_QA_LOAD_STATES.join(", ")}.` };
+	}
+	const checkConsole = input.checkConsole !== false;
+	const checkErrors = input.checkErrors !== false;
+	const checkNetwork = input.checkNetwork !== false;
+	const loadState = (rawLoadState as AgentBrowserQaLoadState | undefined) ?? "domcontentloaded";
+	const steps: CompiledAgentBrowserJobStep[] = [];
+	if (checkNetwork) steps.push({ action: "wait", args: ["network", "requests", "--clear"] });
+	if (checkConsole) steps.push({ action: "wait", args: ["console", "--clear"] });
+	if (checkErrors) steps.push({ action: "wait", args: ["errors", "--clear"] });
+	if (!attached && normalizedUrl) steps.push({ action: "open", args: ["open", normalizedUrl] });
+	steps.push({ action: "wait", args: ["wait", "--load", loadState] });
+	for (const text of expectedText) {
+		steps.push({ action: "assertText", args: ["wait", "--text", text] });
+	}
+	if (typeof expectedSelector === "string") {
+		steps.push({ action: "wait", args: ["wait", expectedSelector] });
+	}
+	if (checkNetwork) steps.push({ action: "wait", args: ["network", "requests"] });
+	if (checkConsole) steps.push({ action: "wait", args: ["console"] });
+	if (checkErrors) steps.push({ action: "wait", args: ["errors"] });
+	if (typeof screenshotPath === "string") steps.push({ action: "screenshot", args: ["screenshot", screenshotPath] });
+	return {
+		compiled: {
+			args: ["batch"],
+			checks: { attached, checkConsole, checkErrors, checkNetwork, expectedSelector, expectedText, loadState, screenshotPath, url: normalizedUrl },
+			stdin: JSON.stringify(steps.map((step) => step.args)),
+			steps,
+		},
+	};
+}