Design stable daemon embedding and complete Android ADB provider APIs

[thymikee]

Context

PR #478 adds an Android ADB provider seam inside the upstream agent-device daemon. It lets device-scoped Android ADB calls made by the upstream daemon route through an injected executor/spawner while local behavior keeps using adb -s <serial>.

That is useful, but it is not enough for external remote-daemon implementations such as agent-device-cloud to cleanly adopt upstream daemon behavior. agent-device-cloud currently owns its own command dispatcher, platform session contract, remote simulator lifecycle, leases, uploads, artifact policy, Metro/DevTools tunnels, and direct ADB execution paths. PR #478 does not affect those paths because they do not run through agent-device's internal request router.

Problem

The current useful hook, androidAdbProvider, lives on createRequestHandler, but the request router is not a supported package-level embedding API. The public export added in PR #478 is agent-device/android-adb, which exposes provider types/helpers but not the daemon hook that consumes them.

Also, Android ADB coverage is still split between upstream daemon internals and external bridges. Remote-device integrations need one clear provider surface for device-scoped Android operations, including command execution, binary stdout, stdin, push/pull, and long-running streams. They also need reusable higher-level Android behaviors that accept an executor without assuming local host discovery or local adb availability.

Proposed Direction

1. Publish a stable daemon embedding API.

Export a supported subpath such as agent-device/daemon with the pieces needed by embedders:

• createRequestHandler
• request-router dependency types
• auth hook types
• lease/session hook types where appropriate
• Android provider injection types
• artifact tracking hooks
• request/response contracts that are safe for package consumers

2. Make Android ADB provider coverage complete.

Define and document the provider contract for all device-scoped Android ADB operations:

• command exec with stdout/stderr/exit code
• binary stdout
• stdin
• push/pull or file transfer helpers
• long-running stream/spawn behavior such as logcat
• cancellation/timeout behavior
• clear fallback behavior when spawn or streaming is not available

3. Export higher-level Android helpers that accept an ADB executor.

Useful helpers include:

• launch and force-stop app
• list launcher/user apps
• foreground app state
• logcat capture/stream
• clipboard read/write
• keyboard status/dismiss
• runtime hints/dev prefs
• port reverse setup/cleanup

This would let remote bridges reuse upstream Android command behavior without delegating their whole daemon/session lifecycle to agent-device.

4. Add a first-class Android port reverse abstraction.

Remote Metro and React DevTools flows need persistent adb reverse state and cleanup. A general abstraction, backed by an injected ADB provider, would be useful for Docker, remote Linux hosts, CI Android farms, and cloud IDEs.

5. Separate device discovery from local host tooling.

Embedders should be able to inject device inventory/resolution rather than relying on local adb devices, simctl, or equivalent host tools.

6. Provide daemon conformance tests.

A package-level harness for "an agent-device-compatible daemon must support these request/response semantics" would let external bridges validate parity against upstream behavior without maintaining parallel assumptions.

Non-goals

• Do not move bridge auth, billing, tenant/run/lease policy, storage, uploads, or control-plane policy into upstream.
• Do not require remote daemons to use the upstream request router if they only want reusable Android helper behavior.

Acceptance Criteria

• A documented package-level daemon embedding surface exists.
• Android provider behavior is documented and covered by tests for exec, binary output, stdin, cancellation/timeouts, and streams/fallbacks.
• At least one reusable Android helper accepts an injected ADB executor and has tests proving local and injected behavior.
• Device inventory/resolution can be supplied by an embedder without shelling out to local host discovery.
• A conformance test harness exists or has a documented initial scope.