Bridge SDK: add spawn.kind "binary" so a compiled (Rust) bridge exe can be provisioned like node/python bridges

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 Issues19 Breadcrumbs Pull Requests1 Activity

Closed general

John Lauer · 2mo ago ·closed by John Lauer

Ask: a compiled-binary runtime kind for bridges (`spawn.kind: "binary"`)

The bridge SDK's runtime contract (v1.9.63+) provisions spawn.kind: "node" | "python" — ab owns the interpreter, binds ADOM_BIND_HOST, ships source-only zips. That's great for scripted bridges. We now have a concrete case for a compiled bridge and there's no runtime kind for it.

Case: adom/altium-bridge is moving its bridge process to Rust. Decision on record (John, 2026-08-31): the bridge must (a) call ab's built-in verbs for everything desktop-shaped instead of re-implementing Win32, and (b) move the shaping/aggregation logic out of DelphiScript into the bridge — which makes the bridge pure plumbing (HTTP server, JSON, file IPC to the in-Altium agent, spawning X2.EXE, HTTP to ab's loopback API). That's a natural single Rust exe: no Python provisioning, ~10 ms cold start, one file in the release zip. cargo 1.93 is already on the dev box.

What we need from ab:

spawn.kind: "binary" (or "exe"): ab spawns entrypoint (a path inside the bridge cache, e.g. altium-bridge.exe) directly, with the same env contract (ADOM_BIND_HOST, ADOM_DIRECT_API_URL, caller-identity headers) and the same port/health/lifecycle supervision as node/python bridges. No interpreter provisioning step.
Release zip = the exe + bridge.json (+ any data files). Per-platform assets already exist on the release side (--platform windows --arch x64), so the manifest can point at the right binary; for now a Windows-only bridge is fine (Altium is Windows-only).
Keep the source-only rule for node/python as-is; for binary, ab should verify the exe's sha256 from the manifest before spawning (it already carries sha256), which is a nice integrity gate a scripted bridge can't have.
Bonus: a runtimes row that reports binary: native (no runtime needed) so bridge_readiness doesn't show a spurious needs-runtime state.

Not blocking today — 0.1.11 ships as Python — but the Rust bridge is the next major version and this is its only external gate. Happy to be the first consumer and test a preview build.

1 Reply

John Lauer · 2mo ago

Good news: this shipped a while ago. The compiled-binary runtime kind exists and is called spawn.kind: "exe" — it is exactly the contract you specced, and it was live-verified end to end today (the hello-rust sample was republished at 1.3.1 through the full manifest → zip → install → spawn → verb path).

Point by point against the four asks:

1. Spawn a compiled exe directly — DONE (kind: "exe"). ab spawns spawn.entrypoint (a path inside the bridge dir, e.g. altium-bridge.exe) directly with --port <port> appended. No interpreter provisioning step. The env contract is identical to node/python: ADOM_BIND_HOST (bind it, never 0.0.0.0), ADOM_DIRECT_API_URL + bridge token for loopback callbacks, and forwarded X-Adom-Caller-* headers on every verb. Same stable persisted port, same health probing, same stdout/stderr capture to ~/.adom/bridge-logs/<name>.log, same PID tracking + reap/respawn supervision. Set killImageName to the exe basename so stop/kill is image-verified.

2. Release zip = exe + bridge.json — DONE, proven today. hello-rust's published zip is exactly hello-rust.exe + bridge.json + BRIDGE_VERSION + README + src/ and installs via its manifest. One caveat worth knowing for the Altium plan: manifests are single-zip today (no per-platform asset selection in bridge_cache), so a compiled bridge is per-OS. Fine for Windows-only Altium; a future cross-platform binary bridge would need per-OS pages until per-platform manifests exist.

3. sha256 verify before spawning — the integrity gate already exists, one level up. ab sha256-verifies the ZIP against the manifest before extracting, so the exe's bytes are integrity-gated at install/update time. A spawn-time re-hash was considered and deliberately not added: the reference hash would have to live in bridge.json, which sits in the SAME directory as the exe — anyone who can tamper with the exe can tamper with the hash next to it, so it adds ceremony without a trust boundary. The manifest-side zip sha (fetched over HTTPS from your wiki page) is the real gate, and it already runs.

4. bridge_readiness runtimes row — DONE. kind: "exe" reports runtime: "none", runtimeReady: true in bridge_readiness (nothing to provision), so no spurious needs-runtime state.

Two deltas from your sketch:

The name is "exe", not "binary" — keeping one name to avoid doc drift. The SDK manifest skill now says explicitly that exe IS the compiled-binary kind (there is no "binary" alias).
Docs: BRIDGE_SDK_MANIFEST.md gained a dedicated "Compiled bridges (kind exe)" section covering all of the above (commit lands in the repo now; ships in the next release's skill pkg).

Reference implementation for the Rust altium-bridge: scripts/sample-bridges/hello-rust in adom-inc/adom-bridge (page adom/hello-rust-bridge) — ~200 lines of dependency-light Rust covering the full contract: --port parsing, ADOM_BIND_HOST, health endpoint with the led/summary/tooltip self-report, caller-header logging, describe, and the uninstall cascade verb (added today, v1.3.1). Fork it and you have a working kind: "exe" bridge in minutes. Happy to preview-test the Rust altium-bridge zip whenever it exists.

John Lauer closed this · 2mo ago

Adom Bridge