docs/automations.md

# Automations — make it autonomous without a custom app

Everything below drives one endpoint. **iOS cannot read iMessage in the background** (no API), so the
autonomy ceiling differs by platform:

| Front-end | Autonomy | Source | Notes |
|---|---|---|---|
| Mac collector (`AGENT_MODE`/`AUTONOMOUS`) | Fully hands-off | iMessage | Needs an always-on Mac |
| iOS Shortcut | One gesture (you trigger it) | anything you share | No background reading possible |
| Android Tasker/MacroDroid | Hands-off | SMS/RCS/notifications | Not iMessage |

## The `/agent` contract (what they all call)

`POST {SPACE_URL}/agent` with `Authorization: Bearer <INGEST_TOKEN>`:

```jsonc
// request — `thread` OR `messages` required; rest optional
{
  "thread": "Room parent: picture day Thursday 9am\nMe: thanks",
  "messages": [{"sender": "Room parent", "text": "picture day Thursday 9am"}],
  "images": ["data:image/png;base64,..."],   // a screenshot
  "existing_ics": "<base64 .ics>",            // optional, enables conflict checks
  "now": "2026-06-05T10:00:00",
  "push_gcal": false,
  "return_ics": true
}
```
```jsonc
// response
{
  "plan": { "events": [{"title":"Picture day","start":"2026-06-11T09:00:00", ...}],
            "conflicts": [], "proposed_times": [], "reply_draft": "...", "needs_clarification": null },
  "ics_base64": "<...>",
  "gcal_links": []
}
```

## (A) Mac collector — fully autonomous (iMessage)

Two equivalent ways; prefer the server-side switch so logic lives in one place:

- **Server-side:** run the Space with `AUTONOMOUS=1`. `/ingest` then assembles a per-chat rolling
  thread, runs the agent, dedupes, and (if Google is configured) pushes events automatically.
- **Collector-side:** run the collector with `AGENT_MODE=1` — it POSTs `/agent` (with `push_gcal`)
  instead of `/ingest`. See `collector/collector.py`.

```bash
# collector-side
cd collector && AGENT_MODE=1 python collector.py
```

## (B) iOS Shortcut — one tap, no `.ics` import

1. New Shortcut → accept **Share Sheet** input (Text and Images).
2. **Text** → set variable `Thread`.
3. **Get Contents of URL** → `https://<your-space>/agent`, Method **POST**, Header
   `Authorization: Bearer <INGEST_TOKEN>`, Request Body **JSON**:
   `{ "thread": Thread, "now": <Current Date, ISO 8601> }`
   (To send a screenshot instead: Base64-encode the shared image into `images`.)
4. **Get Dictionary Value** `plan.events` from the response.
5. **Repeat with Each** → **Add New Event** (Calendar): Title = `title`, Start = `start`,
   End = `end`, Location = `location`, Notes = `notes`.

Now sharing a thread/screenshot to the Shortcut adds the events to Apple Calendar in one tap — no
file download, no import. (Optional: read back `plan.conflicts` and show an alert.)

## (C) Android — Tasker / MacroDroid (SMS/RCS)

1. **Trigger:** Event → *Received Text* (SMS), or a Notification trigger for your messaging app.
2. **Action:** HTTP Request → POST `https://<your-space>/agent`, header
   `Authorization: Bearer <INGEST_TOKEN>`, body `{ "thread": "%astext", "now": "%DATE..." }`.
3. Parse `plan.events` (JSON Read) → for each, **Insert Calendar Event** (Tasker writes via
   `CalendarContract`).

Because Android can read SMS/RCS and run in the background, this path is genuinely autonomous.

## Roadmap — a native app

- **Android:** a real app using a Notification Listener / `READ_SMS`, on-device **Gemma E4B** via
  llama.cpp/MLC (see [on-device.md](./on-device.md)), writing events through the Calendar provider —
  the same `/agent` contract or fully local. Feasible and fully autonomous.
- **iOS:** no background message or LLM-server access — the Shortcut above is the ceiling. An
  autonomous iOS iMessage app is **not possible**; we won't promise one.