fix: optimize remote install artifact uploads (#413)

* fix: optimize remote install artifact uploads

* refactor: clean up upload client flow

* fix: fall back after direct upload failure

* docs: correct ios install source examples

Author: thymikee

skills/agent-device/references/bootstrap-install.md

@@ -17,6 +17,7 @@ Use this exact order when you are not sure about the installed app identifier. O
 ## Install path
 
 - `install` or `reinstall`
+- `install-from-source` when the artifact already exists at a URL the daemon can reach
 
 ## Most common mistake to avoid
 
@@ -60,14 +61,26 @@ agent-device install com.example.app ./build/app.apk --platform android --serial
 agent-device install com.example.app ./build/MyApp.app --platform ios --device "iPhone 17 Pro"
 ```
 
+```bash
+agent-device install-from-source https://example.com/builds/app.aab --platform android
+agent-device install-from-source https://api.github.com/repos/acme/app/actions/artifacts/123/zip --platform ios --header "authorization: Bearer TOKEN"
+```
+
 ## Install guidance
 
 - Use `install <app> <path>` when the app may already be installed and you do not need a fresh-state reset.
 - Use `reinstall <app> <path>` when you explicitly need uninstall plus install as one deterministic step.
+- Use `install-from-source <url>` when an existing artifact URL is already reachable by the daemon.
+- Local `.apk`, `.aab`, `.app`, and `.ipa` paths go through `install` or `reinstall`; existing reachable URLs go through `install-from-source`.
+- Do not download, re-zip, publish temporary GitHub releases, or move CI artifacts elsewhere just to make an install command work.
 - Keep install and open as separate phases. Do not turn them into one default command flow.
 - Supported binary formats:
   - Android: `.apk` and `.aab`
   - iOS: `.app` and `.ipa`
+- Android URL sources can be direct `.apk` or `.aab` files.
+- Trusted artifact service URLs, currently GitHub Actions and EAS, may point at archive-backed downloads that contain one installable artifact. This includes GitHub Actions artifact ZIPs whose URL path does not end in `.zip` and ZIPs containing one nested `.apk`, `.aab`, `.ipa`, or iOS `.app` tar archive.
+- If a trusted artifact archive contains multiple installables, stop and ask for the intended artifact instead of guessing.
+- `.aab` still requires `bundletool` in `PATH`, or `AGENT_DEVICE_BUNDLETOOL_JAR=<absolute-path-to-bundletool-all.jar>` with `java` in `PATH`, when the daemon installs the materialized artifact.
 - For iOS `.ipa` files, `<app>` is used as the bundle id or bundle name hint when the archive contains multiple app bundles.
 - After install or reinstall, later use `open <app>` with the exact discovered or known package/bundle identifier, not the artifact path.
 

skills/agent-device/references/remote-tenancy.md

@@ -27,6 +27,7 @@ agent-device connect \
   --remote-config ./remote-config.json
 
 agent-device install com.example.app ./app.apk
+agent-device install-from-source https://example.com/builds/app.apk --platform android
 agent-device open com.example.app --relaunch
 agent-device snapshot -i
 agent-device fill @e3 "test@example.com"
@@ -35,6 +36,20 @@ agent-device disconnect
 
 `connect` resolves the remote profile, verifies daemon reachability through the normal client path, allocates or refreshes the tenant lease, prepares local Metro when the profile has Metro fields, starts the local Metro companion when the bridge needs it, and writes local non-secret connection state for later commands. `disconnect` closes the session when possible, stops the Metro companion owned by that connection, releases the lease, and removes local connection state.
 
+After `connect`, normal `agent-device` commands use the active remote connection. Do not repeat `--remote-config` on every command.
+
+Remote install examples:
+
+```bash
+agent-device install com.example.app ./app.apk
+agent-device install-from-source https://example.com/builds/app.aab --platform android
+agent-device install-from-source https://api.github.com/repos/acme/app/actions/artifacts/123/zip --platform ios --header "authorization: Bearer TOKEN"
+```
+
+- Use `install` or `reinstall` for local paths; remote daemons upload local artifacts automatically.
+- Use `install-from-source` for artifact URLs the remote daemon can reach.
+- For local-path versus URL artifact rules, follow [bootstrap-install.md](bootstrap-install.md).
+
 Use `agent-device connection status --session adc-android` to inspect the active connection without reading JSON state manually. Status output must not include auth tokens.
 
 ## Remote config shape