Adom Bridge

@@ -31,7 +31,7 @@ List every installed bridge (kicad, puppeteer, fusion360, plus any third-party b  **Returns:** {success:true, bridges:[{name, displayName, version, description, source, paused, spawn:{kind, manifestPort, runtimePort, entrypoint}, verbPrefixes, verbCount, ...}], summary:{total, bundled, cache, third_party, paused}, _hint} -**Note:** v1.8.0 made the bridge list dynamic. Bridges are discovered by scanning %LOCALAPPDATA%\Adom Desktop\bridges-cache\<name>\bridge.json (writable; wiki-streamed + third-party installs) and the bundled installer location (read-only fallback). Cache shadows bundled when both exist. Third-party bridges are installed via bridge_install. v1.8.31+: bridge ports are dynamic, no more 8772/8773/8851 hardcoded — eliminates collision with HD.+**Note:** v1.8.0 made the bridge list dynamic. Bridges are discovered by scanning %LOCALAPPDATA%\Adom Desktop\bridges-cache\<name>\bridge.json (writable; wiki-streamed + third-party installs) and the bundled installer location (read-only fallback). Cache shadows bundled when both exist. Third-party bridges are installed via bridge_install. v1.8.31+: bridge ports are dynamic, no more 8772/8773/8851 hardcoded — eliminates collision with Hydrogen.  **Ports:** v1.8.31+: bridges use DYNAMIC ports. `manifestPort` is what the bridge.json declares (0 = 'let adom-desktop pick'). `runtimePort` is what the bridge is ACTUALLY bound to right now (null if not yet spawned). CALLERS NEVER NEED EITHER. Always route bridge verbs via adom-desktop's CLI/direct-API by bridge id (`kicad_*`, `fusion_*`, etc.) — adom-desktop forwards to whatever port the bridge is on. Bridge ports are pure internal plumbing; if you find yourself reading them, you're probably doing something wrong. @@ -99,21 +99,21 @@ Show a large always-on-top, click-through text overlay on the user's DESKTOP (no  ### `desktop_connect_all` -v1.8.42+: programmatically trigger 'Connect All' for every enabled server entry. Mirrors the tray-menu button and HD's tray-menu 'Connect All' item. Spawns ws_loop for any entry that isn't already connected.+v1.8.42+: programmatically trigger 'Connect All' for every enabled server entry. Mirrors the tray-menu button and Hydrogen's tray-menu 'Connect All' item. Spawns ws_loop for any entry that isn't already connected.  **Returns:** {ok, success, totalEnabled, spawned, alreadyConnected, _hint}   ### `desktop_disconnect_all` -v1.8.42+: programmatically drop every live WS connection. Server entries stay in config (use server_remove to delete). Mirrors HD's tray 'Disconnect All'.+v1.8.42+: programmatically drop every live WS connection. Server entries stay in config (use server_remove to delete). Mirrors Hydrogen's tray 'Disconnect All'.  **Returns:** {ok, success, disconnected, _hint}   ### `desktop_embedded_enter` -v1.8.73+: explicit runtime adopt — HD calls this to switch a running standalone AD into embedded mode immediately (no 60s wait for the embedded_monitor tick). Always sets `entered_via=runtime-adopt`, meaning: when HD subsequently dies, AD will REVERT to standalone (not exit). If HD wants AD to exit on HD-death (the no-hanging-chad rule), HD must spawn AD with `--embedded` instead — that sets `entered_via=launch-flag`. Idempotent: returns `was_embedded:true` if AD was already embedded; no-ops in that case.+v1.8.73+: explicit runtime adopt — Hydrogen calls this to switch a running standalone AD into embedded mode immediately (no 60s wait for the embedded_monitor tick). Always sets `entered_via=runtime-adopt`, meaning: when Hydrogen subsequently dies, AD will REVERT to standalone (not exit). If Hydrogen wants AD to exit on HD-death (the no-hanging-chad rule), Hydrogen must spawn AD with `--embedded` instead — that sets `entered_via=launch-flag`. Idempotent: returns `was_embedded:true` if AD was already embedded; no-ops in that case.  **Returns:** {ok:true, success:true, was_embedded:bool, embedded:true, entered_via:'runtime-adopt', owner:'adom-hydrogen', _hint} @@ -122,16 +122,16 @@ v1.8.73+: explicit runtime adopt — HD calls this to switch a running standalon  ### `desktop_embedded_release` -v1.8.73+: explicit transition out of embedded mode. v1.8.77+ ALWAYS reverts to standalone, regardless of `entered_via`. AD's process REMAINS RUNNING after this call — tray restored, footer pill hidden, updater poller resumed, marker deleted. The two operations are now explicitly separate: this verb says 'stop being embedded, become standalone'; use `desktop_shutdown` to exit AD. Pre-v1.8.77 a launch-flag AD would exit on release, which fought HD's spawn supervisor (HD calls release → AD exits → supervisor respawns → looks like AD didn't exit). v1.8.77 decoupling fixes that.+v1.8.73+: explicit transition out of embedded mode. v1.8.77+ ALWAYS reverts to standalone, regardless of `entered_via`. AD's process REMAINS RUNNING after this call — tray restored, footer pill hidden, updater poller resumed, marker deleted. The two operations are now explicitly separate: this verb says 'stop being embedded, become standalone'; use `desktop_shutdown` to exit AD. Pre-v1.8.77 a launch-flag AD would exit on release, which fought Hydrogen's spawn supervisor (Hydrogen calls release → AD exits → supervisor respawns → looks like AD didn't exit). v1.8.77 decoupling fixes that. -**Returns:** {ok:true, success:true, was_embedded:bool, entered_via_before:'launch-flag'|'runtime-adopt'|null, will_exit:false, _hint}. `will_exit` is always false in v1.8.77+ — kept for back-compat with HD code that checked it pre-v1.8.77.+**Returns:** {ok:true, success:true, was_embedded:bool, entered_via_before:'launch-flag'|'runtime-adopt'|null, will_exit:false, _hint}. `will_exit` is always false in v1.8.77+ — kept for back-compat with Hydrogen code that checked it pre-v1.8.77. -**See also:** desktop_embedded_enter (adopt), desktop_shutdown (explicit AD exit). The 60s embedded_monitor's HD-process-death branch is unchanged: ungraceful HD death still uses entered_via to decide exit-vs-revert (LaunchFlag→exit, RuntimeAdopt→revert).+**See also:** desktop_embedded_enter (adopt), desktop_shutdown (explicit AD exit). The 60s embedded_monitor's HD-process-death branch is unchanged: ungraceful Hydrogen death still uses entered_via to decide exit-vs-revert (LaunchFlag→exit, RuntimeAdopt→revert).   ### `desktop_embedded_status` -v1.8.42+: introspect whether AD is currently running in embedded mode (HD bundling AD). v1.8.73+ also reports `enteredVia` — `launch-flag` means HD spawned AD as its child (AD exits when HD dies, no orphan); `runtime-adopt` means AD was running standalone and HD adopted it at runtime via `/embedded/enter` (AD reverts to standalone when HD dies, keeps running). Standalone AD returns embedded=false.+v1.8.42+: introspect whether AD is currently running in embedded mode (Hydrogen bundling AD). v1.8.73+ also reports `enteredVia` — `launch-flag` means Hydrogen spawned AD as its child (AD exits when Hydrogen dies, no orphan); `runtime-adopt` means AD was running standalone and Hydrogen adopted it at runtime via `/embedded/enter` (AD reverts to standalone when Hydrogen dies, keeps running). Standalone AD returns embedded=false.  **Returns:** {ok, success, embedded:bool, owner:string|null, source:string|null, enteredVia:'launch-flag'|'runtime-adopt'|null, pendingRelayUrl, pendingRelayName, startHidden:bool, markerPath, markerExists:bool, _hint} @@ -184,7 +184,7 @@ List all visible windows with HWNDs, titles, positions  ### `desktop_logout` -v1.8.42+: clear AD's cached Adom Cloud session (~/.adom/session.json). HD calls this on its own sign-out so AD doesn't display a stale email in its footer. Equivalent to the GUI's Sign-out link.+v1.8.42+: clear AD's cached Adom Cloud session (~/.adom/session.json). Hydrogen calls this on its own sign-out so AD doesn't display a stale email in its footer. Equivalent to the GUI's Sign-out link.  **Returns:** {ok, success, _hint}. After logout, adom_whoami returns null until the user signs in again (via the GUI footer link or another handoff). @@ -281,7 +281,7 @@ v1.8.137+: stage an in-window UI element so it can be captured via desktop_scree  ### `desktop_shutdown` -v1.8.42+: graceful AD exit — stop bridges (kicad, fusion, puppeteer) then exit. HD's tray 'Quit' uses this to take AD down with HD. Standalone callers can use it for clean reset between dev iterations.+v1.8.42+: graceful AD exit — stop bridges (kicad, fusion, puppeteer) then exit. Hydrogen's tray 'Quit' uses this to take AD down with Hydrogen. Standalone callers can use it for clean reset between dev iterations.  **Returns:** {ok, success, output, _hint}. The exit happens ~500ms after the response is sent so the caller doesn't see connection-reset. @@ -311,14 +311,14 @@ v1.8.42+: hide AD's main window. App keeps running in the background; use deskto  ### `desktop_window_show` -v1.8.42+: show + focus AD's main window. Used by Adom Hydrogen's tray menu when bundling AD in embedded mode (HD's tray entry 'Open Adom Desktop' fires this). Also reachable standalone — any caller can bring AD to the foreground.+v1.8.42+: show + focus AD's main window. Used by Adom Hydrogen's tray menu when bundling AD in embedded mode (Hydrogen's tray entry 'Open Adom Desktop' fires this). Also reachable standalone — any caller can bring AD to the foreground.  **Returns:** {ok, success, _hint}   ### `direct_api` -INFORMATIONAL — not a CLI verb. v1.8.25+ adds a local HTTP listener on `http://127.0.0.1:47200` inside the adom-desktop GUI. Sibling apps on the same machine (Adom Hydrogen, future Adom-family apps) can POST commands straight in without spawning the CLI or going through the WS relay. Loopback-only bind. The port (47200) lives in the IANA dynamic/private range (49152-65535-adjacent), squarely outside HD's 47083-47185 fallback range — clearly an Adom-family port, but no collision potential. Same `{app, command, args}` envelope as the WS protocol; same response payload (including `_hint` fields) as the CLI returns. Endpoints: `GET /health` (cheap probe), `GET /status` (capability inventory + `cliRequired` list), `POST /command` (verb dispatch). The dispatcher is `commands::handle_command` — exactly the same code the WS path uses.+INFORMATIONAL — not a CLI verb. v1.8.25+ adds a local HTTP listener on `http://127.0.0.1:47200` inside the adom-desktop GUI. Sibling apps on the same machine (Adom Hydrogen, future Adom-family apps) can POST commands straight in without spawning the CLI or going through the WS relay. Loopback-only bind. The port (47200) lives in the IANA dynamic/private range (49152-65535-adjacent), squarely outside Hydrogen's 47083-47185 fallback range — clearly an Adom-family port, but no collision potential. Same `{app, command, args}` envelope as the WS protocol; same response payload (including `_hint` fields) as the CLI returns. Endpoints: `GET /health` (cheap probe), `GET /status` (capability inventory + `cliRequired` list), `POST /command` (verb dispatch). The dispatcher is `commands::handle_command` — exactly the same code the WS path uses.  **Note:** If you (Docker Claude) are talking to a user authoring a sibling Tauri app and they ask 'how do I call adom-desktop without invoking the CLI', point them at this endpoint + the `direct-api-SKILL.md` asset on the wiki. For your own use (cross-machine Docker → Windows), keep using the CLI — the direct API is loopback-only by design and won't be reachable. Streaming verbs (pull_file, send_files, shell_execute) still require the CLI even for sibling apps; the direct API refuses them with `errorCode:"cli_required"`. @@ -368,7 +368,7 @@ v1.8.37+: register THIS cloud Docker container in the user's Adom Cloud profile  **User flow:** Cloud Docker: adom-desktop register_container '{"name":"my-container","url":"wss://..."}'  →  user installs Adom Desktop on Windows from https://wiki.adom.inc/adom/adom-desktop  →  user clicks 'Sign in' in AD's footer + completes the browser flow  →  AD's boot-time cloud-config pull (Phase 2) reads desktop.container.* from the user's carbon-prefs + merges into the GUI's server list. Without register_container the user has to paste-JSON manually; with it the container appears automatically. -**See also:** Designed to work with Phase 1 (auth in AD), Phase 2 (cloud-config sync in AD), and Phase 4 (HD→AD session handoff if AD is bundled with Adom Hydrogen). The full bundle landed across v1.8.33 - v1.8.37.+**See also:** Designed to work with Phase 1 (auth in AD), Phase 2 (cloud-config sync in AD), and Phase 4 (Hydrogen→AD session handoff if AD is bundled with Adom Hydrogen). The full bundle landed across v1.8.33 - v1.8.37.   ### `relaunch_self`@@ -429,7 +429,7 @@ Disconnect (if connected) and delete a relay server entry by name. Inverse of se  ### `shell_auto_approve` -Programmatically enable/revoke shell_execute auto-approve. v1.8.3+. v1.8.116+: `permanent` is the DURABLE user preference — it writes AD's Settings checkbox ('Auto-approve shell commands permanently', config-backed, default OFF), so it survives restarts by design. Timed grants (duration_secs) are session-scoped. In embedded mode HD owns this preference: pass `--shell-approval <prompt|1h|24h|permanent>` when spawning AD, and/or drive this verb at runtime; AD's own checkbox goes read-only ('Managed by Adom Hydrogen').+Programmatically enable/revoke shell_execute auto-approve. v1.8.3+. v1.8.116+: `permanent` is the DURABLE user preference — it writes AD's Settings checkbox ('Auto-approve shell commands permanently', config-backed, default OFF), so it survives restarts by design. Timed grants (duration_secs) are session-scoped. In embedded mode Hydrogen owns this preference: pass `--shell-approval <prompt|1h|24h|permanent>` when spawning AD, and/or drive this verb at runtime; AD's own checkbox goes read-only ('Managed by Adom Hydrogen').  **Args:**   - `duration_secs` — optional int — seconds to enable for (e.g. 86400 = 24h), session-scoped. Pass 0 to revoke immediately (also clears the durable preference). Ignored if `permanent: true`.@@ -440,7 +440,7 @@ Programmatically enable/revoke shell_execute auto-approve. v1.8.3+. v1.8.116+: ` **Note:** Use sparingly. Auto-approve means anything that can reach the relay can run arbitrary shell commands without user consent. The PUBLIC default is per-command approval — leave it that way for end users; permanent is an explicit owner opt-in. Typical patterns:   - Dev session: `adom-desktop shell_auto_approve '{"duration_secs": 86400}'` (24h, then expires).   - Owner's box, durable: `adom-desktop shell_auto_approve '{"permanent": true}'` (equivalent to ticking the Settings checkbox).-  - HD embedded spawn: pass `--shell-approval permanent` (or the user's HD-side choice) on AD's command line — session-only, never persisted by AD.+  - Hydrogen embedded spawn: pass `--shell-approval permanent` (or the user's HD-side choice) on AD's command line — session-only, never persisted by AD.   - Revoke everything: `adom-desktop shell_auto_approve '{"duration_secs": 0}'`.