DEPRECATED: Bridge SDK (moved into Adom Bridge)

@@ -29,6 +29,26 @@ If a *bridge verb* misbehaves → fix the bridge. If a *generic AD capability* i  --- +## Calling AD back (outbound) — you reach the FULL AD verb set (v1.9.84)++Your callback channel is AD's loopback direct API: `POST <ADOM_DIRECT_API_URL>/command` (env var; fallback `~/.adom/direct-api-port` = `host:port`). As of **AD v1.9.84** this reaches **every dispatchable AD verb**, not just `desktop_*` — same dispatcher the CLI uses, identical JSON back. `GET <ADOM_DIRECT_API_URL>/commands` lists the full set so you can capability-probe (don't hardcode).++- **`app` is OPTIONAL** — inferred from the command. Just `POST {"command":"<verb>","args":{…}}`. (Pass `app` to override the inference.)+- **Top-level verbs you can now call:** `notify_user` (walk the user through something — returns `{action:"displayed"}`), `notify_response` (poll a toast button/input), `targets` (list the OTHER ADs on the relay), `ping`, `bridge_list`, `runtimes`, `status`, … — plus every `desktop_*` and every *other* bridge's verbs.+- **Cross-AD (`target`):** add `"target":"<clientName>"` (from `targets`) or `"all"` to route the call to a PEER AD via the relay — e.g. **you run on a VM but the user is on their laptop**: `notify_user` with `target:"<laptop clientName>"` reaches them where they are. `"attended"` isn't resolvable yet (use a concrete clientName).+- **`X-Adom-Bridge-Token` (optional, attribution).** AD injects `ADOM_BRIDGE_TOKEN` into your spawn env. Send it as the `X-Adom-Bridge-Token` header and AD badges your calls "bridge" in its Activity Log — nice for the user's transparency. It is **NOT** an approval gate: you're trusted by transport (AD binds 127.0.0.1 only + the user consented by installing you), so your calls — including `write_file`/`run_script` — run ungated. A stale token → 403 (re-read it from your env after an AD restart); omitting it is fine.+- **`cliRequired`** verbs (`pull_file`/`send_files`/`shell_execute`) return `412 cli_required` — they need the streaming/approval CLI path, not this HTTP channel.++```bash+# Discover, then call — no hardcoding.+curl -s "$ADOM_DIRECT_API_URL/commands"+curl -s -X POST "$ADOM_DIRECT_API_URL/command" -H 'Content-Type: application/json' \+  -H "X-Adom-Bridge-Token: $ADOM_BRIDGE_TOKEN" \+  -d '{"command":"notify_user","args":{"title":"Heads up","body":"…"}}'+```++---+ ## Runtime contract — AD provisions Node/Python; you bind loopback (v1.9.63 / v1.9.69)  **The single most important change for a Node or Python bridge.** As of AD **v1.9.63** you no longer bootstrap your own interpreter, and you MUST bind loopback. Four rules:

