Paired: Phone Agent

SKILL.md

---
name: paired
description: Paired: Phone Agent. Bridges an OpenClaw agent to the user's own phone via Bluetooth and ADB. Provides SMS receive (MAP/MNS), SMS send (ADB), outgoing/incoming calls (HFP), contacts (PBAP), media control (AVRCP), file transfer (OBEX), PAN tethering, and v2.0.0+ voice cloning so the agent speaks in the user's own voice with word-level audio splicing and 30-language multilingual synthesis. Zero recurring cost, no Twilio, Telnyx, Vapi, ElevenLabs, or rented numbers. Voice cloning runs locally via VoxCPM2 (primary, 48kHz studio) with XTTS v2 fallback (24kHz), piper fallback (generic), and espeak-ng last resort. Triggers on phrases like "send SMS", "text someone", "call my phone", "make a call", "what's on my phone", "my contacts", "phone contacts", "play music", "pause", "next track", "send file to phone", "tether", "paired devices", "is my phone connected", "say it in my voice", "voice note", "speak as me", "clone my voice", "Bluetooth", "BT", "/sms", "/phone", "/voice", "/say", "ofono", "AVRCP", "MAP". Configuration lives in ~/.config/paired/paired.conf (phone MAC, adapter, trusted numbers list) and ~/.config/paired/voice.conf (voice cloning config, only if voice features are enabled). Always read the config before acting; never hardcode phone identifiers.
capabilities:
  - sends-sms
  - places-phone-calls
  - reads-sms
  - reads-contacts
  - reads-clipboard
  - controls-mobile-device-via-adb
  - unlocks-mobile-device-with-stored-pin
  - bluetooth-pairing-agent
  - relays-to-external-channel-telegram
  - executes-sudo-commands
  - persistent-systemd-services
  - synthesises-cloned-voice
  - runs-local-docker-services
requires:
  config:
    - path: ~/.config/paired/paired.conf
      purpose: phone MAC, adapter, trusted numbers list
    - path: ~/.config/paired/trusted-numbers.conf
      purpose: allowlist for high-impact outgoing actions (calls, SMS sends)
    - path: ~/.config/paired/pin
      purpose: phone unlock PIN (mode 0600 enforced) — OPTIONAL, only if --auto-unlock used
      sensitive: true
    - path: ~/.config/paired/gemini-keys.conf
      purpose: Gemini API key(s) for paired-respond — OPTIONAL, only if SMS LLM auto-reply is enabled (mode 0600 enforced)
      sensitive: true
    - path: ~/.config/paired/voice.conf
      purpose: voice cloning config (VoxCPM2/XTTS URLs, reference WAV path, word-clips dir) — OPTIONAL, only if voice cloning is used
    - path: ~/.config/paired/voice/reference.wav
      purpose: user-recorded voice reference for cloning — OPTIONAL, generated by paired-voice-setup.py
      sensitive: true
    - path: ~/.config/paired/voice/word-clips/
      purpose: pre-recorded word clips for splicing — OPTIONAL
    - path: ~/.config/paired/inbox.key
      purpose: HMAC secret for paired-inbox-hook command dispatch (mode 0600 enforced) — generated by `paired-inbox-hook --keygen`
      sensitive: true
  system_packages:
    - bluez
    - ofono
    - android-tools-adb
    - systemd
  external_services:
    - telegram (optional, for command vocabulary and incoming-call/SMS alerts)
  python_packages:
    - dbus-python
safety:
  scope: owner-operated
  network_access: bluetooth-LAN-only-plus-user-own-telegram
  credential_handling: user-supplied-only-no-hardcoded-fallbacks
  high_impact_actions:
    - all SMS sends require trusted-numbers allowlist OR explicit --confirm
    - all outbound calls require trusted-numbers allowlist OR explicit --confirm
    - phone unlock requires --auto-unlock flag explicitly per invocation
    - pairing-agent default mode is interactive (auto mode requires explicit --mode auto)
  notes: |
    This skill controls the user's real phone. It is intended for use on a Linux
    host that the user owns, paired to a phone the user owns, with Telegram bot
    credentials the user controls. It is not safe to expose any of these channels
    to untrusted parties. The trusted-numbers allowlist gates outgoing SMS/calls;
    keep it short and review it regularly.
---

## Execution context

You are running on a Linux host with BlueZ + ofono installed and a phone paired over Bluetooth. The skill ships:

