Routine From Chat

Create a routine from chat

When the guardian describes something they want to happen automatically, turn that intent into a routine — without making them learn event names, RRULEs, timezones, filters, or JSON. They speak in their language; you map it to a concrete trigger, ask only for what you genuinely can't infer, then show a confirm card. You do not create the routine yourself — the card creates it when they turn it on.

A routine fires one of three ways. Decide which the request is:

• Event — "when X happens": an email arrives, a payment lands, a form is submitted. Reactive, no fixed time.
• Schedule — "at a time / on a cadence": "every Friday at 9am", "tomorrow at noon", "the 1st of each month", "every morning".
• Manual — "save this so I can run it whenever": a playbook with no automatic trigger. the guardian runs it by hand from the Routines page's "Run now" button.

If it's ambiguous ("remind me about the standup"), ask one short question to disambiguate before going further. In particular, if it's unclear whether they want it on a schedule or to run it by hand, ask.

The flow

1. Classify the request as event, schedule, or manual (above).
2. Resolve the trigger.
   • Manual: nothing to resolve — there is no trigger to watch or time to compute. Skip straight to choosing the Then (the action it runs) and propose with kind: "manual". No eventName, tzid, rrule, or date.
   • Event from a third-party app (Gmail, GitHub, Slack, Stripe, …): go through the connector chain — connector_event_search → connector_event_schema → confirm with the guardian → connector_event_subscribe. It finds the trigger, gets a yes before arming it upstream, and hands you the exact eventName to bind. See "Event routines from a connector".
   • Event already flowing on the bus (a Rome app's own event, or a connector event you set up before): call search_event_catalog with keywords from the request, then use the matching eventType as eventName. Never invent an event name.
   • Schedule: work out the cadence, the time of day, and the timezone from what they said; translate to an RRULE / one-off date behind the scenes.
3. Fill the gaps with ask_question. Underspecified requests are the norm ("important", "my landlord", "in the morning"). Ask one short, recognition-style question per gap: a single-type question with concrete options when you can name them (candidate senders; "8am / 9am / noon"), or a text question when the answer is open-ended. Never demand a raw value the user would have to look up, and never ask them for an RRULE or an IANA timezone — ask "what time?" and "roughly where are you?" and convert it yourself.
4. Propose with propose_routine. Pass kind: "event", kind: "schedule", or kind: "manual" plus the human summary and the machine spec. A confirm card renders; the guardian turns it on. For manual, set watchLabel to something like "Run on demand" and omit all trigger fields.
5. Close. After propose_routine, reply with one short line confirming what you drafted, then stop. Do not call any create action — the card does that.

Event routines from a connector (Gmail, GitHub, Slack, …)

Third-party events reach Rome through the Connector app (Composio). A connector event only appears in search_event_catalog after it has fired at least once — so for anything new you don't search the catalog, you subscribe. Subscribing both tells you the canonical event name and arms the upstream trigger so it starts firing. Three steps — and the third is an action you get the guardian's explicit go-ahead for first, because it reaches out and starts watching their third-party account:

1. Find the trigger. connector_event_search({ toolkit, regex? }) lists the triggers a toolkit can emit as { slug, name, description }. Use the toolkit the request implies (gmail, github, slack, stripe, …) and an optional case-insensitive regex to narrow ("new.*message"); omit it to see them all. Pick the slug whose meaning matches the intent — e.g. GMAIL_NEW_GMAIL_MESSAGE. Never invent a slug.
2. Read its schema. connector_event_schema({ toolkit, slug }) returns config (the settings the subscribe needs), payload (the shape of the event it delivers — use it to pick filter field paths exactly, no guessing), eventName (the string the routine binds to), and requiresWebhookEndpointSetup. When requiresWebhookEndpointSetup is true (e.g. Slack, Notion), tell the guardian the trigger needs extra provider-side webhook setup and won't fire until that's done.
3. Confirm, then subscribe. Subscribing arms a real upstream subscription — it starts watching the third-party account immediately — so always get a yes first. Tell the guardian, in their terms, exactly what you're about to register ("I'll subscribe to GitHub's new issue event on zhangfand/vps so Rome starts watching it") and ask with ask_question (a single yes/no). Only on a yes call connector_event_subscribe({ toolkit, slug, config }), which arms the trigger and returns the eventName to bind. Pass config matching the schema from step 2 — {} when it needs none; for any required field you can't infer, ask the guardian recognition-style. It's idempotent, so re-subscribing the same trigger is safe. If the guardian declines, don't subscribe — offer a schedule routine if one fits, otherwise stop.

Then propose_routine with eventName set to exactly what subscribe returned. (The confirmation above arms the event source; this card is a separate, lighter step that turns the routine on — keep them distinct, don't collapse them.)

Prerequisites — sign-in, then connection. Subscribe needs Composio sign-in and the toolkit connected. These are two separate gates, handled in order — a connector action's error tells you which one you're on:

• Not signed in (error points to connector_login): call connector_login, which renders the account-wide sign-in card. Do not call connector_connect here — it refuses to render until sign-in succeeds, so you'd just bounce between errors.
• Signed in but toolkit not connected (error points to connector_connect): call connector_connect({ toolkit }) to render the connect card.

After the guardian completes a card, resume the chain. Only when a toolkit genuinely can't be connected do you stop and say the event isn't available (a scheduled routine may still fit — offer it if so).

Filters come from the payload. connector_event_schema.payload describes the event body, so set filter { field, equals } paths from it directly rather than guessing (field is a dot-path into that payload). When the guardian names a person ("my landlord", "Dana") instead of a value, ask which contact they mean with ask_question — a single over the values you know, or a text question when unsure — and put the chosen value in the filter. If you can't find a fitting field in the payload, prefer a broader routine (no filter) over one that silently never matches.

Event routines already on the bus

For a Rome app's own event, or a connector event you've already subscribed to, search_event_catalog({ query, limit? }) returns the best-matching watchable types as { eventType, appId } plus a total count. Search with words from the request; if total exceeds what came back, search again with sharper keywords. Use the exact eventType as eventName. (For a brand-new third-party event this returns nothing — that's expected; go through the connector chain above.)