# Agent Phone Use: machine instructions

This is the machine-facing entry point. Human readers should use [English](README.md) or [中文](README.zh-CN.md).

Read the bundled [SKILL.md](skill/agent-phone-use/SKILL.md) and [agent runbook](skill/agent-phone-use/references/agent-runbook.md) before changing the machine. The runbook owns detailed diagnosis, Computer Use behavior, safety boundaries, and regression requirements.

## Compatibility gate

This release supports only a Windows 10/11 computer controlling an Android 11+ phone or tablet. It does not support iPhone/iPad (iOS/iPadOS), and its installer and shortcut are not packaged or tested for macOS/Linux computers. Upstream scrcpy availability on another desktop OS does not make these Windows PowerShell/VBS artifacts portable.

Verify the host OS and target platform before changing the machine. If either is outside that range, stop and explain the boundary; do not improvise an iOS flow or translate the installer to another OS during setup. Android menu names and extra control permissions vary by manufacturer and system version, so follow the observed device and error rather than assuming one vendor.

## Interaction contract

The Android device owner should do only these actions:

1. connect the phone to the same trusted Wi-Fi as the Windows computer;
2. enable Developer options and Wireless debugging;
3. open **Pair device with pairing code**;
4. provide the temporary six-digit code and keep the pairing screen open;
5. unlock or confirm a phone-side security prompt when Android requires it.

Own every Windows-side action. Do not ask a non-technical user to install scrcpy, open PowerShell, copy an IP address, select an mDNS endpoint, create a shortcut, or run a self-check.

Communicate in the user's language. Ask for the pairing code only when the pairing service is ready. Do not repeat the code in commentary or the final response.

## Standard setup sequence

### 0. Acquire the repository

If the repository is not already mounted in the current workspace, use the GitHub URL supplied by the user and acquire it yourself. Do not ask the user to download or extract it.

Prefer Git when available:

```powershell
git clone <repository-url>
Set-Location <repository-folder>
```

Otherwise, download the source archive from that exact GitHub repository and extract it into an agent-controlled workspace. Before running anything, verify that the root contains `install.ps1`, `README.agent.md`, and `skill\agent-phone-use\SKILL.md`.

All following commands assume the repository root as the working directory.

### 1. Inspect before changing

Confirm Windows 10/11, then check WinGet and any existing official scrcpy installation:

```powershell
$os = Get-CimInstance Win32_OperatingSystem
$os | Select-Object Caption, Version
$PSVersionTable.PSVersion
Get-Command winget, scrcpy, adb, wscript, powershell -ErrorAction SilentlyContinue
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  ".\skill\agent-phone-use\scripts\start-agent-phone-use.ps1" `
  -ToolsOnly -NoGui
```

An existing tool probe may fail when scrcpy is not installed. Treat that as a discovery result, not proof of a phone failure.

### 2. Install scrcpy only from its official source

Prefer the official WinGet package:

```powershell
winget install --id Genymobile.scrcpy --exact `
  --accept-source-agreements --accept-package-agreements
```

The only official project source is `https://github.com/Genymobile/scrcpy`. Do not use mirrors, repacks, similarly named download sites, or unrelated ADB binaries.

After installation, rerun `-ToolsOnly -NoGui`. Verify both `scrcpy.exe --version` and the sibling `adb.exe version`; PATH presence alone is not proof.

### 3. Pair using the code supplied by the owner

First ask the owner to keep **Wireless debugging → Pair device with pairing code** visible. The helper discovers exactly one `_adb-tls-pairing._tcp` service, so do not request or hard-code the phone IP or port.

Pass the temporary code through a process-scoped environment variable. The helper validates six digits, pipes the value to ADB over standard input, and clears its inherited copy. The code is not placed in the ADB argument list, a file, configuration, or launcher log.

```powershell
$env:APU_PAIRING_CODE = "<six-digit-code>"
try {
    powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
      ".\skill\agent-phone-use\scripts\pair-android-wireless.ps1"
} finally {
    Remove-Item Env:APU_PAIRING_CODE -ErrorAction SilentlyContinue
}
```

