feat(desktop): MacosAxapiBackend — Node-side bridge client for real macOS AXAPI (Phase 0f')

[rrader26]

Summary

Stacks on PR #16 (macOS scaffold) + PR #17 (macOS capture/execute). Closes the four-PR cross-platform stack: once these merge, Claude Desktop / Cursor / Codex / any MCP client on macOS can drive real Mac software through the same `agentmark_desktop_*` MCP tools, with zero per-AI-tool integration.

Mirror of `WindowsUiaBackend` from the recently-merged PR #14. Same JSON-RPC protocol, same spawn/handshake/correlate-by-id pattern, same close lifecycle. The two backends share ~90% of their code; a future cleanup pass can extract a shared `SubprocessBridgeBackend` base.

What it does

`MacosAxapiBackend` implements the `DesktopCaptureBackend` interface:

• Lazily spawns `agentmark-bridge-macos` (Swift binary from PRs feat(bridge-macos): Phase 0e1' scaffold + stdio JSON-RPC (macOS sidecar foundation) #16/feat(bridge-macos): Phase 0e2' + 0e3' — list_windows, capture, execute (real AXAPI driving real macOS apps) #17) as a child process
• Speaks JSON-RPC 2.0 over stdio (one JSON message per line)
• Performs a ping handshake on first use; tears down + retries on failure
• Correlates concurrent calls by request id with per-call timeouts
• Forwards bridge stderr to a structured logger
• Closes cleanly: end stdin → wait 2s → SIGKILL if still alive
• Re-throws bridge error responses as typed JS errors

Wire-format mapping is identical to `WindowsUiaBackend` (bridges share the same JSON protocol by design).

Bridge resolution

Search order:

1. `options.bridgePath` (explicit)
2. `AGENTMARK_BRIDGE_PATH` env var
3. Walk up from `__dirname` probing common SPM output paths:
   • `apps/agent-runner/bridges/macos/.build/{release,debug}/`
   • Architecture-specific subpaths (`.build/arm64-apple-macosx/...`, `.build/x86_64-apple-macosx/...`)
4. Throws with the `swift build` command + env-var instruction

MCP dispatcher wiring

`agentmark_desktop_open` with `backend: "macos_axapi"` now actually spawns the bridge (instead of returning "not yet bundled"). The optional `bridge_path` arg lets callers override auto-detection. On non-macOS hosts it returns a clear error pointing to `fixture` for testing.

Tests

`test/desktop/macos-axapi-backend.test.ts` (9 tests) reuse the same `fake-bridge.cjs` fixture as the Windows tests — the wire protocol is byte-identical between bridges, so one fake substitutes for both:

• construct refuses on non-macOS without `allowNonMac`
• backend name is `'macos_axapi'`
• capture maps response to `DesktopCapture` shape
• capture forwards target fields to bridge
• execute `type` maps `newValue` → `new_value`
• same bridge process is reused across calls
• handshake failure surfaces with a clear error
• close rejects pending + future calls
• missing bridge path defers until first call

Plus the existing dispatcher test `agentmark_desktop_open with macos_axapi returns "not yet bundled"` updated to reflect the new behaviour (refuses on non-macOS with a clear "requires macOS" message; real spawn path tested separately).

`npm test`: 313 passed, 10 skipped, 0 failed.

After this + PR #16 + PR #17 merge

The full local-test path on macOS:

```jsonc
// %APPDATA%/Claude/claude_desktop_config.json (or Cursor / Codex equivalent)
{
"mcpServers": {
"agentmark": {
"command": "node",
"args": ["/Users/you/Dev/agentmark/dist/src/mcp/cli.js"]
}
}
}
```

Then ask the AI:

• "Open a desktop session with backend macos_axapi"
• "List my windows"
• "Capture TextEdit"
• "Type 'Hello from Claude' into the editor"

Real software, real AXAPI, real round-trip.

Code-sharing note

`WindowsUiaBackend` + `MacosAxapiBackend` share ~90% of their code (process spawn, JSON-RPC lifecycle, request correlation, close logic). A follow-up refactor can extract a `SubprocessBridgeBackend` base class. Keeping them parallel for now so this PR is reviewable in isolation and the diff is easy to read.

🤖 Generated with Claude Code