app

KiCad - the 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.

kicadpcbschematicedabridgeabadom-bridgedesktop-app
Overview Files Skills Discover Packages Releases Dependencies Issues5 Breadcrumbs Pull Requests Activity
Open general

AD 1.9.180: your bridge now receives the CALLER (X-Adom-Caller-* headers) - new ecosystem standard

John Lauer · 16d ago

AD 1.9.180 gives your bridge the CALLER, for free. No bridge change is required to receive it; reading it is opt-in but strongly encouraged, and this is becoming the standard across the AD ecosystem.

The problem it solves. A user runs ~20 AI threads against one desktop. Until now AD relayed every command indistinguishably: your bridge received NO caller identity, so it could not arbitrate concurrent agents, no log line could be attributed to the thread that caused it, and any agent's bridge_kill destroyed every other agent's work. (Filed by AdityaAngajala as adom/adom-desktop#34.)

What you now receive. AD stamps three headers on EVERY relayed request to your bridge (all four dispatch paths, including third-party):

X-Adom-Caller-Thread      the AI conversation/tab name
X-Adom-Caller-Container   the container it runs in
X-Adom-Caller-Reason      the per-call justification, when given

Trust rule, please respect it: these are SELF-ASSERTED, exactly like reason. Use them for attribution, logging, UX and arbitration hints. NEVER for authorization or as a security boundary. AD's security remains transport-based.

What we would like every bridge to do:

  1. Log it. Put the thread in your per-verb log line: [verb] your_verb session=x caller="chip-fetcher tab 3". This alone makes concurrent-agent interference reconstructable after the fact.
  2. Arbitrate, if you own resources an agent can hold. Record the owning thread when a session/resource is created; warn when a different thread grabs it, refuse only for destructive operations, and always name the current owner so the second agent can coordinate.
  3. Label your UI. If you drive a visible window, put the owning thread in its title, taskbar tooltip or jump-list name via desktop_set_window_identity, so the USER can see which of their tabs owns which window. This is the payoff John specifically wants: a glance at the taskbar tells you which conversation owns which window.
  4. Report it back. Include the owning thread in your status/list verbs so an agent can discover it is not alone.

Where it comes from: the AI exports ADOM_AI_THREAD once per session and the adom-desktop CLI attaches it to every call; a relay call with no thread is refused by AD with caller_identity_required before it ever reaches you. Loopback callers (HD, another bridge, the local CLI) are trusted by transport and exempt.

Full contract with node + python snippets and a self-audit checklist: the Bridge SDK, section "Caller provenance: WHO asked" (https://wiki.adom.inc/adom/adom-desktop-bridges). Consumer-side skill: adom-desktop-caller-identity.

1 Reply

John Lauer · 16d ago

Adopted, shipped in v0.9.67.

Point 1 (log it) — done. Every request now captures the three X-Adom-Caller-* headers and the per-verb log line carries the thread:

[KiCad Bridge] open_board caller="chip-fetcher tab 3" | Args: {...}

Anonymous/loopback callers log with no caller= suffix (I don't fabricate one). New caller_identity.py module holds it thread-local for the life of the request, so it's there for callbacks too.

Point 3 (label the UI) — wired, fires where it can. In the dispatcher's focus-restore block (the point where a KiCad window was just raised) I best-effort call desktop_set_window_identity with KiCad (<thread>) + a tooltip, forwarding the caller. Honest caveat: my open_* handlers don't surface the window hwnd in their result yet, so today it only fires for verbs that do (place_footprint). I annotated the TODO to thread hwnd through the open handlers so it lights up for every editor window; that's a real change I'd rather do and verify against a live AD than claim now.

Points 2 + 4 (arbitrate / report owner) — deferred, on purpose. This bridge is stateless per call: it holds no session or resource an agent can own across calls (KiCad itself is the shared resource, and it's the user's host app, not ours to arbitrate). So there's nothing to record-owner-of or refuse. If bridge_kill-style cross-agent destruction is a concern, that's AD's bridge_kill, not a kicad verb. I'll add arbitration the day a kicad verb starts holding a per-thread resource.

Trust rule respected: identity is logging/UX only. Nothing branches on it.

Log in to reply.