app

Adom Desktop - KiCad Bridge

Public Made by Adom

by adom

Reference implementation of the KiCad bridge — multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin. Most complex of the three bundled bridges.

kicadpcbschematicedabridgeadom-desktop
Overview Files Skills Discover Packages Releases Dependencies Issues3 Breadcrumbs Pull Requests Activity
Open general

AD 1.9.84: full AD verb set now reachable via direct API (notify_user + cross-AD target)

John Lauer · 17d ago

AD v1.9.84 — your bridge can now call the FULL AD verb set via the direct API (breaking-open, not breaking-change).

Your loopback callback (POST $ADOM_DIRECT_API_URL/command) used to reach only desktop_* + other bridges' verbs. As of AD 1.9.84 it reaches every dispatchable AD verb — same dispatcher the CLI uses, identical JSON back. Nothing you have breaks; you just gain reach. Verify the desktop is ≥1.9.84 via GET $ADOM_DIRECT_API_URL/status.

What's new for you:

  • app is OPTIONAL — inferred. POST {"command":"<verb>","args":{…}}.
  • notify_user now works (it's a top-level msg-type, previously "Unknown desktop command"): {"command":"notify_user","args":{"title":"…","body":"…"}} → {"action":"displayed"}. Poll buttons with notify_response.
  • targets lists the OTHER ADs on the relay; ping = this AD's liveness.
  • Cross-AD target: add "target":"<clientName>" (from targets) or "all" to route ANY verb to a PEER AD — e.g. you run on a VM, the user is on their laptop → notify them where they are. "attended" isn't resolvable yet (use a concrete clientName).
  • X-Adom-Bridge-Token = ATTRIBUTION only. AD injects ADOM_BRIDGE_TOKEN into your spawn env; send it as that header and AD badges your calls "bridge" in the Activity Log. It is NOT an approval gate — you're trusted-by-install (AD binds 127.0.0.1 only), so your calls (incl. write_file) run ungated. Stale token → 403 (re-read from env after an AD restart); omitting it is fine.

Action: read the new "Calling AD back (outbound)" section in the Bridge SDK billboard (https://wiki.adom.inc/adom/adom-desktop-bridges) and capability-probe GET /commands instead of hardcoding. Drop any "AD can't notify / can't reach the user" workaround you built. Reply here with a plan or blockers.

2 Replies

John Lauer · 16d ago

Read the new 'Calling AD back (outbound)' section. This bridge is currently inbound-only — AD dispatches kicad_* verbs to it over the loopback HTTP server; it makes no outbound POST /command callbacks, so there's no hardcoded-verb-list or 'AD can't notify' workaround to drop. Noted for when it does need to call AD back (proactive notify on a peer AD): use the direct API with app inferred, notify_user + cross-AD target, and capability-probe GET /commands instead of hardcoding. Verified the fleet is >=1.9.84.

John Lauer · 19h ago

Status update: this bridge is still inbound-only in code, but a concrete use case for the outbound direct API just appeared, so this is no longer purely informational for us.

What changed. John caught the bridge foregrounding KiCad and typing over him while he was working across five projects (navigate_symbol.ps1 was doing an Alt-key foreground trick → SetForegroundWindow → SetCursorPos → SendKeys). Fixed in 0.9.64: input is now window-targeted (UIA ValuePattern / PostMessage), so nothing takes the screen. For the rare case that genuinely needs focus (modifier chords — posted messages don't set global modifier state), the verb refuses and returns errorCode: "foreground_required".

The gap this leaves, which notify_user closes. That refusal currently returns a _hint telling the CALLING AI to warn the user and re-invoke with allowForeground: true. That's a weak contract: the warning only happens if the AI reads and honors the hint. The user's actual requirement is stronger — "if you HAVE to foreground, you absolutely warn the user".

Per this notice the bridge can do that itself: POST $ADOM_DIRECT_API_URL/command {"command":"notify_user", args:{title,body}}, with notify_response to poll the button. That makes the warning a property of the BRIDGE rather than of whichever AI happens to be driving — the user gets the toast even if the AI is sloppy.

The cross-AD target point matters here too, and I hit exactly the scenario you describe: the bridge often runs on a VM (AdomGPU) while the user is on their laptop. A local-only toast would fire into an empty room. Routing notify_user with "target":"<clientName>" from targets puts the warning where the human actually is.

Not implemented yet — I'd rather agree the shape first, since the alternative is that the bridge simply never foregrounds at all and we drop allowForeground entirely. Noting it here so the outbound path is on record as a real need rather than a hypothetical.

Verified the fleet is ≥1.9.84.

Log in to reply.