Use this environment form only through a non-interactive agent execution surface that does not persist shell history. Never echo the substituted command, code, or environment value back to the user, and never put it in a reusable script or shell profile.

If working through an interactive terminal, launch the helper without `APU_PAIRING_CODE` and use the agent's input-control capability to type the code at ADB's prompt. This keeps it out of command history. The owner may also choose to type it personally.

Pairing and ordinary connection are different:

- `_adb-tls-pairing._tcp` is used only for the temporary-code step.
- `_adb-tls-connect._tcp` is used for daily connection and scrcpy.

Never reuse a pairing port as the connection port.

### 4. Install the skill and desktop shortcut

For Codex, install both:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\install.ps1"
```

The installed skill becomes discoverable automatically in a new Codex task. Continue the current setup from the repository artifacts; tell the user to start a new task only when they want later requests to trigger the installed skill.

For a different agent host that does not use Codex skills:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\install.ps1" -SkipSkill
```

Pass `-ScrcpyDir "<official-folder>"` only when the launcher cannot find a manually extracted official release. The installer backs up a previous skill or changed runtime before replacement.

### 5. Verify ground truth

Run the non-visual check:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  ".\skill\agent-phone-use\scripts\start-agent-phone-use.ps1" `
  -SelfCheck -NoGui
```

Success requires exit code `0` and one `READY <endpoint>` line. Do not expose that endpoint in the final response.

The default action name is `连接 Android 手机.lnk` on a Chinese Windows UI and `Connect Android Phone.lnk` on other Windows UI languages. Read both the current-user and common desktop sources that Explorer merges, require exactly one current managed action shortcut, and verify that it targets `wscript.exe` with the installed `start-hidden.vbs`. Old managed aliases must no longer be active, and Explorer must visually show one icon after a rename or migration.

```powershell
$desktops = @(
    [Environment]::GetFolderPath('DesktopDirectory'),
    [Environment]::GetFolderPath('CommonDesktopDirectory')
) | Where-Object { $_ } | Sort-Object -Unique
$currentNames = @('连接 Android 手机.lnk', 'Connect Android Phone.lnk')
$currentShortcuts = @($desktops | ForEach-Object {
    $desktop = $_
    $currentNames | ForEach-Object {
        $path = Join-Path $desktop $_
        if (Test-Path -LiteralPath $path -PathType Leaf) { $path }
    }
})
if ($currentShortcuts.Count -ne 1) {
    throw "Expected exactly one current Android phone shortcut; found $($currentShortcuts.Count)."
}
$shortcutPath = $currentShortcuts[0]
$shortcut = (New-Object -ComObject WScript.Shell).CreateShortcut($shortcutPath)
$shortcut | Select-Object TargetPath, Arguments, WorkingDirectory, IconLocation
Start-Process -FilePath $shortcutPath
```

Confirm a live scrcpy window and process. Launch the shortcut a second time and confirm that the single-instance guard does not create another scrcpy process. Also compare the immediate directory set of both real desktop roots before and after setup/testing. The process must not create engineering or test directories such as `.agents`, `.codex`, `.git`, fixture roots, or backup folders on the desktop; test roots belong under the system temporary directory and recoverable backups belong under the runtime backup directory. A file existing or a command returning zero is not enough.

Tell the user setup is complete only after the real launch succeeds. Do not include endpoints, device IDs, logs, or the pairing code in the handoff.

## Method reference

