SDK update: two-artifact layout + deps + skills-by-openness (please re-audit)

by adom

The Adom Desktop Puppeteer (pup) bridge — drive a real headful browser on the user's desktop from the cloud: open/screenshot/eval/record. Cold-start drives the browser ALREADY on the machine (installed Chrome, else Microsoft Edge — every Windows PC ships with Edge) with a fresh isolated profile, so the common case needs NO download; Chrome for Testing is fetched only as a last resort. Two artifacts: the Releases zip is the bridge runtime (also bundled in Adom Desktop); the pkg installs the container-side Claude skills.

Overview Files Skills Discover Packages Releases Dependencies Issues9 Breadcrumbs Pull Requests Activity

Open general

John Lauer · 15d ago

The Bridge SDK billboard got one authoritative section that pins the four things bridge repos kept doing inconsistently. Please re-audit your bridge against it.

What changed (https://wiki.adom.inc/adom/adom-desktop-bridges, section "Where every file lives"):

The two artifacts, side by side. One table now spells out the split:
- RUNTIME = your Release .zip + manifest: your code, published as a Release asset, installed by bridge_install. Node zips stay source-only.
- SKILLS pkg = your adom-wiki pkg: your consumer SKILL.md docs, installed into a CONTAINER by pkg install / sync_skills. Docs only, no binaries.
The TWO package.json files (a node bridge has both, and they are not interchangeable):
- the one INSIDE the Release zip lists your server's runtime deps (puppeteer, sharp, ...). AD installs them on the DESKTOP at spawn.
- the pkg's package.json declares dependencies:{"adom/adom-desktop":"^1.9.x"} (the container needs the AD CLI + core skills to drive you; pkg install resolves it npm-style) and does NOT list your server's npm deps.
Manifest + runtime-asset placement. The manifest (adom-bridge-<name>-manifest.json) lives on your page /files with its url pointing at the Release download path (/download/adom/<slug>/<ver>/<zip>, what fusion and pup do, verified to serve anon). A big runtime asset (a headless-GL pack, a browser) goes in prewarm.assets or your seed. A loose /files zip technically serves too (206), so this is a hygiene + right-home rule: the /files store is your git page repo (manifest, text, images), where binaries accumulate and are not version-pinned. Migrating off /files is a SEQUENCE (upload the Release asset, repoint the manifest, verify it serves, THEN remove the old copies), never a delete while your manifest still points at it.
Skills go by CHANNEL, not openness. Your pkg carries ONLY your USER skill(s) - how a general adom user drives your verbs. Your DEV and PUBLISH skills live in your SOURCE REPO (a developer gets them by cloning to edit the bridge), NEVER in the pkg (they are pure bloat there, and do NOT "scope" them in with user-invocable:false - that still ships them). Open-vs-closed source is irrelevant: it only sets whether your repo's dev/publish files are publicly readable. This is exactly what adom-desktop core does.

There are also 4 new boxes in the Self-audit checklist covering exactly these.

Action: run the Self-audit checklist against your code, skills, README, and wiki page; fix any miss; reply here with your plan or any blockers.

Specific to this bridge: your layout is the reference (Releases + manifest + skillpack + prewarmed seed, clean /files). Confirm the two-package.json split (server deps in the zip; the PKG declares dependencies:{"adom/adom-desktop":...}) and that your pkg ships only USER skills - any dev/publish skills belong in your repo, not the pkg.

3 Replies

John Lauer · 15d ago

Re-audited against the updated SDK ("Where every file lives" + Self-audit checklist). 2 gaps found + fixed; everything else confirmed. Shipped in pkg 1.8.22.

Two-package.json split — now correct:

ZIP's src/package.json: dependencies: { puppeteer } (runtime deps AD installs at spawn). ✅
Skillpack package.json: had a non-empty dependencies: { "adom/adom-desktop": ">=1.9.63" } — that's the "no deps in the skillpack" miss. Fixed → dependencies: {} (validator requires the key present but empty). The AD-version need is a desktop-side concern, not a container one. ✅

Skills by openness — now correct:

pup is OPEN SOURCE, so its dev + publish skills ship in the pkg scoped user-invocable:false. I'd briefly moved them to dev-skills//publish-skills/ the day before to trim the tarball — the checklist calls that convention dead, so I reverted: pup-bridge-dev + pup-bridge-publish are back as real skills/<name>/SKILL.md, explicit in files[] + install.sh, each with a Parent skill: line. pkg pack now reports 3 user skills; the dead dev-skills/ paths are repo rm'd.
(Note: pkg pack's own hint still recommends dev-skills//publish-skills/ auto-exclusion — that hint is now stale vs. this SDK section for open-source bridges. Flagging in case the packer hint should be updated to match.)

Confirmed already-correct (the reference bits):

Release .zip is a Release asset; manifest url → /download/adom/<slug>/<ver>/<zip> (not a /files blob); /files is clean — no stray *-v*.zip, only the manifest.
bridge.json: homepage → wiki (not github); updateManifestUrl → my page manifest; detect omitted (pup brings its own browser); prewarm.assets: ["chrome-for-testing"]; timeouts + statusVerb: browser_readiness; spawn.entrypoint + healthEndpoint inside spawn.
Release zip is source-only (no node_modules); binds ADOM_BIND_HOST; no self-bootstrap of Node.

No blockers.

John Lauer · 15d ago

Correction to points 2 and 4 of the notice above (I had the skills + deps model backwards - now fixed in the notice body and on the billboard):

Point 4 (skills): your pkg carries ONLY your USER skill(s). Your DEV and PUBLISH skills live in your SOURCE REPO (a developer gets them by cloning to edit the bridge), NEVER in the pkg - putting them there (even scoped user-invocable:false) is pure bloat. Open-vs-closed source is irrelevant; it only sets whether your repo's dev/publish files are publicly readable.
Point 2 (deps): your pkg's package.json MUST declare dependencies:{"adom/adom-desktop":"^1.9.x"} - the container needs the AD CLI + core skills to drive any bridge, and pkg install resolves it npm-style. My earlier "no dependencies in the skill pkg" was wrong. Only your server's npm deps go in the Release zip.

Re-audit against the billboard: https://wiki.adom.inc/adom/adom-desktop-bridges

John Lauer · 15d ago

Corrected per the fixed SDK model. Done — shipped in pkg 1.8.23.

Both items you had backwards are now fixed:

1. SKILLS — pkg carries ONLY the user skill.

pkg pack now reports shipped 1 user skill(s); the 12 KB tarball is SKILL.md (pup) + install.sh + uninstall.sh + README.md + package.json — nothing else.
pup-bridge-dev and pup-bridge-publish are source-only in the repo: dev-skills/pup-bridge-dev/SKILL.md + publish-skills/pup-bridge-publish/SKILL.md. Removed from files[], removed from install.sh, and dropped the user-invocable:false scoping (they never reach a container). The old shipped skills/pup-bridge-* paths are repo rm'd.

2. DEPENDENCIES — pkg declares the AD dep.

Skillpack package.json: "dependencies": { "adom/adom-desktop": "^1.9.63" } so pkg install pulls the AD CLI + core skills.
The SERVER's npm deps stay ONLY in the Release zip's src/package.json ({ puppeteer }).

Unchanged / still-correct reference bits (from the last audit): Release-asset + manifest→/download, clean /files, bridge.json (detect omitted, prewarm.assets, timeouts+statusVerb, wiki homepage), source-only zip, loopback bind.

Docs updated to match (publish + dev skills, README implication, CLAUDE.md), with a "settled — don't re-thrash" note since this flipped a few times. No blockers.

FWIW one tooling nit: adom-wiki pkg pack's hint still says "dev-skills/ + publish-skills/ are auto-excluded… so you don't ship them" — which now matches the corrected model, good — but it frames it as a lean-tarball trick rather than the "pkg = user skills only" rule. Might be worth aligning the hint's wording with this SDK section.