import { fileURLToPath } from "node:url"; import { z } from "zod"; import { isMachOFormat, type BinaryTarget, } from "../domain/binaryTargetTypes.js"; import { nativeUiObservationInputSchema, nativeUiScenarioInputSchema, nativeUiSnapshotSchema, nativeUiResultSchema, } from "../domain/native/nativeUiObservation.js"; import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, } from "../domain/analysisErrorCore.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import { err, ok, type Result } from "../domain/result.js"; import { createNativeUiHelperRuntime, type NativeUiHelperRuntime, } from "./NativeUiHelperRuntime.js"; import { NATIVE_UI_OUTPUT_BUDGET_BYTES, NATIVE_UI_OUTPUT_WEIGHT, } from "./NativeUiOutputBudget.js"; const helper = fileURLToPath( new URL("../../bridge/native/ReaNativeUI.swift", import.meta.url), ); const responseSchema = z.discriminatedUnion("ok", [ z.strictObject({ ok: z.literal(true), result: nativeUiSnapshotSchema }), z.strictObject({ ok: z.literal(false), code: z.string(), message: z.string(), }), ]); /** Narrow process seam preserves the native helper's OS and target failures. */ export type NativeUiHelper = ( parameters: Readonly>, signal?: AbortSignal, ) => Promise; /** Capture a selected existing app window and run explicitly selected scenarios. */ export const observeNativeUi = async ( target: BinaryTarget, operation: "observe_native_ui" | "capture_native_ui_scenario", parameters: unknown, options: { environment: Readonly; signal?: AbortSignal | undefined; invoke?: NativeUiHelper; runtime?: NativeUiHelperRuntime; }, ): Promise, AnalysisError>> => { const runtime = options.runtime ?? createNativeUiHelperRuntime(options.environment); try { return await observeWithHelper(target, operation, parameters, { ...options, invoke: options.invoke ?? runtime.invoke, }); } finally { if (options.runtime === undefined) await runtime.close(); } }; const observeWithHelper = async ( target: BinaryTarget, operation: "observe_native_ui" | "capture_native_ui_scenario", parameters: unknown, options: { signal?: AbortSignal | undefined; invoke: NativeUiHelper }, ): Promise, AnalysisError>> => { const parsed = ( operation === "observe_native_ui" ? nativeUiObservationInputSchema : nativeUiScenarioInputSchema ).safeParse(parameters); if (!parsed.success) return err(new AnalysisInputError(operation, { cause: parsed.error })); if (target.kind !== "executable" || !isMachOFormat(target.format)) return err( new AnalysisCapabilityUnavailableError( "native-macos", operation, "Native UI observation requires an active Mach-O executable or app target", ), ); const input = parsed.data; if (!input.screenshot && !input.accessibility) return err( new AnalysisInputError(operation, { cause: new Error("Enable screenshot or accessibility capture"), }), ); const steps = operation === "capture_native_ui_scenario" ? nativeUiScenarioInputSchema.parse(parameters).steps : []; const signal = options.signal === undefined ? AbortSignal.timeout(180_000) : AbortSignal.any([options.signal, AbortSignal.timeout(180_000)]); const invoke = options.invoke; let launchTime: number | undefined; let outputBytes = 0; const take = async ( action?: unknown, ): Promise, AnalysisError>> => { if (signal.aborted) return err(new AnalysisCancelledError(operation)); try { const response = responseSchema.parse( await invoke( { pid: input.pid, window_id: input.window_id, executable: target.path, sha256: target.sha256, ...(launchTime === undefined ? {} : { launch_time: launchTime }), screenshot: input.screenshot, accessibility: input.accessibility, max_nodes: input.max_nodes, ...(action === undefined ? {} : { action }), }, signal, ), ); if (!response.ok) return err( new AnalysisCapabilityUnavailableError( "native-macos", operation, `${response.code}: ${response.message}`, ), ); if ( response.result.window.pid !== input.pid || response.result.window.window_id !== input.window_id || response.result.window.executable !== target.path || (launchTime !== undefined && response.result.window.launch_time !== launchTime) ) return err( new AnalysisCapabilityUnavailableError( "native-macos", operation, "Native helper returned a different target process or window", ), ); launchTime = response.result.window.launch_time; outputBytes += NATIVE_UI_OUTPUT_WEIGHT * Buffer.byteLength(JSON.stringify(response.result)); if (outputBytes > NATIVE_UI_OUTPUT_BUDGET_BYTES) return err( new AnalysisCapabilityUnavailableError( "native-macos", operation, "Scenario captures exceeded the 64 MiB output budget", ), ); return ok(response.result); } catch (cause) { return err( signal.aborted ? new AnalysisCancelledError(operation) : new ProviderAdapterError("native-macos", operation, { cause, diagnostics: { helper_path: helper, reason: cause instanceof Error ? cause.message : String(cause), remediation: "Native helper failed, timed out, or returned malformed capture data; install compatible Xcode command-line tools and inspect local OS permissions", }, }), ); } }; const initial = await take(); if (!initial.ok) return initial; const results: z.infer["steps"] = []; let before = initial.value; for (const [index, step] of steps.entries()) { if (signal.aborted) { results.push({ index, kind: step.kind, before, after: null, outcome: "cancelled", reason: "Scenario cancelled before action", }); break; } if (step.kind === "wait") { try { await new Promise((resolve, reject) => { const abort = () => { clearTimeout(timer); reject(new Error("cancelled")); }; const timer = setTimeout(() => { signal.removeEventListener("abort", abort); resolve(); }, step.milliseconds); signal.addEventListener("abort", abort, { once: true }); if (signal.aborted) abort(); }); } catch (cause: unknown) { // Cancellation is recorded as a cancelled outcome. void cause; results.push({ index, kind: step.kind, before, after: null, outcome: "cancelled", reason: "Scenario cancelled during wait", }); break; } } const after = await take(step.kind === "wait" ? undefined : step); if (!after.ok) { results.push({ index, kind: step.kind, before, after: null, outcome: after.error._tag === "AnalysisCancelledError" ? "cancelled" : "failed", reason: after.error.message, }); break; } results.push({ index, kind: step.kind, before, after: after.value, outcome: "completed", reason: null, }); before = after.value; } return ok( nativeUiResultSchema.parse({ target_sha256: target.sha256, initial: initial.value, steps: results, restore: "leave-as-is", limitations: [ "Only the explicitly selected already-running process/window is admitted. REA starts no target process and does not change permissions, foreground applications, or restore application data.", "Click uses AXPress; scroll uses AXIncrement/AXDecrement; key-entry sets the selected element's AXValue. Unsupported elements fail without global event fallback.", "Each completed action is followed immediately by capture; delayed UI changes require explicit wait steps. A failed after-capture can follow a completed action, so failure does not prove absence of application effects.", "Scenarios can change app data, cause app network activity and persist changes. The caller explicitly chooses leave-as-is; automatic restoration is unsupported.", "Window matching uses exact PID and window ID for screenshots and unique accessibility geometry. Accessibility paths can change as the UI changes; stale or ambiguous paths fail. Screenshots are scaled to at most 2048 pixels; scenario output is budgeted at 64 MiB and execution is cancelled after 180 seconds.", ], }), ); };