@forsion/tangu-computer-use 0.5.8

package/src/vendor/output.ts

@@ -0,0 +1,134 @@
+import { closeSync, mkdtempSync, openSync, readSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+export const MODEL_TEXT_MAX_BYTES = 48 * 1024;
+export const MODEL_TEXT_MAX_LINES = 2_000;
+export const OUTPUT_PAGE_BYTES = 16 * 1024;
+export const UI_TEXT_PAGE_CHARS = 12 * 1024;
+export const MODEL_PREVIEW_BYTES = 16 * 1024;
+const OUTPUT_ENTRY_MAX_BYTES = 16 * 1024 * 1024;
+const OUTPUT_STORE_MAX_BYTES = 64 * 1024 * 1024;
+
+interface StoredOutput {
+	ref: string;
+	filePath: string;
+	storedBytes: number;
+	totalBytes: number;
+	complete: boolean;
+}
+
+const outputs = new Map<string, StoredOutput>();
+let outputDirectory: string | undefined;
+let outputBytes = 0;
+let nextOutputId = 1;
+
+function utf8Prefix(bytes: Uint8Array, maxBytes: number): Uint8Array {
+	if (bytes.byteLength <= maxBytes) return bytes;
+	let end = Math.max(0, maxBytes);
+	while (end > 0 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+	return bytes.subarray(0, end);
+}
+
+function boundedPrefix(value: string, maxBytes: number, maxLines: number): string {
+	const lines = value.split("\n", maxLines + 1);
+	const lineBounded = lines.length > maxLines ? lines.slice(0, maxLines).join("\n") : value;
+	return new TextDecoder().decode(utf8Prefix(new TextEncoder().encode(lineBounded), maxBytes));
+}
+
+function storeOutput(value: string): StoredOutput {
+	const encoded = new TextEncoder().encode(value);
+	const stored = encoded.byteLength > OUTPUT_ENTRY_MAX_BYTES ? utf8Prefix(encoded, OUTPUT_ENTRY_MAX_BYTES) : encoded;
+	outputDirectory ??= mkdtempSync(path.join(os.tmpdir(), "tangu-computer-use-output-"));
+	const ref = `@o${nextOutputId++}`;
+	const filePath = path.join(outputDirectory, `${ref.slice(2)}.txt`);
+	writeFileSync(filePath, stored, { mode: 0o600 });
+	const entry: StoredOutput = { ref, filePath, storedBytes: stored.byteLength, totalBytes: encoded.byteLength, complete: stored.byteLength === encoded.byteLength };
+	outputs.set(entry.ref, entry);
+	outputBytes += entry.storedBytes;
+	while (outputBytes > OUTPUT_STORE_MAX_BYTES && outputs.size > 1) {
+		const oldestRef = outputs.keys().next().value as string | undefined;
+		if (!oldestRef) break;
+		const oldest = outputs.get(oldestRef)!;
+		outputs.delete(oldestRef);
+		outputBytes -= oldest.storedBytes;
+		try { unlinkSync(oldest.filePath); } catch { /* already removed */ }
+	}
+	return entry;
+}
+
+function refinementFor(tool: string): string {
+	if (tool === "search_ui") return "use a more selective text, role, or capability predicate";
+	if (tool === "find_roots") return "use a more selective text, app, bundleId, pid, or kind filter";
+	if (tool === "evaluate_browser") return "return selected fields, an aggregate, or a smaller slice";
+	if (tool === "observe_ui" || tool === "expand_ui") return "use search_ui or expand a more specific ref";
+	return "request a smaller or more focused result";
+}
+
+export function applyOutputEnvelope<T>(tool: string, result: AgentToolResult<T>): AgentToolResult<T> {
+	const textParts = result.content.filter((part): part is Extract<(typeof result.content)[number], { type: "text" }> => part.type === "text");
+	const combined = textParts.map((part) => part.text).join("\n");
+	const bytes = new TextEncoder().encode(combined).byteLength;
+	const lines = combined === "" ? 0 : combined.split("\n").length;
+	if (bytes <= MODEL_TEXT_MAX_BYTES && lines <= MODEL_TEXT_MAX_LINES) return result;
+
+	const entry = storeOutput(combined);
+	const preview = boundedPrefix(combined, MODEL_PREVIEW_BYTES, MODEL_TEXT_MAX_LINES - 4);
+	const returnedBytes = new TextEncoder().encode(preview).byteLength;
+	const availability = entry.complete
+		? `continue: read_text({ ref: "${entry.ref}", offset: ${returnedBytes} })`
+		: `continue: read_text({ ref: "${entry.ref}", offset: ${returnedBytes} }); only the first ${entry.storedBytes} bytes were stored, so refine for the remainder`;
+	const trailer = [
+		`output truncated: returned ${returnedBytes} of ${entry.totalBytes} utf-8 bytes`,
+		`refine: ${refinementFor(tool)}`,
+		availability,
+	].join("\n");
+	const images = result.content.filter((part) => part.type === "image");
+	return { ...result, content: [{ type: "text", text: `${preview}\n\n${trailer}` }, ...images] };
+}
+
+export function boundToolError(tool: string, error: unknown): Error {
+	const message = error instanceof Error ? error.message : String(error);
+	const bytes = new TextEncoder().encode(message).byteLength;
+	const lines = message.split("\n").length;
+	if (bytes <= MODEL_TEXT_MAX_BYTES && lines <= MODEL_TEXT_MAX_LINES) return error instanceof Error ? error : new Error(message);
+	const entry = storeOutput(message);
+	const preview = boundedPrefix(message, MODEL_PREVIEW_BYTES, MODEL_TEXT_MAX_LINES - 4);
+	const returnedBytes = new TextEncoder().encode(preview).byteLength;
+	const storageNote = entry.complete ? "" : `; only the first ${entry.storedBytes} bytes were stored`;
+	return new Error(`${preview}\n\nerror truncated: returned ${returnedBytes} of ${entry.totalBytes} utf-8 bytes\nrefine: ${refinementFor(tool)}\ncontinue: read_text({ ref: "${entry.ref}", offset: ${returnedBytes} })${storageNote}`);
+}
+
+export function readStoredOutput(ref: string, offsetValue: unknown): { text: string; offset: number; limit: number; totalBytes: number; hasMore: boolean; complete: boolean } | undefined {
+	const entry = outputs.get(ref);
+	if (!entry) return undefined;
+	let offset = Math.min(entry.storedBytes, Math.max(0, Math.trunc(typeof offsetValue === "number" && Number.isFinite(offsetValue) ? offsetValue : 0)));
+	const requestedBytes = Math.min(entry.storedBytes - offset, OUTPUT_PAGE_BYTES + 4);
+	const buffer = new Uint8Array(Math.max(0, requestedBytes));
+	const fd = openSync(entry.filePath, "r");
+	try { if (buffer.byteLength > 0) readSync(fd, buffer, 0, buffer.byteLength, offset); } finally { closeSync(fd); }
+	let start = 0;
+	while (start < buffer.byteLength && (buffer[start] & 0xc0) === 0x80) start += 1;
+	offset += start;
+	const slice = utf8Prefix(buffer.subarray(start), OUTPUT_PAGE_BYTES);
+	const actualEnd = offset + slice.byteLength;
+	return {
+		text: new TextDecoder().decode(slice),
+		offset,
+		limit: slice.byteLength,
+		totalBytes: entry.totalBytes,
+		hasMore: actualEnd < entry.storedBytes,
+		complete: entry.complete,
+	};
+}
+
+export function clearStoredOutputs(): void {
+	outputs.clear();
+	if (outputDirectory) {
+		try { rmSync(outputDirectory, { recursive: true, force: true }); } catch { /* best-effort session cleanup */ }
+	}
+	outputDirectory = undefined;
+	outputBytes = 0;
+	nextOutputId = 1;
+}

package/src/vendor/permissions.ts

@@ -0,0 +1,111 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// Which process identity the permission answers reflect. Platforms may
+// attribute grants to a responsible parent process rather than the helper
+// executable itself.
+export type PermissionAttribution = "helper-app" | "caller";
+export type PermissionKind = "accessibility" | "screenRecording";
+
+export interface PermissionSource {
+	attribution: PermissionAttribution;
+	pid?: number;
+	parentPid?: number;
+	executablePath?: string;
+	parentPath?: string;
+	parentBundleId?: string;
+	os?: string;
+}
+
+export interface PermissionStatus {
+	accessibility: boolean;
+	screenRecording: boolean;
+	screenRecordingPreflight?: boolean;
+	source?: PermissionSource;
+}
+
+interface PermissionKindCopy {
+	kind: PermissionKind;
+	openOption: string;
+}
+
+interface PermissionFlowCopy {
+	nonInteractiveError(helperPath: string): string;
+	prompt(status: PermissionStatus, helperPath: string, hint?: string): string;
+	incompleteError(helperPath: string): string;
+	readyMessage: string;
+	stillMissing(kinds: PermissionKind[]): string;
+}
+
+export interface PermissionBridge {
+	kinds: PermissionKindCopy[];
+	copy: PermissionFlowCopy;
+	checkPermissions(signal?: AbortSignal): Promise<PermissionStatus>;
+	registerPermissions(signal?: AbortSignal): Promise<void>;
+	openPermissionPane(kind: PermissionKind, signal?: AbortSignal): Promise<void>;
+	// Platforms may cache permission answers per process, so restart before
+	// recheck lets a new grant become visible to the helper.
+	restartHelper(signal?: AbortSignal): Promise<void>;
+	permissionHint?: string;
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+	if (signal?.aborted) throw new Error("Operation aborted.");
+}
+
+function granted(status: PermissionStatus, kind: PermissionKind): boolean {
+	return status[kind] === true;
+}
+
+function allGranted(status: PermissionStatus, kinds: PermissionKindCopy[]): boolean {
+	return kinds.every(({ kind }) => granted(status, kind));
+}
+
+function missingKinds(status: PermissionStatus, kinds: PermissionKindCopy[]): PermissionKind[] {
+	return kinds.flatMap(({ kind }) => granted(status, kind) ? [] : [kind]);
+}
+
+export async function ensurePermissions(
+	ctx: ExtensionContext,
+	bridge: PermissionBridge,
+	helperPath: string,
+	signal?: AbortSignal,
+): Promise<PermissionStatus> {
+	let status = await bridge.checkPermissions(signal);
+	if (allGranted(status, bridge.kinds)) return status;
+
+	if (!ctx.hasUI) throw new Error(bridge.copy.nonInteractiveError(helperPath));
+
+	// Register before prompting so platform settings panes can already list
+	// the helper and the user only has to enable existing entries.
+	await bridge.registerPermissions(signal).catch(() => undefined);
+
+	while (!allGranted(status, bridge.kinds)) {
+		throwIfAborted(signal);
+
+		const missing = missingKinds(status, bridge.kinds);
+		const options = bridge.kinds
+			.filter(({ kind }) => missing.includes(kind))
+			.map(({ openOption }) => openOption);
+		options.push("Recheck (restarts helper)", "Cancel");
+
+		const choice = await ctx.ui.select(bridge.copy.prompt(status, helperPath, bridge.permissionHint), options, { signal });
+		if (!choice || choice === "Cancel") throw new Error(bridge.copy.incompleteError(helperPath));
+
+		const selected = bridge.kinds.find(({ openOption }) => choice === openOption);
+		if (selected) await bridge.openPermissionPane(selected.kind, signal);
+
+		if (choice.startsWith("Recheck")) {
+			// Restart first: permission decisions can be cached by a running
+			// helper process and remain stale after the user grants access.
+			await bridge.restartHelper(signal);
+			status = await bridge.checkPermissions(signal);
+			if (allGranted(status, bridge.kinds)) {
+				ctx.ui.notify(bridge.copy.readyMessage, "info");
+			} else {
+				ctx.ui.notify(bridge.copy.stillMissing(missingKinds(status, bridge.kinds)), "warning");
+			}
+		}
+	}
+
+	return status;
+}

package/src/vendor/platform/architecture.ts

@@ -0,0 +1,23 @@
+import type { PlatformDiagnostics } from "./types.ts";
+
+export const PLATFORM_ARCHITECTURE_VERSION = 1;
+export const REQUIRED_PLATFORM_INVARIANTS = [
+	"state-scoped-observations",
+	"bounded-observation-history",
+	"multi-root-forest",
+	"progressive-disclosure",
+	"atomic-physical-input",
+	"concurrent-requests",
+	"transactional-batching",
+] as const;
+
+export function assertPlatformArchitecture(platform: string, diagnostics: PlatformDiagnostics): void {
+	if (diagnostics.architectureVersion !== PLATFORM_ARCHITECTURE_VERSION) {
+		throw new Error(`${platform} helper architecture mismatch: expected ${PLATFORM_ARCHITECTURE_VERSION}, got ${diagnostics.architectureVersion ?? "unknown"}. Rebuild and restart the helper.`);
+	}
+	const reported = new Set(diagnostics.invariants ?? []);
+	const missing = REQUIRED_PLATFORM_INVARIANTS.filter((invariant) => !reported.has(invariant));
+	if (missing.length > 0) {
+		throw new Error(`${platform} helper does not satisfy the shared computer-use contract: ${missing.join(", ")}.`);
+	}
+}

package/src/vendor/platform/coerce.ts

@@ -0,0 +1,16 @@
+export function toBoolean(value: unknown): boolean {
+	return value === true || value === "true" || value === 1;
+}
+
+export function toFiniteNumber(value: unknown, fallback: number): number {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return fallback;
+}
+
+export function toOptionalString(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/vendor/platform/index.ts

@@ -0,0 +1,59 @@
+import { macosBackend } from "./macos/backend.ts";
+import { isBrowserApp, isChromeFamilyApp, openBrowserLocationWithAppleScript } from "./macos/browser.ts";
+import { ensureMacosReady } from "./macos/permissions.ts";
+import type { ComputerUsePlatformBackend, PlatformName } from "./types.ts";
+import { linuxBackend } from "./linux/backend.ts";
+import { windowsBackend } from "./windows/backend.ts";
+
+const macosPlatformBackend: ComputerUsePlatformBackend = {
+	name: "macos",
+	ensureReady: ensureMacosReady,
+	listApps: macosBackend.listApps,
+	listRoots: macosBackend.listRoots,
+	getFrontmost: macosBackend.getFrontmost,
+	focusWindow: macosBackend.focusWindow,
+	observe: macosBackend.observe,
+	act: macosBackend.act,
+	actBatch: macosBackend.actBatch,
+	readText: macosBackend.readText,
+	waitFor: macosBackend.waitFor,
+	isBrowserApp,
+	isChromeFamilyApp,
+	openBrowserLocation: openBrowserLocationWithAppleScript,
+};
+
+class UnsupportedPlatformBackend implements ComputerUsePlatformBackend {
+	readonly name: PlatformName;
+	private readonly platform: NodeJS.Platform;
+
+	constructor(platform: NodeJS.Platform) {
+		this.platform = platform;
+		this.name = platform === "win32" ? "windows" : "linux";
+	}
+
+	private unsupported(): never {
+		throw new Error(`tangu-computer-use does not support platform '${this.platform}' yet.`);
+	}
+
+	async ensureReady(): Promise<never> { this.unsupported(); }
+	async listApps(): Promise<never> { this.unsupported(); }
+	async listRoots(): Promise<never> { this.unsupported(); }
+	async getFrontmost(): Promise<never> { this.unsupported(); }
+	async focusWindow(): Promise<never> { this.unsupported(); }
+	async observe(): Promise<never> { this.unsupported(); }
+	async act(): Promise<never> { this.unsupported(); }
+	async readText(): Promise<never> { this.unsupported(); }
+	async waitFor(): Promise<never> { this.unsupported(); }
+	isBrowserApp(): never { this.unsupported(); }
+	isChromeFamilyApp(): never { this.unsupported(); }
+	async openBrowserLocation(): Promise<boolean> { this.unsupported(); }
+}
+
+export function platformBackendForRuntime(platform: NodeJS.Platform = process.platform): ComputerUsePlatformBackend {
+	if (platform === "darwin") return macosPlatformBackend;
+	if (platform === "win32") return windowsBackend;
+	if (platform === "linux") return linuxBackend;
+	return new UnsupportedPlatformBackend(platform);
+}
+
+export const currentPlatformBackend = platformBackendForRuntime();

package/src/vendor/platform/linux/backend.ts

@@ -0,0 +1,186 @@
+import { parseLookResponse, type LookResponse } from "../../outline.ts";
+import { assertPlatformArchitecture } from "../architecture.ts";
+import { toBoolean, toFiniteNumber, toOptionalString } from "../coerce.ts";
+import type {
+	ComputerUsePlatformBackend,
+	FramePoints,
+	HelperActResult,
+	PlatformActRequest,
+	PlatformApp,
+	PlatformFocusWindowResult,
+	PlatformFrontmostResult,
+	PlatformObserveRequest,
+	PlatformReadTextRequest,
+	PlatformReadTextResponse,
+	PlatformReadyState,
+	PlatformRoot,
+	PlatformRootKind,
+	PlatformRootQuery,
+	PlatformTarget,
+	PlatformWaitForRequest,
+	PlatformWaitForResponse,
+} from "../types.ts";
+import { LINUX_HELPER_PROTOCOL_VERSION, linuxHelper } from "./helper.ts";
+
+function normalizedProcessName(appName: string): string {
+	return appName.toLowerCase().split("/").pop()!.replace(/\.desktop$/i, "");
+}
+
+function classifyBrowser(appName: string): false | "chromium" | "firefox" {
+	switch (normalizedProcessName(appName)) {
+		case "chrome":
+		case "google-chrome":
+		case "google-chrome-stable":
+		case "chromium":
+		case "chromium-browser":
+		case "microsoft-edge":
+		case "microsoft-edge-stable":
+		case "brave":
+		case "brave-browser":
+		case "vivaldi":
+		case "vivaldi-stable":
+		case "opera":
+			return "chromium";
+		case "firefox":
+		case "firefox-esr":
+			return "firefox";
+		default:
+			return false;
+	}
+}
+
+function parseFramePoints(raw: unknown): FramePoints {
+	const frame = (raw as any)?.framePoints ?? (raw as any)?.bounds ?? {};
+	return {
+		x: toFiniteNumber(frame.x, 0),
+		y: toFiniteNumber(frame.y, 0),
+		w: Math.max(1, toFiniteNumber(frame.w ?? frame.width, 1)),
+		h: Math.max(1, toFiniteNumber(frame.h ?? frame.height, 1)),
+	};
+}
+
+function parseRootKind(raw: unknown): PlatformRootKind {
+	return raw === "menu" || raw === "sheet" || raw === "dialog" || raw === "popover" || raw === "window" ? raw : "window";
+}
+
+function parseRoots(result: unknown): PlatformRoot[] {
+	const roots = Array.isArray(result) ? result : (result as any)?.roots;
+	if (!Array.isArray(roots)) return [];
+	return roots.map((raw: any, index): PlatformRoot => ({
+		kind: parseRootKind(raw?.kind),
+		rootRef: toOptionalString(raw?.rootRef ?? raw?.windowRef ?? raw?.ref),
+		windowRef: toOptionalString(raw?.windowRef ?? raw?.rootRef ?? raw?.ref),
+		windowId: Number.isFinite(raw?.windowId) ? Math.trunc(raw.windowId) : undefined,
+		pid: Number.isFinite(raw?.pid) ? Math.trunc(raw.pid) : undefined,
+		appName: toOptionalString(raw?.appName ?? raw?.processName),
+		bundleId: toOptionalString(raw?.bundleId ?? raw?.desktopId),
+		title: toOptionalString(raw?.title) ?? "",
+		role: toOptionalString(raw?.role),
+		subrole: toOptionalString(raw?.subrole),
+		zOrder: Math.trunc(toFiniteNumber(raw?.zOrder, index)),
+		framePoints: parseFramePoints(raw),
+		scaleFactor: Math.max(1, toFiniteNumber(raw?.scaleFactor, 1)),
+		isOnscreen: raw?.isOnscreen === undefined ? true : toBoolean(raw.isOnscreen),
+		isFocused: toBoolean(raw?.isFocused),
+		isMinimized: toBoolean(raw?.isMinimized),
+		isMain: toBoolean(raw?.isMain ?? raw?.isFocused),
+		isModal: toBoolean(raw?.isModal),
+		metadata: raw?.metadata,
+	}));
+}
+
+function appsFromRoots(roots: PlatformRoot[]): PlatformApp[] {
+	const seen = new Set<number>();
+	return roots.flatMap((root) => {
+		if (!root.pid || seen.has(root.pid)) return [];
+		seen.add(root.pid);
+		return [{
+			appName: root.appName ?? "Unknown",
+			bundleId: root.bundleId,
+			pid: root.pid,
+			isFrontmost: root.isFocused,
+		}];
+	});
+}
+
+function helperAction(request: PlatformActRequest): Record<string, unknown> {
+	if (!("focus" in request.target)) return { ...request };
+	return { ...request, target: request.target.focus, params: { ...request.params, preserveFocus: true } };
+}
+
+async function ensureReady(_ctx: unknown, state: PlatformReadyState, signal?: AbortSignal): Promise<PlatformReadyState> {
+	await linuxHelper.ensureInstalled(signal);
+	const diagnostics = await linuxHelper.command<any>("diagnostics", {}, { signal, timeoutMs: 5_000 });
+	if (diagnostics?.protocolVersion !== LINUX_HELPER_PROTOCOL_VERSION) {
+		throw new Error(`Linux helper protocol mismatch: expected ${LINUX_HELPER_PROTOCOL_VERSION}, got ${diagnostics?.protocolVersion ?? "unknown"}. Restart Tangu to use the installed helper.`);
+	}
+	assertPlatformArchitecture("Linux", diagnostics);
+	if (diagnostics?.accessibility === false) {
+		throw new Error("Linux accessibility is unavailable. Ensure AT-SPI is enabled and a D-Bus desktop accessibility bus is running.");
+	}
+	return { ...state, lastPermissionCheckAt: Date.now(), helperDiagnostics: diagnostics };
+}
+
+export const linuxBackend: ComputerUsePlatformBackend = {
+	name: "linux",
+	shutdown(): void {
+		linuxHelper.dispose();
+	},
+	ensureReady,
+	async listApps(signal?: AbortSignal): Promise<PlatformApp[]> {
+		return appsFromRoots(parseRoots(await linuxHelper.command("listRoots", {}, { signal })));
+	},
+	async listRoots(query: PlatformRootQuery, signal?: AbortSignal): Promise<PlatformRoot[]> {
+		const roots = parseRoots(await linuxHelper.command("listRoots", Number.isFinite(query.pid) ? { pid: Math.trunc(query.pid!) } : {}, { signal }));
+		const title = query.title?.trim().toLowerCase();
+		return title ? roots.filter((root) => root.title.trim().toLowerCase().includes(title)) : roots;
+	},
+	async getFrontmost(signal?: AbortSignal): Promise<PlatformFrontmostResult> {
+		const roots = parseRoots(await linuxHelper.command("listRoots", {}, { signal }));
+		const focused = roots.find((root) => root.isFocused) ?? roots[0];
+		if (!focused?.pid) throw new Error("No frontmost window was available.");
+		return {
+			appName: focused.appName ?? "Unknown",
+			bundleId: focused.bundleId,
+			pid: focused.pid,
+			windowTitle: focused.title,
+			windowId: focused.windowId,
+			rootRef: focused.rootRef,
+		};
+	},
+	async focusWindow(target: PlatformTarget, signal?: AbortSignal): Promise<PlatformFocusWindowResult> {
+		return await linuxHelper.command("focusWindow", { ...target }, { signal });
+	},
+	async observe(request: PlatformObserveRequest, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<LookResponse> {
+		return parseLookResponse(await linuxHelper.command("look", {
+			...request.target,
+			baseLookId: request.baseLookId,
+			maxDimension: request.maxDimension,
+			readText: request.readText,
+			scopeRef: request.scopeRef,
+			includeImage: request.includeImage,
+		}, options));
+	},
+	async act(request: PlatformActRequest, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<HelperActResult> {
+		return await linuxHelper.command("act", helperAction(request), options);
+	},
+	async actBatch(requests: PlatformActRequest[], options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<HelperActResult> {
+		return await linuxHelper.command("actBatch", { actions: requests.map(helperAction) }, options);
+	},
+	async readText(args: PlatformReadTextRequest, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<PlatformReadTextResponse> {
+		return await linuxHelper.command("atspiReadText", { ...args }, options);
+	},
+	async waitFor(args: PlatformWaitForRequest, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<PlatformWaitForResponse> {
+		return await linuxHelper.command("atspiWaitFor", { ...args }, options);
+	},
+	isBrowserApp(appName: string): boolean {
+		return classifyBrowser(appName) !== false;
+	},
+	isChromeFamilyApp(appName: string): boolean {
+		return classifyBrowser(appName) === "chromium";
+	},
+	async openBrowserLocation(target: { appName: string; bundleId?: string }, url: string, signal?: AbortSignal): Promise<boolean> {
+		await linuxHelper.command("openBrowserLocation", { ...target, url }, { signal, timeoutMs: 10_000 });
+		return true;
+	},
+};