# car-integrations

Account-bound integrations for [Common Agent Runtime](https://github.com/Parslee-ai/car) — Calendar, Contacts, Mail, Messages, Notes, Reminders, Photos, Bookmarks, Files, Keychain.

## What it does

The logical capabilities are the same on every OS; the backends are not. v1 defines the **release contract** — stable return shapes that carry explicit `available` + `backend` fields so downstream apps branch cleanly while backends light up incrementally.

| OS | Calendar | Contacts | Mail | Messages | Other Apple account surfaces |
|----|----------|----------|------|----------|------------------------------|
| macOS | EventKit (`EKEventStore`) | Contacts.framework | Mail.app automation | Messages.app automation | Notes/Reminders/Photos app automation, Safari bookmarks, iCloud Drive paths, Keychain |
| Windows | MS Graph + Outlook MAPI | Windows.Contacts + Graph | MS Graph + MAPI | Not modeled | Not modeled |
| Linux | Evolution DS + CalDAV | Evolution DS + CardDAV | Evolution DS + IMAP | Not modeled | Not modeled |

## Dependencies (and honest gaps)

Full operation requires:
- **`car-secrets`** — where credentials and tokens live
- **`car-accounts`** — to know which account a call is bound to
- **`car-permissions`** — to preflight OS consent before the side effect

The macOS Calendar, Contacts, Mail account discovery, and Messages account discovery paths are implemented. Backends still return `available:false` with an explicit reason when macOS denies TCC access or an OS service is not configured.

Messages chat listing falls back to `~/Library/Messages/chat.db` when Messages.app automation cannot enumerate chats. macOS protects that database behind Full Disk Access, which must be granted to the host app by the user; there is no entitlement that can silently grant it.

## Where it fits

Surfaced via the WebSocket `calendar.*`, `contacts.*`, `mail.*`, `messages.*`, `notes.*`, `reminders.*`, `photos.*`, `bookmarks.*`, `files.*`, and `keychain.*` methods. See [`docs/websocket-protocol.md`](../../../docs/websocket-protocol.md).
