Bridge SDK: document and scaffold the dock-bar manifest + dashboard contract for bridge authors

by adom

Adom Bridge unleashes your AI onto your full PC: full power, full safety. The AI breaks out of the container it runs in and onto your real machine, managing and running your entire laptop as you: launch apps, move files, drive any window, control KiCad, Fusion 360 or your real signed-in browser. Works with any AI, cloud or local (Claude Desktop, Claude Code, Codex), no Hydrogen required. Bridge and its bridges are an operating system for AI, with managed Node and Python runtimes, and a human-onl

Overview Files Skills Discover Packages Releases Dependencies Issues20 Breadcrumbs Pull Requests1 Activity

Closed general

John Lauer · 2mo ago ·closed by John Lauer

SDK: a documented contract for a bridge to ship its own dock-bar dashboard

Building the Altium bridge's dock dashboard, I had to reverse-engineer the whole contract from kicad-bridge's tree (dockbar.json shape, the <bridge>-dashboard serve --print-url command the dock runs, install.sh planting the dashboard wrapper into ~/.local/bin, the LED-facet + say-strip + status-pill anatomy, the health-poll URL). The dock-dashboard skill documents the anatomy beautifully, but the bridge-author mechanics live only as tribal knowledge copied between kicad/fusion.

Request: fold a "give your bridge a dock dashboard" section into the bridge SDK so a new bridge author gets a documented, copy-pasteable contract instead of cloning kicad's repo and diffing:

dockbar.json at the repo root: dock_manifest version, say[], webview{title,favicon}, health{url,poll_seconds,timeout_ms}, launch{mode:"container_command", steps[], on_ready, ai{prompt,thread,submit}} — field-by-field meaning.
The dashboard command contract: <bridge>-dashboard serve --print-url (idempotent, version-aware, prints its URL), the /api/status LED payload shape (per-facet {label,state,detail,_hint,short} + rollup), /events SSE, /api/action.
Delivery: install.sh plants the dashboard tree + a ~/.local/bin/<bridge>-dashboard wrapper; pkg files[] lists it; the dock runs the wrapper.
Cross-link the ONE-APP-ONE-DASHBOARD rule and the desktop/container serving asymmetry from dock-dashboard.

Ideally also a bridge scaffold-dashboard generator (or an SDK template) that emits a working dockbar.json + dashboard stub keyed off the bridge's verb prefix, so every bridge's dock card is one family without N hand-copies.

Filed while shipping adom/altium-bridge's dashboard (a from-scratch kicad clone). Happy to contribute the Altium one back as a second reference implementation.

1 Reply

John Lauer · 2mo ago

Done - folded the full author contract into the Bridge SDK (BRIDGE_SDK_PUBLISH.md, Artifact 4). Ships in the next patch and rides the pkg/installer with the rest of the SDK.

Artifact 4 already wired the dashboard (the serve --print-url verb contract, delivery as a platform-tagged release asset, the LED _hint rule). What was missing - and what you had to reverse-engineer - is now there:

The dock manifest, field-by-field: dock_manifest, say[], webview{title,favicon}, health{url,poll_seconds,timeout_ms}, launch{mode, steps[], on_ready, ai{prompt,thread,submit}}, with a worked JSON example.
GET /api/status LED payload shape: per-facet {label, state, detail, _hint, short} + a rollup, with _hint naming the fixing verb made concrete.
GET /events (SSE) and POST /api/action, which weren't documented at all.
Cross-links to ONE-APP-ONE-DASHBOARD and the container-serving asymmetry.

One thing I did deliberately, and want to flag: the dock MANIFEST is Hydrogen's Dock SDK contract, not ab's - Hydrogen's dock reads it and launches your dashboard. So I documented it as a convenience copy and told the reader to confirm the current filename + fields against the live Dock SDK before shipping, because ab's SDK must not become the source of truth for a contract another app owns (the same "relay, don't reimplement" rule ab follows for Hydrogen's runtime state). I also flagged the dockbar.json vs dock.json drift you'd have hit - older bridges ship dockbar.json, current guidance is dock.json - so please sanity-check the name against whatever the Dock SDK says today and I'll correct the SDK copy if it's stale.

On the bridge scaffold-dashboard generator: great idea, and I deliberately did NOT build it in ab. A generator that emits a dock.json + stub would bake ab's copy of Hydrogen's manifest and drift the moment the Dock SDK changes a field - the exact coupling the ownership note avoids. If it ships it belongs with the Dock SDK (which owns the manifest), keyed off your verb prefix. Your offer to contribute the Altium dashboard back as a second reference implementation is the more valuable move - two worked examples beat one generated stub for a contract this young. Please do; I'll link it from the SDK.

John Lauer closed this · 2mo ago