@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/computer/motor/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../../../src/core/computer/motor/bridge.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ChildProcess, spawn } from \"node:child_process\";\nimport { randomUUID } from \"node:crypto\";\nimport { constants as fsConstants } from \"node:fs\";\nimport { access } from \"node:fs/promises\";\nimport net from \"node:net\";\nimport os from \"node:os\";\nimport path from \"node:path\";\nimport type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from \"../../extensions/types.ts\";\nimport {\n\ttype ActionState,\n\tcanRetryInForeground,\n\toutcomeAfterCheck,\n\toutcomeAfterObservedValues,\n\ttype PreparedAction,\n\tprepareAction,\n} from \"./actions.ts\";\nimport {\n\ttype CdpConsoleEntry,\n\ttype CdpPageSnapshot,\n\tcdpClickForContext,\n\tcdpDragForContext,\n\tcdpEvaluateForContext,\n\tcdpKeypressForContext,\n\tcdpMouseForContext,\n\tcdpNavigateContext,\n\tcdpScrollForContext,\n\tcdpSnapshotForContext,\n\tcdpTabForWindow,\n\tcdpTypeFocusedForContext,\n\tcdpTypeForContext,\n\tdisconnectCdp,\n\tlistCdpPageContexts,\n} from \"./cdp.ts\";\nimport { getComputerUseConfig, isBrowserUseEnabled, isHeadlessMode, loadComputerUseConfig } from \"./config.ts\";\nimport {\n\ttype ActParams,\n\tAGENT_TOOL_NAMES,\n\ttype EvaluateBrowserParams,\n\ttype ExpandUiParams,\n\ttype FindParams,\n\ttype ImageMode,\n\ttype InspectUiParams,\n\ttype LaunchBrowserParams,\n\ttype NavigateBrowserParams,\n\ttype ObserveParams,\n\ttype ObserveTargetParams,\n\ttype ReadTextParams,\n\ttype RootSelector,\n\ttype SearchUiParams,\n\ttype UiAction,\n\ttype WaitForParams,\n} from \"./contract.ts\";\nimport { noteAfterAct, noteFromLook, noteRegionKeyForRef, renderNote, type WindowNote } from \"./note.ts\";\nimport {\n\tfoldToBudget,\n\tgraftScopedOutline,\n\ttype LookResponse,\n\tnodeByRef,\n\ttype Outline,\n\ttype OutlineChange,\n\ttype OutlineNode,\n\ttype OutlineSearchMatch,\n\toutlineNodeLabel,\n\toutlineNodePath,\n\trankedTextMatch,\n\trestoreOutline,\n\ttype SerializedOutline,\n\ttype SerializedOutlineNode,\n\ttype SerializedOutlineSearchMatch,\n\tsearchOutline,\n\tsearchOutlineRanked,\n\tserializeOutline,\n\tserializeOutlineNodeShallow,\n\tserializeOutlineSearchMatch,\n} from \"./outline.ts\";\nimport {\n\tapplyOutputEnvelope,\n\tboundToolError,\n\tclearStoredOutputs,\n\treadStoredOutput,\n\tUI_TEXT_PAGE_CHARS,\n} from \"./output.ts\";\nimport type { PermissionStatus } from \"./permissions.ts\";\nimport { toFiniteNumber } from \"./platform/coerce.ts\";\nimport { currentPlatformBackend } from \"./platform/index.ts\";\nimport type {\n\tFramePoints,\n\tPlatformFrontmostResult as FrontmostResult,\n\tHelperActPerformed,\n\tHelperActResult,\n\tPlatformApp as HelperApp,\n\tPlatformRoot as HelperWindow,\n\tNativeInputDelivery,\n\tPlatformActRequest,\n\tPlatformDiagnostics,\n} from \"./platform/types.ts\";\nimport { scoreWindow, shouldPreferForegroundModalWindow } from \"./root-selection.ts\";\nimport { ResourceScheduler } from \"./runtime.ts\";\nimport { type CurrentCapture, type CurrentTarget, type OperationState, SavedStates } from \"./state.ts\";\nimport { changesBetween, renderChanges, stabilizeRefs } from \"./view.ts\";\n\nexport type {\n\tActParams,\n\tEvaluateBrowserParams,\n\tExpandUiParams,\n\tFindParams,\n\tImageMode,\n\tInspectUiParams,\n\tLaunchBrowserParams,\n\tMouseButtonName,\n\tNavigateBrowserParams,\n\tObserveParams,\n\tObserveTargetParams,\n\tReadTextParams,\n\tRootSelector,\n\tSearchUiParams,\n\tStateTargetParams,\n\tUiAction,\n\tWaitForParams,\n} from \"./contract.ts\";\n\ninterface ActivationFlags {\n\tactivated: boolean;\n\tunminimized: boolean;\n\traised: boolean;\n}\n\ntype ExecutionVariant = \"stealth\" | \"default\";\ntype ActionDelivery = \"ax\" | NativeInputDelivery;\ntype DeliveryPolicy = \"ax_only\" | \"background\" | \"default\" | \"foreground\";\ntype ActOutcome = \"worked\" | \"didnt\" | \"unknown\";\n\ninterface ExecutionTrace {\n\tstrategy: \"look\" | \"act\" | \"wait\" | \"browser_open_location\" | \"cdp_navigate\";\n\truntimeMode?: ExecutionVariant;\n\tvariant?: ExecutionVariant;\n\tstealthCompatible?: boolean;\n\tdelivery?: ActionDelivery;\n\tdeliveryPolicy?: DeliveryPolicy;\n\toutcome?: ActOutcome;\n\tperformed?: HelperActPerformed;\n\tevidence?: Record<string, unknown>;\n\terror?: HelperActResult[\"error\"];\n\trootDelta?: HelperActResult[\"rootDelta\"];\n\tsteps?: ExecutionTrace[];\n\tactionCount?: number;\n\tstoppedAt?: number;\n\tbackgroundFirst?: boolean;\n\tescalatedToForeground?: boolean;\n\tescalationReason?: string;\n\tbackgroundAttempt?: { outcome: \"foreground_required\" | \"didnt\"; reason: string };\n\tverification?: {\n\t\tstatus: \"verified\" | \"preexisting\" | \"failed\";\n\t\ttext?: string;\n\t\trole?: string;\n\t\tvalue?: string;\n\t\tgone?: boolean;\n\t\ttimeoutMs: number;\n\t};\n}\n\ninterface ComputerUseDetails {\n\ttool: string;\n\ttarget: {\n\t\tapp: string;\n\t\tbundleId?: string;\n\t\tpid: number;\n\t\twindowTitle: string;\n\t\twindowId: number;\n\t\twindowRef?: string;\n\t\tnativeWindowRef?: string;\n\t};\n\tcapture: {\n\t\tstateId: string;\n\t\twidth: number;\n\t\theight: number;\n\t\tscaleFactor: number;\n\t\ttimestamp: number;\n\t\tcoordinateSpace: \"window-relative-screenshot-pixels\";\n\t};\n\tlookId?: string;\n\tview: \"full\" | \"diff\";\n\tbaseStateId?: string;\n\tchanges?: OutlineChange[];\n\tviewReason?: \"root_replaced\" | \"change_budget_exceeded\" | \"identity_confidence_low\";\n\trenderedOutline?: string;\n\toutline?: SerializedOutline;\n\tnote?: WindowNote;\n\tactivation: ActivationFlags;\n\texecution: ExecutionTrace;\n\tconfig?: {\n\t\tbrowser_use: boolean;\n\t\theadless: boolean;\n\t};\n\thelper?: PlatformDiagnostics;\n\tstatus?: \"ok\";\n\taxDiagnostics?: {\n\t\treason?: string;\n\t\tmessage?: string;\n\t\tdebug?: unknown;\n\t};\n\t/** Recent browser console messages/exceptions; only present when CDP is active. */\n\tconsole?: CdpConsoleEntry[];\n\timageReason?:\n\t\t| \"fallback_recovery\"\n\t\t| \"browser_ax_window_unavailable\"\n\t\t| \"no_ax_targets\"\n\t\t| \"sparse_ax_targets\"\n\t\t| \"weak_ax_targets\"\n\t\t| \"unlabeled_ax_targets\"\n\t\t| \"duplicated_ax_labels\"\n\t\t| \"browser_wait_verification\";\n}\ninterface TerminalDesktopActionDetails {\n\ttool: \"act_ui\";\n\tstatus: \"target_closed\" | \"post_action_observation_failed\";\n\tbaseStateId: string;\n\ttarget: {\n\t\tapp: string;\n\t\tbundleId?: string;\n\t\tpid: number;\n\t\twindowTitle: string;\n\t\twindowId: number;\n\t\twindowRef?: string;\n\t\tnativeWindowRef?: string;\n\t};\n\texecution: ExecutionTrace;\n\terror: { code: string; message: string };\n}\n\ninterface ListWindowsDetails {\n\ttool: \"find_roots\";\n\tquery: FindParams;\n\ttotalMatches?: number;\n\treturned?: number;\n\thasMore?: boolean;\n\twindows: Array<{\n\t\tapp: string;\n\t\tbundleId?: string;\n\t\tpid: number;\n\t\tkind: string;\n\t\twindowTitle: string;\n\t\twindowId?: number;\n\t\twindowRef: string;\n\t\tnativeWindowRef?: string;\n\t\tframePoints: FramePoints;\n\t\tscaleFactor: number;\n\t\tisMinimized: boolean;\n\t\tisOnscreen: boolean;\n\t\tisMain: boolean;\n\t\tisFocused: boolean;\n\t\tisModal: boolean;\n\t\tsheetCount?: number;\n\t\trole?: string;\n\t\tsubrole?: string;\n\t\tpairing?: { confidence: \"exact\" | \"high\" | \"low\"; score: number };\n\t\tzOrder: number;\n\t\tbrowserUseAllowed: boolean;\n\t\tscore: number;\n\t\turl?: string;\n\t}>;\n\tconfig: {\n\t\tbrowser_use: boolean;\n\t\theadless: boolean;\n\t};\n}\n\ninterface BrowserObservationDetails {\n\ttool: string;\n\tkind: \"browser_page\";\n\tstateId: string;\n\tbaseStateId?: string;\n\tview: \"full\" | \"diff\";\n\tchanges?: OutlineChange[];\n\troot: { ref: string; kind: \"browser_page\"; title: string; url: string };\n\toutline: SerializedOutline;\n\trenderedOutline: string;\n}\n\ninterface EvaluateBrowserDetails {\n\ttool: \"evaluate_browser\";\n\tbaseStateId: string;\n\tstateId: string;\n\tview: \"full\" | \"diff\";\n\tchanges?: OutlineChange[];\n\toutline: SerializedOutline;\n\trenderedOutline: string;\n}\n\ninterface ReadTextDetails {\n\ttool: \"read_text\";\n\tref?: string;\n\toffset: number;\n\tlimit: number;\n\ttotalChars?: number;\n\ttotalBytes?: number;\n\thasMore: boolean;\n\tcomplete?: boolean;\n\ttext: string;\n}\n\ninterface WaitForDetails {\n\ttool: \"wait_for\";\n\tstateId: string;\n\tbaseStateId?: string;\n\tview: \"full\" | \"diff\";\n\tchanges?: OutlineChange[];\n\tfound: boolean;\n\tgone?: boolean;\n\ttimedOut?: boolean;\n\ttarget?: SerializedOutlineSearchMatch;\n\tnodeCount?: number;\n\ttext?: string;\n\trole?: string;\n\tvalue?: string;\n\tscopeRef?: string;\n\toutline: SerializedOutline;\n\trenderedOutline: string;\n}\n\ninterface OutlineToolDetails {\n\ttool: \"search_ui\" | \"expand_ui\" | \"inspect_ui\";\n\tstateId?: string;\n\tlookId?: string;\n\toutline?: SerializedOutline;\n\trenderedOutline?: string;\n\ttotalMatches?: number;\n\treturned?: number;\n\thasMore?: boolean;\n\tmatches?: SerializedOutlineSearchMatch[];\n\ttarget?: SerializedOutlineNode;\n\tnote?: WindowNote;\n}\n\ninterface ResolvedTarget extends CurrentTarget {\n\tframePoints: FramePoints;\n\tscaleFactor: number;\n\tisMinimized: boolean;\n\tisOnscreen: boolean;\n\tisMain: boolean;\n\tisFocused: boolean;\n}\n\ninterface WindowRefRecord {\n\tref: string;\n\tappName: string;\n\tbundleId?: string;\n\tpid: number;\n\twindowTitle: string;\n\twindowId?: number;\n\tnativeWindowRef?: string;\n\tframePoints: FramePoints;\n\tscaleFactor: number;\n\tisMinimized: boolean;\n\tisOnscreen: boolean;\n\tisMain: boolean;\n\tisFocused: boolean;\n}\n\ninterface RuntimeState {\n\twindowRefs: Map<string, WindowRefRecord>;\n\twindowRefByIdentity: Map<string, string>;\n\tbrowserRootByContext: Map<string, string>;\n\tbrowserContextByRoot: Map<string, string>;\n\tnextRootRefIndex: number;\n\tmanagedBrowser?: ChildProcess;\n\tmanagedBrowserCdpPort?: string;\n\tpreviousCdpPort?: string;\n\tpermissionStatus?: PermissionStatus;\n\thelperDiagnostics?: PlatformDiagnostics;\n\tlastPermissionCheckAt: number;\n}\n\nconst MISSING_TARGET_ERROR = \"No current controlled window. Call observe_ui first to choose a target window.\";\nconst CURRENT_TARGET_GONE_ERROR =\n\t\"The current controlled window is no longer available. Call observe_ui to choose a new target window.\";\n\nconst COMMAND_TIMEOUT_MS = 15_000;\nconst LOOK_TIMEOUT_MS = 33_000;\n\nconst ACTION_SETTLE_MS = 280;\n\nconst BROWSER_CONTEXT_PREFIX = \"browser:\";\nconst MANAGED_BROWSER_READY_TIMEOUT_MS = 15_000;\nconst AUTO_IMAGE_MAX_DIMENSION = 900;\nconst EXPLICIT_IMAGE_MAX_DIMENSION = 1_600;\nconst BROWSER_TRANSACTION_ACTIONS = new Set<UiAction[\"action\"]>([\n\t\"press\",\n\t\"click\",\n\t\"setText\",\n\t\"typeText\",\n\t\"keypress\",\n\t\"scroll\",\n\t\"drag\",\n\t\"moveMouse\",\n]);\n\nconst runtimeState: RuntimeState = {\n\tlastPermissionCheckAt: 0,\n\twindowRefs: new Map(),\n\twindowRefByIdentity: new Map(),\n\tbrowserRootByContext: new Map(),\n\tbrowserContextByRoot: new Map(),\n\tnextRootRefIndex: 1,\n};\n\nconst savedStates = new SavedStates();\nlet resourceScheduler = new ResourceScheduler();\n\nfunction operationState(): OperationState {\n\treturn savedStates.current();\n}\n\nfunction desktopResourceKey(target: Pick<CurrentTarget, \"pid\">): string {\n\treturn `desktop-pid:${target.pid}`;\n}\n\nfunction persistOperation(state: OperationState): void {\n\tif (!state.currentTarget || !state.currentCapture || !state.currentLook || !state.currentOutline) return;\n\tconst resourceKey = state.resourceKey ?? desktopResourceKey(state.currentTarget);\n\tconst epoch = state.epoch ?? resourceScheduler.epoch(resourceKey);\n\tsavedStates.saveDesktop(state, resourceKey, epoch);\n}\n\n/** Release handles and state owned by the current Pi session. */\nexport async function shutdownComputerUseSession(): Promise<void> {\n\tawait resourceScheduler.close();\n\tresourceScheduler = new ResourceScheduler();\n\tdisconnectCdp();\n\n\tconst managedBrowser = runtimeState.managedBrowser;\n\truntimeState.managedBrowser = undefined;\n\tif (managedBrowser) {\n\t\tmanagedBrowser.kill(\"SIGTERM\");\n\t\tmanagedBrowser.unref();\n\t}\n\tif (\n\t\truntimeState.managedBrowserCdpPort &&\n\t\tprocess.env.ADA_COMPUTER_USE_CDP_PORT === runtimeState.managedBrowserCdpPort\n\t) {\n\t\tif (runtimeState.previousCdpPort === undefined) delete process.env.ADA_COMPUTER_USE_CDP_PORT;\n\t\telse process.env.ADA_COMPUTER_USE_CDP_PORT = runtimeState.previousCdpPort;\n\t}\n\truntimeState.managedBrowserCdpPort = undefined;\n\truntimeState.previousCdpPort = undefined;\n\n\tsavedStates.clear();\n\tclearStoredOutputs();\n\truntimeState.windowRefs.clear();\n\truntimeState.windowRefByIdentity.clear();\n\truntimeState.browserRootByContext.clear();\n\truntimeState.browserContextByRoot.clear();\n\truntimeState.nextRootRefIndex = 1;\n\truntimeState.permissionStatus = undefined;\n\truntimeState.helperDiagnostics = undefined;\n\truntimeState.lastPermissionCheckAt = 0;\n\tawait currentPlatformBackend.shutdown?.();\n}\n\nfunction currentRuntimeMode(): ExecutionVariant {\n\treturn isHeadlessMode() ? \"stealth\" : \"default\";\n}\n\nfunction currentDeliveryPolicy(): DeliveryPolicy {\n\tif (isHeadlessMode()) return \"background\";\n\tconst value = (\n\t\tprocess.env.ADA_COMPUTER_USE_DELIVERY_POLICY ??\n\t\tprocess.env.ADA_COMPUTER_USE_EVENT_DELIVERY ??\n\t\t\"default\"\n\t).toLowerCase();\n\treturn value === \"background\" || value === \"pid\"\n\t\t? \"background\"\n\t\t: value === \"foreground\" || value === \"hid\"\n\t\t\t? \"foreground\"\n\t\t\t: value === \"ax_only\" || value === \"ax-only\"\n\t\t\t\t? \"ax_only\"\n\t\t\t\t: \"default\";\n}\n\nfunction nativeInputDelivery(policy = currentDeliveryPolicy()): NativeInputDelivery {\n\treturn policy === \"foreground\" ? \"hid\" : \"pid\";\n}\n\nfunction executionTrace(\n\tstrategy: ExecutionTrace[\"strategy\"],\n\tvariant: ExecutionVariant,\n\tmetadata: Omit<ExecutionTrace, \"strategy\" | \"runtimeMode\" | \"variant\" | \"stealthCompatible\"> = {},\n): ExecutionTrace {\n\treturn {\n\t\tstrategy,\n\t\truntimeMode: currentRuntimeMode(),\n\t\tvariant,\n\t\tstealthCompatible: variant === \"stealth\",\n\t\t...metadata,\n\t};\n}\n\nfunction settleMsForExecution(execution: ExecutionTrace): number {\n\t// Any deltaSource means the helper already awaited UI quiescence; the\n\t// bridge must not double-pay with its own settle sleep.\n\tif (execution.performed?.deltaSource) return 0;\n\tif (execution.variant === \"stealth\") {\n\t\tswitch (execution.strategy) {\n\t\t\tcase \"browser_open_location\":\n\t\t\t\treturn 120;\n\t\t\tdefault:\n\t\t\t\treturn 120;\n\t\t}\n\t}\n\treturn ACTION_SETTLE_MS;\n}\n\nfunction throwIfAborted(signal?: AbortSignal): void {\n\tif (signal?.aborted) {\n\t\tthrow new Error(\"Operation aborted.\");\n\t}\n}\n\nasync function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\tif (ms <= 0) return;\n\tthrowIfAborted(signal);\n\n\tawait new Promise<void>((resolve, reject) => {\n\t\tconst timer = setTimeout(() => {\n\t\t\tcleanup();\n\t\t\tresolve();\n\t\t}, ms);\n\n\t\tconst onAbort = () => {\n\t\t\tcleanup();\n\t\t\treject(new Error(\"Operation aborted.\"));\n\t\t};\n\n\t\tconst cleanup = () => {\n\t\t\tclearTimeout(timer);\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t};\n\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t});\n}\n\nasync function withWindowWriteLock<T>(target: ResolvedTarget | CurrentTarget, work: () => Promise<T>): Promise<T> {\n\tconst state = operationState();\n\tconst key = desktopResourceKey(target);\n\tconst baseEpoch = state.epoch ?? resourceScheduler.epoch(key);\n\tconst result = await resourceScheduler.write(key, baseEpoch, async (nextEpoch) => {\n\t\tstate.resourceKey = key;\n\t\tstate.epoch = nextEpoch;\n\t\treturn await work();\n\t});\n\treturn result.value;\n}\n\nfunction trimOrUndefined(value: string | undefined): string | undefined {\n\tif (typeof value !== \"string\") return undefined;\n\tconst trimmed = value.trim();\n\treturn trimmed.length > 0 ? trimmed : undefined;\n}\n\nfunction normalizeText(value: string | undefined): string {\n\treturn (value ?? \"\").trim().toLowerCase();\n}\n\nfunction toBoolean(value: unknown): boolean {\n\treturn value === true;\n}\n\nfunction outlineNodeCenter(node: OutlineNode): { x: number; y: number } {\n\tif (!node.rect) {\n\t\tthrow new Error(\n\t\t\t`Outline ref '${node.ref}' has no full-look coordinates after scoped expansion. Re-observe for coordinates.`,\n\t\t);\n\t}\n\treturn { x: node.rect.x + node.rect.w / 2, y: node.rect.y + node.rect.h / 2 };\n}\n\nfunction validateStateId(stateId?: string): CurrentCapture {\n\tconst state = operationState();\n\tif (!state.currentCapture) {\n\t\tthrow new Error(\"No observation state is available. Call observe_ui first.\");\n\t}\n\tconst supplied = stateId;\n\tif (supplied && state.currentCapture.stateId !== supplied) {\n\t\tthrow new Error(\n\t\t\t`Stale state '${supplied}'. The active operation state is '${state.currentCapture.stateId}'. Observe the root again and retry.`,\n\t\t);\n\t}\n\tconst stateTarget = state.currentStateTarget;\n\tif (\n\t\tstateTarget &&\n\t\tstate.currentTarget &&\n\t\t(stateTarget.pid !== state.currentTarget.pid || stateTarget.windowId !== state.currentTarget.windowId)\n\t) {\n\t\tthrow new Error(\n\t\t\t\"The latest state belongs to a different window. Call observe_ui for the target window and retry.\",\n\t\t);\n\t}\n\treturn state.currentCapture;\n}\n\nfunction formatOutlineNodeLabel(node: OutlineNode): string {\n\tconst label = outlineNodeLabel(node) || \"(unlabeled)\";\n\tconst identifier = node.identifier ? ` id=${JSON.stringify(node.identifier)}` : \"\";\n\tconst capabilities = [\n\t\tnode.canSetValue ? \"setValue\" : undefined,\n\t\tnode.canPress ? \"press\" : undefined,\n\t\tnode.canFocus ? \"focus\" : undefined,\n\t\tnode.canScroll ? \"scroll\" : undefined,\n\t\tnode.canIncrement || node.canDecrement ? \"adjust\" : undefined,\n\t\tnode.pictureOnly ? \"pictureOnly\" : undefined,\n\t].filter((item): item is string => Boolean(item));\n\treturn `${node.ref} ${node.role}${node.subrole ? `/${node.subrole}` : \"\"}${identifier} ${JSON.stringify(label)}${capabilities.length ? ` [${capabilities.join(\",\")}]` : \"\"}`;\n}\n\nfunction outlineNodeByRef(ref: string): OutlineNode {\n\tconst state = operationState();\n\tconst outline = state.currentOutline;\n\tconst node = outline ? nodeByRef(outline, ref) : undefined;\n\tif (!node) {\n\t\tconst windowHint = state.currentTarget?.windowRef ? `({ root: \"${state.currentTarget.windowRef}\" })` : \"\";\n\t\tthrow new Error(\n\t\t\t`Outline ref '${ref}' is stale or not available for the latest state. Call observe_ui${windowHint} again and choose a current @e ref.`,\n\t\t);\n\t}\n\treturn node;\n}\n\nfunction wireRefForNode(node: OutlineNode): string {\n\tif (node.pictureOnly || !node.wireRef) {\n\t\tthrow new Error(\n\t\t\t`Outline ref '${node.ref}' is pictureOnly and has no semantic element. It can be clicked by coordinates, but semantic-only actions are not available.`,\n\t\t);\n\t}\n\treturn node.wireRef;\n}\n\nfunction imageFallbackReason(\n\ttool: string,\n\tresult: CaptureResult,\n\timageMode: ImageMode = \"auto\",\n): { reason: NonNullable<ComputerUseDetails[\"imageReason\"]>; message: string } | undefined {\n\tif (imageMode === \"never\") return undefined;\n\tif (imageMode === \"always\")\n\t\treturn { reason: \"fallback_recovery\", message: \"An image was requested explicitly for visual verification.\" };\n\tconst outline = result.outline;\n\tconst labeled = outline.nodes.filter((node) => outlineNodeLabel(node)).length;\n\tif (outline.nodes.length < 3) {\n\t\treturn {\n\t\t\treason: \"sparse_ax_targets\",\n\t\t\tmessage: \"Only a few outline nodes were found, so the look image is attached for context.\",\n\t\t};\n\t}\n\tif (labeled * 3 < outline.nodes.length) {\n\t\treturn {\n\t\t\treason: \"unlabeled_ax_targets\",\n\t\t\tmessage: \"Most outline nodes are unlabeled, so the look image is attached for context.\",\n\t\t};\n\t}\n\tif (tool === \"wait\" && currentPlatformBackend.isBrowserApp(result.target.appName, result.target.bundleId)) {\n\t\treturn {\n\t\t\treason: \"browser_wait_verification\",\n\t\t\tmessage: \"Browser content may have changed visually during wait, so an image is attached for fallback.\",\n\t\t};\n\t}\n\treturn undefined;\n}\n\nfunction currentTargetOrThrow(): CurrentTarget {\n\tconst target = operationState().currentTarget;\n\tif (!target) {\n\t\tthrow new Error(MISSING_TARGET_ERROR);\n\t}\n\treturn target;\n}\n\nfunction emptyActivation(): ActivationFlags {\n\treturn { activated: false, unminimized: false, raised: false };\n}\n\nasync function ensureReady(ctx: ExtensionContext, signal?: AbortSignal): Promise<void> {\n\tloadComputerUseConfig(ctx.cwd);\n\n\tthrowIfAborted(signal);\n\tconst ready = await currentPlatformBackend.ensureReady(\n\t\tctx,\n\t\t{\n\t\t\tpermissionStatus: runtimeState.permissionStatus,\n\t\t\tlastPermissionCheckAt: runtimeState.lastPermissionCheckAt,\n\t\t\thelperDiagnostics: runtimeState.helperDiagnostics,\n\t\t},\n\t\tsignal,\n\t);\n\truntimeState.permissionStatus = ready.permissionStatus;\n\truntimeState.lastPermissionCheckAt = ready.lastPermissionCheckAt;\n\truntimeState.helperDiagnostics = ready.helperDiagnostics;\n}\n\nexport async function ensureComputerUseSetup(ctx: ExtensionContext, signal?: AbortSignal): Promise<void> {\n\tawait ensureReady(ctx, signal);\n}\n\nasync function listApps(signal?: AbortSignal): Promise<HelperApp[]> {\n\treturn await currentPlatformBackend.listApps(signal);\n}\n\nasync function listWindows(pid: number, signal?: AbortSignal): Promise<HelperWindow[]> {\n\treturn await currentPlatformBackend.listRoots({ pid }, signal);\n}\n\nfunction appMatchesWindowQuery(app: HelperApp, query: FindParams): boolean {\n\tconst appQuery = trimOrUndefined(query.app);\n\tconst bundleQuery = trimOrUndefined(query.bundleId);\n\tconst pidQuery = Number.isFinite(query.pid) ? Math.trunc(query.pid!) : undefined;\n\n\tif (pidQuery !== undefined && app.pid !== pidQuery) return false;\n\tif (bundleQuery && normalizeText(app.bundleId ?? \"\") !== normalizeText(bundleQuery)) return false;\n\tif (appQuery && normalizeText(app.appName) !== normalizeText(appQuery)) return false;\n\treturn true;\n}\n\nfunction platformRootSheetCount(window: Pick<HelperWindow, \"metadata\">): number | undefined {\n\tconst value = window.metadata?.sheetCount;\n\treturn typeof value === \"number\" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : undefined;\n}\n\nfunction platformRootPairing(\n\twindow: Pick<HelperWindow, \"metadata\">,\n): { confidence: \"exact\" | \"high\" | \"low\"; score: number } | undefined {\n\tconst value = window.metadata?.pairing;\n\tif (!value || typeof value !== \"object\") return undefined;\n\tconst pairing = value as { confidence?: unknown; score?: unknown };\n\tif (pairing.confidence !== \"exact\" && pairing.confidence !== \"high\" && pairing.confidence !== \"low\")\n\t\treturn undefined;\n\treturn {\n\t\tconfidence: pairing.confidence,\n\t\tscore:\n\t\t\ttypeof pairing.score === \"number\" && Number.isFinite(pairing.score) ? pairing.score : Number.NEGATIVE_INFINITY,\n\t};\n}\n\nfunction formatWindowLine(window: ListWindowsDetails[\"windows\"][number]): string {\n\tif (window.kind === \"browser_page\")\n\t\treturn `- ${window.windowRef} browser_page ${JSON.stringify(window.windowTitle)}${window.url ? ` — ${window.url}` : \"\"}`;\n\tconst flags = [\n\t\twindow.isFocused ? \"focused\" : undefined,\n\t\twindow.isMain ? \"main\" : undefined,\n\t\twindow.isModal ? \"modal\" : undefined,\n\t\twindow.sheetCount ? `sheets=${window.sheetCount}` : undefined,\n\t\twindow.isOnscreen ? \"onscreen\" : undefined,\n\t\twindow.isMinimized ? \"minimized\" : undefined,\n\t\twindow.browserUseAllowed ? undefined : \"browser_use_disabled\",\n\t]\n\t\t.filter(Boolean)\n\t\t.join(\", \");\n\tconst frame = `${Math.round(window.framePoints.x)},${Math.round(window.framePoints.y)} ${Math.round(window.framePoints.w)}x${Math.round(window.framePoints.h)}`;\n\tconst id = window.windowId\n\t\t? `windowId ${window.windowId}`\n\t\t: window.nativeWindowRef\n\t\t\t? `nativeRootRef ${window.nativeWindowRef}`\n\t\t\t: \"unstable root id\";\n\tconst pairing = window.pairing ? `, pairing ${window.pairing.confidence}/${Math.round(window.pairing.score)}` : \"\";\n\treturn `- ${window.windowRef} ${window.kind} ${window.app} pid ${window.pid} — ${window.windowTitle || \"(untitled)\"} (z ${window.zOrder}, ${id}, frame ${frame}${pairing}${flags ? `, ${flags}` : \"\"})`;\n}\n\nasync function getFrontmost(signal?: AbortSignal): Promise<FrontmostResult> {\n\treturn await currentPlatformBackend.getFrontmost(signal);\n}\n\nfunction assertBrowserUseAllowed(target: { appName: string; bundleId?: string }): void {\n\tif (!isBrowserUseEnabled() && currentPlatformBackend.isBrowserApp(target.appName, target.bundleId)) {\n\t\tthrow new Error(\n\t\t\t`Browser use is disabled by ada-computer-use config, so '${target.appName}' cannot be controlled. Enable browser_use in ~/.pi/agent/extensions/ada-computer-use.json or .pi/computer-use.json to allow browser windows.`,\n\t\t);\n\t}\n}\n\nfunction windowRecordIdentity(\n\trecord: Pick<WindowRefRecord, \"pid\" | \"windowId\" | \"nativeWindowRef\" | \"windowTitle\" | \"framePoints\">,\n): string {\n\tif (record.windowId && record.windowId > 0) {\n\t\treturn `pid:${record.pid}|id:${record.windowId}`;\n\t}\n\tif (record.nativeWindowRef) {\n\t\treturn `pid:${record.pid}|ref:${record.nativeWindowRef}`;\n\t}\n\tconst { x, y, w, h } = record.framePoints;\n\treturn `pid:${record.pid}|title:${normalizeText(record.windowTitle)}|frame:${Math.round(x)},${Math.round(y)},${Math.round(w)},${Math.round(h)}`;\n}\n\nfunction storeWindowRef(record: Omit<WindowRefRecord, \"ref\">): WindowRefRecord {\n\tconst identity = windowRecordIdentity(record);\n\tconst existingRef = runtimeState.windowRefByIdentity.get(identity);\n\tif (existingRef) {\n\t\tconst existing = runtimeState.windowRefs.get(existingRef);\n\t\tif (existing) {\n\t\t\tconst updated = { ...record, ref: existingRef };\n\t\t\truntimeState.windowRefs.set(existingRef, updated);\n\t\t\treturn updated;\n\t\t}\n\t}\n\n\tconst ref = `@r${runtimeState.nextRootRefIndex++}`;\n\tconst stored = { ...record, ref };\n\truntimeState.windowRefByIdentity.set(identity, ref);\n\truntimeState.windowRefs.set(ref, stored);\n\treturn stored;\n}\n\nfunction storeBrowserRootRef(contextId: string): string {\n\tconst existing = runtimeState.browserRootByContext.get(contextId);\n\tif (existing) return existing;\n\tconst ref = `@r${runtimeState.nextRootRefIndex++}`;\n\truntimeState.browserRootByContext.set(contextId, ref);\n\truntimeState.browserContextByRoot.set(ref, contextId);\n\treturn ref;\n}\n\nfunction storeWindowRefForTarget(target: ResolvedTarget): string {\n\treturn storeWindowRef({\n\t\tappName: target.appName,\n\t\tbundleId: target.bundleId,\n\t\tpid: target.pid,\n\t\twindowTitle: target.windowTitle,\n\t\twindowId: target.windowId > 0 ? target.windowId : undefined,\n\t\tframePoints: target.framePoints,\n\t\tscaleFactor: target.scaleFactor,\n\t\tisMinimized: target.isMinimized,\n\t\tisOnscreen: target.isOnscreen,\n\t\tisMain: target.isMain,\n\t\tisFocused: target.isFocused,\n\t}).ref;\n}\n\nfunction storeWindowRefForAppWindow(app: HelperApp, window: HelperWindow): WindowRefRecord {\n\treturn storeWindowRef({\n\t\tappName: app.appName,\n\t\tbundleId: app.bundleId,\n\t\tpid: app.pid,\n\t\twindowTitle: window.title || \"(untitled)\",\n\t\twindowId: window.windowId,\n\t\tnativeWindowRef: window.windowRef,\n\t\tframePoints: window.framePoints,\n\t\tscaleFactor: window.scaleFactor,\n\t\tisMinimized: window.isMinimized,\n\t\tisOnscreen: window.isOnscreen,\n\t\tisMain: window.isMain,\n\t\tisFocused: window.isFocused,\n\t});\n}\n\nfunction choosePreferredWindow(windows: HelperWindow[], appName: string): HelperWindow {\n\tif (!windows.length) {\n\t\tthrow new Error(`No controllable root was found in app '${appName}'.`);\n\t}\n\n\tconst scored = [...windows].sort((a, b) => scoreWindow(b) - scoreWindow(a));\n\treturn scored[0];\n}\n\nfunction summarizeWindowCandidate(window: HelperWindow): string {\n\tconst flags = [\n\t\twindow.isFocused ? \"focused\" : undefined,\n\t\twindow.isMain ? \"main\" : undefined,\n\t\twindow.isOnscreen ? \"onscreen\" : undefined,\n\t\twindow.isMinimized ? \"minimized\" : undefined,\n\t]\n\t\t.filter(Boolean)\n\t\t.join(\",\");\n\treturn `${window.title || \"(untitled)\"} [score=${scoreWindow(window)}${flags ? `, ${flags}` : \"\"}]`;\n}\n\nfunction summarizeWindowCandidates(windows: HelperWindow[], limit = 6): string {\n\treturn [...windows]\n\t\t.sort((a, b) => scoreWindow(b) - scoreWindow(a))\n\t\t.slice(0, limit)\n\t\t.map(summarizeWindowCandidate)\n\t\t.join(\"; \");\n}\n\nfunction chooseRankedWindowOrUndefined(windows: HelperWindow[]): HelperWindow | undefined {\n\tif (windows.length === 0) return undefined;\n\tconst ranked = [...windows].sort((a, b) => scoreWindow(b) - scoreWindow(a));\n\tif (ranked.length === 1) return ranked[0];\n\tconst topScore = scoreWindow(ranked[0]);\n\tconst nextScore = scoreWindow(ranked[1]);\n\treturn topScore >= nextScore + 25 ? ranked[0] : undefined;\n}\n\nfunction toResolvedTarget(app: HelperApp, window: HelperWindow): ResolvedTarget {\n\tconst baseTarget = {\n\t\tappName: app.appName,\n\t\tbundleId: app.bundleId,\n\t\tpid: app.pid,\n\t\twindowTitle: window.title || \"(untitled)\",\n\t\twindowId: typeof window.windowId === \"number\" ? window.windowId : 0,\n\t\tnativeWindowRef: window.windowRef,\n\t\tframePoints: window.framePoints,\n\t\tscaleFactor: window.scaleFactor,\n\t\tisMinimized: window.isMinimized,\n\t\tisOnscreen: window.isOnscreen,\n\t\tisMain: window.isMain,\n\t\tisFocused: window.isFocused,\n\t};\n\treturn { ...baseTarget, windowRef: storeWindowRefForAppWindow(app, window).ref };\n}\n\nfunction nativeWindowRequest(target: Pick<CurrentTarget, \"pid\" | \"windowId\" | \"nativeWindowRef\">): {\n\tpid: number;\n\twindowId: number;\n\twindowRef?: string;\n} {\n\treturn { pid: target.pid, windowId: target.windowId, windowRef: target.nativeWindowRef };\n}\n\nfunction setCurrentTarget(target: ResolvedTarget): void {\n\tassertBrowserUseAllowed(target);\n\tconst windowRef = target.windowRef ?? storeWindowRefForTarget(target);\n\toperationState().currentTarget = {\n\t\tappName: target.appName,\n\t\tbundleId: target.bundleId,\n\t\tpid: target.pid,\n\t\twindowTitle: target.windowTitle,\n\t\twindowId: target.windowId,\n\t\twindowRef,\n\t\tnativeWindowRef: target.nativeWindowRef,\n\t};\n}\n\nfunction normalizeWindowSelector(selector: RootSelector | undefined): string | undefined {\n\tif (typeof selector === \"number\" && Number.isFinite(selector)) return String(Math.trunc(selector));\n\tif (typeof selector === \"string\") return trimOrUndefined(selector);\n\treturn undefined;\n}\n\nasync function resolveTargetByWindowSelector(selector: RootSelector, signal?: AbortSignal): Promise<ResolvedTarget> {\n\tconst normalized = normalizeWindowSelector(selector);\n\tif (!normalized) {\n\t\tthrow new Error(\"root target must be a non-empty @r ref or numeric windowId.\");\n\t}\n\n\tconst current = operationState().currentTarget;\n\tif (current?.windowRef === normalized) {\n\t\treturn await resolveCurrentTarget(signal);\n\t}\n\n\tconst fromRef = runtimeState.windowRefs.get(normalized);\n\tif (fromRef) {\n\t\tconst app: HelperApp = { appName: fromRef.appName, bundleId: fromRef.bundleId, pid: fromRef.pid };\n\t\tconst windows = await listWindows(fromRef.pid, signal);\n\t\tconst match =\n\t\t\t(fromRef.windowId ? windows.find((window) => window.windowId === fromRef.windowId) : undefined) ??\n\t\t\t(fromRef.nativeWindowRef\n\t\t\t\t? windows.find((window) => window.windowRef === fromRef.nativeWindowRef)\n\t\t\t\t: undefined) ??\n\t\t\twindows.find((window) => normalizeText(window.title || \"(untitled)\") === normalizeText(fromRef.windowTitle));\n\t\tif (!match) {\n\t\t\tthrow new Error(`Root ref '${normalized}' is stale. Call find_roots again and choose a current window.`);\n\t\t}\n\t\tconst resolved = toResolvedTarget(app, match);\n\t\tsetCurrentTarget(resolved);\n\t\treturn resolved;\n\t}\n\n\tconst numericWindowId = Number(normalized);\n\tif (Number.isInteger(numericWindowId) && numericWindowId > 0) {\n\t\tconst apps = await listApps(signal);\n\t\tfor (const app of apps) {\n\t\t\tconst windows = await listWindows(app.pid, signal);\n\t\t\tconst match = windows.find((window) => window.windowId === numericWindowId);\n\t\t\tif (match) {\n\t\t\t\tassertBrowserUseAllowed(app);\n\t\t\t\tconst resolved = toResolvedTarget(app, match);\n\t\t\t\tsetCurrentTarget(resolved);\n\t\t\t\treturn resolved;\n\t\t\t}\n\t\t}\n\t\tthrow new Error(\n\t\t\t`Window id '${numericWindowId}' was not found. Call find_roots again and choose a current window.`,\n\t\t);\n\t}\n\n\tif (normalized.startsWith(\"@r\")) {\n\t\tthrow new Error(`Root ref '${normalized}' is not available in this session. Call find_roots first.`);\n\t}\n\n\tconst config = getComputerUseConfig();\n\tconst candidates = await collectWindowDetails(await listApps(signal), config, signal);\n\tconst query = normalizeText(normalized);\n\tconst exact = candidates.filter(\n\t\t(candidate) => normalizeText(candidate.app) === query || normalizeText(candidate.windowTitle) === query,\n\t);\n\tconst fuzzy =\n\t\texact.length > 0\n\t\t\t? exact\n\t\t\t: candidates.filter((candidate) =>\n\t\t\t\t\t`${normalizeText(candidate.app)} ${normalizeText(candidate.windowTitle)}`.includes(query),\n\t\t\t\t);\n\tconst match = fuzzy.sort((a, b) => Number(b.isFocused) - Number(a.isFocused) || a.zOrder - b.zOrder)[0];\n\tif (!match)\n\t\tthrow new Error(`Root query '${normalized}' did not match any current root. Call find_roots to inspect roots.`);\n\tconst app: HelperApp = { appName: match.app, bundleId: match.bundleId, pid: match.pid };\n\tconst roots = await listWindows(match.pid, signal);\n\tconst helperRoot =\n\t\troots.find(\n\t\t\t(root) =>\n\t\t\t\troot.rootRef === match.nativeWindowRef ||\n\t\t\t\troot.windowRef === match.nativeWindowRef ||\n\t\t\t\troot.windowId === match.windowId,\n\t\t) ?? roots[0];\n\tconst resolved = toResolvedTarget(app, helperRoot);\n\tsetCurrentTarget(resolved);\n\treturn resolved;\n}\n\nasync function resolveCurrentTarget(signal?: AbortSignal): Promise<ResolvedTarget> {\n\tconst current = currentTargetOrThrow();\n\tconst windows = await listWindows(current.pid, signal);\n\tif (!windows.length) {\n\t\tthrow new Error(CURRENT_TARGET_GONE_ERROR);\n\t}\n\n\tconst hadStableWindowId = current.windowId > 0;\n\tconst titleQuery = normalizeText(current.windowTitle);\n\tlet match = current.nativeWindowRef\n\t\t? windows.find(\n\t\t\t\t(window) => window.windowRef === current.nativeWindowRef || window.rootRef === current.nativeWindowRef,\n\t\t\t)\n\t\t: undefined;\n\tmatch ??= hadStableWindowId\n\t\t? windows.find((window) => window.windowId !== undefined && window.windowId === current.windowId)\n\t\t: undefined;\n\tif (!match) {\n\t\tconst exactTitleMatches =\n\t\t\ttitleQuery && titleQuery !== \"(untitled)\"\n\t\t\t\t? windows.filter((window) => normalizeText(window.title) === titleQuery)\n\t\t\t\t: [];\n\t\tif (exactTitleMatches.length === 1) {\n\t\t\tmatch = exactTitleMatches[0];\n\t\t} else if (exactTitleMatches.length > 1) {\n\t\t\tmatch = chooseRankedWindowOrUndefined(exactTitleMatches);\n\t\t\tif (!match) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`${CURRENT_TARGET_GONE_ERROR} Multiple windows now match '${current.windowTitle}': ${summarizeWindowCandidates(exactTitleMatches)}.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tif (!match && !hadStableWindowId) {\n\t\tmatch = chooseRankedWindowOrUndefined(windows);\n\t}\n\n\tif (!match) {\n\t\tthrow new Error(CURRENT_TARGET_GONE_ERROR);\n\t}\n\n\tconst modal = windows\n\t\t.filter((window) => shouldPreferForegroundModalWindow(match!, window))\n\t\t.sort((a, b) => scoreWindow(b) - scoreWindow(a))[0];\n\tif (modal) match = modal;\n\n\tconst app: HelperApp = {\n\t\tappName: current.appName,\n\t\tbundleId: current.bundleId,\n\t\tpid: current.pid,\n\t};\n\n\tconst resolved = toResolvedTarget(app, match);\n\tsetCurrentTarget(resolved);\n\treturn resolved;\n}\n\nasync function resolveFrontmostTarget(signal?: AbortSignal): Promise<ResolvedTarget> {\n\tconst frontmost = await getFrontmost(signal);\n\tconst apps = await listApps(signal);\n\tconst app = apps.find((candidate) => candidate.pid === frontmost.pid) ?? {\n\t\tappName: frontmost.appName,\n\t\tbundleId: frontmost.bundleId,\n\t\tpid: frontmost.pid,\n\t};\n\n\tconst windows = await listWindows(frontmost.pid, signal);\n\tif (!windows.length) {\n\t\tthrow new Error(\"No frontmost controllable root was found. Open an app window and call observe_ui again.\");\n\t}\n\n\tif (currentPlatformBackend.isBrowserApp(app.appName, app.bundleId)) {\n\t\tassertBrowserUseAllowed(app);\n\t}\n\n\tlet selected = windows.find((window) => window.windowId !== undefined && window.windowId === frontmost.windowId);\n\tif (!selected && frontmost.windowTitle) {\n\t\tselected = windows.find((window) => normalizeText(window.title) === normalizeText(frontmost.windowTitle));\n\t}\n\tselected ??= choosePreferredWindow(windows, app.appName);\n\n\tconst resolved = toResolvedTarget(app, selected);\n\tsetCurrentTarget(resolved);\n\treturn resolved;\n}\n\nfunction matchesObserveSelection(target: ResolvedTarget, selection: ObserveTargetParams): boolean {\n\tconst root = normalizeWindowSelector(selection.root);\n\treturn !root || target.windowRef === root;\n}\n\nasync function resolveTargetForObserve(signal?: AbortSignal): Promise<ResolvedTarget> {\n\treturn operationState().currentTarget ? await resolveCurrentTarget(signal) : await resolveFrontmostTarget(signal);\n}\n\nasync function ensureTargetWindowId(target: ResolvedTarget, signal?: AbortSignal): Promise<ResolvedTarget> {\n\tif (target.windowId > 0 || target.nativeWindowRef) {\n\t\treturn target;\n\t}\n\n\tconst refreshed = await resolveCurrentTarget(signal);\n\tif (refreshed.windowId <= 0 && !refreshed.nativeWindowRef) {\n\t\tthrow new Error(CURRENT_TARGET_GONE_ERROR);\n\t}\n\treturn refreshed;\n}\n\ninterface CaptureResult {\n\ttarget: ResolvedTarget;\n\tcapture: CurrentCapture;\n\tlook: LookResponse;\n\toutline: Outline;\n\tactivation: ActivationFlags;\n}\n\nfunction captureForLook(look: LookResponse): CurrentCapture {\n\treturn {\n\t\tstateId: randomUUID(),\n\t\twidth: look.image?.width ?? 0,\n\t\theight: look.image?.height ?? 0,\n\t\tscaleFactor: look.window.scaleFactor,\n\t\ttimestamp: Date.now(),\n\t};\n}\n\nasync function performLook(\n\ttarget: ResolvedTarget,\n\toptions: {\n\t\treadText: \"auto\" | \"always\" | \"never\";\n\t\tbaseLookId?: string;\n\t\tscopeRef?: string;\n\t\tmaxDimension?: number;\n\t\tincludeImage?: boolean;\n\t},\n\tsignal?: AbortSignal,\n): Promise<LookResponse> {\n\tif ((!Number.isFinite(target.windowId) || target.windowId <= 0) && !target.nativeWindowRef)\n\t\tthrow new Error(\n\t\t\t`Current platform requires a stable root id to observe '${target.windowTitle}'. Call find_roots and select a root with a stable id.`,\n\t\t);\n\treturn await currentPlatformBackend.observe(\n\t\t{\n\t\t\ttarget: nativeWindowRequest(target),\n\t\t\tbaseLookId: options.baseLookId,\n\t\t\treadText: options.readText,\n\t\t\tscopeRef: options.scopeRef,\n\t\t\tmaxDimension: options.maxDimension,\n\t\t\tincludeImage: options.includeImage,\n\t\t},\n\t\t{ signal, timeoutMs: LOOK_TIMEOUT_MS },\n\t);\n}\n\nfunction noteWindowForTarget(target: ResolvedTarget | CurrentTarget, look?: LookResponse) {\n\treturn {\n\t\twindowRef: target.windowRef,\n\t\ttitle: target.windowTitle,\n\t\tpairing:\n\t\t\tlook?.window.metadata?.pairing && typeof look.window.metadata.pairing === \"object\"\n\t\t\t\t? (look.window.metadata.pairing as { confidence?: \"exact\" | \"high\" | \"low\" }).confidence\n\t\t\t\t: undefined,\n\t\tpairingScore:\n\t\t\tlook?.window.metadata?.pairing && typeof look.window.metadata.pairing === \"object\"\n\t\t\t\t? (look.window.metadata.pairing as { score?: number }).score\n\t\t\t\t: undefined,\n\t};\n}\n\nasync function captureCurrentTarget(\n\tsignal?: AbortSignal,\n\treadText: \"auto\" | \"always\" | \"never\" = \"auto\",\n\tmaxDimension = AUTO_IMAGE_MAX_DIMENSION,\n\ttargetOverride?: ResolvedTarget,\n\tincludeImage = true,\n): Promise<CaptureResult> {\n\tconst state = operationState();\n\tconst baseOutline = state.currentOutline;\n\tconst baseTarget = state.currentTarget;\n\tlet target = targetOverride ?? (await resolveCurrentTarget(signal));\n\ttarget = await ensureTargetWindowId(target, signal);\n\tconst look = await performLook(target, { maxDimension, readText, includeImage }, signal);\n\tconst outline = stabilizeRefs(\n\t\tbaseTarget && sameRootIdentity(baseTarget, target) ? baseOutline : undefined,\n\t\tlook.parsedOutline!,\n\t);\n\tlook.parsedOutline = outline;\n\tlook.outline = outline.root;\n\tconst capture = captureForLook(look);\n\n\tsetCurrentTarget(target);\n\tstate.currentCapture = capture;\n\tstate.currentStateTarget = { pid: target.pid, windowId: target.windowId, windowRef: target.windowRef };\n\tstate.currentLook = look;\n\tstate.currentOutline = outline;\n\tstate.currentNote = noteFromLook(state.currentNote, outline, noteWindowForTarget(target, look));\n\tstate.resourceKey = desktopResourceKey(target);\n\tstate.epoch ??= resourceScheduler.epoch(state.resourceKey);\n\n\treturn {\n\t\ttarget,\n\t\tcapture,\n\t\tlook,\n\t\toutline,\n\t\tactivation: emptyActivation(),\n\t};\n}\n\nasync function buildToolResult(\n\ttool: string,\n\tsummary: string,\n\tresult: CaptureResult,\n\texecution: ExecutionTrace,\n\t_signal?: AbortSignal,\n\timageMode: ImageMode = operationState().currentImageMode ?? \"auto\",\n\tbase?: { stateId: string; outline: Outline },\n): Promise<AgentToolResult<ComputerUseDetails>> {\n\tconst state = operationState();\n\tconst fallbackReason = imageFallbackReason(tool, result, imageMode);\n\tconst transition = base ? changesBetween(base.outline, result.outline) : undefined;\n\tconst useDiff = Boolean(transition && !transition.useFullView);\n\tconst folded = foldToBudget(result.outline);\n\tconst renderedNote = renderNote(state.currentNote);\n\n\tconst details: ComputerUseDetails = {\n\t\ttool,\n\t\ttarget: {\n\t\t\tapp: result.target.appName,\n\t\t\tbundleId: result.target.bundleId,\n\t\t\tpid: result.target.pid,\n\t\t\twindowTitle: result.target.windowTitle,\n\t\t\twindowId: result.target.windowId,\n\t\t\twindowRef: result.target.windowRef ?? state.currentTarget?.windowRef,\n\t\t\tnativeWindowRef: result.target.nativeWindowRef ?? state.currentTarget?.nativeWindowRef,\n\t\t},\n\t\tcapture: {\n\t\t\tstateId: result.capture.stateId,\n\t\t\twidth: result.capture.width,\n\t\t\theight: result.capture.height,\n\t\t\tscaleFactor: result.capture.scaleFactor,\n\t\t\ttimestamp: result.capture.timestamp,\n\t\t\tcoordinateSpace: \"window-relative-screenshot-pixels\",\n\t\t},\n\t\tlookId: result.look.lookId,\n\t\tview: useDiff ? \"diff\" : \"full\",\n\t\tbaseStateId: transition ? base?.stateId : undefined,\n\t\tchanges: useDiff ? transition?.changes : undefined,\n\t\tviewReason: transition?.useFullView ? transition.reason : undefined,\n\t\trenderedOutline: folded.text,\n\t\toutline: serializeOutline(result.outline),\n\t\tnote: state.currentNote,\n\t\tactivation: result.activation,\n\t\texecution,\n\t\tstatus: \"ok\",\n\t\tconfig: getComputerUseConfig(),\n\t\thelper: runtimeState.helperDiagnostics,\n\t\timageReason: fallbackReason?.reason,\n\t};\n\n\t// Console piggyback: when a CDP connection is active for this browser\n\t// window, surface console output collected since the last tool result.\n\tlet consoleText = \"\";\n\tif (currentPlatformBackend.isChromeFamilyApp(result.target.appName, result.target.bundleId)) {\n\t\tconst tab = await cdpTabForWindow(result.target.windowTitle, result.target.framePoints);\n\t\tconst entries = tab?.drainConsole() ?? [];\n\t\tif (entries.length > 0) {\n\t\t\tdetails.console = entries;\n\t\t\tconsoleText = `\\n\\nBrowser console since the last action:\\n${entries.map((entry) => `[${entry.level}] ${entry.text}`).join(\"\\n\")}`;\n\t\t}\n\t}\n\n\tconst noteText = renderedNote ? `\\n\\n${renderedNote}` : \"\";\n\t// The model must echo capture.stateId into follow-up tools. Exposing only the\n\t// helper-internal lookId here makes a plausible but invalid stateId easy to use.\n\tconst renderedChanges = useDiff ? renderChanges(transition!.changes) : \"\";\n\tconst outlineText = useDiff\n\t\t? `\\n\\nChanges (${transition!.changedNodeCount}, ${base!.stateId} → ${result.capture.stateId}):\\n${renderedChanges || \"(no element changes)\"}\\nUse stateId ${result.capture.stateId} for subsequent actions and queries.`\n\t\t: `\\n\\nOutline (${folded.nodeCount} nodes, stateId ${result.capture.stateId}${transition?.reason ? `, full view: ${transition.reason}` : \"\"}${folded.truncated ? \", folded output truncated\" : \"\"}):\\n${folded.text}`;\n\tconst fallbackText = fallbackReason ? `\\n\\n${fallbackReason.message}` : \"\";\n\tconst deltaText = rootDeltaLines(execution).join(\"\\n\");\n\tconst content: AgentToolResult<ComputerUseDetails>[\"content\"] = [\n\t\t{\n\t\t\ttype: \"text\",\n\t\t\ttext: `${summary}${deltaText ? `\\n${deltaText}` : \"\"}${consoleText}${noteText}${outlineText}${fallbackText}`,\n\t\t},\n\t];\n\tif (fallbackReason && result.look.image?.jpegBase64) {\n\t\tcontent.push({\n\t\t\ttype: \"image\",\n\t\t\tdata: result.look.image.jpegBase64,\n\t\t\tmimeType: result.look.image.mimeType ?? \"image/jpeg\",\n\t\t});\n\t}\n\n\treturn { content, details };\n}\n\ntype NativePreparedAction = Exclude<PreparedAction, { action: \"wait\" }>;\n\nfunction currentLookOrThrow(): LookResponse {\n\tconst state = operationState();\n\tif (!state.currentLook || !state.currentCapture) {\n\t\tthrow new Error(\"No current look. Call observe_ui first, then act using refs or coordinates from that look.\");\n\t}\n\treturn state.currentLook;\n}\n\nfunction ensurePointIsInLookImage(x: number, y: number, look: LookResponse, errorPrefix = \"Coordinates\"): void {\n\tif (!look.image?.jpegBase64) {\n\t\tthrow new Error(\n\t\t\t`${errorPrefix} require an image-bearing root. This look is outline-only; use an @e ref with a semantic action or observe an image-bearing root.`,\n\t\t);\n\t}\n\tif (!Number.isFinite(x) || !Number.isFinite(y)) {\n\t\tthrow new Error(`${errorPrefix} must be finite numbers.`);\n\t}\n\tif (x < 0 || y < 0 || x >= look.image.width || y >= look.image.height) {\n\t\tthrow new Error(\n\t\t\t`${errorPrefix} (${Math.round(x)},${Math.round(y)}) are outside the latest look image bounds (${look.image.width}x${look.image.height}). Call observe_ui again and retry.`,\n\t\t);\n\t}\n}\n\nfunction modelRefForRootDelta(delta: NonNullable<HelperActResult[\"rootDelta\"]>[number]): string | undefined {\n\tif (!delta.ref) return undefined;\n\tif (delta.ref.startsWith(\"@r\")) return delta.ref;\n\tfor (const record of runtimeState.windowRefs.values()) {\n\t\tif (record.nativeWindowRef === delta.ref || record.ref === delta.ref) return record.ref;\n\t}\n\tconst ref = `@r${runtimeState.nextRootRefIndex++}`;\n\tconst current = operationState().currentTarget;\n\tconst record: WindowRefRecord = {\n\t\tref,\n\t\tappName: current?.pid === delta.pid ? current.appName : \"Unknown App\",\n\t\tbundleId: current?.pid === delta.pid ? current.bundleId : undefined,\n\t\tpid: delta.pid,\n\t\twindowTitle: delta.title ?? \"(untitled)\",\n\t\tnativeWindowRef: delta.ref,\n\t\tframePoints: { x: 0, y: 0, w: 1, h: 1 },\n\t\tscaleFactor: 1,\n\t\tisMinimized: false,\n\t\tisOnscreen: true,\n\t\tisMain: false,\n\t\tisFocused: delta.change === \"focused\",\n\t};\n\truntimeState.windowRefs.set(ref, record);\n\truntimeState.windowRefByIdentity.set(windowRecordIdentity(record), ref);\n\treturn ref;\n}\n\nfunction executionTraceFromAct(result: HelperActResult, policy = currentDeliveryPolicy()): ExecutionTrace {\n\tconst rootDelta = result.rootDelta?.map((delta) => ({ ...delta, ref: modelRefForRootDelta(delta) }));\n\treturn executionTrace(\"act\", result.performed?.delivery === \"ax\" ? \"stealth\" : \"default\", {\n\t\toutcome: result.outcome,\n\t\tperformed: result.performed,\n\t\tevidence: result.evidence,\n\t\terror: result.error,\n\t\tstoppedAt: result.stoppedAt,\n\t\trootDelta,\n\t\tdelivery: result.performed?.delivery,\n\t\tdeliveryPolicy: policy,\n\t});\n}\n\nasync function helperAct(\n\ttarget: ResolvedTarget,\n\taction: NativePreparedAction,\n\theadless: boolean,\n\tsignal?: AbortSignal,\n): Promise<ExecutionTrace> {\n\tconst checked = (candidate: HelperActResult): HelperActResult => {\n\t\tif (!candidate || ![\"worked\", \"didnt\", \"unknown\"].includes(candidate.outcome)) {\n\t\t\tthrow new Error(\"Helper act returned an invalid result without an outcome.\");\n\t\t}\n\t\treturn candidate;\n\t};\n\tconst textTimeout = \"text\" in action.params ? action.params.text.length * 25 + 4_000 : COMMAND_TIMEOUT_MS;\n\tconst timeoutMs = Math.max(COMMAND_TIMEOUT_MS, textTimeout);\n\tif ((action.usesCurrentFocus || action.needsForeground) && !headless) {\n\t\tconst foreground = checked(\n\t\t\tawait currentPlatformBackend.act(helperActRequest(target, action, \"foreground\"), { signal, timeoutMs }),\n\t\t);\n\t\tconst trace = executionTraceFromAct(foreground, \"foreground\");\n\t\ttrace.backgroundFirst = false;\n\t\treturn trace;\n\t}\n\ttry {\n\t\tconst initialPolicy = headless ? \"ax_only\" : \"background\";\n\t\tconst result = checked(\n\t\t\tawait currentPlatformBackend.act(helperActRequest(target, action, initialPolicy), { signal, timeoutMs }),\n\t\t);\n\t\tif (canRetryInForeground(action, result.outcome, headless)) {\n\t\t\tconst foreground = checked(\n\t\t\t\tawait currentPlatformBackend.act(helperActRequest(target, action, \"foreground\"), { signal, timeoutMs }),\n\t\t\t);\n\t\t\tconst trace = executionTraceFromAct(foreground, \"foreground\");\n\t\t\ttrace.backgroundFirst = true;\n\t\t\ttrace.escalatedToForeground = true;\n\t\t\ttrace.escalationReason = \"side_effect_free_didnt\";\n\t\t\ttrace.backgroundAttempt = {\n\t\t\t\toutcome: \"didnt\",\n\t\t\t\treason: \"Background input produced no observable value change; a foreground retry was safe.\",\n\t\t\t};\n\t\t\treturn trace;\n\t\t}\n\t\tconst trace = executionTraceFromAct(result, \"background\");\n\t\ttrace.backgroundFirst = true;\n\t\treturn trace;\n\t} catch (error) {\n\t\tconst code = (error as Error & { code?: string })?.code;\n\t\tif (code !== \"foreground_required\" || headless) throw error;\n\t\tconst foreground = checked(\n\t\t\tawait currentPlatformBackend.act(helperActRequest(target, action, \"foreground\"), { signal, timeoutMs }),\n\t\t);\n\t\tconst trace = executionTraceFromAct(foreground, \"foreground\");\n\t\ttrace.backgroundFirst = true;\n\t\ttrace.escalatedToForeground = true;\n\t\ttrace.escalationReason = code;\n\t\ttrace.backgroundAttempt = {\n\t\t\toutcome: \"foreground_required\",\n\t\t\treason: error instanceof Error ? error.message : String(error),\n\t\t};\n\t\treturn trace;\n\t}\n}\n\nfunction helperActRequest(\n\ttarget: ResolvedTarget,\n\taction: NativePreparedAction,\n\tpolicy = currentDeliveryPolicy(),\n): PlatformActRequest {\n\tconst look = currentLookOrThrow();\n\tconst delivery = nativeInputDelivery(policy);\n\tconst base = { lookId: look.lookId, pid: target.pid, target: action.target, policy };\n\treturn (() => {\n\t\tswitch (action.action) {\n\t\t\tcase \"press\":\n\t\t\tcase \"click\":\n\t\t\t\treturn { ...base, action: action.action, params: { ...action.params, delivery } };\n\t\t\tcase \"setText\":\n\t\t\t\treturn { ...base, action: action.action, params: { text: action.params.text, delivery } };\n\t\t\tcase \"typeText\":\n\t\t\t\treturn { ...base, action: action.action, params: { text: action.params.text, delivery } };\n\t\t\tcase \"keypress\":\n\t\t\t\treturn { ...base, action: action.action, params: { keys: action.params.keys, delivery } };\n\t\t\tcase \"scroll\":\n\t\t\t\treturn {\n\t\t\t\t\t...base,\n\t\t\t\t\taction: action.action,\n\t\t\t\t\tparams: { scrollX: action.params.scrollX, scrollY: action.params.scrollY, delivery },\n\t\t\t\t};\n\t\t\tcase \"drag\":\n\t\t\t\treturn { ...base, action: action.action, params: { path: action.params.path, delivery } };\n\t\t\tcase \"moveMouse\":\n\t\t\t\treturn { ...base, action: action.action, params: { delivery } };\n\t\t}\n\t})();\n}\n\nfunction rootDeltaLines(execution: ExecutionTrace): string[] {\n\treturn (execution.rootDelta ?? []).map((delta) => {\n\t\tconst quotedTitle = delta.title ? ` ${JSON.stringify(delta.title)}` : \"\";\n\t\tconst ref = delta.ref ? ` (${delta.ref.startsWith(\"@\") ? delta.ref : `@${delta.ref}`})` : \"\";\n\t\tconst sheetCount =\n\t\t\ttypeof delta.metadata?.sheetCount === \"number\" && Number.isFinite(delta.metadata.sheetCount)\n\t\t\t\t? Math.max(0, Math.trunc(delta.metadata.sheetCount))\n\t\t\t\t: undefined;\n\t\tconst flags = [delta.isModal ? \"modal\" : undefined, sheetCount ? `sheets=${sheetCount}` : undefined]\n\t\t\t.filter(Boolean)\n\t\t\t.join(\", \");\n\t\tconst suffix = `${quotedTitle}${flags ? ` (${flags})` : \"\"}${ref}`;\n\t\tif (delta.change === \"appeared\") return `New root: ${delta.kind}${suffix}`;\n\t\tif (delta.change === \"closed\") return `Root closed: ${delta.kind}${suffix}`;\n\t\treturn `Root focused: ${delta.kind}${suffix}`;\n\t});\n}\n\nfunction windowDetails(\n\tapp: HelperApp,\n\twindow: HelperWindow,\n\tconfig: ReturnType<typeof getComputerUseConfig>,\n): ListWindowsDetails[\"windows\"][number] {\n\tconst storedRef = storeWindowRefForAppWindow(app, window);\n\treturn {\n\t\tapp: app.appName,\n\t\tbundleId: app.bundleId,\n\t\tpid: app.pid,\n\t\tkind: window.kind,\n\t\twindowTitle: window.title || \"(untitled)\",\n\t\twindowId: window.windowId,\n\t\twindowRef: storedRef.ref,\n\t\tnativeWindowRef: window.windowRef,\n\t\tframePoints: window.framePoints,\n\t\tscaleFactor: window.scaleFactor,\n\t\tisMinimized: window.isMinimized,\n\t\tisOnscreen: window.isOnscreen,\n\t\tisMain: window.isMain,\n\t\tisFocused: window.isFocused,\n\t\tisModal: window.isModal,\n\t\tsheetCount: platformRootSheetCount(window),\n\t\trole: window.role,\n\t\tsubrole: window.subrole,\n\t\tpairing: platformRootPairing(window),\n\t\tzOrder: window.zOrder,\n\t\tbrowserUseAllowed: config.browser_use || !currentPlatformBackend.isBrowserApp(app.appName, app.bundleId),\n\t\tscore: scoreWindow(window),\n\t};\n}\n\nfunction sortWindowDetails(windows: ListWindowsDetails[\"windows\"]): ListWindowsDetails[\"windows\"] {\n\treturn windows.sort(\n\t\t(a, b) => b.score - a.score || a.app.localeCompare(b.app) || a.windowTitle.localeCompare(b.windowTitle),\n\t);\n}\n\n// Side effect: stores stable @r refs for discovered windows in runtimeState.\nasync function collectWindowDetails(\n\tapps: HelperApp[],\n\tconfig: ReturnType<typeof getComputerUseConfig>,\n\tsignal?: AbortSignal,\n): Promise<ListWindowsDetails[\"windows\"]> {\n\tconst perApp = await Promise.all(apps.map(async (app) => ({ app, windows: await listWindows(app.pid, signal) })));\n\treturn sortWindowDetails(\n\t\tperApp.flatMap(({ app, windows }) => windows.map((window) => windowDetails(app, window, config))),\n\t);\n}\n\nfunction collectBroadWindowDetails(\n\troots: HelperWindow[],\n\tconfig: ReturnType<typeof getComputerUseConfig>,\n): ListWindowsDetails[\"windows\"] {\n\tconst windows: ListWindowsDetails[\"windows\"] = [];\n\tfor (const window of roots) {\n\t\tif (!window.pid) continue;\n\t\twindows.push(\n\t\t\twindowDetails(\n\t\t\t\t{ appName: window.appName ?? \"Unknown App\", bundleId: window.bundleId, pid: window.pid },\n\t\t\t\twindow,\n\t\t\t\tconfig,\n\t\t\t),\n\t\t);\n\t}\n\treturn sortWindowDetails(windows);\n}\n\nasync function windowDetailsForFind(\n\tquery: FindParams,\n\tconfig: ReturnType<typeof getComputerUseConfig>,\n\tsignal?: AbortSignal,\n): Promise<ListWindowsDetails[\"windows\"]> {\n\tif (!query.app && !query.bundleId && !Number.isFinite(query.pid)) {\n\t\treturn collectBroadWindowDetails(await currentPlatformBackend.listRoots({}, signal), config);\n\t}\n\tconst apps = (await listApps(signal)).filter((app) => appMatchesWindowQuery(app, query));\n\treturn await collectWindowDetails(apps, config, signal);\n}\n\nasync function performListWindows(\n\tparams: FindParams,\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<ListWindowsDetails>> {\n\tconst rawParams = params ?? {};\n\tconst query: FindParams = {\n\t\ttext: trimOrUndefined(rawParams.text),\n\t\tapp: trimOrUndefined(rawParams.app),\n\t\tbundleId: trimOrUndefined(rawParams.bundleId),\n\t\tpid: Number.isFinite(rawParams.pid) ? Math.trunc(rawParams.pid!) : undefined,\n\t\tkind: rawParams.kind,\n\t};\n\tconst config = getComputerUseConfig();\n\tconst desktopForest = await windowDetailsForFind(query, config, signal);\n\tconst includeBrowserPages =\n\t\t!query.pid && !query.bundleId && (!query.app || normalizeText(query.app) === \"browser\") && config.browser_use;\n\tconst browserForest: ListWindowsDetails[\"windows\"] = !includeBrowserPages\n\t\t? []\n\t\t: (await listCdpPageContexts().catch(() => [])).map((page) => ({\n\t\t\t\tapp: \"Browser\",\n\t\t\t\tpid: 0,\n\t\t\t\tkind: \"browser_page\",\n\t\t\t\twindowTitle: page.title || page.url,\n\t\t\t\twindowRef: storeBrowserRootRef(page.contextId),\n\t\t\t\tframePoints: { x: 0, y: 0, w: 1, h: 1 },\n\t\t\t\tscaleFactor: 1,\n\t\t\t\tisMinimized: false,\n\t\t\t\tisOnscreen: true,\n\t\t\t\tisMain: false,\n\t\t\t\tisFocused: false,\n\t\t\t\tisModal: false,\n\t\t\t\tzOrder: Number.MAX_SAFE_INTEGER,\n\t\t\t\tbrowserUseAllowed: true,\n\t\t\t\tscore: 0,\n\t\t\t\turl: page.url,\n\t\t\t}));\n\tconst allRoots = [...desktopForest, ...browserForest];\n\tconst forest = allRoots.filter((root) => !query.kind || root.kind === query.kind);\n\tconst ranked = forest\n\t\t.map((root, order) => ({\n\t\t\troot,\n\t\t\torder,\n\t\t\tmatch: query.text\n\t\t\t\t? rankedTextMatch([root.app, root.windowTitle], query.text)\n\t\t\t\t: { reason: \"filter\" as const, score: 1 },\n\t\t}))\n\t\t.filter((entry) => entry.match)\n\t\t.sort(\n\t\t\t(a, b) =>\n\t\t\t\tb.match!.score - a.match!.score ||\n\t\t\t\tNumber(b.root.isFocused) - Number(a.root.isFocused) ||\n\t\t\t\ta.root.zOrder - b.root.zOrder ||\n\t\t\t\ta.order - b.order,\n\t\t);\n\tconst totalMatches = ranked.length;\n\tconst windows = ranked.slice(0, 12).map((entry) => entry.root);\n\tconst details: ListWindowsDetails = {\n\t\ttool: \"find_roots\",\n\t\tquery,\n\t\twindows,\n\t\ttotalMatches,\n\t\treturned: windows.length,\n\t\thasMore: totalMatches > windows.length,\n\t\tconfig,\n\t};\n\tconst lines = windows.map(formatWindowLine);\n\tconst text = lines.length\n\t\t? `Found ${totalMatches} matching root${totalMatches === 1 ? \"\" : \"s\"}; returned ${windows.length}${totalMatches > windows.length ? \". Refine the filters for additional roots\" : \"\"}. Use @r refs with observe_ui({ root: \"@rN\" }).\\n${lines.join(\"\\n\")}`\n\t\t: query.text || query.app || query.bundleId || query.pid || query.kind\n\t\t\t? \"No roots matched the supplied filters.\"\n\t\t\t: \"No roots are currently visible to ada-computer-use.\";\n\treturn { content: [{ type: \"text\", text }], details };\n}\n\nfunction normalizeImageMode(value: unknown): ImageMode {\n\treturn value === \"always\" || value === \"never\" ? value : \"auto\";\n}\n\nfunction isBrowserContextId(contextId: string | undefined): contextId is string {\n\treturn Boolean(contextId?.startsWith(BROWSER_CONTEXT_PREFIX));\n}\n\nfunction browserSnapshotTarget(\n\tsnapshotId: string | undefined,\n\tref: string | undefined,\n): { contextId: string; backendNodeId?: number } | undefined {\n\tif (!snapshotId || !ref) return undefined;\n\tconst record = savedStates.get(snapshotId);\n\tconst snapshot = record?.value.kind === \"browser\" ? record.value.snapshot : undefined;\n\tconst target = snapshot?.targets.find((candidate) => candidate.ref === ref);\n\tif (!snapshot || !target) return undefined;\n\treturn { contextId: snapshot.contextId, backendNodeId: target.backendNodeId };\n}\n\nfunction browserContextForOperation(): string | undefined {\n\tconst contextId = operationState().contextId;\n\treturn isBrowserContextId(contextId) ? contextId : undefined;\n}\n\nasync function withBrowserWrite<T>(contextId: string, work: () => Promise<T>): Promise<T> {\n\tconst state = operationState();\n\tconst targetId = contextId.slice(BROWSER_CONTEXT_PREFIX.length);\n\tconst resourceKey = `cdp:${targetId}`;\n\tconst baseEpoch = state.epoch ?? resourceScheduler.epoch(resourceKey);\n\tconst result = await resourceScheduler.write(resourceKey, baseEpoch, async (nextEpoch) => {\n\t\tstate.resourceKey = resourceKey;\n\t\tstate.epoch = nextEpoch;\n\t\treturn await work();\n\t});\n\treturn result.value;\n}\n\nfunction browserObservationResult(\n\tbrowser: CdpPageSnapshot,\n\tresourceKey: string,\n\tepoch: number,\n\ttool: string,\n\tbase?: { stateId: string; outline: SerializedOutline },\n): AgentToolResult<BrowserObservationDetails> {\n\tsavedStates.set({\n\t\tstateId: browser.snapshotId,\n\t\tresourceKey,\n\t\tepoch,\n\t\tvalue: { kind: \"browser\", snapshot: browser, outline: browser.outline },\n\t});\n\tconst currentOutline = restoreOutline(browser.outline);\n\tconst transition = base ? changesBetween(restoreOutline(base.outline), currentOutline) : undefined;\n\tconst useDiff = Boolean(transition && !transition.useFullView);\n\tconst folded = foldToBudget(currentOutline);\n\tconst root = {\n\t\tref: storeBrowserRootRef(browser.contextId),\n\t\tkind: \"browser_page\" as const,\n\t\ttitle: browser.title,\n\t\turl: browser.url,\n\t};\n\tconst details: BrowserObservationDetails = {\n\t\ttool,\n\t\tkind: \"browser_page\",\n\t\tstateId: browser.snapshotId,\n\t\tbaseStateId: base?.stateId,\n\t\tview: useDiff ? \"diff\" : \"full\",\n\t\tchanges: useDiff ? transition?.changes : undefined,\n\t\troot,\n\t\toutline: browser.outline,\n\t\trenderedOutline: folded.text,\n\t};\n\tconst viewText = useDiff\n\t\t? `Changes (${transition!.changedNodeCount}, ${base!.stateId} → ${browser.snapshotId}):\\n${renderChanges(transition!.changes) || \"(no element changes)\"}\\nUse stateId ${browser.snapshotId} for subsequent actions and queries.`\n\t\t: folded.text;\n\treturn {\n\t\tcontent: [\n\t\t\t{\n\t\t\t\ttype: \"text\",\n\t\t\t\ttext: `${tool} completed for ${root.ref} ${JSON.stringify(browser.title)}. State ${browser.snapshotId}.\\n${viewText}`,\n\t\t\t},\n\t\t],\n\t\tdetails,\n\t};\n}\n\nasync function refreshBrowserSnapshot(\n\tcontextId: string,\n\ttool: string,\n\tbase?: { stateId: string; outline: SerializedOutline },\n): Promise<AgentToolResult<BrowserObservationDetails>> {\n\tconst browser = await cdpSnapshotForContext(contextId);\n\tif (!browser)\n\t\tthrow new Error(`Browser root '${contextId}' is no longer available. Call find_roots and observe_ui again.`);\n\tconst state = operationState();\n\tconst resourceKey = state.resourceKey ?? `cdp:${browser.targetId}`;\n\treturn browserObservationResult(\n\t\tbrowser,\n\t\tresourceKey,\n\t\tstate.epoch ?? resourceScheduler.epoch(resourceKey),\n\t\ttool,\n\t\tbase,\n\t);\n}\n\nfunction sliceText(\n\tvalue: string,\n\toffsetValue: unknown,\n\t_limitValue?: unknown,\n): Pick<ReadTextDetails, \"offset\" | \"limit\" | \"totalChars\" | \"hasMore\" | \"text\"> {\n\tconst offset = Math.max(0, Math.trunc(toFiniteNumber(offsetValue, 0)));\n\tconst limit = UI_TEXT_PAGE_CHARS;\n\tconst characters = Array.from(value);\n\tconst end = Math.min(characters.length, offset + limit);\n\treturn {\n\t\toffset,\n\t\tlimit,\n\t\ttotalChars: characters.length,\n\t\thasMore: end < characters.length,\n\t\ttext: offset >= characters.length ? \"\" : characters.slice(offset, end).join(\"\"),\n\t};\n}\n\nasync function performReadText(\n\tparams: ReadTextParams,\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<ReadTextDetails>> {\n\tconst ref = trimOrUndefined(params.ref);\n\tif (ref?.startsWith(\"@o\")) {\n\t\tconst page = readStoredOutput(ref, params.offset);\n\t\tif (!page) throw new Error(`Output ref '${ref}' is unavailable or was evicted. Rerun the focused query.`);\n\t\tconst details: ReadTextDetails = { tool: \"read_text\", ref, ...page };\n\t\tconst suffix = page.hasMore\n\t\t\t? `\\n\\ncontinue: read_text({ ref: \"${ref}\", offset: ${page.offset + page.limit} })`\n\t\t\t: page.complete\n\t\t\t\t? \"\"\n\t\t\t\t: \"\\n\\ncontinuation storage limit reached; rerun a more focused query for the remainder\";\n\t\treturn { content: [{ type: \"text\", text: `${page.text || \"(empty output page)\"}${suffix}` }], details };\n\t}\n\tconst contextId = operationState().contextId;\n\tif (isBrowserContextId(contextId)) {\n\t\tconst snapshot = operationState().browserSnapshot;\n\t\tif (!snapshot || snapshot.contextId !== contextId)\n\t\t\tthrow new Error(`Browser state '${params.stateId}' is unavailable. Observe the browser root again.`);\n\t\tif (!ref)\n\t\t\tthrow new Error(\n\t\t\t\t\"read_text requires an @e ref for browser contexts; use the outline root ref for whole-page text.\",\n\t\t\t);\n\t\tconst outline = restoreOutline(snapshot.outline);\n\t\tconst node = nodeByRef(outline, ref);\n\t\tif (!node) throw new Error(`Browser text ref '${ref}' is unavailable in this state.`);\n\t\tconst collect = (current: OutlineNode): string[] =>\n\t\t\t[\n\t\t\t\toutlineNodeLabel(current),\n\t\t\t\t...current.text.map((item) => item.string),\n\t\t\t\t...current.children.flatMap(collect),\n\t\t\t].filter(Boolean);\n\t\tconst value = node === outline.root ? snapshot.text : [...new Set(collect(node))].join(\"\\n\");\n\t\tconst sliced = sliceText(value, params.offset);\n\t\tconst details: ReadTextDetails = { tool: \"read_text\", ref, ...sliced };\n\t\treturn { content: [{ type: \"text\", text: sliced.text || \"(empty text slice)\" }], details };\n\t}\n\n\tvalidateStateId(params.stateId);\n\tif (!ref)\n\t\tthrow new Error(\n\t\t\t\"read_text requires ref for desktop contexts. Call observe_ui/inspect_ui and use a text-bearing outline ref.\",\n\t\t);\n\tconst node = outlineNodeByRef(ref);\n\tconst state = operationState();\n\tif (!state.resourceKey || state.epoch === undefined)\n\t\tthrow new Error(\"The observation has no live resource identity. Observe again.\");\n\tconst raw = (\n\t\tawait resourceScheduler.readAt(\n\t\t\tstate.resourceKey,\n\t\t\tstate.epoch,\n\t\t\tasync () =>\n\t\t\t\tawait currentPlatformBackend.readText(\n\t\t\t\t\t{\n\t\t\t\t\t\tlookId: state.currentOutline!.lookId,\n\t\t\t\t\t\telementRef: wireRefForNode(node),\n\t\t\t\t\t\toffset: Math.max(0, Math.trunc(toFiniteNumber(params.offset, 0))),\n\t\t\t\t\t\tlimit: UI_TEXT_PAGE_CHARS,\n\t\t\t\t\t},\n\t\t\t\t\t{ signal, timeoutMs: COMMAND_TIMEOUT_MS },\n\t\t\t\t),\n\t\t)\n\t).value;\n\tconst text = raw.text;\n\tconst details: ReadTextDetails = {\n\t\ttool: \"read_text\",\n\t\tref,\n\t\toffset: raw.offset,\n\t\tlimit: raw.limit,\n\t\ttotalChars: raw.totalChars,\n\t\thasMore: raw.hasMore,\n\t\ttext,\n\t};\n\treturn { content: [{ type: \"text\", text: text || \"(empty text slice)\" }], details };\n}\n\nfunction normalizeWaitTimeoutMs(value: unknown): number {\n\treturn Math.max(100, Math.min(60_000, Math.trunc(toFiniteNumber(value, 10_000))));\n}\n\nfunction conditionScopeRef(params: WaitForParams | NonNullable<ActParams[\"expect\"]>): string | undefined {\n\tconst ref = trimOrUndefined(params.ref);\n\tconst scopeRef = trimOrUndefined(params.scopeRef);\n\tif (ref && scopeRef) throw new Error(\"A UI condition accepts ref or scopeRef, not both.\");\n\treturn ref ?? scopeRef;\n}\n\nfunction validateCondition(params: WaitForParams | NonNullable<ActParams[\"expect\"]>): {\n\ttext?: string;\n\trole?: string;\n\tvalue?: string;\n\tscopeRef?: string;\n\tscopeExact: boolean;\n\tgone: boolean;\n\ttimeoutMs: number;\n} {\n\tconst text = trimOrUndefined(params.text);\n\tconst role = trimOrUndefined(params.role);\n\tconst value = trimOrUndefined(params.value);\n\tconst scopeRef = conditionScopeRef(params);\n\tif (!text && !role && !value) throw new Error(\"A UI condition requires text, role, or value.\");\n\tif (role && !text && !value && !scopeRef) throw new Error(\"A role-only UI condition requires ref or scopeRef.\");\n\tif (value && !params.ref) throw new Error(\"A value UI condition requires an exact ref.\");\n\treturn {\n\t\ttext,\n\t\trole,\n\t\tvalue,\n\t\tscopeRef,\n\t\tscopeExact: Boolean(params.ref),\n\t\tgone: params.until === \"absent\",\n\t\ttimeoutMs: normalizeWaitTimeoutMs(params.timeoutMs),\n\t};\n}\n\nfunction nodeWithinScope(node: OutlineNode, scopeRef: string | undefined, scopeExact: boolean): boolean {\n\tif (!scopeRef) return true;\n\tif (scopeExact) return node.ref === scopeRef;\n\tlet current: OutlineNode | undefined = node;\n\twhile (current) {\n\t\tif (current.ref === scopeRef) return true;\n\t\tcurrent = current.parent;\n\t}\n\treturn false;\n}\n\nfunction normalizedRole(value: string): string {\n\treturn value\n\t\t.toLowerCase()\n\t\t.replace(/^ax/, \"\")\n\t\t.replace(/[ _-]+/g, \"\");\n}\n\nfunction platformRole(outline: Outline, role: string | undefined): string | undefined {\n\tif (!role) return undefined;\n\treturn outline.nodes.find((node) => normalizedRole(node.role) === normalizedRole(role))?.role ?? role;\n}\n\nfunction outlineConditionPresent(outline: Outline, condition: ReturnType<typeof validateCondition>): boolean {\n\treturn searchOutline(outline, condition.text, undefined, undefined, outline.nodes.length).some(\n\t\t(match) =>\n\t\t\t(!condition.role || normalizedRole(match.node.role) === normalizedRole(condition.role)) &&\n\t\t\tnodeWithinScope(match.node, condition.scopeRef, condition.scopeExact) &&\n\t\t\t(!condition.value || normalizeText(match.node.value) === normalizeText(condition.value)),\n\t);\n}\n\nfunction conditionScopeNode(\n\toutline: Outline,\n\tcondition: ReturnType<typeof validateCondition>,\n): OutlineNode | undefined {\n\tconst scopeNode = condition.scopeRef ? nodeByRef(outline, condition.scopeRef) : undefined;\n\tif (condition.scopeRef && !scopeNode)\n\t\tthrow new Error(`Condition scope ref '${condition.scopeRef}' is unavailable in this state.`);\n\treturn scopeNode;\n}\n\nasync function performWaitFor(params: WaitForParams, signal?: AbortSignal): Promise<AgentToolResult<WaitForDetails>> {\n\tconst contextId = operationState().contextId;\n\tconst condition = validateCondition(params);\n\tconst { text, role, value, scopeRef, scopeExact, gone, timeoutMs } = condition;\n\n\tif (isBrowserContextId(contextId)) {\n\t\tconst state = operationState();\n\t\tif (!state.resourceKey) throw new Error(\"The browser observation has no live resource identity. Observe again.\");\n\t\tconst baseSnapshot = state.browserSnapshot;\n\t\tif (!baseSnapshot) throw new Error(\"Browser wait requires a complete base observation.\");\n\t\tconditionScopeNode(restoreOutline(baseSnapshot.outline), condition);\n\t\tconst deadline = Date.now() + timeoutMs;\n\t\tlet lastSnapshot: CdpPageSnapshot | undefined;\n\t\tlet lastEpoch = state.epoch ?? resourceScheduler.epoch(state.resourceKey);\n\t\tconst finish = (found: boolean, timedOut?: boolean): AgentToolResult<WaitForDetails> => {\n\t\t\tif (!lastSnapshot) throw new Error(\"Browser wait completed without an observation.\");\n\t\t\tsavedStates.set({\n\t\t\t\tstateId: lastSnapshot.snapshotId,\n\t\t\t\tresourceKey: state.resourceKey!,\n\t\t\t\tepoch: lastEpoch,\n\t\t\t\tvalue: { kind: \"browser\", snapshot: lastSnapshot, outline: lastSnapshot.outline },\n\t\t\t});\n\t\t\tconst successorOutline = restoreOutline(lastSnapshot.outline);\n\t\t\tconst transition = changesBetween(restoreOutline(baseSnapshot.outline), successorOutline);\n\t\t\tconst useDiff = !transition.useFullView;\n\t\t\tconst renderedOutline = foldToBudget(successorOutline).text;\n\t\t\tconst details: WaitForDetails = {\n\t\t\t\ttool: \"wait_for\",\n\t\t\t\tstateId: lastSnapshot.snapshotId,\n\t\t\t\tbaseStateId: baseSnapshot.snapshotId,\n\t\t\t\tview: useDiff ? \"diff\" : \"full\",\n\t\t\t\tchanges: useDiff ? transition.changes : undefined,\n\t\t\t\tfound,\n\t\t\t\tgone: (found && gone) || undefined,\n\t\t\t\ttimedOut,\n\t\t\t\tnodeCount: lastSnapshot.targets.length,\n\t\t\t\ttext,\n\t\t\t\trole,\n\t\t\t\tvalue,\n\t\t\t\tscopeRef,\n\t\t\t\toutline: lastSnapshot.outline,\n\t\t\t\trenderedOutline,\n\t\t\t};\n\t\t\tconst message = found\n\t\t\t\t? gone\n\t\t\t\t\t? \"Condition disappeared.\"\n\t\t\t\t\t: \"Condition appeared.\"\n\t\t\t\t: `Timed out after ${timeoutMs}ms waiting for condition.`;\n\t\t\tconst viewText = useDiff\n\t\t\t\t? `${renderChanges(transition.changes) || \"(no element changes)\"}\\nUse stateId ${lastSnapshot.snapshotId} for subsequent actions and queries.`\n\t\t\t\t: renderedOutline;\n\t\t\treturn { content: [{ type: \"text\", text: `${message}\\n${viewText}` }], details };\n\t\t};\n\t\tdo {\n\t\t\tconst scheduled = await resourceScheduler.read(\n\t\t\t\tstate.resourceKey,\n\t\t\t\tasync () => await cdpSnapshotForContext(contextId),\n\t\t\t);\n\t\t\tlastSnapshot = scheduled.value;\n\t\t\tlastEpoch = scheduled.epoch;\n\t\t\tif (!lastSnapshot)\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Browser root '${contextId}' is no longer available. Call find_roots and observe_ui again.`,\n\t\t\t\t);\n\t\t\tconst present = outlineConditionPresent(restoreOutline(lastSnapshot.outline), condition);\n\t\t\tif (present !== gone) return finish(true);\n\t\t\tawait sleep(200, signal);\n\t\t} while (Date.now() < deadline);\n\t\treturn finish(false, true);\n\t}\n\n\tconst state = operationState();\n\tconst baseView = { stateId: state.currentCapture!.stateId, outline: state.currentOutline! };\n\tlet target = await resolveCurrentTarget(signal);\n\ttarget = await ensureTargetWindowId(target, signal);\n\tconst scopeNode = conditionScopeNode(state.currentOutline!, condition);\n\tconst raw = await currentPlatformBackend.waitFor(\n\t\t{\n\t\t\t...nativeWindowRequest(target),\n\t\t\tlookId: state.currentOutline!.lookId,\n\t\t\ttext,\n\t\t\trole: platformRole(state.currentOutline!, role),\n\t\t\tvalue,\n\t\t\tscopeRef: scopeNode ? wireRefForNode(scopeNode) : undefined,\n\t\t\tscopeExact,\n\t\t\tgone,\n\t\t\ttimeoutMs,\n\t\t},\n\t\t{ signal, timeoutMs: timeoutMs + 2_000 },\n\t);\n\tif (!state.resourceKey || state.epoch === undefined)\n\t\tthrow new Error(\"The observation has no live resource identity. Observe again.\");\n\tconst refreshed = (\n\t\tawait resourceScheduler.readAt(\n\t\t\tstate.resourceKey,\n\t\t\tstate.epoch,\n\t\t\tasync () => await captureCurrentTarget(signal, \"auto\"),\n\t\t)\n\t).value;\n\tconst transition = changesBetween(baseView.outline, refreshed.outline);\n\tconst useDiff = !transition.useFullView;\n\tconst matches = searchOutline(refreshed.outline, text, role, undefined, 1);\n\tconst foundTarget = matches[0];\n\tconst details: WaitForDetails = {\n\t\ttool: \"wait_for\",\n\t\tstateId: refreshed.capture.stateId,\n\t\tbaseStateId: baseView.stateId,\n\t\tview: useDiff ? \"diff\" : \"full\",\n\t\tchanges: useDiff ? transition.changes : undefined,\n\t\tfound: raw.found,\n\t\tgone: raw.gone || undefined,\n\t\ttimedOut: raw.timedOut || undefined,\n\t\ttarget: foundTarget ? serializeOutlineSearchMatch(foundTarget) : undefined,\n\t\tnodeCount: Number.isFinite(raw.nodeCount) ? Number(raw.nodeCount) : refreshed.outline.nodes.length,\n\t\ttext,\n\t\trole,\n\t\tvalue,\n\t\tscopeRef,\n\t\toutline: serializeOutline(refreshed.outline),\n\t\trenderedOutline: foldToBudget(refreshed.outline).text,\n\t};\n\tconst message = details.found\n\t\t? details.gone\n\t\t\t? \"Condition disappeared.\"\n\t\t\t: \"Condition appeared.\"\n\t\t: `Timed out after ${timeoutMs}ms waiting for condition.`;\n\tconst viewText = useDiff\n\t\t? `${renderChanges(transition.changes) || \"(no element changes)\"}\\nUse stateId ${refreshed.capture.stateId} for subsequent actions and queries.`\n\t\t: details.renderedOutline;\n\treturn { content: [{ type: \"text\", text: `${message}\\n${viewText}` }], details };\n}\n\nfunction sameRootIdentity(a: CurrentTarget, b: CurrentTarget): boolean {\n\tif (a.pid !== b.pid) return false;\n\tif (a.windowId > 0 && b.windowId > 0) return a.windowId === b.windowId;\n\tif (a.nativeWindowRef && b.nativeWindowRef) return a.nativeWindowRef === b.nativeWindowRef;\n\treturn normalizeText(a.windowTitle) === normalizeText(b.windowTitle);\n}\n\n/** Side effects: captures/updates current target, capture state, look, and parsed outline. */\nasync function performObserve(\n\tparams: ObserveParams,\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<ComputerUseDetails | BrowserObservationDetails>> {\n\tconst requestedRoot = typeof params.root === \"string\" ? params.root : undefined;\n\tif (requestedRoot && !/^@r\\d+$/.test(requestedRoot))\n\t\tthrow new Error(\"observe_ui.root must be an exact @r ref issued by find_roots.\");\n\tconst browserContextId = requestedRoot ? runtimeState.browserContextByRoot.get(requestedRoot) : undefined;\n\tif (isBrowserContextId(browserContextId)) {\n\t\tconst targetId = browserContextId.slice(BROWSER_CONTEXT_PREFIX.length);\n\t\tconst resourceKey = `cdp:${targetId}`;\n\t\tconst scheduled = await resourceScheduler.read(\n\t\t\tresourceKey,\n\t\t\tasync () => await cdpSnapshotForContext(browserContextId),\n\t\t);\n\t\tconst browser = scheduled.value;\n\t\tif (!browser)\n\t\t\tthrow new Error(`Browser context '${browserContextId}' is no longer available. Call find_roots again.`);\n\t\treturn browserObservationResult(browser, resourceKey, scheduled.epoch, \"observe_ui\");\n\t}\n\tconst state = operationState();\n\tconst mode = params.mode ?? \"fused\";\n\tconst image = mode === \"semantic\" ? \"never\" : mode === \"visual\" ? \"always\" : \"auto\";\n\tconst defaultReadText = mode === \"semantic\" ? \"never\" : mode === \"visual\" ? \"always\" : \"auto\";\n\tconst readText = params.readText ?? defaultReadText;\n\tstate.currentImageMode = normalizeImageMode(image);\n\tconst selection: ObserveTargetParams = { root: normalizeWindowSelector(params.root) };\n\tconst requestedTarget = selection.root\n\t\t? await resolveTargetByWindowSelector(params.root!, signal)\n\t\t: await resolveTargetForObserve(signal);\n\tconst imageMode = normalizeImageMode(image);\n\tconst resourceKey = desktopResourceKey(requestedTarget);\n\tconst scheduled = await resourceScheduler.read(resourceKey, async (epoch) => {\n\t\tstate.resourceKey = resourceKey;\n\t\tstate.epoch = epoch;\n\t\treturn await captureCurrentTarget(\n\t\t\tsignal,\n\t\t\treadText,\n\t\t\timageMode === \"always\" ? EXPLICIT_IMAGE_MAX_DIMENSION : AUTO_IMAGE_MAX_DIMENSION,\n\t\t\trequestedTarget,\n\t\t\timageMode !== \"never\",\n\t\t);\n\t});\n\tconst captureResult = scheduled.value;\n\t// Model @r refs are re-minted on re-resolution, so ref string equality\n\t// alone false-positives as drift for the same root; compare stable\n\t// identity against the resolved request too.\n\tif (\n\t\t!matchesObserveSelection(captureResult.target, selection) &&\n\t\t!sameRootIdentity(captureResult.target, requestedTarget)\n\t) {\n\t\tthrow new Error(\n\t\t\t`Observation target drifted from the requested selection. Requested ${requestedTarget.appName} — ${requestedTarget.windowTitle}, captured ${captureResult.target.appName} — ${captureResult.target.windowTitle}. Call observe_ui again or specify a more exact window title.`,\n\t\t);\n\t}\n\tconst summary = `Observed ${mode} ${captureResult.target.windowRef ? `${captureResult.target.windowRef} ` : \"\"}${captureResult.target.appName} — ${captureResult.target.windowTitle}. Returned the latest outline state.`;\n\treturn await buildToolResult(\n\t\t\"observe_ui\",\n\t\tsummary,\n\t\tcaptureResult,\n\t\texecutionTrace(\"look\", \"stealth\"),\n\t\tsignal,\n\t\timageMode,\n\t);\n}\n\nfunction currentOutlineOrThrow(stateId?: string): Outline {\n\tvalidateStateId(stateId);\n\tconst outline = operationState().currentOutline;\n\tif (!outline) throw new Error(\"No observation outline is available. Call observe_ui first.\");\n\treturn outline;\n}\n\nfunction matchIsNonActionableStatic(match: OutlineSearchMatch): boolean {\n\tconst node = match.node;\n\treturn !node.canPress && !node.canFocus && !node.canSetValue && node.actions.length === 0 && !node.pictureOnly;\n}\n\nfunction shouldEscalateSearchOCR(matches: OutlineSearchMatch[], _text?: string): boolean {\n\treturn matches.length === 0 || matches.every(matchIsNonActionableStatic);\n}\n\n/** Pure outline query unless a window selector is supplied, in which case current target selection may change. */\nasync function performSearchUi(\n\tparams: SearchUiParams,\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<OutlineToolDetails>> {\n\tconst state = operationState();\n\tlet outline = currentOutlineOrThrow(params.stateId);\n\tconst text = trimOrUndefined(params.text);\n\tconst role = trimOrUndefined(params.role);\n\tconst capability = trimOrUndefined(params.capability);\n\tif (!text && !role && !capability)\n\t\tthrow new Error(\"search_ui requires text, role, or capability. Use observe_ui for a bounded overview.\");\n\tconst limit = 12;\n\tlet ranked = searchOutlineRanked(outline, text, role, capability, limit);\n\tlet matches = ranked.matches;\n\tlet escalatedOCR = false;\n\tconst look = state.currentLook;\n\tif (\n\t\tshouldEscalateSearchOCR(matches, text) &&\n\t\tlook &&\n\t\tlook.readText?.requested !== \"never\" &&\n\t\t!look.readText?.executed &&\n\t\tstate.lastSearchOcrEscalatedLookId !== look.lookId\n\t) {\n\t\tstate.lastSearchOcrEscalatedLookId = look.lookId;\n\t\tconst currentTarget = await ensureTargetWindowId(await resolveCurrentTarget(signal), signal);\n\t\t// captureCurrentTarget adopts the new look/outline/capture into\n\t\t// runtimeState, so refs in these matches stay actable. Keep the image\n\t\t// payload: OCR-only matches are clicked by coordinate, and coordinate\n\t\t// acts require the current look to be image-bearing.\n\t\tif (!state.resourceKey || state.epoch === undefined)\n\t\t\tthrow new Error(\"The observation has no live resource identity. Observe again.\");\n\t\tconst captureResult = (\n\t\t\tawait resourceScheduler.readAt(\n\t\t\t\tstate.resourceKey,\n\t\t\t\tstate.epoch,\n\t\t\t\tasync () => await captureCurrentTarget(signal, \"always\", AUTO_IMAGE_MAX_DIMENSION, currentTarget),\n\t\t\t)\n\t\t).value;\n\t\toutline = captureResult.outline;\n\t\tranked = searchOutlineRanked(outline, text, role, capability, limit);\n\t\tmatches = ranked.matches;\n\t\tescalatedOCR = true;\n\t}\n\tconst detailMatches = matches.map(serializeOutlineSearchMatch);\n\tconst details: OutlineToolDetails = {\n\t\ttool: \"search_ui\",\n\t\tstateId: state.currentCapture?.stateId,\n\t\tlookId: outline.lookId,\n\t\tmatches: detailMatches,\n\t\ttotalMatches: ranked.totalMatches,\n\t\treturned: matches.length,\n\t\thasMore: ranked.totalMatches > matches.length,\n\t\tnote: state.currentNote,\n\t};\n\tconst lines = matches.map(\n\t\t(match) =>\n\t\t\t`${match.ref} ${match.role || \"Unknown\"} ${JSON.stringify(match.label || \"(unlabeled)\")} [${match.matchReason}${match.matchReason === \"fuzzy\" ? ` ${match.score?.toFixed(2)}` : \"\"}]\\n  path: ${match.path}`,\n\t);\n\tconst noteHeader = renderNote(state.currentNote);\n\tconst noteText = noteHeader ? `${noteHeader}\\n\\n` : \"\";\n\tconst escalationText = escalatedOCR\n\t\t? \" OCR text was escalated for this search after the cached outline had no matches.\"\n\t\t: \"\";\n\tconst moreText =\n\t\tranked.totalMatches > matches.length\n\t\t\t? ` Refine the query to inspect ${ranked.totalMatches - matches.length} additional matches.`\n\t\t\t: \"\";\n\treturn {\n\t\tcontent: [\n\t\t\t{\n\t\t\t\ttype: \"text\",\n\t\t\t\ttext: `${noteText}Found ${ranked.totalMatches} outline match${ranked.totalMatches === 1 ? \"\" : \"es\"}; returned ${matches.length}.${moreText}${escalationText}\\n${lines.join(\"\\n\")}`,\n\t\t\t},\n\t\t],\n\t\tdetails,\n\t};\n}\n\n/** Reads cached outline; truncated refs trigger a scoped look. */\nasync function performExpandUi(\n\tparams: ExpandUiParams,\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<OutlineToolDetails>> {\n\tconst state = operationState();\n\tconst outline = currentOutlineOrThrow(params.stateId);\n\tconst ref = trimOrUndefined(params.ref);\n\tif (!ref) throw new Error(\"expand_ui.ref is required.\");\n\tconst initialTarget = nodeByRef(outline, ref);\n\tif (!initialTarget) throw new Error(`Outline ref '${ref}' is not available in the current outline.`);\n\tlet target: OutlineNode = initialTarget;\n\tconst depth = Math.max(1, Math.min(8, Math.trunc(toFiniteNumber(params.depth, 3))));\n\tconst regionKey = noteRegionKeyForRef(outline, ref);\n\tconst regionChanged = Boolean(\n\t\tregionKey && state.currentNote?.regions.some((region) => region.key === regionKey && region.status === \"changed\"),\n\t);\n\tif (target.truncated || regionChanged) {\n\t\tconst currentTarget = await ensureTargetWindowId(await resolveCurrentTarget(signal), signal);\n\t\tconst targetWireRef = wireRefForNode(target);\n\t\tif (!state.resourceKey || state.epoch === undefined)\n\t\t\tthrow new Error(\"The observation has no live resource identity. Observe again.\");\n\t\tconst scoped = (\n\t\t\tawait resourceScheduler.readAt(\n\t\t\t\tstate.resourceKey,\n\t\t\t\tstate.epoch,\n\t\t\t\tasync () =>\n\t\t\t\t\tawait performLook(\n\t\t\t\t\t\tcurrentTarget,\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\treadText: \"auto\",\n\t\t\t\t\t\t\tbaseLookId: outline.lookId,\n\t\t\t\t\t\t\tscopeRef: targetWireRef,\n\t\t\t\t\t\t\tmaxDimension: 1,\n\t\t\t\t\t\t\tincludeImage: false,\n\t\t\t\t\t\t},\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t),\n\t\t\t)\n\t\t).value;\n\t\ttarget = graftScopedOutline(outline, target.ref, scoped.parsedOutline!);\n\t\toutline.lookId = scoped.lookId;\n\t\tstate.currentOutline = outline;\n\t\tstate.currentLook = { ...scoped, image: state.currentLook?.image, outline: outline.root, parsedOutline: outline };\n\t\tpersistOperation(state);\n\t}\n\tconst folded = foldToBudget(outline, { maxDepth: depth, maxNodes: 150 }, [target.ref]);\n\tconst details: OutlineToolDetails = {\n\t\ttool: \"expand_ui\",\n\t\tstateId: state.currentCapture?.stateId,\n\t\tlookId: outline.lookId,\n\t\ttarget: serializeOutlineNodeShallow(target),\n\t\trenderedOutline: folded.text,\n\t\tnote: state.currentNote,\n\t};\n\treturn {\n\t\tcontent: [\n\t\t\t{\n\t\t\t\ttype: \"text\",\n\t\t\t\ttext: `${formatOutlineNodeLabel(target)}\\npath: ${outlineNodePath(target)}\\n\\n${folded.text}`,\n\t\t\t},\n\t\t],\n\t\tdetails,\n\t};\n}\n\n/** Pure cached-outline inspection. */\nasync function performInspectUi(params: InspectUiParams): Promise<AgentToolResult<OutlineToolDetails>> {\n\tconst state = operationState();\n\tconst outline = currentOutlineOrThrow(params.stateId);\n\tconst ref = trimOrUndefined(params.ref);\n\tif (!ref) throw new Error(\"inspect_ui.ref is required.\");\n\tconst target = nodeByRef(outline, ref);\n\tif (!target) throw new Error(`Outline ref '${ref}' is not available in the current outline.`);\n\tconst details: OutlineToolDetails = {\n\t\ttool: \"inspect_ui\",\n\t\tstateId: state.currentCapture?.stateId,\n\t\tlookId: outline.lookId,\n\t\ttarget: serializeOutlineNodeShallow(target),\n\t\tnote: state.currentNote,\n\t};\n\tconst fields = [\n\t\tformatOutlineNodeLabel(target),\n\t\t`path: ${outlineNodePath(target)}`,\n\t\t`rect: ${JSON.stringify(target.rect)}`,\n\t\t`actions: ${target.actions.join(\",\") || \"none\"}`,\n\t\t`capabilities: ${\n\t\t\t[\n\t\t\t\ttarget.canPress ? \"press\" : undefined,\n\t\t\t\ttarget.canFocus ? \"focus\" : undefined,\n\t\t\t\ttarget.canSetValue ? \"setValue\" : undefined,\n\t\t\t\ttarget.canScroll ? \"scroll\" : undefined,\n\t\t\t\ttarget.canIncrement ? \"increment\" : undefined,\n\t\t\t\ttarget.canDecrement ? \"decrement\" : undefined,\n\t\t\t\ttarget.isTextInput ? \"textInput\" : undefined,\n\t\t\t]\n\t\t\t\t.filter(Boolean)\n\t\t\t\t.join(\",\") || \"none\"\n\t\t}`,\n\t\t`annotations: ${\n\t\t\t[\n\t\t\t\ttarget.offscreen ? \"offscreen\" : undefined,\n\t\t\t\ttarget.pictureOnly ? \"pictureOnly\" : undefined,\n\t\t\t\ttarget.truncated ? \"truncated\" : undefined,\n\t\t\t\ttarget.scrollExtent ? `scrollable ${target.scrollExtent.seen}/${target.scrollExtent.total}` : undefined,\n\t\t\t]\n\t\t\t\t.filter(Boolean)\n\t\t\t\t.join(\",\") || \"none\"\n\t\t}`,\n\t];\n\treturn { content: [{ type: \"text\", text: fields.join(\"\\n\") }], details };\n}\n\nfunction prepareUiAction(action: UiAction, state: ActionState, look: LookResponse, headless: boolean): PreparedAction {\n\treturn prepareAction(action, state, {\n\t\theadless,\n\t\timage: look.image,\n\t\tnode: outlineNodeByRef,\n\t\tcenter: outlineNodeCenter,\n\t\tvalidatePoint: (x, y, label) => ensurePointIsInLookImage(x, y, look, label),\n\t});\n}\n\nasync function dispatchUiAction(\n\taction: UiAction,\n\ttarget: ResolvedTarget,\n\tlook: LookResponse,\n\theadless: boolean,\n\tstate: ActionState,\n\tsignal?: AbortSignal,\n): Promise<ExecutionTrace> {\n\tconst prepared = prepareUiAction(action, state, look, headless);\n\tif (prepared.action === \"wait\") {\n\t\tawait sleep(prepared.params.ms, signal);\n\t\treturn executionTrace(\"wait\", \"stealth\", { outcome: \"worked\" });\n\t}\n\tconst trace = await helperAct(target, prepared, headless, signal);\n\tif (!headless && (prepared.establishesFocus || (prepared.action === \"click\" && \"x\" in prepared.target))) {\n\t\tstate.currentFocus = true;\n\t}\n\treturn trace;\n}\n\nasync function dispatchUiTransaction(\n\tactions: UiAction[],\n\ttarget: ResolvedTarget,\n\tlook: LookResponse,\n\theadless: boolean,\n\tsignal?: AbortSignal,\n): Promise<ExecutionTrace> {\n\t// Strict-headless batches have one immutable delivery class. When foreground\n\t// fallback is permitted, decide independently per action so a completed\n\t// background prefix is never replayed as part of a foreground batch.\n\tif (headless && currentPlatformBackend.actBatch) {\n\t\tconst actionState: ActionState = { currentFocus: false };\n\t\tconst requests = actions.map((action) =>\n\t\t\thelperActRequest(target, prepareUiAction(action, actionState, look, true) as NativePreparedAction, \"ax_only\"),\n\t\t);\n\t\tconst textLength = actions.reduce((sum, action) => sum + (action.text?.length ?? 0), 0);\n\t\tconst result = await currentPlatformBackend.actBatch(requests, {\n\t\t\tsignal,\n\t\t\ttimeoutMs: Math.max(COMMAND_TIMEOUT_MS, textLength * 25 + 6_000),\n\t\t});\n\t\tif (!result.steps || result.steps.length === 0)\n\t\t\tthrow new Error(\"Native action transaction returned no checked steps.\");\n\t\tconst execution = aggregateExecutions(result.steps.map((step) => executionTraceFromAct(step, \"ax_only\")));\n\t\tconst batchTrace = executionTraceFromAct(result, \"ax_only\");\n\t\texecution.outcome = result.outcome;\n\t\texecution.performed = result.performed;\n\t\texecution.rootDelta = batchTrace.rootDelta;\n\t\texecution.stoppedAt = result.stoppedAt;\n\t\treturn execution;\n\t}\n\tconst steps: ExecutionTrace[] = [];\n\tconst actionState: ActionState = { currentFocus: false };\n\tfor (const action of actions) {\n\t\tconst step = await dispatchUiAction(action, target, look, headless, actionState, signal);\n\t\tsteps.push(step);\n\t\tif (step.outcome === \"didnt\") break;\n\t}\n\treturn aggregateExecutions(steps);\n}\n\nfunction aggregateExecutions(steps: ExecutionTrace[]): ExecutionTrace {\n\tconst outcomes = steps.map((step) => step.outcome);\n\tconst outcome: ActOutcome = outcomes.includes(\"didnt\")\n\t\t? \"didnt\"\n\t\t: outcomes.includes(\"unknown\")\n\t\t\t? \"unknown\"\n\t\t\t: \"worked\";\n\tconst fallback = steps.find((step) => step.escalatedToForeground);\n\treturn executionTrace(\"act\", steps.every((step) => step.variant === \"stealth\") ? \"stealth\" : \"default\", {\n\t\toutcome,\n\t\tsteps,\n\t\tactionCount: steps.length,\n\t\trootDelta: steps.flatMap((step) => step.rootDelta ?? []),\n\t\tbackgroundFirst: true,\n\t\tescalatedToForeground: Boolean(fallback),\n\t\tescalationReason: fallback?.escalationReason,\n\t\tbackgroundAttempt: fallback?.backgroundAttempt,\n\t});\n}\n\nfunction exactPlatformRootMatchesTarget(root: HelperWindow, target: ResolvedTarget): boolean {\n\tif (root.pid !== target.pid) return false;\n\tconst nativeRefMatches = Boolean(\n\t\ttarget.nativeWindowRef && (root.rootRef === target.nativeWindowRef || root.windowRef === target.nativeWindowRef),\n\t);\n\tconst windowIdMatches = target.windowId > 0 && root.windowId === target.windowId;\n\treturn nativeRefMatches || windowIdMatches;\n}\n\nfunction clearDesktopOperationState(state: OperationState): void {\n\tstate.currentTarget = undefined;\n\tstate.currentCapture = undefined;\n\tstate.currentStateTarget = undefined;\n\tstate.currentLook = undefined;\n\tstate.currentOutline = undefined;\n\tstate.currentNote = undefined;\n}\n\nasync function terminalDesktopActionResult(\n\ttarget: ResolvedTarget,\n\tbaseStateId: string,\n\texecution: ExecutionTrace,\n\terror: unknown,\n\tcondition?: ReturnType<typeof validateCondition>,\n): Promise<AgentToolResult<TerminalDesktopActionDetails>> {\n\tlet exactRootAvailable: boolean | undefined;\n\ttry {\n\t\tfor (let attempt = 0; attempt < 3; attempt += 1) {\n\t\t\tconst roots = await currentPlatformBackend.listRoots({ pid: target.pid });\n\t\t\texactRootAvailable = roots.some((root) => exactPlatformRootMatchesTarget(root, target));\n\t\t\tif (exactRootAvailable) break;\n\t\t\tif (attempt < 2) await sleep(75);\n\t\t}\n\t} catch {\n\t\t// A failed identity probe cannot prove that the root closed.\n\t}\n\tconst targetClosed = exactRootAvailable === false;\n\tif (\n\t\ttargetClosed &&\n\t\t!(execution.rootDelta ?? []).some(\n\t\t\t(delta) =>\n\t\t\t\tdelta.change === \"closed\" &&\n\t\t\t\tdelta.pid === target.pid &&\n\t\t\t\t(delta.ref === target.windowRef || delta.ref === target.nativeWindowRef),\n\t\t)\n\t) {\n\t\texecution.rootDelta = [\n\t\t\t...(execution.rootDelta ?? []),\n\t\t\t{\n\t\t\t\tchange: \"closed\",\n\t\t\t\tkind: \"window\",\n\t\t\t\tref: target.windowRef,\n\t\t\t\ttitle: target.windowTitle,\n\t\t\t\tpid: target.pid,\n\t\t\t\tmetadata: { source: \"post_action_identity_probe\" },\n\t\t\t},\n\t\t];\n\t}\n\tif (targetClosed && condition) {\n\t\tconst verificationStatus = condition.gone ? \"verified\" : \"failed\";\n\t\texecution.verification = {\n\t\t\tstatus: verificationStatus,\n\t\t\ttext: condition.text,\n\t\t\trole: condition.role,\n\t\t\tvalue: condition.value,\n\t\t\tgone: condition.gone || undefined,\n\t\t\ttimeoutMs: condition.timeoutMs,\n\t\t};\n\t\texecution.outcome = outcomeAfterCheck(execution.outcome ?? \"unknown\", verificationStatus);\n\t\tif (verificationStatus === \"failed\") {\n\t\t\texecution.error = {\n\t\t\t\tcode: \"postcondition_failed\",\n\t\t\t\tmessage: \"The source root closed before the requested presence or value postcondition could be verified.\",\n\t\t\t};\n\t\t}\n\t}\n\tconst status = targetClosed ? \"target_closed\" : \"post_action_observation_failed\";\n\tconst code = targetClosed ? \"target_closed\" : \"post_action_observation_failed\";\n\tconst message = error instanceof Error ? error.message : String(error);\n\tclearDesktopOperationState(operationState());\n\tconst details: TerminalDesktopActionDetails = {\n\t\ttool: \"act_ui\",\n\t\tstatus,\n\t\tbaseStateId,\n\t\ttarget: {\n\t\t\tapp: target.appName,\n\t\t\tbundleId: target.bundleId,\n\t\t\tpid: target.pid,\n\t\t\twindowTitle: target.windowTitle,\n\t\t\twindowId: target.windowId,\n\t\t\twindowRef: target.windowRef,\n\t\t\tnativeWindowRef: target.nativeWindowRef,\n\t\t},\n\t\texecution,\n\t\terror: { code, message },\n\t};\n\tconst result = targetClosed\n\t\t? `The action was delivered, and its source root ${target.appName} — ${target.windowTitle} closed before a successor observation could be captured.`\n\t\t: `The action was delivered, but its source root ${target.appName} — ${target.windowTitle} could not be observed afterward: ${message}`;\n\treturn {\n\t\tcontent: [\n\t\t\t{\n\t\t\t\ttype: \"text\",\n\t\t\t\ttext: `${result}\\nNo successor state was created. Call find_roots, then observe_ui to continue.`,\n\t\t\t},\n\t\t],\n\t\tdetails,\n\t};\n}\n\nasync function performDesktopTransaction(\n\tparams: ActParams,\n\tactions: UiAction[],\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<ComputerUseDetails | TerminalDesktopActionDetails>> {\n\tconst state = operationState();\n\tstate.currentImageMode = \"auto\";\n\tvalidateStateId(params.stateId);\n\tconst look = currentLookOrThrow();\n\tconst baseView = { stateId: state.currentCapture!.stateId, outline: state.currentOutline! };\n\tconst condition = params.expect ? validateCondition(params.expect) : undefined;\n\tconst scopeNode = condition ? conditionScopeNode(look.parsedOutline!, condition) : undefined;\n\tconst target = await ensureTargetWindowId(await resolveCurrentTarget(signal), signal);\n\tconst noteBefore = state.currentNote;\n\treturn await withWindowWriteLock(target, async () => {\n\t\tconst headless = getComputerUseConfig().headless;\n\t\tconst execution = await dispatchUiTransaction(actions, target, look, headless, signal);\n\t\tconst executedActions = actions.slice(0, execution.actionCount ?? actions.length);\n\t\ttry {\n\t\t\tif (condition) {\n\t\t\t\tconst {\n\t\t\t\t\ttext: expectedText,\n\t\t\t\t\trole: expectedRole,\n\t\t\t\t\tvalue: expectedValue,\n\t\t\t\t\tscopeExact,\n\t\t\t\t\tgone,\n\t\t\t\t\ttimeoutMs,\n\t\t\t\t} = condition;\n\t\t\t\tconst beforePresent = outlineConditionPresent(look.parsedOutline!, condition);\n\t\t\t\tconst desiredWasPreexisting = beforePresent !== gone;\n\t\t\t\tconst verification = await currentPlatformBackend.waitFor(\n\t\t\t\t\t{\n\t\t\t\t\t\t...nativeWindowRequest(target),\n\t\t\t\t\t\tlookId: look.parsedOutline!.lookId,\n\t\t\t\t\t\ttext: expectedText,\n\t\t\t\t\t\trole: platformRole(look.parsedOutline!, expectedRole),\n\t\t\t\t\t\tvalue: expectedValue,\n\t\t\t\t\t\tscopeRef: scopeNode ? wireRefForNode(scopeNode) : undefined,\n\t\t\t\t\t\tscopeExact,\n\t\t\t\t\t\tgone,\n\t\t\t\t\t\ttimeoutMs,\n\t\t\t\t\t},\n\t\t\t\t\t{ signal, timeoutMs: timeoutMs + 2_000 },\n\t\t\t\t);\n\t\t\t\texecution.verification = {\n\t\t\t\t\tstatus: verification.found ? (desiredWasPreexisting ? \"preexisting\" : \"verified\") : \"failed\",\n\t\t\t\t\ttext: expectedText,\n\t\t\t\t\trole: expectedRole,\n\t\t\t\t\tvalue: expectedValue,\n\t\t\t\t\tgone: gone || undefined,\n\t\t\t\t\ttimeoutMs,\n\t\t\t\t};\n\t\t\t\texecution.outcome = outcomeAfterCheck(execution.outcome ?? \"unknown\", execution.verification.status);\n\t\t\t\tif (!verification.found) {\n\t\t\t\t\texecution.error = {\n\t\t\t\t\t\tcode: \"postcondition_failed\",\n\t\t\t\t\t\tmessage: `The action was delivered but its postcondition was not satisfied within ${timeoutMs}ms.`,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tawait sleep(settleMsForExecution(execution), signal);\n\t\t\t}\n\t\t\tconst capture = await captureCurrentTarget(signal, \"auto\", AUTO_IMAGE_MAX_DIMENSION, target);\n\t\t\texecution.outcome = outcomeAfterObservedValues(\n\t\t\t\texecution.outcome ?? \"unknown\",\n\t\t\t\texecutedActions,\n\t\t\t\t(ref) => nodeByRef(capture.outline, ref)?.value,\n\t\t\t);\n\t\t\tfor (const action of executedActions) {\n\t\t\t\tstate.currentNote = noteAfterAct(state.currentNote ?? noteBefore, action.ref, capture.outline, {\n\t\t\t\t\twindow: noteWindowForTarget(capture.target, capture.look),\n\t\t\t\t\trootDelta: execution.rootDelta,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn await buildToolResult(\n\t\t\t\t\"act_ui\",\n\t\t\t\t`Executed ${executedActions.length} checked UI action${executedActions.length === 1 ? \"\" : \"s\"} in ${target.appName} — ${target.windowTitle}. Returned state ${capture.capture.stateId}.`,\n\t\t\t\tcapture,\n\t\t\t\texecution,\n\t\t\t\tsignal,\n\t\t\t\tstate.currentImageMode,\n\t\t\t\tbaseView,\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tif (signal?.aborted) {\n\t\t\t\tclearDesktopOperationState(state);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\treturn await terminalDesktopActionResult(target, baseView.stateId, execution, error, condition);\n\t\t}\n\t});\n}\n\nasync function performBrowserTransaction(\n\tparams: ActParams,\n\tactions: UiAction[],\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<BrowserObservationDetails>> {\n\tconst contextId = browserContextForOperation();\n\tif (!contextId) throw new Error(\"Browser transaction requires a browser observation state.\");\n\tconst baseSnapshot = operationState().browserSnapshot;\n\tif (!baseSnapshot) throw new Error(\"Browser transaction requires a complete base observation.\");\n\tconst baseView = { stateId: baseSnapshot.snapshotId, outline: baseSnapshot.outline };\n\tconst condition = params.expect ? validateCondition(params.expect) : undefined;\n\tif (condition) conditionScopeNode(restoreOutline(baseSnapshot.outline), condition);\n\tconst prepared = actions.map((action) => {\n\t\tif (!BROWSER_TRANSACTION_ACTIONS.has(action.action))\n\t\t\tthrow new Error(`Browser transactions do not support '${action.action}'.`);\n\t\tif (action.action === \"click\" && action.ref && action.button && action.button !== \"left\")\n\t\t\tthrow new Error(\n\t\t\t\t\"Browser ref clicks support only the left button; use coordinate clicks for right or middle buttons.\",\n\t\t\t);\n\t\tconst target = browserSnapshotTarget(params.stateId, trimOrUndefined(action.ref));\n\t\tif (\n\t\t\t(action.action === \"press\" ||\n\t\t\t\taction.action === \"setText\" ||\n\t\t\t\t(action.action === \"click\" && action.ref) ||\n\t\t\t\t(action.action === \"typeText\" && action.ref)) &&\n\t\t\t!Number.isFinite(target?.backendNodeId)\n\t\t) {\n\t\t\tthrow new Error(`Browser ${action.action} requires an actionable @e ref owned by ${params.stateId}.`);\n\t\t}\n\t\tif (action.ref && (!target || target.contextId !== contextId))\n\t\t\tthrow new Error(`Browser ${action.action} ref must be owned by ${params.stateId}.`);\n\t\treturn { action, target };\n\t});\n\treturn await withBrowserWrite(contextId, async () => {\n\t\tfor (const { action, target } of prepared) {\n\t\t\tlet worked = false;\n\t\t\tif (action.action === \"press\" || (action.action === \"click\" && action.ref)) {\n\t\t\t\tworked = true;\n\t\t\t\tfor (let count = 0; count < (action.clickCount ?? 1); count += 1)\n\t\t\t\t\tworked = (await cdpClickForContext(contextId, target!.backendNodeId!)) && worked;\n\t\t\t} else if (action.action === \"click\") {\n\t\t\t\tworked =\n\t\t\t\t\t(await cdpMouseForContext(\n\t\t\t\t\t\tcontextId,\n\t\t\t\t\t\taction.x!,\n\t\t\t\t\t\taction.y!,\n\t\t\t\t\t\t\"mousePressed\",\n\t\t\t\t\t\taction.button ?? \"left\",\n\t\t\t\t\t\taction.clickCount ?? 1,\n\t\t\t\t\t)) &&\n\t\t\t\t\t(await cdpMouseForContext(\n\t\t\t\t\t\tcontextId,\n\t\t\t\t\t\taction.x!,\n\t\t\t\t\t\taction.y!,\n\t\t\t\t\t\t\"mouseReleased\",\n\t\t\t\t\t\taction.button ?? \"left\",\n\t\t\t\t\t\taction.clickCount ?? 1,\n\t\t\t\t\t));\n\t\t\t} else if (action.action === \"setText\")\n\t\t\t\tworked = await cdpTypeForContext(contextId, target!.backendNodeId!, action.text ?? \"\", true);\n\t\t\telse if (action.action === \"typeText\")\n\t\t\t\tworked = target?.backendNodeId\n\t\t\t\t\t? await cdpTypeForContext(contextId, target.backendNodeId, action.text ?? \"\", false)\n\t\t\t\t\t: await cdpTypeFocusedForContext(contextId, action.text ?? \"\");\n\t\t\telse if (action.action === \"keypress\") worked = await cdpKeypressForContext(contextId, action.keys ?? []);\n\t\t\telse if (action.action === \"scroll\")\n\t\t\t\tworked = await cdpScrollForContext(\n\t\t\t\t\tcontextId,\n\t\t\t\t\ttoFiniteNumber(action.scrollX, 0),\n\t\t\t\t\ttoFiniteNumber(action.scrollY, 0),\n\t\t\t\t\ttarget?.backendNodeId,\n\t\t\t\t);\n\t\t\telse if (action.action === \"drag\")\n\t\t\t\tworked = await cdpDragForContext(contextId, normalizeActionPath(action.path));\n\t\t\telse if (action.action === \"moveMouse\")\n\t\t\t\tworked = await cdpMouseForContext(contextId, action.x!, action.y!, \"mouseMoved\");\n\t\t\tif (!worked)\n\t\t\t\tthrow new Error(\"The browser root became unavailable during the action transaction. Observe it again.\");\n\t\t}\n\t\tif (condition) {\n\t\t\tconst deadline = Date.now() + condition.timeoutMs;\n\t\t\tlet satisfied = false;\n\t\t\tdo {\n\t\t\t\tconst snapshot = await cdpSnapshotForContext(contextId);\n\t\t\t\tif (!snapshot) throw new Error(`Browser root '${contextId}' is no longer available. Observe it again.`);\n\t\t\t\tconst present = outlineConditionPresent(restoreOutline(snapshot.outline), condition);\n\t\t\t\tsatisfied = present !== condition.gone;\n\t\t\t\tif (!satisfied) await sleep(100, signal);\n\t\t\t} while (!satisfied && Date.now() < deadline);\n\t\t\tif (!satisfied)\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`The browser action was delivered but its postcondition was not satisfied within ${condition.timeoutMs}ms.`,\n\t\t\t\t);\n\t\t}\n\t\treturn await refreshBrowserSnapshot(contextId, \"act_ui\", baseView);\n\t});\n}\n\nfunction normalizeActionPath(path: UiAction[\"path\"]): Array<{ x: number; y: number }> {\n\treturn (path ?? []).map((point) =>\n\t\tArray.isArray(point)\n\t\t\t? { x: toFiniteNumber(point[0], 0), y: toFiniteNumber(point[1], 0) }\n\t\t\t: { x: toFiniteNumber(point.x, 0), y: toFiniteNumber(point.y, 0) },\n\t);\n}\n\nfunction validateActionTarget(action: UiAction): void {\n\tconst hasRef = Boolean(trimOrUndefined(action.ref));\n\tconst hasX = Number.isFinite(action.x);\n\tconst hasY = Number.isFinite(action.y);\n\tif (hasX !== hasY) throw new Error(`${action.action} coordinates require both x and y.`);\n\tconst hasPoint = hasX && hasY;\n\tif ((action.action === \"click\" || action.action === \"moveMouse\") && hasRef === hasPoint) {\n\t\tthrow new Error(`${action.action} requires exactly one target: ref or x/y coordinates.`);\n\t}\n\tif (action.action === \"press\" && !hasRef) throw new Error(\"press requires an actionable ref.\");\n\tif (action.action === \"scroll\" && toFiniteNumber(action.scrollX, 0) === 0 && toFiniteNumber(action.scrollY, 0) === 0)\n\t\tthrow new Error(\"scroll requires a non-zero scrollX or scrollY delta.\");\n\tif (\n\t\taction.clickCount !== undefined &&\n\t\t(!Number.isInteger(action.clickCount) || action.clickCount < 1 || action.clickCount > 3)\n\t)\n\t\tthrow new Error(\"clickCount must be an integer from 1 to 3.\");\n}\n\nasync function performAct(\n\tparams: ActParams,\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<ComputerUseDetails | TerminalDesktopActionDetails | BrowserObservationDetails>> {\n\tconst actions = Array.isArray(params.actions) ? params.actions : [];\n\tif (actions.length === 0) throw new Error(\"act_ui.actions must contain at least one action.\");\n\tif (actions.length > 20) throw new Error(\"act_ui supports at most 20 actions per transaction.\");\n\tfor (const action of actions) validateActionTarget(action);\n\tif (operationState().contextId) return await performBrowserTransaction(params, actions, signal);\n\treturn await performDesktopTransaction(params, actions, signal);\n}\n\nfunction managedBrowserExecutableCandidates(browser: \"helium\" | \"chrome\"): string[] {\n\tconst overrideName =\n\t\tbrowser === \"helium\" ? \"ADA_COMPUTER_USE_HELIUM_EXECUTABLE\" : \"ADA_COMPUTER_USE_CHROME_EXECUTABLE\";\n\tconst override = trimOrUndefined(process.env[overrideName]);\n\tif (override) return [path.resolve(override)];\n\n\tconst platformCandidates =\n\t\tprocess.platform === \"darwin\"\n\t\t\t? browser === \"helium\"\n\t\t\t\t? [\n\t\t\t\t\t\t\"/Applications/Helium.app/Contents/MacOS/Helium\",\n\t\t\t\t\t\tpath.join(os.homedir(), \"Applications\", \"Helium.app\", \"Contents\", \"MacOS\", \"Helium\"),\n\t\t\t\t\t]\n\t\t\t\t: [\n\t\t\t\t\t\t\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\",\n\t\t\t\t\t\tpath.join(os.homedir(), \"Applications\", \"Google Chrome.app\", \"Contents\", \"MacOS\", \"Google Chrome\"),\n\t\t\t\t\t]\n\t\t\t: process.platform === \"win32\"\n\t\t\t\t? browser === \"helium\"\n\t\t\t\t\t? [\n\t\t\t\t\t\t\tprocess.env.LOCALAPPDATA &&\n\t\t\t\t\t\t\t\tpath.join(process.env.LOCALAPPDATA, \"Helium\", \"Application\", \"helium.exe\"),\n\t\t\t\t\t\t\tprocess.env.PROGRAMFILES &&\n\t\t\t\t\t\t\t\tpath.join(process.env.PROGRAMFILES, \"Helium\", \"Application\", \"helium.exe\"),\n\t\t\t\t\t\t]\n\t\t\t\t\t: [\n\t\t\t\t\t\t\tprocess.env.LOCALAPPDATA &&\n\t\t\t\t\t\t\t\tpath.join(process.env.LOCALAPPDATA, \"Google\", \"Chrome\", \"Application\", \"chrome.exe\"),\n\t\t\t\t\t\t\tprocess.env.PROGRAMFILES &&\n\t\t\t\t\t\t\t\tpath.join(process.env.PROGRAMFILES, \"Google\", \"Chrome\", \"Application\", \"chrome.exe\"),\n\t\t\t\t\t\t\tprocess.env[\"PROGRAMFILES(X86)\"] &&\n\t\t\t\t\t\t\t\tpath.join(process.env[\"PROGRAMFILES(X86)\"], \"Google\", \"Chrome\", \"Application\", \"chrome.exe\"),\n\t\t\t\t\t\t]\n\t\t\t\t: browser === \"helium\"\n\t\t\t\t\t? [\n\t\t\t\t\t\t\t\"/usr/bin/helium\",\n\t\t\t\t\t\t\t\"/usr/bin/helium-browser\",\n\t\t\t\t\t\t\t\"/opt/helium/chrome\",\n\t\t\t\t\t\t\tpath.join(os.homedir(), \".local\", \"helium\", \"chrome\"),\n\t\t\t\t\t\t]\n\t\t\t\t\t: [\n\t\t\t\t\t\t\t\"/usr/bin/google-chrome\",\n\t\t\t\t\t\t\t\"/usr/bin/google-chrome-stable\",\n\t\t\t\t\t\t\t\"/usr/bin/chromium\",\n\t\t\t\t\t\t\t\"/usr/bin/chromium-browser\",\n\t\t\t\t\t\t\t\"/snap/bin/chromium\",\n\t\t\t\t\t\t];\n\tconst pathNames =\n\t\tbrowser === \"helium\"\n\t\t\t? process.platform === \"win32\"\n\t\t\t\t? [\"helium.exe\"]\n\t\t\t\t: [\"helium\", \"helium-browser\"]\n\t\t\t: process.platform === \"win32\"\n\t\t\t\t? [\"chrome.exe\"]\n\t\t\t\t: [\"google-chrome\", \"google-chrome-stable\", \"chromium\", \"chromium-browser\"];\n\tconst pathCandidates = (process.env.PATH ?? \"\")\n\t\t.split(path.delimiter)\n\t\t.filter(Boolean)\n\t\t.flatMap((directory) => pathNames.map((name) => path.join(directory, name)));\n\treturn [\n\t\t...new Set([\n\t\t\t...platformCandidates.filter((candidate): candidate is string => Boolean(candidate)),\n\t\t\t...pathCandidates,\n\t\t]),\n\t];\n}\n\nasync function managedBrowserExecutable(browser: \"helium\" | \"chrome\"): Promise<string> {\n\tconst candidates = managedBrowserExecutableCandidates(browser);\n\tfor (const candidate of candidates) {\n\t\ttry {\n\t\t\tawait access(candidate, fsConstants.X_OK);\n\t\t\treturn candidate;\n\t\t} catch {\n\t\t\t// Try the next platform-appropriate installation location.\n\t\t}\n\t}\n\tconst overrideName =\n\t\tbrowser === \"helium\" ? \"ADA_COMPUTER_USE_HELIUM_EXECUTABLE\" : \"ADA_COMPUTER_USE_CHROME_EXECUTABLE\";\n\tif (trimOrUndefined(process.env[overrideName])) {\n\t\tthrow new Error(\n\t\t\t`${browser} executable from ${overrideName} was not found or is not executable: ${candidates[0]}.`,\n\t\t);\n\t}\n\tthrow new Error(`${browser} executable was not found. Set ${overrideName} to its absolute path.`);\n}\n\nfunction freeTcpPort(): Promise<number> {\n\treturn new Promise((resolve, reject) => {\n\t\tconst server = net.createServer();\n\t\tserver.on(\"error\", reject);\n\t\tserver.listen(0, \"127.0.0.1\", () => {\n\t\t\tconst address = server.address();\n\t\t\tconst port = typeof address === \"object\" && address ? address.port : 0;\n\t\t\tserver.close(() => (port > 0 ? resolve(port) : reject(new Error(\"Could not allocate a local CDP port.\"))));\n\t\t});\n\t});\n}\n\nasync function waitForCdpPort(port: number, signal?: AbortSignal): Promise<void> {\n\tconst deadline = Date.now() + MANAGED_BROWSER_READY_TIMEOUT_MS;\n\twhile (Date.now() < deadline) {\n\t\tif (signal?.aborted) throw new Error(\"Browser launch was aborted.\");\n\t\ttry {\n\t\t\tconst response = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(500) });\n\t\t\tif (response.ok) return;\n\t\t} catch {\n\t\t\t// Browser is still starting.\n\t\t}\n\t\tawait sleep(200, signal);\n\t}\n\tthrow new Error(`Managed browser did not expose CDP on port ${port} within ${MANAGED_BROWSER_READY_TIMEOUT_MS}ms.`);\n}\n\n// Side effects: starts a Pi-managed browser process, replaces any previous managed browser,\n// and sets ADA_COMPUTER_USE_CDP_PORT for subsequent CDP context discovery.\nasync function performLaunchBrowser(\n\tparams: LaunchBrowserParams,\n\tsignal?: AbortSignal,\n): Promise<AgentToolResult<BrowserObservationDetails>> {\n\tconst browser = getComputerUseConfig().managed_browser;\n\tconst executable = await managedBrowserExecutable(browser);\n\tconst port = await freeTcpPort();\n\tconst requestedUrl = trimOrUndefined(params.url);\n\tif (requestedUrl && !/^https?:\\/\\//i.test(requestedUrl))\n\t\tthrow new Error(\"launch_browser.url must be an absolute HTTP(S) URL.\");\n\tconst url = requestedUrl ?? \"about:blank\";\n\tconst profileDir = path.join(os.tmpdir(), `pi-${browser}-cdp-${port}`);\n\tdisconnectCdp();\n\truntimeState.managedBrowser?.kill(\"SIGTERM\");\n\tconst args = [\n\t\t`--remote-debugging-port=${port}`,\n\t\t`--user-data-dir=${profileDir}`,\n\t\t\"--no-first-run\",\n\t\t\"--no-default-browser-check\",\n\t\turl,\n\t];\n\tif (runtimeState.previousCdpPort === undefined && runtimeState.managedBrowserCdpPort === undefined) {\n\t\truntimeState.previousCdpPort = process.env.ADA_COMPUTER_USE_CDP_PORT;\n\t}\n\tconst managedBrowser = spawn(executable, args, { stdio: \"ignore\", detached: false });\n\tmanagedBrowser.unref();\n\truntimeState.managedBrowser = managedBrowser;\n\truntimeState.managedBrowserCdpPort = String(port);\n\tprocess.env.ADA_COMPUTER_USE_CDP_PORT = String(port);\n\ttry {\n\t\tawait waitForCdpPort(port, signal);\n\t} catch (error) {\n\t\tif (runtimeState.managedBrowser === managedBrowser) {\n\t\t\truntimeState.managedBrowser = undefined;\n\t\t\tmanagedBrowser.kill(\"SIGTERM\");\n\t\t\tif (runtimeState.previousCdpPort === undefined) delete process.env.ADA_COMPUTER_USE_CDP_PORT;\n\t\t\telse process.env.ADA_COMPUTER_USE_CDP_PORT = runtimeState.previousCdpPort;\n\t\t\truntimeState.managedBrowserCdpPort = undefined;\n\t\t\truntimeState.previousCdpPort = undefined;\n\t\t}\n\t\tthrow error;\n\t}\n\tconst page = (await listCdpPageContexts())[0];\n\tif (!page) throw new Error(\"Managed browser launched without a CDP page context.\");\n\tconst resourceKey = `cdp:${page.targetId}`;\n\tconst scheduled = await resourceScheduler.read(resourceKey, async () => await cdpSnapshotForContext(page.contextId));\n\tif (!scheduled.value) throw new Error(\"Managed browser page could not be observed after launch.\");\n\treturn browserObservationResult(scheduled.value, resourceKey, scheduled.epoch, \"launch_browser\");\n}\n\nasync function performNavigateBrowser(\n\tparams: NavigateBrowserParams,\n): Promise<AgentToolResult<BrowserObservationDetails>> {\n\tconst contextId = browserContextForOperation();\n\tconst url = trimOrUndefined(params.url);\n\tif (!contextId)\n\t\tthrow new Error(\n\t\t\t\"navigate_browser.stateId must belong to a CDP browser-page observation. Native browser windows use act_ui.\",\n\t\t);\n\tif (!url || !/^https?:\\/\\//i.test(url)) throw new Error(\"navigate_browser.url must be an absolute HTTP(S) URL.\");\n\tconst baseSnapshot = operationState().browserSnapshot;\n\tif (!baseSnapshot) throw new Error(\"Browser navigation requires a complete base observation.\");\n\treturn await withBrowserWrite(contextId, async () => {\n\t\tconst ok = await cdpNavigateContext(contextId, url);\n\t\tif (!ok) throw new Error(`Browser context '${contextId}' is no longer available. Observe it again.`);\n\t\treturn await refreshBrowserSnapshot(contextId, \"navigate_browser\", {\n\t\t\tstateId: baseSnapshot.snapshotId,\n\t\t\toutline: baseSnapshot.outline,\n\t\t});\n\t});\n}\n\nasync function performEvaluateBrowser(params: EvaluateBrowserParams): Promise<AgentToolResult<EvaluateBrowserDetails>> {\n\tconst contextId = browserContextForOperation();\n\tconst expression = typeof params.expression === \"string\" ? params.expression : \"\";\n\tif (!contextId) throw new Error(\"evaluate_browser.stateId must belong to a browser observation.\");\n\tif (!expression.trim()) throw new Error(\"evaluate_browser.expression must be non-empty JavaScript.\");\n\tconst baseSnapshot = operationState().browserSnapshot;\n\tif (!baseSnapshot) throw new Error(\"Browser evaluation requires a complete base observation.\");\n\treturn await withBrowserWrite(contextId, async () => {\n\t\tconst result = await cdpEvaluateForContext(contextId, expression);\n\t\tif (!result) throw new Error(`Browser context '${contextId}' is no longer available. Observe it again.`);\n\t\tconst successor = await refreshBrowserSnapshot(contextId, \"evaluate_browser\", {\n\t\t\tstateId: baseSnapshot.snapshotId,\n\t\t\toutline: baseSnapshot.outline,\n\t\t});\n\t\tconst details: EvaluateBrowserDetails = {\n\t\t\ttool: \"evaluate_browser\",\n\t\t\tbaseStateId: baseSnapshot.snapshotId,\n\t\t\tstateId: successor.details.stateId,\n\t\t\tview: successor.details.view,\n\t\t\tchanges: successor.details.changes,\n\t\t\toutline: successor.details.outline,\n\t\t\trenderedOutline: successor.details.renderedOutline,\n\t\t};\n\t\treturn {\n\t\t\tcontent: [...successor.content, { type: \"text\", text: `Evaluation value: ${JSON.stringify(result.value)}` }],\n\t\t\tdetails,\n\t\t};\n\t});\n}\n\nasync function executeTool<P, T>(\n\tctx: ExtensionContext,\n\tparams: P,\n\tsignal: AbortSignal | undefined,\n\trun: () => Promise<T>,\n): Promise<T> {\n\tconst outputRef = trimOrUndefined((params as { ref?: string } | undefined)?.ref)?.startsWith(\"@o\") === true;\n\tconst requestedStateId = outputRef\n\t\t? undefined\n\t\t: trimOrUndefined((params as { stateId?: string } | undefined)?.stateId);\n\tconst stateRecord = requestedStateId ? savedStates.get(requestedStateId) : undefined;\n\tif (requestedStateId && !stateRecord) {\n\t\tthrow new Error(`State '${requestedStateId}' is unavailable or was evicted. Observe the root again.`);\n\t}\n\tconst operation = savedStates.hydrate(stateRecord);\n\treturn await savedStates.operations.run(operation, async () => {\n\t\tawait resourceScheduler.read(\"session-lifecycle\", async () => await ensureReady(ctx, signal));\n\t\tthrowIfAborted(signal);\n\t\tconst result = await run();\n\t\tpersistOperation(operation);\n\t\treturn result;\n\t});\n}\n\nfunction makeToolExecutor<P, D>(\n\ttool: string,\n\tperform: (params: P, signal?: AbortSignal) => Promise<AgentToolResult<D>>,\n) {\n\treturn async (\n\t\t_toolCallId: string,\n\t\tparams: P,\n\t\tsignal: AbortSignal | undefined,\n\t\t_onUpdate: AgentToolUpdateCallback<D> | undefined,\n\t\tctx: ExtensionContext,\n\t): Promise<AgentToolResult<D>> => {\n\t\ttry {\n\t\t\treturn applyOutputEnvelope(tool, await executeTool(ctx, params, signal, () => perform(params, signal)));\n\t\t} catch (error) {\n\t\t\tthrow boundToolError(tool, error);\n\t\t}\n\t};\n}\n\nexport const executeFind = makeToolExecutor(\"find_roots\", performListWindows);\nexport const executeReadText = makeToolExecutor(\"read_text\", performReadText);\nexport const executeWaitFor = makeToolExecutor(\"wait_for\", performWaitFor);\nexport const executeObserve = makeToolExecutor(\"observe_ui\", performObserve);\nexport const executeSearchUi = makeToolExecutor(\"search_ui\", performSearchUi);\nexport const executeExpandUi = makeToolExecutor(\"expand_ui\", performExpandUi);\nexport const executeInspectUi = makeToolExecutor(\"inspect_ui\", performInspectUi);\nexport const executeAct = makeToolExecutor<\n\tActParams,\n\tComputerUseDetails | TerminalDesktopActionDetails | BrowserObservationDetails\n>(\"act_ui\", performAct);\nexport const executeNavigateBrowser = makeToolExecutor(\"navigate_browser\", performNavigateBrowser);\nexport const executeEvaluateBrowser = makeToolExecutor(\"evaluate_browser\", performEvaluateBrowser);\nexport const executeLaunchBrowser = makeToolExecutor(\"launch_browser\", performLaunchBrowser);\n\nexport function reconstructStateFromBranch(ctx: ExtensionContext): void {\n\tsavedStates.clear();\n\tclearStoredOutputs();\n\truntimeState.windowRefs.clear();\n\truntimeState.windowRefByIdentity.clear();\n\truntimeState.nextRootRefIndex = 1;\n\n\tconst restoredResources = new Set<string>();\n\tfor (const entry of [...ctx.sessionManager.getBranch()].reverse()) {\n\t\tif ((entry as any)?.type !== \"message\") continue;\n\t\tconst message = (entry as any).message;\n\t\tif (!message || message.role !== \"toolResult\") continue;\n\t\tif (!AGENT_TOOL_NAMES.has(message.toolName)) continue;\n\n\t\tconst rawDetails = message.details as any;\n\t\tif (rawDetails?.tool === \"find_roots\" && Array.isArray(rawDetails.windows)) {\n\t\t\tfor (const window of rawDetails.windows) {\n\t\t\t\tif (typeof window?.windowRef !== \"string\" || !Number.isFinite(window?.pid)) continue;\n\t\t\t\tconst record: WindowRefRecord = {\n\t\t\t\t\tref: window.windowRef,\n\t\t\t\t\tappName: typeof window.app === \"string\" ? window.app : \"Unknown App\",\n\t\t\t\t\tbundleId: typeof window.bundleId === \"string\" ? window.bundleId : undefined,\n\t\t\t\t\tpid: Math.trunc(window.pid),\n\t\t\t\t\twindowTitle: typeof window.windowTitle === \"string\" ? window.windowTitle : \"(untitled)\",\n\t\t\t\t\twindowId: Number.isFinite(window.windowId) ? Math.trunc(window.windowId) : undefined,\n\t\t\t\t\tnativeWindowRef: typeof window.nativeWindowRef === \"string\" ? window.nativeWindowRef : undefined,\n\t\t\t\t\tframePoints: {\n\t\t\t\t\t\tx: toFiniteNumber(window.framePoints?.x, 0),\n\t\t\t\t\t\ty: toFiniteNumber(window.framePoints?.y, 0),\n\t\t\t\t\t\tw: Math.max(1, toFiniteNumber(window.framePoints?.w, 1)),\n\t\t\t\t\t\th: Math.max(1, toFiniteNumber(window.framePoints?.h, 1)),\n\t\t\t\t\t},\n\t\t\t\t\tscaleFactor: Math.max(1, toFiniteNumber(window.scaleFactor, 1)),\n\t\t\t\t\tisMinimized: toBoolean(window.isMinimized),\n\t\t\t\t\tisOnscreen: toBoolean(window.isOnscreen),\n\t\t\t\t\tisMain: toBoolean(window.isMain),\n\t\t\t\t\tisFocused: toBoolean(window.isFocused),\n\t\t\t\t};\n\t\t\t\truntimeState.windowRefs.set(record.ref, record);\n\t\t\t\truntimeState.windowRefByIdentity.set(windowRecordIdentity(record), record.ref);\n\t\t\t\tconst match = /^@r(\\d+)$/.exec(record.ref);\n\t\t\t\tif (match) runtimeState.nextRootRefIndex = Math.max(runtimeState.nextRootRefIndex, Number(match[1]) + 1);\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst details = rawDetails as Partial<ComputerUseDetails> | undefined;\n\t\tif (!details?.target || !details?.capture) continue;\n\n\t\tconst app = typeof details.target.app === \"string\" ? details.target.app : undefined;\n\n\t\tif (!app) continue;\n\t\tif (!Number.isFinite(details.target.pid) || !Number.isFinite(details.target.windowId)) continue;\n\t\tif (typeof details.capture.stateId !== \"string\") continue;\n\n\t\tconst target: CurrentTarget = {\n\t\t\tappName: app,\n\t\t\tbundleId: details.target.bundleId,\n\t\t\tpid: Math.trunc(details.target.pid),\n\t\t\twindowTitle: details.target.windowTitle ?? \"(untitled)\",\n\t\t\twindowId: Math.trunc(details.target.windowId),\n\t\t\twindowRef: typeof details.target.windowRef === \"string\" ? details.target.windowRef : undefined,\n\t\t\tnativeWindowRef:\n\t\t\t\ttypeof (details.target as any).nativeWindowRef === \"string\"\n\t\t\t\t\t? (details.target as any).nativeWindowRef\n\t\t\t\t\t: undefined,\n\t\t};\n\n\t\tconst resourceKey = desktopResourceKey(target);\n\t\tif (restoredResources.has(resourceKey)) continue;\n\t\tconst capture: CurrentCapture = {\n\t\t\tstateId: details.capture.stateId,\n\t\t\twidth: Math.max(1, Math.trunc(toFiniteNumber(details.capture.width, 1))),\n\t\t\theight: Math.max(1, Math.trunc(toFiniteNumber(details.capture.height, 1))),\n\t\t\tscaleFactor: Math.max(1, toFiniteNumber(details.capture.scaleFactor, 1)),\n\t\t\ttimestamp: Number.isFinite(details.capture.timestamp) ? details.capture.timestamp : Date.now(),\n\t\t};\n\t\tif (details.outline?.root && typeof details.outline.lookId === \"string\") {\n\t\t\tconst epoch = 0;\n\t\t\tresourceScheduler.restoreEpoch(resourceKey, epoch);\n\t\t\tsavedStates.set({\n\t\t\t\tstateId: capture.stateId,\n\t\t\t\tresourceKey,\n\t\t\t\tepoch,\n\t\t\t\tvalue: {\n\t\t\t\t\tkind: \"desktop\",\n\t\t\t\t\ttarget,\n\t\t\t\t\tcapture,\n\t\t\t\t\toutline: details.outline,\n\t\t\t\t\tlook: {\n\t\t\t\t\t\tlookId: details.outline.lookId,\n\t\t\t\t\t\tcapturedAt: details.capture.timestamp / 1000,\n\t\t\t\t\t\twindow: {\n\t\t\t\t\t\t\twindowId: Math.trunc(details.target.windowId),\n\t\t\t\t\t\t\tframePoints: { x: 0, y: 0, w: details.capture.width, h: details.capture.height },\n\t\t\t\t\t\t\tscaleFactor: details.capture.scaleFactor,\n\t\t\t\t\t\t\tisModal: false,\n\t\t\t\t\t\t\trole: \"\",\n\t\t\t\t\t\t\tsubrole: \"\",\n\t\t\t\t\t\t},\n\t\t\t\t\t\timage: { jpegBase64: \"\", width: details.capture.width, height: details.capture.height },\n\t\t\t\t\t\ttimings: {},\n\t\t\t\t\t},\n\t\t\t\t\tnote: details.note,\n\t\t\t\t},\n\t\t\t});\n\t\t\trestoredResources.add(resourceKey);\n\t\t}\n\t}\n}\n"]}