| Method | Purpose | Inputs | Verifiable result |
|---|---|---|---|
| `install.ps1` | Install/update the bundled Codex skill and desktop runtime | `-ScrcpyDir`, `-SkillsRoot`, `-SkipSkill`, `-SkipShortcut`, `-SkipLegacyMigration` | Recoverable backup when updating; installed files and/or shortcut |
| `scripts/pair-android-wireless.ps1` | Discover one pairing service and run one-time ADB pairing | `-ScrcpyDir`, optional `-PairingEndpoint`; optional process env `APU_PAIRING_CODE` | ADB pairing succeeds without persisting the code |
| `scripts/install-shortcut.ps1` | Install or repair the hidden desktop launcher | optional `-ScrcpyDir`, `-InstallDir`, `-ShortcutPath`, legacy-path parameters, `-SkipLegacyMigration` | Exactly one localized action shortcut resolves to `wscript.exe → start-hidden.vbs`; recognized managed aliases move to a recoverable backup; an unverified product-named conflict stops setup |
| `scripts/start-agent-phone-use.ps1 -ToolsOnly -NoGui` | Resolve and probe the official scrcpy/ADB pair | optional `-ScrcpyDir` | Prints tool paths after real version probes |
| `scripts/start-agent-phone-use.ps1 -SelfCheck -NoGui` | Discover, connect, and check exact device state without opening scrcpy | optional `-ScrcpyDir` | Exit `0`; one `READY` result |
| `scripts/start-agent-phone-use.ps1` | Start daily control | optional `-ScrcpyDir`, `-NoGui` | One live scrcpy chain; duplicate launch exits quietly |
| `scripts/start-hidden.vbs` | Hide the PowerShell console for daily use | installed runtime files | scrcpy appears without a terminal window |

Use paths relative to the skill folder when the skill is installed independently. Use the repository paths shown in the standard sequence when operating from a clone.

## Safe diagnosis

- No `_adb-tls-connect._tcp`: ask the owner to wake/unlock the phone, confirm the same trusted Wi-Fi, and re-enable Wireless debugging. Pairing may still be saved.
- Paired-computer entry still present: reconnect; do not re-pair automatically.
- Paired-computer entry gone: repeat the pairing-code flow.
- Multiple connect services: stop and ask the owner to disable Wireless debugging on unintended devices. Do not guess.
- Duplicate `adb devices` rows: one phone may have endpoint and mDNS aliases. Pin every device-specific action with `adb -s <selected-endpoint>`.
- Input blocked on a manufacturer build: request only the phone-side security setting that the observed error requires.
- Secure app surface, lock screen, banking/payment, DRM, biometric, or work-profile boundary: stop and return control to the owner.

Do not change firewall rules, expose ADB publicly, revoke authorizations, forget devices, reset Developer options, kill unrelated processes, or install a third-party mobile MCP merely to make setup pass.

## Computer Use after setup

scrcpy window capture may work while the window is occluded, but Windows click/type injection can still steal focus. Tell the user to pause during consequential actions.

Use an observe → one bounded action → immediate refresh → wait about 0.5–1.2 seconds → fresh observation loop. Do not reuse stale screenshot IDs or coordinates. Allow Chinese IME composition to commit before verification. Stop on main/clone ambiguity. Confirm app, account, recipient, and full content immediately before an outbound send, then read back the sender-side result.

For repeatable high-consequence automation, evaluate a reviewed semantic Android control surface instead of relying on pixel coordinates. Do not default to the first device.

## Uninstall or revoke

Close scrcpy first. Remove the desktop shortcut and `%LOCALAPPDATA%\AgentPhoneUse` only when the user asks to uninstall the launcher. Remove `%USERPROFILE%\.codex\skills\agent-phone-use` only when they also want the Codex skill removed.

For full ADB revocation, ask the owner to use the phone's **Wireless debugging → Paired devices → Forget** action. Do not forget the workstation merely to repair a connection; pairing may still be valid when only the Wireless debugging switch is off.

## Repository validation

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\tests\launcher-regression.ps1"
python ".\tests\docs_contract.py"
python ".\tests\publication_scan.py"
python ".\tests\quick_validate.py" ".\skill\agent-phone-use"
```

Before publication, scan the tracked tree for real endpoints, mDNS instances, device serials, usernames, pairing codes, private conversations, and runtime logs. Documentation-only placeholders and synthetic test values must be visibly non-production.

Primary references:

- `https://developer.android.com/tools/adb`
- `https://github.com/Genymobile/scrcpy`
- `https://github.com/Genymobile/scrcpy/blob/master/doc/connection.md`
- `https://github.com/Genymobile/scrcpy/blob/master/doc/keyboard.md`
- `https://github.com/Genymobile/scrcpy/blob/master/doc/shortcuts.md`
- `https://developer.android.com/training/testing/other-components/ui-automator`