feat(bridge-macos): Phase 0e2' + 0e3' — list_windows, capture, execute (real AXAPI driving real macOS apps)

[rrader26]

Summary

Brings the macOS bridge from "scaffolded" to "actually drives macOS
software." Includes list_windows, capture, and execute via the
Accessibility framework (AXAPI). Live-demo PASSED against real
TextEdit on Apple Silicon arm64 — bridge captured the editor
element, typed a message via AXUIElementSetAttributeValue,
re-captured to verify the text landed.

Stacks on PR #16 (the macOS scaffold). Same architecture as the
Windows PR #13 — by design, the Node-side MacosAxapiBackend (Phase
0f') will be a near-exact mirror of WindowsUiaBackend (PR #14).

Validation

End-to-end demo on a real Mac:

Step 2 -- list_windows: 22 windows across 13 apps
  found TextEdit window: axapi:21232:0 (Untitled 5)

Step 3 -- capture TextEdit...
  treeDepth=3  elementCount=47
  editor element_id: First Text View

Step 4 -- execute type...
  ok: True
  newValue: Hello from AgentMark Desktop -- macOS bridge phase 0e3'

Step 5 -- re-capture and verify...
  editor value after type: "Hello from AgentMark Desktop -- macOS bridge phase 0e3'"

LIVE DEMO PASSED -- AgentMark Desktop drove real TextEdit end-to-end on macOS.

A separate list_windows-only test enumerated 22 real windows across
13 apps (Finder x3, Cursor x3, Chrome x5, VS Code, Claude Desktop,
Teams, Messages, Outlook, Parallels, Terminal, etc.) with focused
window correctly marked.

What's in this PR

Sources/AgentMarkBridgeMacos/Axapi.swift

• AccessibilityPermission.isGranted — probes AXIsProcessTrusted()
• AxElement — defensive wrapper around AXUIElement. Every
  attribute read returns nil on AXAPI errors so a single stale
  element doesn't abort the capture.
• RoleMapper — AXAPI roles → normalised DesktopRole vocab.
  Handles subroles for password fields, search fields, dialogs.
  Unknown → "other".

Sources/AgentMarkBridgeMacos/AxapiCapturer.swift

• listWindows() — walks NSWorkspace.runningApplications, filters
  to .regular policy, creates per-app AX refs, enumerates
  kAXWindowsAttribute. hasFocus marked by cross-referencing
  NSWorkspace.frontmostApplication.
• capture(req) — resolves target by windowId /
  processId / processName (substring, .app-tolerant) /
  windowTitle, or falls back to focused window. Walks tree
  depth-first with depth + element-count + deadline caps. Stashes
  every walked AX element in a per-session lookup map so execute
  can find it later.
• execute(req) — routes 8 action types through the right AXAPI
  pattern (AXPress / AXSetValue / AXScrollToVisible /
  AXShowMenu / etc.) with sensible fallbacks (keyboard simulation
  via CGEvent.keyboardSetUnicodeString for text typing when
  AXValue isn't writable; modifier-aware CGEvent for key
  actions).
• requirePermission() surfaces a clear accessibilityNotGranted
  JSON-RPC error (code -32020) pointing the user at System Settings.

Sources/AgentMarkBridgeMacos/Dispatcher.swift

Routes list_windows / capture / execute to AxapiCapturer
(lazy init). Adds accessibilityGranted to capabilities response
so clients can detect permission state without waiting for first
capture.

scripts/textedit-demo.py

Python end-to-end demo. Same shape as the Windows
notepad-demo.ps1: opens TextEdit, drives capture → execute →
re-capture, asserts the typed text in element.value.

Protocol compatibility with the Windows bridge

Same JSON shape on the wire. Same error code numbering. The
Node-side MacosAxapiBackend (Phase 0f', future PR) shares 90% of
its code with WindowsUiaBackend (PR #14) — only difference is
which binary it spawns and where it looks for it.

Accessibility permission gotcha

macOS guards AXAPI behind System Settings → Privacy & Security →
Accessibility. The parent process that launches the bridge must
be granted:

• For Claude Desktop integration: grant Claude Desktop
• For dev / Cursor integration: grant the terminal or Cursor

Without permission the bridge returns
{ "error": { "code": -32020, "message": "Accessibility permission not granted..." } }
on the first list_windows / capture / execute call.

Stack order

1. Merge PR feat(bridge-macos): Phase 0e1' scaffold + stdio JSON-RPC (macOS sidecar foundation) #16 first (macOS bridge scaffold)
2. Rebase this PR on the new main, then merge
3. Phase 0f': Node-side MacosAxapiBackend (mirror of
   WindowsUiaBackend from PR feat(desktop): WindowsUiaBackend — Node-side bridge client (Phase 0f) #14)
4. Live macOS demo via Claude Desktop driving real macOS apps —
   no PowerShell scripts, just "Capture TextEdit and type into it."

🤖 Generated with Claude Code