- **Low-level primitives** at `skill/bin/bt-*.py` — BlueZ/ofono/ADB direct interfaces
- **High-level wrappers** at `skill/wrappers/paired-*.py` — JSON-clean interfaces designed for agents to call
- **Systemd unit files** at `skill/systemd/*.service.txt` — for persistent listeners (SMS push, call watch, command hook). The `.txt` suffix is a packaging convention; rename to `.service` when copying into `~/.config/systemd/user/` (see Installation below).

## Installation

After `clawhub install paired`:

```bash
# 1. Symlink (or copy) the bin/ and wrappers/ scripts into ~/bin/, dropping .py from filenames
#    so the user/agent can invoke `paired-sms-send` rather than `paired-sms-send.py`.
mkdir -p ~/bin
for f in ~/.openclaw/workspace/skills/paired/bin/*.py; do
  ln -sf "$f" ~/bin/"$(basename "$f" .py)"
done
for f in ~/.openclaw/workspace/skills/paired/wrappers/*.py; do
  ln -sf "$f" ~/bin/"$(basename "$f" .py)"
done
for f in ~/.openclaw/workspace/skills/paired/wrappers/*.sh; do
  ln -sf "$f" ~/bin/"$(basename "$f" .sh)"
done
chmod +x ~/.openclaw/workspace/skills/paired/bin/*.py \
         ~/.openclaw/workspace/skills/paired/wrappers/*.py \
         ~/.openclaw/workspace/skills/paired/wrappers/*.sh

# 2. Optional: enable systemd user services. Strip the .txt suffix on copy.
mkdir -p ~/.config/systemd/user
for f in ~/.openclaw/workspace/skills/paired/systemd/*.service.txt; do
  cp "$f" ~/.config/systemd/user/"$(basename "$f" .txt)"
done
systemctl --user daemon-reload

# 3. One-time inbox HMAC key generation (required for paired-inbox-hook)
paired-inbox-hook --keygen

# 4. Optional: enable the inbox hook (HMAC-signed command dispatcher)
systemctl --user enable --now paired-inbox-hook.service
```

The `.py`, `.sh`, and `.service.txt` extensions exist to satisfy the ClawHub packaging text-file allowlist; on disk in your `~/bin/` and `~/.config/systemd/user/` they should be the unsuffixed names referenced throughout this document.

When reasoning about a phone task, prefer the high-level `paired-*` wrappers — they handle trust checks, error formatting, and JSON output. Drop to `bt-*` only for diagnostic or low-level work. **The low-level `bt-call` and `bt-sms` primitives now also enforce the trusted-numbers allowlist** (since v1.0.4) and refuse to dial/SMS unlisted numbers unless `--confirm` is passed.

**Acting on the world vs. answering questions:** for status queries ("is my phone connected?", "any new SMS?"), running the tool and reporting the result is the right call. For high-impact actions (sending SMS, dialling calls, pairing new devices, unlocking the phone), confirm with the user first unless the request is unambiguous and the destination is on the trusted-numbers allowlist.

**Phone identity comes from `~/.config/paired/paired.conf`**, key `phone_bt_mac`. If a command needs the phone's MAC, read it from the config rather than asking the user. If the config is missing, tell the user to copy `paired.conf.example` and fill in the MAC.

## Most-used commands

### Stack health and discovery

```bash
~/bin/bt-test                              # 10-check stack health (one-shot diagnostic)
~/bin/bt-adapters                          # list HCI adapters
~/bin/bt-list --paired                     # paired devices with CONN/PAIR/TRUST status
~/bin/bt-list --connected                  # only currently-connected
~/bin/bt-list --scan 10                    # 10-second scan for nearby
~/bin/bt-info <MAC>                        # full device detail (UUIDs, RSSI, profiles)
~/bin/bt-recover                           # USB-reset adapter if hung
```

### Pairing and connection

```bash
~/bin/bt-pair <MAC>                        # initiate pairing (passkey via bt-agent)
~/bin/bt-pair <MAC> --connect              # pair + trust + connect in one step
~/bin/bt-connect <MAC>                     # connect to an already-paired device
~/bin/bt-disconnect <MAC>
~/bin/bt-trust <MAC> | ~/bin/bt-untrust <MAC>
~/bin/bt-forget <MAC>                      # remove pairing entirely
```

### Phone — SMS

Receive (read-only via Bluetooth, fully working on most phones):