@@ -29,6 +29,26 @@ If a *bridge verb* misbehaves → fix the bridge. If a *generic AD capability* i  --- +## Calling AD back (outbound) — you reach the FULL AD verb set (v1.9.84)++Your callback channel is AD's loopback direct API: `POST <ADOM_DIRECT_API_URL>/command` (env var; fallback `~/.adom/direct-api-port` = `host:port`). As of **AD v1.9.84** this reaches **every dispatchable AD verb**, not just `desktop_*` — same dispatcher the CLI uses, identical JSON back. `GET <ADOM_DIRECT_API_URL>/commands` lists the full set so you can capability-probe (don't hardcode).++- **`app` is OPTIONAL** — inferred from the command. Just `POST {"command":"<verb>","args":{…}}`. (Pass `app` to override the inference.)+- **Top-level verbs you can now call:** `notify_user` (walk the user through something — returns `{action:"displayed"}`), `notify_response` (poll a toast button/input), `targets` (list the OTHER ADs on the relay), `ping`, `bridge_list`, `runtimes`, `status`, … — plus every `desktop_*` and every *other* bridge's verbs.+- **Cross-AD (`target`):** add `"target":"<clientName>"` (from `targets`) or `"all"` to route the call to a PEER AD via the relay — e.g. **you run on a VM but the user is on their laptop**: `notify_user` with `target:"<laptop clientName>"` reaches them where they are. `"attended"` isn't resolvable yet (use a concrete clientName).+- **`X-Adom-Bridge-Token` (optional, attribution).** AD injects `ADOM_BRIDGE_TOKEN` into your spawn env. Send it as the `X-Adom-Bridge-Token` header and AD badges your calls "bridge" in its Activity Log — nice for the user's transparency. It is **NOT** an approval gate: you're trusted by transport (AD binds 127.0.0.1 only + the user consented by installing you), so your calls — including `write_file`/`run_script` — run ungated. A stale token → 403 (re-read it from your env after an AD restart); omitting it is fine.+- **`cliRequired`** verbs (`pull_file`/`send_files`/`shell_execute`) return `412 cli_required` — they need the streaming/approval CLI path, not this HTTP channel.++```bash+# Discover, then call — no hardcoding.+curl -s "$ADOM_DIRECT_API_URL/commands"+curl -s -X POST "$ADOM_DIRECT_API_URL/command" -H 'Content-Type: application/json' \+  -H "X-Adom-Bridge-Token: $ADOM_BRIDGE_TOKEN" \+  -d '{"command":"notify_user","args":{"title":"Heads up","body":"…"}}'+```++---+ ## Runtime contract — AD provisions Node/Python; you bind loopback (v1.9.63 / v1.9.69)  **The single most important change for a Node or Python bridge.** As of AD **v1.9.63** you no longer bootstrap your own interpreter, and you MUST bind loopback. Four rules:

@@ -29,6 +29,26 @@ If a *bridge verb* misbehaves → fix the bridge. If a *generic AD capability* i  --- +## Calling AD back (outbound) — you reach the FULL AD verb set (v1.9.84)++Your callback channel is AD's loopback direct API: `POST <ADOM_DIRECT_API_URL>/command` (env var; fallback `~/.adom/direct-api-port` = `host:port`). As of **AD v1.9.84** this reaches **every dispatchable AD verb**, not just `desktop_*` — same dispatcher the CLI uses, identical JSON back. `GET <ADOM_DIRECT_API_URL>/commands` lists the full set so you can capability-probe (don't hardcode).++- **`app` is OPTIONAL** — inferred from the command. Just `POST {"command":"<verb>","args":{…}}`. (Pass `app` to override the inference.)+- **Top-level verbs you can now call:** `notify_user` (walk the user through something — returns `{action:"displayed"}`), `notify_response` (poll a toast button/input), `targets` (list the OTHER ADs on the relay), `ping`, `bridge_list`, `runtimes`, `status`, … — plus every `desktop_*` and every *other* bridge's verbs.+- **Cross-AD (`target`):** add `"target":"<clientName>"` (from `targets`) or `"all"` to route the call to a PEER AD via the relay — e.g. **you run on a VM but the user is on their laptop**: `notify_user` with `target:"<laptop clientName>"` reaches them where they are. `"attended"` isn't resolvable yet (use a concrete clientName).+- **`X-Adom-Bridge-Token` (optional, attribution).** AD injects `ADOM_BRIDGE_TOKEN` into your spawn env. Send it as the `X-Adom-Bridge-Token` header and AD badges your calls "bridge" in its Activity Log — nice for the user's transparency. It is **NOT** an approval gate: you're trusted by transport (AD binds 127.0.0.1 only + the user consented by installing you), so your calls — including `write_file`/`run_script` — run ungated. A stale token → 403 (re-read it from your env after an AD restart); omitting it is fine.+- **`cliRequired`** verbs (`pull_file`/`send_files`/`shell_execute`) return `412 cli_required` — they need the streaming/approval CLI path, not this HTTP channel.++```bash+# Discover, then call — no hardcoding.+curl -s "$ADOM_DIRECT_API_URL/commands"+curl -s -X POST "$ADOM_DIRECT_API_URL/command" -H 'Content-Type: application/json' \+  -H "X-Adom-Bridge-Token: $ADOM_BRIDGE_TOKEN" \+  -d '{"command":"notify_user","args":{"title":"Heads up","body":"…"}}'+```++---+ ## Runtime contract — AD provisions Node/Python; you bind loopback (v1.9.63 / v1.9.69)  **The single most important change for a Node or Python bridge.** As of AD **v1.9.63** you no longer bootstrap your own interpreter, and you MUST bind loopback. Four rules: