Adom Bridge (macOS)

@@ -1,276 +1,173 @@-# Adom Bridge+# Adom Bridge for macOS -**A small operating system for AI on your Windows PC.** Adom Bridge gives an AI real hands on your native desktop: your signed-in browser, KiCad, Fusion 360, the shell, files, window automation and screenshots. **Bridges** extend that reach to any app, and Adom Bridge provisions its own Node and Python to run them, so an add-on installs without touching your setup. It talks straight to your machine. It ships with **Adom Hydrogen** and installs standalone too, so if you drive your PC with Claude Desktop or another AI, this is what gives that AI hands.+**A small operating system for AI on your Mac.** Adom Bridge gives an AI real hands on your native desktop: your signed-in browser, KiCad, Fusion 360, the shell, files, windows, screenshots and the Accessibility tree. **Bridges** extend that reach to any app, and Adom Bridge provisions its own Node and Python to run them, so an add-on installs without touching your setup. It ships with **Adom Hydrogen** and installs standalone too, so if you drive your Mac with Claude Desktop, Claude Code, Codex or another local AI, this is what gives that AI hands. -![Adom Bridge main window](docs/main-view.png)+This page is the macOS line (Apple Silicon). The Windows line lives on its own page, [adom/adom-bridge](https://wiki.adom.inc/adom/adom-bridge); the two share one verb catalog, one relay protocol and one mesh, so a Mac and a Windows PC on the same account are peers. -- **Full desktop control:** windows, input, screenshots, UI Automation, the shell, files, the registry, WSL.+- **Full desktop control:** windows, keyboard and mouse input, screenshots, the Accessibility tree (background clicks that never steal focus), the shell, files, processes, notifications. - **Bridges:** first-class mini-apps. Puppeteer (browser), KiCad, Fusion 360, your real signed-in browser, Blender, or your own.-- **You are in control:** localhost-only, an install-consent trust model, a visible activity log, and an approval gate for the remote cloud-AI path.-- **Multi-machine:** one relay can hold many desktops. Address any of them by name, or fan a command out to all.-- **Self-updating and signed:** every release is Azure code-signed and auto-updates from this page.+- **You are in control:** loopback-only, an install-consent trust model, an activity log, and a human-only approval gate for anything that arrives from the cloud.+- **Multi-machine:** address any of your machines by name over the relay, or reach it directly over the **Adom Mesh**, end-to-end encrypted between your own boxes.+- **Signed and self-updating:** every release is Developer ID-signed, notarized, SHA-256-verified, and the app updates itself from this page.  ## How it works -![Architecture](docs/arch-flow.svg)--The cloud AI never touches your machine directly. It sends a verb to the **relay**; Adom Bridge, connected out to that relay from your desktop, executes it against Windows or forwards it to a bridge, and streams the result back. A co-resident sibling app (Adom Hydrogen) can skip the relay and POST straight to the **loopback HTTP API** at `127.0.0.1`.--```-Adom container (this package)            User's laptop-+--------------------------+             +--------------------------+-| adom-bridge CLI + skills|  <-relay->  | Adom Bridge GUI (Tauri) |-| (Claude drives verbs)    |             | KiCad, Fusion, Chrome    |-+--------------------------+             | shell, files, screens    |-                                         +--------------------------+-```--## Install (in an Adom container)+The cloud AI never touches your Mac directly. It sends a verb to the **relay**; Adom Bridge, connected out to that relay from your Mac, executes it or forwards it to a bridge, and streams the result back. A co-resident app (Adom Hydrogen, or a local AI's CLI) skips the relay and POSTs straight to the **loopback HTTP API** on `127.0.0.1`. Another of your own machines can reach this one over the **mesh** without going through the cloud relay at all.  ```-adom-wiki pkg install adom/adom-bridge+Adom container (this package)            Your Mac++--------------------------+             +--------------------------------++| adom-bridge CLI + skills |  <-relay->  | Adom Bridge.app (menu-bar agent)|+| (the AI drives verbs)    |             | KiCad, Fusion, Chrome, shell,   |++--------------------------+             | files, screens, notifications   |+                                         +--------------------------------++                                                   ^  mesh (QUIC, e2e encrypted)+                                                   v+                                         +--------------------------------++                                         | your other Macs / Windows PCs   |+                                         +--------------------------------+ ``` -That installs the **container-side** pieces: the `adom-bridge` CLI (SHA256-verified against this page's `version.json`) and the Claude skill bundle into `~/.claude/skills/`:+- **Two binaries.** The **app** is the automation surface on the Mac. The **CLI** (`adom-bridge`) is the caller: on the same Mac it uses the loopback API, from a container it routes the same verbs over the relay.+- **Bridges** are separate processes the app spawns and supervises. Each owns a verb prefix (`browser_*`, `kicad_*`, ...) and a small HTTP endpoint; the app relays verbs to it verbatim and reports its health.+- **Verbs return identical JSON** on every path (relay, loopback, CLI, mesh): the same `_hint`, `errorCode` and `status` fields, so a caller writes the code once. -| Skill | What Claude learns |-|---|---|-| `adom-bridge` | the main verb catalog: screenshots, files, shell, windows, notifications |-| `adom-bridge-pup` | real-Chrome (Puppeteer) automation: sessions, tabs, eval, recording |-| `adom-bridge-notify` | native Windows toasts: progress bars, sticky reminders, buttons that round-trip |-| `adom-bridge-bridge-sdk` | author your own bridge: `bridge.json`, health/describe/rich-hint contracts, lifecycle |-| `adom-bridge-bridge-ownership` | the boundary: what AD core owns versus what a bridge author owns |-| `adom-bridge-multi-ad` | address multiple Adom Bridges on one relay (`--target`, fan-out) |-| `adom-bridge-direct-api` | the loopback HTTP API for sibling apps |-| `adom-bridge-installer`, `adom-bridge-windows-host`, `adom-bridge-discovery` | install, host, and discovery details |--`adom-wiki pkg update` keeps it current. The **KiCad** and **Fusion 360** bridge skills install from their own cloud-owned bridge pages.--## Drive it from a local AI on the same PC+## Install on the Mac -You do not need the cloud. The Windows installer puts `adom-bridge-cli.exe` on PATH and links the Adom Bridge skills into `~/.claude/skills` and `~/.codex/skills` automatically, so Claude Desktop, Claude Code, or Codex on the same machine can drive your desktop immediately with no relay and no setup. Deep dive: [using Adom Bridge from a local AI](docs/local-ai.md).--## Sign in once, connect everywhere+Requirements: macOS on Apple Silicon. -Sign in to your Adom account inside the app (Connections panel) and your cloud containers appear in the connection list and connect automatically: no JSON, no copy-paste. An AI in a container registers itself with one command. Deep dive: [sign-in and cloud configuration](docs/auth-and-cloud-config.md).+**One line** (downloads the signed DMG from this page, verifies its SHA-256, installs to `/Applications`, launches): -## Many machines, many containers+```bash+curl -fsSL https://wiki.adom.inc/api/v1/pages/adom-bridge-macos/files/install.sh | sh+``` -One desktop can connect to many containers, many desktops can share one container, and both at once. Address any desktop by name with `--target`. Deep dive with a topology diagram: [connection topology](docs/topology.md).+Or download the DMG from the *Download for your machine* box and drag **Adom Bridge.app** to Applications. **Adom Hydrogen** users do neither: Hydrogen installs and manages Bridge automatically. -## Running under Adom Hydrogen+First run shows the sign-in window. After that Bridge is a **menu-bar agent**: no window, no Dock icon, launched at login by a LaunchAgent. Double-click the app (or use the menu-bar item) to summon the window for settings, approvals and sign-in; closing it or pressing Cmd-Q hides it again rather than stopping the agent. -When Adom Hydrogen is present it runs Adom Bridge embedded: hidden window, HD-owned permission prompts, and a distinct taskbar tile. If HD ever goes away, Adom Bridge comes back standalone so your machine stays reachable. Deep dive: [how AD interacts with Adom Hydrogen](docs/adom-hydrogen.md).+**macOS permissions.** Bridge is the single TCC identity for everything it drives. It asks for **Screen Recording** the first time a screenshot is requested, **Accessibility** the first time a background UI click is requested, and **Full Disk Access** only when a caller needs a protected folder. Nothing is requested at install. `desktop_permission_status` reports all three. -## The laptop GUI+**Uninstall:** quit from the menu bar, then `adom-bridge uninstall` from the bundled CLI (removes the LaunchAgent) and drag the app to the Trash. Your sign-in lives in the shared keychain item and survives a reinstall. -The **Windows GUI** installs separately: a signed NSIS installer served from this page (*Download for your machine* above; Adom Hydrogen installs it automatically). It installs to `%LOCALAPPDATA%\Adom Bridge\`, adds a tray icon, starts on login, and **auto-updates itself** from this page's `version.json` (prompt by default; every 4h and on launch).+## Install in a container (this package) -The main window (top) puts everything on one surface: **Connections** (each relay plus the other Adom Bridges on it as peers), the **Activity Log** (every command, badged by source and type, filterable), the **Bridges sidebar** (installed bridges as mini-app cards), the provisioned **Runtimes**, and the footer approval bar.+```bash+adom-wiki pkg install adom/adom-bridge-macos+``` -Deep dives: [presence, tray and icon states](docs/presence.md) and [the managed Node and Python runtimes](docs/runtimes.md).+This installs the **container-side** pieces: the Claude skill set that teaches an AI every desktop verb, and the Linux `adom-bridge` CLI when one is staged with the release. Not needed under Adom Hydrogen, which wires its container to Bridge itself. `adom-wiki pkg update` keeps it current. -## Downloads+| Skill | What the AI learns |+|---|---|+| `adom-bridge` | the main verb catalog: screenshots, files, shell, windows, notifications, the mesh |+| `adom-bridge-window-capture` | every capture verb on macOS, the response shape, the on-disk cache |+| `adom-bridge-notify` | native Notification Center alerts with buttons that round-trip |+| `adom-bridge-permissions` | the human approval gate and the macOS TCC permissions under it |+| `adom-bridge-multi-ad` | addressing many machines: `--target`, fan-out, `targets` |+| `adom-bridge-direct-api` | the loopback HTTP API for co-resident apps |+| `adom-bridge-local-ai` | driving the Mac from Claude Desktop / Claude Code / Codex on the same machine |+| `adom-bridge-bridge-sdk`, `adom-bridge-bridge-ownership`, `adom-bridge-bridges-guide` | author, own and operate a bridge |+| `adom-bridge-auth`, `adom-bridge-embedded`, `adom-bridge-presence`, `adom-bridge-runtimes`, `adom-bridge-cli-guide`, `adom-bridge-discovery` | sign-in, Hydrogen embedding, menu-bar states, managed runtimes, the CLI, discovery | -Everything a real user installs comes from this page.+The **KiCad** and **Fusion 360** bridge skills install from their own pages: [adom-bridge-kicad-bridge](https://wiki.adom.inc/adom/adom-bridge-kicad-bridge) and [adom-bridge-fusion-bridge-macos](https://wiki.adom.inc/adom/adom-bridge-fusion-bridge-macos). -| Artifact | Platform | What it is | How to get it |-|---|---|---|---|-| Signed installer (NSIS) | Windows x64 | The GUI desktop app. Azure Trusted Signing. Installs to `%LOCALAPPDATA%\Adom Bridge\` and auto-updates. | The *Download for your machine* box at the top of this page. This is the one promoted Windows download. |-| CLI + skills package | Linux (container) | The `adom-bridge` CLI and Claude skill set for a cloud container driving your desktop remotely. Not needed if you use Adom Hydrogen, which bundles Adom Bridge. SHA256-verified on install. | `adom-wiki pkg install adom/adom-bridge` |-| `version.json` | manifest | The auto-update manifest the GUI polls: per-platform installer URL, SHA256, and size. | Read automatically by the app; you never fetch it by hand. |+## Drive it from a local AI on the same Mac -The Windows GUI installer is the only promoted Windows download. There is intentionally no standalone Windows CLI download. macOS is planned; the manifest reserves a slot for it.+You do not need the cloud. The app bundles its CLI at `Adom Bridge.app/Contents/Resources/adom-bridge-cli` and, on every launch, copies its skills into `~/.claude/skills` and `~/.codex/skills`, so Claude Desktop, Claude Code or Codex on the same Mac can drive the desktop with no relay and no setup. Local callers talk to the loopback API and are trusted by transport: no approval prompts. -## Staying current: updates and the restart schedule+## Sign in once, connect everywhere -Adom Bridge polls the wiki manifest on launch and every 4 hours. Every release is Azure code-signed and its installer is SHA256-verified before it runs. What differs is urgency, and the manifest carries a `priority`:+Sign in to your Adom account in the app and your cloud containers connect automatically: no JSON, no copy-paste. The session is one keychain item **shared with Adom Hydrogen**, so signing in to either app signs in both, and it survives uninstall and reinstall. An AI in a container registers its relay with one verb (`server_add`). -| Tier | How it is presented | Overrides your mode? |-|---|---|---|-| **Normal** | Almost every release. A footer banner: Install now / Later. Silent in Auto, nothing in Off. | No. |-| **High** | A recommended fix. Auto-installs in the background (even in Prompt) with a heads-up toast, then restarts. | Overrides Prompt; still respects Off. |-| **Emergency** | A bug bad enough to pull from the whole fleet at once. A red, non-dismissible countdown to a forced restart; AD Authenticode-verifies the installer (must be signed by Adom Industries) before it runs. | Overrides everything, even Off, even embedded. |+## Under Adom Hydrogen -You set your preference once in **Settings, Updates**: Prompt (default), Auto, or Off. A normal release carries no priority; the emergency tier is a deliberate, per-incident action.+When Adom Hydrogen launches Bridge it runs **embedded**: hidden, with Hydrogen owning the sign-in, the updates and the permission dialog. Gated commands from the cloud show up as a card in Hydrogen's own approval dialog; your choice there (allow once, 1 hour, 24 hours, bypass, deny) applies to Bridge. If Hydrogen ever goes away, Bridge reverts to standalone so your Mac stays reachable. -**When a normal update actually installs.** Adom Bridge lives in the tray and can run for weeks without a restart, so a Prompt-mode update you never click would never install. The restart schedule closes that: once an update is downloaded AND you have been away from the keyboard for about 15 minutes AND AD is not mid-task, it installs and relaunches quietly. It is idle-based, not a fixed clock, so it never interrupts active work or an overnight job, and restarting Adom Bridge has no effect on your other apps (it reconnects in seconds). Turn it off in Settings, Updates, "Restart when idle to finish updates," and a Prompt-mode update simply waits for your click. Auto installs immediately; Off never auto-installs (except an Emergency release). Embedded in Adom Hydrogen, HD owns the restart timing.+## Staying current -## Screenshots+Bridge polls this page's `version.json` on launch and every 4 hours. A new release downloads as a DMG, is SHA-256-verified against the manifest, and is applied silently: mount, swap the app bundle, relaunch. Your preference is **Prompt** (default), **Auto** or **Off** in Settings; a release can also carry a `priority` that overrides Prompt for a recommended fix or forces an emergency update. Embedded under Hydrogen, Hydrogen owns the update timing. -Anything AD can see, it can screenshot, losslessly, with **no focus steal** (`PrintWindow` or full-screen DXGI, never a foreground grab). *Every image on this page was produced by these verbs.* `desktop_screenshot_window` returns a **`screenshots[]` array**: the window plus each owned popup or child dialog as its own image (so a confirm bubble hovering over an app comes back alongside the parent, never missed); `desktop_screenshot_screen` grabs the full virtual screen including borderless popups; `browser_screenshot` grabs the pup viewport. Every shot carries a **`coordMap`** so the AI clicks *what it sees* (`{space:"image", shotId, x, y}` to real screen px, no DPI math). It stays generic: AD returns the rich array, the AI decides. `ad_scroll` even lets the AI page AD's own window to capture content below the fold.+## Screenshots on macOS -## Recording+Anything on screen can be captured **without stealing focus**: `desktop_list_windows` enumerates windows (the `hwnd` field carries the CGWindowID, same arg name as the Windows line), `desktop_screenshot_window {hwnd | titleContains}` captures one window with its chrome, `desktop_screenshot_screen` captures the main display, `desktop_list_monitors` enumerates displays. Everything the window and input verbs speak is in **points**, one coordinate space, so a rect from `desktop_list_windows` can be passed straight to `desktop_click {x, y}`. Captures need the Screen Recording permission; until it is granted the response says `permission_required` instead of returning an empty list. -![Adom Bridge Recorder](docs/recorder.png)+Not on macOS: owned-popup arrays, per-monitor capture, the image-space `coordMap`, and native video recording (`recording_unsupported`). Recording a browser tab is the Puppeteer bridge's own feature. -AD records the desktop or a browser session to video. The recorder HUD (above) **requires a `reason`** shown to the user up front, so a recording never starts silently, with live Screen/Microphone toggles and a Start/Stop control. `desktop_recorder_open {reason}` and `desktop_recorder_close` for the desktop; `browser_record_start` and `browser_record_stop` for the pup browser. Built for smooth, high-frame-rate video, not a choppy screenshot loop.+## Background UI automation -Deep dive: [recording](docs/recording.md).+The `desktop_ui_*` family is backed by the macOS Accessibility API: `desktop_find_control {hwnd, name|contains}` returns a control's on-screen rect, `desktop_ui_click` presses it via AXPress and `desktop_ui_set` sets its value, all in the background. `desktop_mouse_click` posts a click to a specific process without raising it. Every response carries a measured `foreground` block saying whether anything was raised, never an assertion. Synthetic foreground input (`desktop_click`, `desktop_type`, `desktop_press_key`) uses CGEvent and rides the same approval grant as the shell.  ## Bridges -Each bridge is a small, independently-versioned process the app spawns, supervises, health-checks, and auto-updates from its own wiki page. Every install ships with the six below, and each shows up in the Bridges sidebar as a card: its billboard, a health LED, and language/source badges.--### Puppeteer (`browser_*`)--![Puppeteer bridge card](docs/bridge-card-puppeteer.png)--A dedicated Chrome-for-Testing (or Edge) that AD downloads and manages: open windows and tabs, drive pages, evaluate JS, screenshot, and record. No manual browser install.--### Native Browser (`nbrowser_*`)--![Native Browser bridge card](docs/bridge-card-native-browser.png)--Your *real*, signed-in Chrome or Edge profile, for the logins and forms a throwaway automation profile cannot do. The desktop bridge is bundled and works extension-free out of the box: it discovers your browser profiles, opens URLs in the right signed-in profile (OAuth consent flows), and inventories browser windows. Installing the companion browser extension unlocks full in-page drive: tabs, clicks, JS eval, and background screenshots.--### KiCad (`kicad_*`)--![KiCad bridge card](docs/bridge-card-kicad.png)--Schematic and PCB automation: DRC/ERC, gerber and STEP export, 3D board render, and netlist/footprint queries.--### Fusion 360 (`fusion_*`) plus APS (`aps_*`)--![Fusion 360 bridge card](docs/bridge-card-fusion360.png)--Parametric modeling scripts and exports, plus fast indexed cloud-file search through Autodesk Platform Services.--### Blender (`blender_*`)--![Blender bridge card](docs/bridge-card-blender.png)--Headless Python scripting and renders.--### Adom Hydrogen (`hydrogen_*`)--![Adom Hydrogen bridge card](docs/bridge-card-hd.png)--The local dev-environment app AD can embed into; AD relays HD's runtime state and drives its lifecycle.--Install a third-party bridge by pasting its manifest URL, or `bridge_install {"manifestUrl":"..."}`. Build one with the [Bridge SDK](https://wiki.adom.inc/adom/adom-bridge-bridges).--Deep dive: [bridges from the user's side](docs/bridges.md) (cards, LEDs, console, installing and updating).--## The taskbar icon tells you the mode+Each bridge is a small, independently versioned process the app spawns, supervises, health-checks and updates from its own wiki page. A bridge whose page declares macOS unsupported is never run; the bundled build is used instead. -AD's window carries a mode-specific app identity, so the taskbar button swaps its whole tile AND its name the moment the mode changes: no restart, no flicker.--| Icon | Mode | Taskbar name | Meaning |-|:---:|:---|:---|:---|-| <img src="docs/taskbar-standalone.png" alt="Standalone: muted Adom tile" width="88"> | **Standalone** | Adom Bridge | AD running on its own. The default for a normal install. |-| <img src="docs/taskbar-embedded.png" alt="Embedded: vivid Adom tile" width="88"> | **Embedded** | Adom Bridge HD Embedded | Adom Hydrogen launched AD and drives its lifecycle. |--Muted "Adom Bridge" = AD by itself; vivid "Adom Bridge HD Embedded" = HD has the helm. Each mode is a registered Windows app identity, and flipping the window between them makes the shell rebuild the button with the other identity's icon and name. Because the modes are distinct identities, a taskbar pin made in one mode shows the running window as a separate button while AD is in the other mode.--## Window identity (branding a window the AI drives)--The same Windows shell mechanism (the Application User Model ID, or AUMID) is exposed as generic verbs so a bridge can make a window it drives present as *its* app. The motivating case: a Chrome for Testing window that would otherwise read "Test" with Chrome's icon in the taskbar, Alt-Tab, and the right-click menu.--- `desktop_register_app_identity` teaches Windows what an app id means (name plus icon), HKCU only, no UAC; `shortcut:false` gives a per-session identity with no Start Menu spam.-- `desktop_set_window_identity` stamps that id onto a live window plus its title-bar and Alt-Tab icon and the jump-list header.-- `desktop_set_window_jumplist` attaches a custom right-click menu and brands its header row.-- `desktop_taskbar` paints a progress bar, an overlay badge, and the hover-preview tooltip (`thumbnailTooltip`, the one uncapped text surface) and clip on any window's button.--These verbs inspect any icon you pass and return an `iconCheck` that explains, in plain terms, why an icon renders as a generic white document (the 256px `.ico` size must be PNG-compressed; SVG does not load; a `.ico` uses a bare path while a `.exe` uses `path,index`), so the caller fixes the file instead of shipping a broken icon. The full guide ships as the `adom-bridge-window-identity` skill.--## Settings--![Settings](docs/settings.png)+| Bridge | Verbs | On a Mac |+|---|---|---|+| Puppeteer | `browser_*` | Your installed Chrome launched with a fresh isolated profile (Chrome for Testing downloaded only if there is none): windows, tabs, page drive, JS eval, screenshots, tab recording. |+| Native Browser | `nbrowser_*` | Your real, signed-in Chrome profile, for the logins a throwaway profile cannot do. The companion extension unlocks full in-page drive. |+| KiCad | `kicad_*` | Schematic and PCB automation: open designs, DRC/ERC, gerber and STEP export, window capture and keyboard/click automation. Updates from the Mac manifest on the KiCad bridge page. |+| Fusion 360 + APS | `fusion_*`, `aps_*` | Modeling scripts, imports and exports, BOM and API queries, cloud-file search. Its own page: adom-bridge-fusion-bridge-macos. |+| Blender | `blender_*` | Headless Python scripting and renders; auto-detects `/Applications/Blender.app`. |+| Adom Hydrogen | `hydrogen_*` | The dev-environment app Bridge embeds into; Bridge relays its status and screenshots. | -Auto-connect behavior, the update channel (**prompt** / auto / off) and *restart when idle to finish updates*, the shell-approval preference, Adom Hydrogen integration (including *exit when HD exits*), and runtime prewarming. While embedded in HD, HD-owned preferences show as *managed by Adom Hydrogen*.+Install a third-party bridge with `bridge_install {"manifestUrl": "..."}`. Bridge provisions a managed Node and Python for bridges that need them, with no admin prompt. Build your own with the [Bridge SDK](https://wiki.adom.inc/adom/adom-bridge-bridges).  ## Security and the approval gate -![Shell approval bar](docs/approve-bar.png)--**The trust boundary is install-consent plus the localhost bind.** Installing the app (and each bridge) is you granting permission for the AI to drive your machine; if you do not want that, uninstall. And the app plus every bridge binds `127.0.0.1` **only, never `0.0.0.0`**, so a caller must already be a program you installed on your own machine to reach it. No network attack surface by construction.+**The trust boundary is install-consent plus the loopback bind.** Installing Bridge (and each bridge) is you granting permission for the AI to drive your Mac; if you do not want that, uninstall. The app and every bridge bind `127.0.0.1` only, so a caller must already be a program you installed on your own machine to reach it. -On top of that, the **remote cloud-AI path is approval-gated.** Verbs that run code or change the machine (`shell_execute`, `run_script`, `launch_process`, `write_file`, `registry_*`, `process_kill`, and so on) require a human grant when they arrive over the *relay*: **+1hr / +24hr** (time-boxed), **Bypass** (indefinite), or **Revoke**. The grant is human-only; local callers (your CLI, HD, bridges) are trusted by transport and never prompt; read-only verbs are never gated.--Deep dive: [permissions](docs/permissions.md) (what each Approve choice means, and how to revoke).+On top of that, **the remote path is approval-gated.** Verbs that run code or change the machine (`shell_execute`, `run_script`, `launch_process`, `write_file`, `delete_file`, `process_kill`, synthetic input and Accessibility actions) require a human grant when they arrive over the relay or the mesh: **1 hour** or **24 hours** (time-boxed), **Bypass** (until revoked), or **Deny**. Every gated call must carry a `reason`, shown to you verbatim. The grant is **human-only**: the AI can surface the prompt (`request_shell_approval`) but can never grant it to itself. Read-only verbs are never gated. Under Hydrogen the prompt is Hydrogen's permission dialog; standalone it is the Bridge window and a notification.  ## Notifications -AD speaks to you through native Windows toasts via `notify_user`, under Adom Bridge's own identity (the Adom logo, and Action Center history like any first-class app). A cloud AI or a bridge, even one on a different machine addressed with `target`, fires them to reach you wherever you are. Every image below is the real toast, captured live from the exact call shown.--**Basic alert.** Awareness: a build finished, a file is ready. Auto-dismisses in about 7 seconds. Add `"durationLong":true` to hold it around 25 seconds; `"level":"error"` and up do that automatically, and `"emergency"` also flashes the taskbar.--![Basic alert toast](docs/toast-basic.png)+`notify_user` fires a native **Notification Center** notification under Adom Bridge's own identity, from a cloud AI, a bridge, or another of your machines. Buttons round-trip: `"wait": true` blocks until you click and returns your choice, or the AI drains clicks later with `notify_events`. `focus` makes a click reveal a window on your screen (Hydrogen, a browser waiting on a login). Progress bars and inline text fields from the Windows line do not exist in Notification Center; the verb ignores what the platform cannot render and the response says so.  ```bash-adom-bridge notify_user '{"title":"Export done","body":"gerbers.zip is ready in C:/exports."}'+adom-bridge notify_user '{"title":"Ship v2?","buttons":[{"label":"Ship it"},{"label":"Hold"}],"wait":true,"timeoutSec":120}' ``` -**Click-to-focus: send them where the notification points.** Most notifications are about something else on screen: a browser waiting on a login, a dialog, an app that needs a click. Pass `focus` and clicking the notification brings THAT window to the front, instead of opening Adom Bridge. Name the window by `hwnd` (exact, from `desktop_list_windows`), by `cacheKey`, or by `titleContains`.+## Many machines: the relay and the Adom Mesh -```bash-adom-bridge notify_user '{"title":"Sign-in needed","body":"Confirm in the browser and I will continue.","focus":{"titleContains":"Sign in - Google Chrome"}}'-```--The response says whether the target resolved, so the AI finds out at send time rather than you finding out by clicking a notification that does nothing. If the window is gone by the time you click, it falls back to opening Adom Bridge, so a click is never dead. The click also counts as an acknowledgement, so the AI learns you engaged even with no buttons on the toast.--**Sticky choice with buttons that round-trip.** Stays on screen until the user clicks (no auto-dismiss). Give it an `id` you choose, then read the click back.--![Sticky toast with buttons](docs/toast-buttons.png)+One relay can hold many Bridges. Address any of them by name, or fan out:  ```bash-adom-bridge notify_user '{"id":"deploy-42","title":"Ship v2 to production?","body":"The build is green and staged.","scenario":"reminder","buttons":[{"label":"Ship it"},{"label":"Hold"}]}'+adom-bridge targets                                   # every machine the relay or the mesh knows+adom-bridge --target kbergss-Air desktop_screenshot_screen+adom-bridge --target all bridge_list ``` -**Progress bar.** For a long job (a gerber export, a render). Re-fire with the SAME `id` as the job advances toward `1.0`. `body` is optional here.+Since 1.9.219 the Mac line also runs the **Adom Mesh**. Each box mints an ed25519 node key, publishes its public identity to your account's directory, and `--target` tries the mesh **first**: an end-to-end encrypted QUIC connection between your two boxes, carried through the Adom mesh relay when they are on different networks, direct on a LAN in `direct` mode. A mesh answer carries `route.via: "mesh"`. When a target is not on the cloud relay, the relay hands the call to a connected Bridge to carry over its mesh. Files move the same way: `desktop_mesh_pull_files` pulls SHA-256-verified over the mesh path. -![Progress bar toast](docs/toast-progress.png)+- Off by default. `desktop_mesh_set_mode {"mode":"relay"}` turns it on; `direct` adds a LAN socket.+- Trust is per box: after first start a new node is refused both ways until a human trusts it. `desktop_mesh_trust` lists, raises, revokes and denies by verb; it never approves.+- `desktop_mesh_status` and `desktop_mesh_peers` show identity, relay state, trust and the path each peer selected.+- Both machines have to be awake and connected: a sleeping Mac is not on the mesh.+- A Windows Bridge 2.1.40 or later on the same account is a full peer. -```bash-adom-bridge notify_user '{"id":"job-1","title":"Exporting gerbers","progress":{"title":"myboard.kicad_pcb","value":0.6,"status":"Plotting copper layers...","valueOverride":"6 / 10 layers"}}'-```--**Reply input.** The text field renders, but Windows does not return typed text over protocol activation, so it is display-only today. For a real choice, use buttons.--![Reply input toast](docs/toast-input.png)--```bash-adom-bridge notify_user '{"title":"Quick note","body":"Leave a note for the next run.","scenario":"reminder","inputs":[{"id":"reply","type":"text","placeholder":"Type a reply..."}],"buttons":[{"label":"Send"}]}'-```--**Shell-approval.** Fired by AD itself when a gated command needs a human: *Approve 1 hr / 24 hr / Bypass Permissions*, granted straight from the toast without opening the window.--![Shell approval toast](docs/approve-bar.png)--**How the AI tracks the response, or expires the notify.** A toast is fire-and-forget, but a clicked button is recorded durably, so the AI learns the outcome even on a headless box:--```bash-adom-bridge notify_response '{"id":"deploy-42"}'   # pending:true until clicked, then action:"Ship it"-adom-bridge notify_events '{"sinceSeq":0}'          # drain EVERY click since a cursor, no per-id polling-adom-bridge notify_dismiss '{"id":"deploy-42"}'     # retract a sticky toast once you have handled it-```--Or skip the polling entirely with `"wait":true`, which blocks until you act (or `timeoutSec` elapses) and hands the AI your answer directly.--Clicking the toast body brings the window named by `focus` to the front, or opens Adom Bridge when no `focus` was given. Button clicks deliberately do not steal focus: a toast exists to reach you without interrupting what you were doing.--The AI does not have to read any of this first. When a call leaves something on the table, such as no `focus`, or buttons on a toast that will vanish before you see it, the response says so and lists what the verb can do. That coaching stops once the AI gets it right. Full reference lives in the `adom-bridge-notify` skill.--Deep dive: [notifications](docs/notifications.md).+Deep dive: the `adom-bridge-mesh-macos` skill on this page.  ## Verbs -![Core vs bridge verbs](docs/core-vs-bridge.svg)--AD-core owns the generic verbs (`desktop_*`, `shell`, `ui_*`, files, `notify_user`, multi-AD). Each bridge owns its own prefix and ships its own verbs; the app relays them verbatim and stays generic. Invoke the same way on every transport, for identical JSON back:+Bridge core owns the generic verbs (`desktop_*`, shell, files, `notify_user`, multi-machine, mesh). Each bridge owns its prefix. Invoke the same way on every transport:  ```bash-adom-bridge screenshot_window '{"hwnd": 12345}'              # CLI (relay / direct API)-adom-bridge --target AzureVM list_windows                    # target a named machine+adom-bridge commands                                        # the live catalog, run this first+adom-bridge desktop_screenshot_window '{"titleContains":"KiCad"}'+adom-bridge shell_execute '{"command":"git status","reason":"Checking the working tree"}' curl -s -X POST 127.0.0.1:47200/command \-  -d '{"command":"notify_user","args":{"title":"Hi"}}'        # loopback direct API+  -d '{"app":"desktop","command":"notify_user","args":{"title":"Hi"}}'   # loopback API ``` -`adom-bridge help` and `GET /commands` are the live discovery surfaces for the full verb set.+The loopback port is `47200` (it may walk to `47209`; `~/.adom/direct-api-port` says which). `GET /commands` on it is the same catalog. -Deep dive on the CLI itself: [the CLI guide](docs/cli.md).+## What is on this page -## Versioning+| File | What it is |+|---|---|+| `Adom.Bridge_<version>_macos_aarch64.dmg` | The signed, notarized app, in the *Download for your machine* box |+| `install.sh` | The one-line installer above |+| `version.json` | The update manifest the app polls: DMG URL, SHA-256, arch |+| this package | The container-side skills and CLI | -This package version tracks the Adom Bridge release. The scaffold is small; the multi-MB binaries are fetched at install time with SHA256 verification (the manifest's `assets` map carries server-computed checksums per platform).+Source: `adom-inc/bridge-macos` on GitHub (the macOS line; the Windows line is `adom-inc/adom-bridge`).