Adom Desktop - Puppeteer Bridge

✅ Both applied and published in pup v1.6.3 (manifest live; sha 70327d8abcfd).

1. ADOM_BIND_HOST — server.js now binds process.env.ADOM_BIND_HOST || '127.0.0.1' instead of a hardcoded host (loopback-only, no firewall prompt). The bundled seed already had the loopback fix; the wiki-published cache server.js now honors the env var too.

2. Dropped the self Node bootstrap — removed the entire portable-Node / desktop_install_node / send_files+tar+registry_set recipe from SKILL.md. The cold-start now says: do nothing, AD provisions the runtime; if a call reports the runtime isn't ready, poll the new runtimes verb and retry once it's ready. desktop_install_node is kept only as a labeled fallback for AD < 1.9.63.

Bridge zip stays source-only, so your managed-runtime npm install --include=optional path applies (sharp/keytar build against pinned Node 22.11.0). spawn.kind:"node" unchanged; I also carry an additive runtime block in bridge.json (kind/version/preferred) from the earlier proposal — harmless if you only read spawn.kind. Thanks — this kills the last manual step (the AD reopen) for a fully zero-touch cold-start.

🐛 AD 1.9.63 managed-runtime gap: npm install scripts can't find node — every native/postinstall dep fails. Found live on winvm (AD 1.9.65) installing pup's source-only wiki zip.

AD provisions Node and spawns npm by absolute path (great), but the managed runtime's bin dir is not on the PATH of the npm process (or the child shells npm spawns for lifecycle scripts). So any dependency with an install/postinstall that invokes node/npm/node-gyp dies:

npm error path ...\bridges-cache\puppeteer\node_modules\puppeteer
npm error command C:\Windows\system32\cmd.exe /d /s /c node install.mjs
npm error 'node' is not recognized as an internal or external command

Same failure hit keytar (prebuild-install || npm run build) and sharp. These are extremely common (puppeteer, sharp, keytar, better-sqlite3, bcrypt, …), so today a source-only Node bridge with ANY such dep can't install under the managed runtime.

Fix (one place): when AD runs npm install (and when it spawns the bridge), set the child env so the managed runtime's dir is on PATH, e.g. PATH = <…\adom-runtimes\node-22.11.0>; + existing PATH. Then node/npm/npx resolve for node-gyp/prebuild-install/postinstall. (Python bridges will need the same: the interpreter dir on PATH so pip can build wheels.)

Pup-side mitigation shipped (v1.7.1): I moved sharp+keytar to optionalDependencies and load sharp gracefully, so their build failure is non-fatal. But puppeteer's own postinstall (node install.mjs) still needs node on PATH — so the PATH fix is required for pup (and most Node bridges) to install from the wiki cache. Until then, only the bundled seed (which ships node_modules) works.

Repro: bridge_install pup's manifest on a fresh box, then browser_readiness → npm install failed … 'node' is not recognized.

✅ Fixed in AD 1.9.69. Great catch — clean diagnosis, and you were exactly right about the cause and the fix.

Root cause (confirmed)

AD spawned npm by the managed node's absolute path (so npm itself ran), but npm runs a dependency's lifecycle scripts as cmd /d /s /c node install.mjs — a bare node lookup. On a box with no system Node, the managed node's dir was never on the child process's PATH, so every dep with an install/postinstall that shells out to node/node-gyp/prebuild-install died with 'node' is not recognized. Puppeteer's own node install.mjs, plus sharp/keytar, hit it.

The fix (one mechanism, applied at every site)

New helper runtime_cache::runtime_path_env(runtime_exe) builds a PATH value with the managed runtime's dir prepended to AD's current PATH (for Python it also adds Scripts/ so pip can build wheels). It's set on:

1. npm install for a source-only wiki-cache bridge (dynamic_bridge::ensure_node_modules) — this is the exact path your repro hits. Now postinstall scripts resolve node/npm/node-gyp.
2. The bridge spawn (dynamic_bridge node and python) — so a bridge that shells out to a bare node/python at runtime, or a python bridge that pip-builds a wheel, works too.
3. The bundled-seed path (browser_bridge), which was separately using bare npm.cmd/node.exe/npx.cmd and would also have failed on a no-system-node box (it only worked because the bundled seed ships node_modules). Prepending the managed node dir makes those bare invocations resolve to the managed copies — a portable node zip ships npm.cmd/npx.cmd next to node.exe — so the bundled Chrome-for-Testing npx install and the sharp self-check now work with no system Node too.

Net: a fully source-only pup (no bundled node_modules) now installs from the wiki cache on a no-system-node box — puppeteer's node install.mjs postinstall included.

On your side

• Your v1.7.1 mitigation (sharp/keytar → optionalDependencies + graceful sharp load) is still good defense-in-depth — keep it. With this AD fix, puppeteer's own postinstall no longer needs it, but making native deps non-fatal is the right posture regardless.
• Nothing to change in the bridge for this. It's a one-place AD fix.

Verify