```bash
~/bin/paired-sms-watch --status            # is the MNS push daemon running?
~/bin/paired-sms-watch --last 10           # last 10 SMS the daemon caught
~/bin/bt-sms-list --map <MAC> --max 10     # explicit MAP read of recent
~/bin/bt-adb-sms-list --limit 10           # ADB read of inbox (works while phone is locked)
~/bin/bt-adb-sms-list --sent --limit 10    # sent folder
```

Send (via ADB-over-USB autosend — Bluetooth MAP send is blocked on most Samsung firmware):

```bash
~/bin/paired-sms-send <NUMBER> "<text>" --json
# Pass --auto-unlock to dismiss the lock screen using the PIN at
# ~/.config/paired/pin (mode 0600 enforced). Pass --relock to re-lock after.
# Without --auto-unlock, the tool returns error=keyguard_locked when phone is locked.
```

Telegram command shortcut: when the user types `/sms NUMBER text` in Telegram, run `~/bin/paired-sms-send NUMBER "text" --json` and report the JSON result. Quote the entire body as one argument.

### Phone — calls (HFP via ofono)

```bash
~/bin/paired-call status --json            # active calls in structured form
~/bin/paired-call dial <NUMBER>            # initiate outbound
~/bin/paired-call answer                   # accept incoming
~/bin/paired-call hangup                   # end all calls
~/bin/paired-call-and-speak <NUMBER> "<msg>" # dial + speak via Tasker TTS (see limits)
~/bin/bt-modems --full                     # ofono modem state, network registration
~/bin/paired-call-watch --last 10          # last 10 incoming calls caught by daemon
~/bin/paired-call-watch --status           # is the call watcher daemon running?
```

Real-time incoming-call alerts run as a systemd user service (`paired-call-watch.service`) — caught calls go to the user's Telegram via `paired-call-watch-tg-hook` with sender + trust-status info.

### Phone — Telegram command vocabulary (deterministic, bypasses LLM)

`paired-sms-command-hook.service` reads commands from a dedicated, append-only inbox at `~/.openclaw/paired/inbox/` (NOT from raw agent session logs — see Security model below) and dispatches recognised commands without invoking the LLM:

| Telegram command | Action | Trust check | Underlying call |
|---|---|---|---|
| `/sms <num> <body>` | Send SMS via ADB | **trusted-numbers allowlist required** (or `--confirm`) | `paired-sms-send` |
| `/phone <num>` | Dial outbound | **trusted-numbers allowlist required** (or `--confirm`) | `paired-call dial` |
| `/phone <num> <msg>` | Dial + speak via Tasker TTS, optional SMS fallback | **trusted-numbers allowlist required** | `paired-call-and-speak` |
| `/phone <num> attach <path>` | Dial + speak file content | **trusted-numbers allowlist required** | as above |
| `/phone hangup` (or `/phone end`) | End all active calls | none | `paired-call hangup` |
| `/phone status` | Active call state | none | `paired-call status` |

Trusted list at `~/.config/paired/trusted-numbers.conf` — managed via `~/bin/paired-trusted add | remove | list`. UK number normalization: `+44`, `0044`, `44`, and `07` formats all match the same entry. **An empty trusted-numbers file blocks all outgoing SMS and calls except for explicit `--confirm` invocations.** This is the safe default — fill the file in deliberately.

**SMS fallback for `/phone <num> <msg>`:** TTS during calls is blocked on some phone firmware (notably Samsung — see "Known phone-side limits" below). When TTS-during-call fails, the wrapper *can* also send an SMS with the same body so the recipient still gets the message. This is **opt-in per invocation** — pass `--with-sms-fallback` to enable it. Without that flag, a TTS failure returns an error and the wrapper does not send any SMS. The Telegram reply notes the chosen behaviour explicitly: "📞 TTS only" or "📞 TTS + 📨 SMS fallback (best-effort)".

### Security model (read this before enabling persistent services)

This skill runs **persistent systemd services** that can dispatch phone actions automatically:

- `paired-sms-watch.service` — listens for incoming SMS (via Bluetooth MAP-MNS), forwards alerts to Telegram. Read-only with respect to the phone.
- `paired-call-watch.service` — listens for incoming calls (via ofono D-Bus), forwards alerts to Telegram. Read-only.
- `paired-sms-command-hook.service` — reads command messages from `~/.openclaw/paired/inbox/`, dispatches recognised commands. **This is the surface that can act.** It accepts commands ONLY from a directory the user controls, with a per-message HMAC signature using a secret in `~/.config/paired/inbox.key` (mode 0600). Commands from any other source — raw session logs, the agent's chat memory, an SMS body, etc. — are NOT dispatched.

