Subscriptions

Put an agent behind an event — /subscriptions is event-fired Chats. A Subscription is the event-driven sibling of a Routine: where a routine fires on a cron, a subscription fires when its source observes an occurrence. Each fire starts one turn of Master — or the agent you pin — in a fresh Chat named "{Subscription name} — {date}", with the triggering event rendered into the turn so the agent knows exactly what woke it.

The first source is calendar.event_upcoming: fire a configurable lead time before each event on a connected Google Calendar. "Prep me 6 hours before every customer meeting, and again 10 minutes before" is two subscriptions on the same calendar connection — one per lead time, each with its own prompt, agent, and per-fire policy.

The model

event observed (e.g. "Acme QBR", starts 15:00)
   │
   ▼
fire planned: due_at = max(now, start − lead)
   - discovered OUTSIDE the lead window → fires exactly at start − lead
   - discovered already INSIDE the window → fires immediately
   - start already passed → never fires
   - rescheduled → the old occurrence's pending fires cancel; the new start plans fresh
   - cancelled → pending fires cancel
   │
   ▼
new Chat "Meeting prep — 2026-08-24"
   │
   ▼
one Master turn, headless:
   - prompt = the subscription's prompt + the event rendered as a readable block
   - config = the subscription's run_config (depth, actions_allowed, …)
   - on_question is ALWAYS "none"

Every fire is a normal Chat run: watch it over the same SSE stream / read handles, find it in the Chats list (GET /chats?subscription_id=<id> scopes the list to one subscription's fires), and every Chat it starts carries a subscription trigger badge.

Connect a calendar first

The calendar source reads through a google_calendar connection (Connections → Google Calendar; OAuth, per-member — each member connects their own calendar). The connect flow requests offline access so the subscription sweep can keep reading after the initial sign-in. A subscription then names the connection it watches via config.connection_id, and may only name a connection in its own workspace.

Create a subscription

Read GET /subscriptions/kinds first — the source-kind catalog is self-describing: each kind ships its config fields (key, type, required, description), so the config you write matches what the kind expects.

curl -X POST https://app.amdahl.ai/api/platform/v1/subscriptions \
  -H "X-API-Key: $AMDAHL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meeting prep",
    "source_kind": "calendar.event_upcoming",
    "prompt": "Prep me for this meeting: who is attending, what we last discussed with their company, open deals, and the three things to bring up.",
    "config": {
      "connection_id": "<google_calendar connection id>",
      "lead_minutes": 360,
      "require_attendees": true
    },
    "agent": "gtm-strategist"
  }'

Body fields

* Required in practice for calendar.event_upcoming (it declares required fields); a kind with no required fields accepts an empty config.

calendar.event_upcoming config

Run config

The persisted per-fire Chat policy. on_question is not configurable — subscription fires are headless, so a human ask always fails fast with no_human_in_loop.

The retired write_outputs and write_memory knobs are refused like any other unknown key.

Manage subscriptions

test-fire returns the same { chat_id, run_id, stream_url, read_url, resume_url } envelope a Chat START does, so you can watch the fire live before trusting the source. A test fire is not written to the fires ledger — it is a preview, not an occurrence.

The fires ledger

GET /subscriptions/:id/fires is the answer to "is my trigger actually firing?". Each row is one planned occurrence:

Reliability semantics

• Fresh Chat per fire. A subscription never appends into an old Chat.
• One fire per occurrence, structurally. The ledger's dedupe key (for calendar: event + start time + lead) is UNIQUE, so sweep re-runs and concurrent workers cannot double-plan, and a claim race resolves to exactly one dispatcher.
• Reschedules re-fire; cancellations never fire. A rescheduled event is a new occurrence — its old pending fires cancel and the new start plans fresh. A cancelled event's pending fires cancel.
• Never after start. A fire is due at max(now, start − lead) and an event whose start has passed never fires — a "prep me before the meeting" agent is never woken after the meeting began.
• Rate-capped per workspace. Fires that start runs are capped per business per hour (default 30, operator-tunable), so a calendar with hundreds of imminent events cannot start hundreds of agent runs.
• A broken credential is a skip, not an outage — and a NAMED one. A connection whose Google credential fails skips its groups for the tick and is retried next tick; other connections are unaffected. The failure is classified and recorded: a definitive credential death (Google rejects the refresh with invalid_grant, or no usable credential is stored) flips the connection to needs_reauth on the Connections surface, while a transient Google error never does.

Source health

A quiet fires ledger has two very different causes — "no matching events" and "we cannot read the calendar" — and GET /subscriptions/:id tells them apart. The detail read carries a derived source_health block:

{
  "status": "connection_needs_reauth",
  "detail": "Google rejected the stored credential, reconnect Google Calendar under Connections, then fires resume automatically.",
  "last_swept_at": "2026-08-25T12:00:00Z",
  "checked_at": "2026-08-25T12:06:31Z"
}

source_health can also be null, which means "not assessed" (the health lookup itself failed, or the source kind has no health resolver) — never a claim that the source is healthy. Recovery is automatic in both directions: a successful read clears a recorded failure, and a successful token refresh clears a needs_reauth stamp.

Over MCP

Subscriptions are not on the Amdahl MCP server's tool list: their only event source, Google Calendar, is retired, so no Subscription can fire. Use the REST endpoints above. Subscription reads are still MCP resources: subscription://kinds, subscription://list, subscription://<id>, and subscription://<id>/fires. Scopes: subscriptions:read / subscriptions:write (both on the customer-agent key bundle; existing keys were backfilled).

Scopes