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>:

// 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
}

// 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.

# 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), 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.