**Why the inbox model:** earlier versions of this skill parsed the agent's session JSONL log directly. That made the session log a control surface — anything that landed in it (including unfiltered text from incoming SMS/calls) was a potential command source. The inbox model isolates the dispatch surface to messages the user (or a trusted bot relay) explicitly drops into the inbox dir, signed with the inbox key.

**To stop all persistent services in one go:**

```bash
systemctl --user stop paired-sms-watch paired-call-watch paired-sms-command-hook
systemctl --user disable paired-sms-watch paired-call-watch paired-sms-command-hook
```

### Phone — contacts (PBAP)

```bash
~/bin/bt-contacts <MAC> --max 10           # list 10 contacts
~/bin/bt-contacts <MAC> --pull             # pull entire phonebook to ~/Downloads/bluetooth/<mac>.vcf
~/bin/bt-contacts <MAC> --search "name"    # search by name
```

### Phone — media (AVRCP via BT, fallback to ADB)

```bash
~/bin/paired-media status --json           # current track + status (auto BT/ADB transport)
~/bin/paired-media play | pause | next | prev | stop
~/bin/paired-media volume 50               # set BT volume 0-100
~/bin/paired-media current                 # what's playing right now
```

Auto-detects connected phone, picks BT/AVRCP first then falls back to ADB media controller.

### File transfer (OBEX)

```bash
~/bin/bt-send <FILE> <MAC>                 # push file to phone
~/bin/bt-receive                           # listen for incoming pushes (saves to ~/Downloads/bluetooth/)
~/bin/bt-browse <MAC>                      # OBEX-FTP browse (vendor-dependent)
```

### Network (PAN)

```bash
~/bin/bt-pan up <MAC>                      # connect as NAP client (phone-side BT-tethering must be ON)
~/bin/bt-pan down                          # disconnect
~/bin/bt-pan status                        # show bnep0 state
```

### GATT / BLE

```bash
~/bin/bt-gatt-tree <MAC>                   # enumerate services + characteristics
~/bin/bt-gatt-read <MAC> <UUID>            # read a characteristic
~/bin/bt-gatt-write <MAC> <UUID> <HEX>     # write a characteristic
```

### Audio

```bash
~/bin/bt-audio <MAC> --info                # available profiles
~/bin/bt-volume <MAC>                      # current volume
~/bin/bt-play <FILE> <MAC>                 # play file through BT speaker
```

## LLM-drafted SMS reply (showcase feature, opt-in)

When an SMS arrives whose body starts with the phrase set in `paired.conf[llm_trigger]` (default: `"Hi Agent,"`) **and** the sender is on the `paired.conf[llm_trigger_whitelist]`, `paired-respond` will:

1. Strip the trigger prefix
2. Call the configured LLM (Gemini / OpenAI / local) with a tight system prompt
3. Post a richer Telegram alert containing sender, original question, drafted reply, and a tap-to-copy `/sms` command

The user decides whether to send the draft by tapping the `/sms` line. **No automatic SMS reply.** Empty whitelist disables the feature. Logs at `~/.paired/sms-respond.log`.

## Common phrasings → tool mapping

- "Stack health?" → `~/bin/bt-test`
- "What's paired?" / "What devices?" → `~/bin/bt-list --paired`
- "Is my phone connected?" → `~/bin/bt-list --connected | grep -i <phone-label>`
- "Pair with X" → `~/bin/bt-pair X --connect`
- "Network signal?" → `~/bin/bt-modems --full`
- "Any new SMS?" / "Watch SMS" → `~/bin/paired-sms-watch --last 5`
- "Is SMS watcher running?" → `~/bin/paired-sms-watch --status`
- `/sms NUMBER text` → `~/bin/paired-sms-send NUMBER "text" --json`
- "Reply to that SMS with X" → user provides text; you call `paired-sms-send LAST_SENDER "X" --json`. Get LAST_SENDER from the most recent `~/.paired/sms-events.jsonl` entry.
- "Call NUMBER" → `~/bin/paired-call dial NUMBER --json`
- "Hang up" → `~/bin/paired-call hangup --json`
- "Pause music" / "play music" / "next song" → `~/bin/paired-media pause/play/next`
- "What's playing?" → `~/bin/paired-media current`

## Known phone-side limits (clean errors, not bugs)

