Activities¶

Launching Android activities (adb shell am start), resolving which activity would handle an intent without launching it (cmd package resolve-activity), and reading the current foreground activity.

`get_foreground_activity` ¶

Report the currently resumed/top Activity: adb shell dumpsys activity activities.

The way to confirm what's actually in front after a start_activity (or a tap, or a back press) — parses the resumed-activity markers out of dumpsys instead of returning the raw dump.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
`ForegroundActivitySnapshot`	resolved (False when nothing is resumed anywhere — screen off, all apps stopped — which is a valid answer, not an error), and when resolved: component ("package/class"), package_name, activity_class, user_id, display_id and task_id of the globally-focused Activity, plus per_display — the resumed Activity of each display that has one (more than one entry only on a multi-display device).

Error handling

An unknown serial raises DEVICE_NOT_FOUND; an unreachable adb binary raises ADB_UNAVAILABLE. Output whose format this build's dumpsys doesn't match parses to resolved=false rather than raising.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "com.android.car.carlauncher/.CarLauncher is foreground on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "resolved": true,
    "component": "com.android.car.carlauncher/.CarLauncher",
    "package_name": "com.android.car.carlauncher",
    "activity_class": ".CarLauncher",
    "user_id": 10,
    "display_id": 0,
    "task_id": 1000004,
    "per_display": [
      {
        "display_id": 0,
        "component": "com.android.car.carlauncher/.CarLauncher",
        "package_name": "com.android.car.carlauncher",
        "activity_class": ".CarLauncher",
        "user_id": 10,
        "task_id": 1000004
      }
    ]
  },
  "error": null
}

`resolve_activity` ¶

Resolve which Activity would handle an Intent, without launching it: cmd package resolve-activity.

The safe way to find out what start_activity (or the system) would pick for a given Intent — nothing is started. Describe the Intent with the typed fields below (at least one is required); they map to the same -a/-d/ -t/-c/-n/-p options Android's own tooling uses.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`action`	`str \| None`	Intent action, e.g. "android.intent.action.VIEW" (`-a`).	`None`
`data_uri`	`str \| None`	Intent data URI, e.g. "https://example.com" (`-d`).	`None`
`mime_type`	`str \| None`	Explicit MIME type, e.g. "text/plain" (`-t`).	`None`
`categories`	`list[str] \| None`	Intent categories, e.g. ["android.intent.category.HOME"] (`-c`, repeatable).	`None`
`component`	`str \| None`	An explicit "package/class" component to resolve (`-n`) — resolution still confirms it exists and is enabled.	`None`
`package_name`	`str \| None`	Constrain resolution to one package (`-p`).	`None`
`user_id`	`int \| None`	Resolve as one Android user (`--user`, see list_users).	`None`

Returns:

Type	Description
`ResolvedActivity`	resolved (False for the normal "no activity handles this" outcome, not an error), and when resolved: component ("package/class"), its package_name and activity_class, is_default (whether the winner is a registered default handler vs. the system resolver), the match hex, and priority.

Error handling

Specifying no Intent fields at all, or a negative user_id, raises INVALID_ARGUMENT before any adb call. A malformed component string (not "package/class" shape) also raises INVALID_ARGUMENT — Android's Intent parser rejects it. An unknown serial raises DEVICE_NOT_FOUND; an unreachable adb binary raises ADB_UNAVAILABLE. A build whose resolve-activity lacks an option used here raises BACKEND_ERROR.

Example

Called with serial="emulator-5554", action="android.intent.action.MAIN", categories=["android.intent.category.HOME"]. A typical response:

{
  "status": "success",
  "message": "com.android.car.carlauncher/.CarLauncher resolves that intent on emulator-5554 (default).",
  "data": {
    "serial": "emulator-5554",
    "resolved": true,
    "component": "com.android.car.carlauncher/.CarLauncher",
    "package_name": "com.android.car.carlauncher",
    "activity_class": ".CarLauncher",
    "is_default": true,
    "match": "0x108000",
    "priority": 0
  },
  "error": null
}

`start_activity` ¶

Launch an Android activity on a device: adb shell am start.

Models the launch target semantically (an explicit component) rather than accepting a raw am command string — see the module docs for why this server never exposes arbitrary shell arguments. Only an explicit component launch is supported; other Intent options (action, extras, flags, data URI) are not, and this tool never starts broadcasts or services (use send_broadcast or start_service for those).

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`component`	`str`	The activity to launch, in "package/class" form, e.g. "com.example.app/.MainActivity" (`-n`). A relative class name (starting with ".") is resolved against the package.	required
`user_id`	`int \| None`	Launch the activity as one specific Android user (`--user`, see list_users). Omit to use am's default user.	`None`
`display_id`	`int \| None`	Launch the activity on one specific display (`--display`, see list_displays). Omit to use the default display.	`None`
`wait_for_launch`	`bool`	Wait for the launch to complete and report detailed status (`-W`): populates status/launch_state/total_time_ms/ wait_time_ms/activity. Without it (the default), `am start` is fire-and-forget — success=True only means the request wasn't immediately rejected, not that the activity finished launching.	`False`

Returns:

Type	Description
`StartActivityResult`	Whether the launch succeeded, the component requested, and — only when wait_for_launch=True and available — the ActivityManager- confirmed activity and launch timing/status detail. On a launch failure that isn't a bad request (success=False), error_type/ error_message carry ActivityManager's own error text.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error. A malformed component string (not "package/class" shape) raises COMPONENT_NOT_FOUND; a protected activity the caller isn't allowed to start raises PERMISSION_DENIED; any other ActivityManager transport failure raises a generic BACKEND_ERROR. A well-formed component that ActivityManager can't resolve or launch (e.g. a class that doesn't exist) is NOT a tool error — it's a normal response with success=False and error_type/error_message populated, since that's a genuine launch outcome rather than a bad call.

Example

Called with serial="emulator-5554", component="com.example.app/.MainActivity". A typical response:

{
  "status": "success",
  "message": "Launched com.example.app/.MainActivity on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "component": "com.example.app/.MainActivity",
    "user_id": null,
    "display_id": null,
    "wait_for_launch": false,
    "success": true,
    "activity": null,
    "status": null,
    "launch_state": null,
    "total_time_ms": null,
    "wait_time_ms": null,
    "error_type": null,
    "error_message": null,
    "output": "Starting: Intent { cmp=com.example.app/.MainActivity }\n"
  },
  "error": null
}

Activities¶

get_foreground_activity ¶

resolve_activity ¶

start_activity ¶

`get_foreground_activity` ¶

`resolve_activity` ¶

`start_activity` ¶