Module agent 

The resident agent from the host side (design D2 and D3): deploying it, reusing or replacing a running one, and the connection a session drives.

• AgentJar is the single-dex jar agent-android/build.sh writes and the version its hello must name.
• Deployer::attach reuses a running agent this host started when its protocol and agent versions match, replaces one that does not, and otherwise pushes the jar read-only, starts it detached as the shell user with a per-launch socket name and token, and waits for its ready line. Another holder of UI automation is reported as a Conflict naming the likely holder, and taken over only with DeployOptions::force.
• Connection drives the protocol crate’s HostSession over the agent’s abstract socket, opened as an adb service stream, on a reader thread that answers pings and delivers responses and events.

Nothing is installed on the device: no package, no instrumentation, no forward rule. The pushed jar is deleted once the agent has started, and the agent exits on shutdown, on its idle bound without a host, or when a host refuses its protocol version.

Structs

AgentInfo

The agent a connection reaches.

AgentJar

The agent’s jar, read into memory, and the version its hello must name.

Attached

A connection to an agent, with how it was obtained.

Conflict

Another process holds UI automation.

ConflictLine

The line the agent prints before exiting with status 3 when another process holds UI automation: conflict pid=<pid> holder=<name> holder_pid=<pid or -> message=<text>.

Connection

A live connection to one agent. Dropping it closes the connection; the agent keeps running.

DeployOptions

How to attach.

Deployer

Deploys one agent build on one device. Clones share the records.

Holder

A process named in an agent’s report: uiautomator and its pid.

JarError

The jar could not be read.

Launched

A launch.

ReadyLine

The line the agent prints once it holds UI automation and listens: ready socket=<name> pid=<pid> uid=<uid> protocol=<n> capabilities=0x<bits> ownership=held connect_ms=<ms> window_wait_ms=<ms> windows=<n> active=<package> forced=<name:pid or ->.

Record

One agent this host started.

Records

The records of one host, shared by every clone.

Replaced

An incompatible agent that was stopped.

RunningAgent

An agent process found in the process list.

SocketName

A per-launch socket name that also says which agent listens on it: mobile-agent-<version>-p<protocol>-<build>-<id>. The process list shows it, so the agent state of a target is known without connecting, which would take the agent’s connection away from whoever holds it. The build tells apart two builds that report the same version.

Timings

Where an attach spent its time.

Enums

AgentState

Whether an agent runs on a target, from the process list alone: an attach would take the agent’s connection away from whoever holds it, so the state is read from the socket name, which says the version.

Compatibility

Whether an agent can be reused, from its handshake.

DeployError

Why an attach or a stop failed.

Incompatibility

Why a running agent cannot be reused.

Outcome

How an attach went.

Stopped

How an agent ended.

Constants

AGENT_NAME

The name every agent build puts before its version in its hello.

AGENT_VERSION

The agent version this driver deploys: agent-android/VERSION, which build.sh compiles into the agent’s banner and hello, read through the crate’s AGENT_VERSION, a link to it that the crate’s package holds as a copy of the file.

JAR_MODE

Mode of the pushed jar: read-only for everyone. adbd copies the owner’s bits to group and other, so 0o444 is the one mode that arrives unwidened and never writable (task 5.1 measured 0o644 arriving as 0666).

JAR_VAR

Environment variable naming the jar to deploy instead of the default.

MAIN_CLASS

The class app_process starts.

PROCESS_NAME

The name the agent gives itself in the process list, followed by its socket name: mobile-agent <socket>.

PS_COMMAND

Lists every process with its command line, where the agent appears as mobile-agent <socket>.

TOKEN_VARIABLE

The environment variable that carries the per-launch token, which keeps it out of the process list.

Functions

agent_state

The state agents add up to for a driver deploying build of version over protocol: running when one of them is that build, else incompatible when any runs.

compatibility

Judges a running agent by its handshake: compatible when the host accepted its hello and it is the build expected_agent names (mobile-agent-android <version>).

default_jar_path

Where agent-android/build.sh writes the jar in this source tree.

launch_command

The shell command that starts the agent from the jar at jar, listening on socket, and returns at once, leaving it running.

parse_agents

The agents in PS_COMMAND’s output: processes named mobile-agent <socket>, and app_process running the agent’s main class where the process could not rename itself. Wrappers such as timeout and the shell that started them are left out.

parse_conflict

Parses a conflict line; None for any other line.

parse_ready

Parses a ready line; None for any other line.

push_jar

Pushes jar to remote read-only (super::JAR_MODE).

random_hex

bytes random bytes from the operating system as lowercase hex.

remote_jar

Where the jar of the launch whose socket is socket is pushed.

Type Aliases

EventSink

Receives the session’s events other than responses, with the host time each arrived: protocol events, sequence gaps and resyncs, and finally Closed.