These are **phone-firmware constraints, not skill bugs**. The tools return clean errors and the docs explain workarounds.

### Samsung firmware (Note 8/9/10/20, S-series tested through OneUI 12)

- **SMS-send via Bluetooth (HFP / MAP) is blocked.** Samsung firmware does not implement `MAP UpdateInbox` and ofono SMS-send returns access-denied. Workaround: use `paired-sms-send` (ADB-over-USB autosend) — fully working.
- **In-call TTS is blocked at the audio policy level.** Samsung Telecom holds `AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE | AUDIOFOCUS_FLAG_LOCK` for the entire ring+call lifecycle. No third-party app (Tasker included) can inject audio into the call audio path. The `paired-call-and-speak` tool runs but the recipient hears silence — **SMS fail-soft compensates** (the message body is also sent as SMS, recipient guaranteed to receive). On non-Samsung devices (Pixel/AOSP, LineageOS, rooted) this is expected to work normally.
- **OBEX-FTP browse not advertised.** Use `bt-send` to push files instead.

### ofono + PipeWire (Debian 13, Ubuntu 24.04)

- **Two-way SCO audio in calls is blocked.** ofono 2.16 + PipeWire 1.4.x + libspa-bluetooth 1.4.x do not cooperate for HFP audio routing on current Debian. Outgoing calls work — the audio just routes through the phone earpiece, not the host's speaker/mic. Tested on both BCM43142 BT 4.0 and RTL8761B BT 5.1 adapters. `paired-sco-agent` is shipped as experimental — see `docs/ARCHITECTURE.md`.
- **A2DP source profile (phone music → host speaker)** is blocked by the same conflict. Receive (host as sink) works; source does not.

### General

- The "Hi Agent," LLM trigger is **opt-in** via `paired.conf` and bound to a **whitelist**. Default config has the whitelist empty, which keeps the feature off until the user explicitly trusts a number.
- Auto-unlock is **opt-in only**. Storing a phone PIN on the host is a security trade — see `paired.conf.example` for the warning.

## Architecture notes

- ofono owns HFP. PipeWire bluez monitor loaded but A2DP-source profile blocked by ofono/PipeWire HFP backend conflict — known trade-off, documented in `docs/ARCHITECTURE.md`.
- `bt-agent.service` runs as a system service to handle pairing PIN/passkey requests.
- The `paired-*` wrappers are the agent-facing interface; the underlying `bt-*` tools are CLI primitives that wrap BlueZ D-Bus and ofono D-Bus directly. Wrappers add JSON output, trust gating, fail-soft behaviour, and Telegram integration.

## Hardware compatibility

See `docs/HARDWARE-COMPATIBILITY.md` for the full matrix. Tested combinations:

| Phone | Android | What works | What's blocked |
|---|---|---|---|
| Samsung Note 9 | 10 / OneUI 12 | Pairing, contacts, SMS receive, outgoing calls, media, file push, PAN, ADB SMS send | In-call TTS, two-way SCO, MAP send, A2DP source |

| Adapter | Type | Status |
|---|---|---|
| BCM43142A0 | Internal BT 4.0 | All features tested working |
| RTL8761B | USB BT 5.1 | All features tested working |

## Setup checklist (for first-time users)

1. **Pair your phone:**
   ```bash
   ~/bin/bt-list --scan 10                # find your phone in the scan output
   ~/bin/bt-pair <MAC> --connect          # pair, trust, connect
   ```

2. **Write your config:**
   ```bash
   cp config-templates/paired.conf.example ~/.config/paired/paired.conf
   $EDITOR ~/.config/paired/paired.conf   # set phone_bt_mac, adapter, etc.
   ```

3. **Set up the trusted-numbers list (optional, recommended):**
   ```bash
   cp config-templates/trusted-numbers.conf.example ~/.config/paired/trusted-numbers.conf
   ~/bin/paired-trusted add 07911123456 "main mobile"
   ~/bin/paired-trusted list
   ```

4. **Enable the systemd user services you want:**
   ```bash
   systemctl --user enable --now paired-sms-watch.service       # real-time SMS push
   systemctl --user enable --now paired-call-watch.service      # incoming call alerts
   systemctl --user enable --now paired-sms-command-hook.service # /sms /phone Telegram commands
   ```

5. **Verify:**
   ```bash
   ~/bin/bt-test                          # 10-check stack health
   ```

If everything's green, the agent is ready to use the skill.