Add Apple Music listening history (what played and when)

[jmcte]

Goal

Add a read-only icloud-cli surface that shows what the authenticated user listened to in Apple Music and when it was played.

Proposed CLI

icloud music history
icloud music history --limit 50
icloud music history --since 2026-07-01
icloud music history --json

The exact command name may change to match existing CLI conventions.

Required output

For each available listening event, return:

• track/song title
• artist
• album, when available
• playback timestamp, including timezone or an unambiguous UTC value
• Apple Music/catalog identifier, when available
• source/type where useful (song, station, playlist, etc.)

Results should be newest first and support bounded pagination or a limit.

Investigation notes

Apple's recently played APIs may expose only recent resources rather than a complete timestamped event log. Before implementation, verify:

1. whether MusicKit / Apple Music API returns per-play timestamps;
2. the maximum history window and pagination behavior;
3. required Apple Music authorization and entitlements;
4. whether macOS-local Music data can safely supplement missing timestamps without relying on brittle or destructive access.

If Apple does not expose exact per-play times, document the limitation clearly and return the best truthful data available. Do not synthesize timestamps.

Privacy and safety

• Read-only: no library or playback mutations.
• Keep raw listening history local to Hermes/OpenClaw unless the user explicitly exports it.
• Do not log credentials, developer tokens, user tokens, or full raw API payloads.
• Fail clearly when Apple Music authorization is missing or expired.

Acceptance criteria

• A documented command returns recently played Apple Music items.
• Human-readable and structured JSON output are supported.
• Exact playback time is included when the source provides it.
• Missing timestamps are represented honestly, not inferred.
• Limit/pagination behavior is bounded and tested.
• Authorization failures have actionable messages.
• Unit tests cover parsing, ordering, timestamp handling, pagination, and redaction.
• Documentation states the available history window and Apple API limitations.

Future use

This will feed a private OpenClaw “media history” view alongside Apple Books progress and a future Audible listening-history connector.