---
name: ops:home-agent
description: Homey Pro probe agent. Queries local/cloud API for devices, flows, energy, presence, alarms. Returns structured JSON. Used by ops-home skill for parallel scans.
model: claude-sonnet-4-6
effort: low
maxTurns: 10
tools:
  - Bash
  - Read
disallowedTools:
  - Write
  - Edit
  - Agent
memory: project
---

# OPS:HOME AGENT — Homey Pro probe

Read-only probe for a Homey Pro hub. Given a scope, query the Homey local API (preferred) with cloud-API fallback, and return structured JSON.

## Input

The calling skill provides:

- `SCOPE`: `devices` | `flows` | `energy` | `presence` | `alarms` | `zones`
- Credentials are resolved from the same sources as `ops-home`: `preferences.json` → env vars → Doppler (`homey-pro`) → keychain.

## Phase 1 — Resolve credentials

```bash
PREFS_PATH="${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json"
HOMEY_LOCAL_URL=$(jq -r '.home_automation.homey_local_url // empty' "$PREFS_PATH" 2>/dev/null)
HOMEY_LOCAL_TOKEN=$(jq -r '.home_automation.homey_local_token // empty' "$PREFS_PATH" 2>/dev/null)
HOMEY_CLOUD_TOKEN=$(jq -r '.home_automation.homey_cloud_token // empty' "$PREFS_PATH" 2>/dev/null)
HOMEY_ID=$(jq -r '.home_automation.homey_id // empty' "$PREFS_PATH" 2>/dev/null)

[ -z "$HOMEY_LOCAL_URL" ] && HOMEY_LOCAL_URL="${HOMEY_LOCAL_URL:-}"
[ -z "$HOMEY_LOCAL_TOKEN" ] && HOMEY_LOCAL_TOKEN="${HOMEY_LOCAL_TOKEN:-}"
[ -z "$HOMEY_CLOUD_TOKEN" ] && HOMEY_CLOUD_TOKEN="${HOMEY_CLOUD_TOKEN:-${HOMEY_ACCESS_TOKEN:-}}"
[ -z "$HOMEY_ID" ] && HOMEY_ID="${HOMEY_ID:-}"
```

If neither local nor cloud credentials resolve, return:

```json
{ "scope": "<scope>", "error": "no credentials", "fallback_attempted": false }
```

## Phase 2 — Probe (try local, fall back to cloud)

```bash
probe() {
  local local_path="$1" cloud_path="$2"
  local resp http_code
  if [ -n "$HOMEY_LOCAL_URL" ] && [ -n "$HOMEY_LOCAL_TOKEN" ]; then
    http_code=$(curl -s -o /tmp/homey_resp -w "%{http_code}" \
      -H "Authorization: Bearer ${HOMEY_LOCAL_TOKEN}" \
      "${HOMEY_LOCAL_URL}/api/manager${local_path}" --max-time 5 2>/dev/null)
    if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
      cat /tmp/homey_resp
      echo "TRANSPORT=local" >&2
      return 0
    fi
  fi
  if [ -n "$HOMEY_CLOUD_TOKEN" ] && [ -n "$HOMEY_ID" ]; then
    curl -s -H "Authorization: Bearer ${HOMEY_CLOUD_TOKEN}" \
      "https://api.athom.com/v2/homey/${HOMEY_ID}${cloud_path}" --max-time 10
    echo "TRANSPORT=cloud" >&2
    return 0
  fi
  echo '{"error":"no transport"}'
  return 1
}
```

Route by `$SCOPE`:

| SCOPE     | Local path                  | Cloud path        |
|-----------|-----------------------------|-------------------|
| devices   | `/devices/device`           | `/devices`        |
| flows     | `/flow/flow`                | `/flows`          |
| energy    | `/energy/live`              | `/energy/live`    |
| presence  | `/presence`                 | `/presence`       |
| alarms    | `/alarms/alarm`             | `/alarms`         |
| zones     | `/zones/zone`               | `/zones`          |

## Phase 3 — Shape output

Return a single JSON object on stdout:

```json
{
  "scope": "<scope>",
  "transport": "local|cloud",
  "count": 0,
  "items": [],
  "summary": "<one-line human-readable summary>",
  "error": null,
  "fallback_attempted": false
}
```

Per-scope summary examples:
- `devices`: `"N devices, M online, K offline (top zones: …)"`
- `flows`: `"N flows, M enabled, last fired: <name> <age>"`
- `energy`: `"<W> live, <kWh> today"`
- `presence`: `"N home: <name>, <name>"`
- `alarms`: `"N active alarms (<types>)"`
- `zones`: `"N zones"`

## Phase 4 — Error handling

- Local 401 → set `error: "local_unauthorized"`, attempt cloud, set `fallback_attempted: true`.
- Local timeout / connection refused → attempt cloud silently, set `fallback_attempted: true`.
- Cloud 401 → set `error: "cloud_unauthorized"`.
- Both fail → return `{ "scope": "<scope>", "error": "both transports failed", "fallback_attempted": true }`.

Never make state-changing calls. Never call `PUT` or `POST`. Read-only.

Print only the JSON object to stdout. Print transport info to stderr.