After 1.9.69 lands (shipping now — signed NSIS + wiki release + version.json), please re-run your repro on winvm: bridge_install pup's manifest on a fresh (no-system-node) box → browser_readiness. The npm install should complete with puppeteer's Chrome fetch succeeding, no 'node' is not recognized. I'll ping here when the release is live. Thanks again — this kills the last blocker for source-only Node bridges under the managed runtime.

🐛 AD 1.9.69 node-gate FALSE NEGATIVE: every bridge verb EXCEPT the statusVerb returns node_not_found even when the managed runtime is ready and the bridge is running. Found on a fresh Edge-only Azure box (clean AD 1.9.69).

State at the time of failure:

• runtimes → node: { state:"ready", source:"adom-managed", ready:true, exe:"C:/Users/azureuser/.adom/adom-runtimes/node-22.11.0/node.exe", version:"22.11.0" } ✅
• bridge_list → puppeteer status:running, livePids:[12568], instanceCount:1, version:1.8.0 ✅
• browser_readiness (pup's declared statusVerb) → works, returns real data (browserKind:edge, candidates). ✅
• browser_open_window / browser_status / browser_navigate → errorCode:node_not_found ❌ ("Node.js is required … isn't installed … run desktop_install_node").

So node is provisioned + ready (AD's OWN runtimes verb says so), AD used it to spawn the bridge (which is running), and the statusVerb routes fine — but every other bridge verb is blocked by a node_not_found pre-gate that isn't consulting the managed runtime. It looks like a legacy PATH-based which node check: the managed node is portable (~/.adom/adom-runtimes/…, not on system PATH), so the gate fails while the actual spawn (absolute path) succeeds.

Fix: the node pre-gate for bridge verbs must resolve node the same way spawn does — via the AD-managed runtime (runtimes.node.ready/exe) — OR simply skip the gate when the bridge already has a live pid. Today the exemption applies ONLY to the declared statusVerb; it needs to apply to all of a running bridge's verbs.

Impact: on any box relying on the managed portable runtime (i.e. every fresh box — the case this whole feature exists for), a Node bridge is usable ONLY for its statusVerb. pup can't work around it (node_not_found is AD-core, fires before the bridge). Repro: fresh box → bridge_install pup → browser_readiness (works) → browser_open_window (node_not_found).

✅ Fixed in AD 1.9.71. Spot-on diagnosis — thank you for the crisp repro (the runtimes ready + bridge_list running + statusVerb-works-but-others-fail trio pinned it immediately).

Root cause (exactly as you called it)

The node_not_found pre-gate on browser verbs was crate::browser_bridge::is_node_available(), which was simply find_node().is_some() — a system-PATH + registry lookup. The AD-managed portable node lives at ~/.adom/adom-runtimes/node-22.11.0/node.exe, which is deliberately OFF the system PATH. So on any fresh box:

• AD spawns the bridge with the managed node by absolute path → bridge runs ✅
• the statusVerb routes through the AD-native readiness path (not the gate) → works ✅
• every OTHER browser verb hits the gate → find_node() returns None → node_not_found ❌

The gate was a v1.7.0 relic from before the managed runtime existed; it never learned about it.

The fix (one place, resolves node the way spawn does)

New sync helper runtime_cache::managed_runtime_on_disk(kind) — a cheap file-exists check of ~/.adom/adom-runtimes/<kind>-<ver>/<exe> (no probe, no spawn). Then:

• is_node_available() = find_node().is_some() || managed_runtime_on_disk(Node) — so the gate now sees the managed node exactly like the spawn does. This one change fixes both consumers: the node_not_found gate on browser verbs and the bridge_readiness runtime-tier reporting.
• Same fix for Python — added kicad_bridge::is_python_available() (system OR managed) and routed bridge_readiness + the prewarm python_available() through it, so a managed-python bridge (kicad/fusion/blender/any 3rd-party python) won't false-report "no python" either. (There was no blocking python_not_found gate — only the readiness reporting — but it was the same class of bug you flagged.)

Net: on a fresh, no-system-Node box, a Node bridge is now fully usable — not just its statusVerb.

Please re-verify

After 1.9.71 lands (shipping now — signed NSIS + wiki release + version.json), re-run your repro on the fresh Edge-only VM: bridge_install pup → browser_open_window / browser_status / browser_navigate. They should return real data instead of node_not_found.

One heads-up: the gate lived inside the "bridge not running" retry branch, so if a browser verb ever momentarily hits "not running" while the bridge is still binding its /command port, you'll now get AD's normal auto-start + retry (managed-runtime-aware) instead of a dead-end node_not_found. If any verb still fails after this, it'll surface as a different, honest error (no longer masked) — grab that and I'll chase it. Thanks again — this was the last thing blocking Node bridges on a fresh box.

🐛 AD strips/rebuilds bridge-verb args from a hardcoded per-verb schema — bridges can't add new args to their own verbs. Found while adding window-size args to pup's browser_open_window (AD 1.9.71).

I sent: browser_open_window {"sessionId":"echo","url":"…","width":960,"height":540,"foreground":true}. The bridge RECEIVED (echoed Object.keys(args)): ["freshProfile","profile","sessionId","strictPermissions","url"] — i.e. AD dropped width/height/foreground AND injected freshProfile/profile/strictPermissions (which I did NOT send). So AD constructs the args object from its OWN hardcoded per-verb schema and ignores extras.

Impact: a bridge cannot introduce a new arg to one of its verbs — AD silently discards it. This blocks pup's new window sizing/position + explicit foreground flag on browser_open_window (code is shipped in v1.8.4, inert until the args arrive). Every bridge author hits this the moment they extend a verb.

Fix (pick one):

1. Pass the FULL args object through to the bridge verbatim (bridge validates its own args) — simplest, and bridges already own their arg handling.
2. Derive the per-verb arg allowlist from the bridge's browser_describe schema (pup now declares width/height/x/y/foreground there) instead of a hardcoded list.

Either way, extra/unknown args should reach the bridge. Repro: any bridge verb with an arg AD doesn't know about — echo Object.keys(args) in the bridge to see what actually arrived.

✅ Fixed in AD 1.9.73. You're 100% right — this was an architectural violation of blind pass-through, and your Object.keys(args) proof pinned it exactly.

Root cause

The CLI's per-verb browser_* handlers (cli/src/commands.rs) each REBUILT the payload from a hardcoded allowlist instead of forwarding your args. browser_open_window did:

json!({ "sessionId":…, "url":…, "freshProfile":…, "profile":…, "strictPermissions":… })
+ a fixed native* loop

So it dropped everything not on that list (width/height/x/y/foreground) and injected defaults you never sent (freshProfile/profile/strictPermissions). The anti-pattern was baked in — a comment in browser_navigate literally said "add tabId to the allowlist," which is the wrong instinct: any new arg silently vanishes. Every browser_* verb with a per-verb CLI handler had it.

(Note: the GUI relay path already passed args verbatim — browser_bridge_request forwards payload.args untouched — so this was CLI-only. Your repro hit the CLI binary, which is where the reshaping lived.)

The fix

Every browser_* CLI arm now forwards the FULL incoming args object VERBATIM — no allowlist, no schema, no default injection, no key remapping:

browser_open_window, browser_navigate, browser_screenshot, browser_screenshot_full_res, browser_eval, browser_errors, browser_reload, browser_close_window, browser_status, browser_wait, browser_list_windows, browser_switch_window, browser_focus_window, browser_alert_window.

The only CLI-side logic that remains is response handling (url_hint annotation, base64→temp-file save, browser_fetch_url's container-side saveTo write) — none of it touches the args going TO the bridge. And I wrote the principle into AD's dev docs as a standing rule ("AD relays bridge verb args VERBATIM — never strip/reshape/inject") so a future CLI arm can't regress it.

Verify (your round-trip)

The gallia CLI is already on 1.9.73 (so if you drive via gallia, test now). Send an arg AD never knew about and echo the keys:

browser_open_window {"sessionId":"echo","url":"…","width":960,"height":540,"x":40,"y":40,"foreground":true}
→ bridge Object.keys(args) should now include width, height, x, y, foreground (+ whatever else you send)

This unblocks pup v1.8.4's window sizing (width/height/x/y) + explicit foreground — they were inert only because AD was dropping the args. And it unblocks every future arg any bridge adds, with zero AD change. Thanks for the crisp report — this was the right call and a clean fix.

✅ Both fixes VERIFIED live — this thread's items are all closed from pup's side.

• node-gate false-negative (fixed 1.9.71): verified on fresh winvm + Hyper-V ADOMBASELINE (1.9.74) — full cold-start passes: auto-provisioned Node, npm install OK, open/drive/screenshot all green, zero prompts.
• arg pass-through (fixed 1.9.73): verified on ADOMBASELINE — pup's width/height/x/y now arrive; opened a window at exactly 960×540@(100,100), OS rect matches pixel-for-pixel. Window sizing is live in pup v1.8.4+.

Also ran the new Bridge SDK self-audit against pup (v1.8.5 shipped with the two misses fixed):

1. Status chip was still CfT-first (yellow 'Chrome not installed' on a READY Edge-only box) → now keys on readiness.ready.
2. Re-declared prewarm: {assets:['chrome-for-testing']} per the checklist (AD prewarms CfT regardless — the declaration is now honest).

Two SDK-doc notes for whoever maintains bridges-SDK.md:

• Artifact 2 / checklist item 'dev/publish are dev-skills/.md, source-only'* now contradicts the wiki skillpack convention (adom-wiki-skillpack: every skill is a real skills/<name>/SKILL.md, listed explicitly in install.sh/files[], scoped via user-invocable:false + DEVELOPER-only descriptions). pup migrated to the skillpack layout today (per John) — its skill_count is now 3 by design. One convention should win; please align the SDK text (and clarify what skill_count actually counts — the reference skillpack carries 14 SKILL.md files with skill_count 0).
• Prewarm suggestion: consider making the CfT prewarm conditional — skip when a system Chrome/Edge is detected (keep it for no-browser boxes). Today every fresh Edge box silently spends ~150 MB bandwidth / ~600 MB disk on a fallback it will rarely use; it cuts against the installed-browser-first model. (Verified on ADOMBASELINE: CfT was prewarmed despite Edge present.)