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

Schedule routines — translating natural language

Map what they said to tzid (IANA), localTime (24-hour HH:mm), and either rrule (recurring) or date (one-off YYYY-MM-DD). Keep all of that internal — the card shows plain language like "Every Friday at 9:00 AM".

• "every day at 9am" → localTime: "09:00", rrule: "FREQ=DAILY"
• "every Friday at 5pm" → "17:00", rrule: "FREQ=WEEKLY;BYDAY=FR"
• "every weekday at 8am" → "08:00", rrule: "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
• "the 1st of every month at 9am" → "09:00", rrule: "FREQ=MONTHLY;BYMONTHDAY=1" (MONTHLY always needs BYMONTHDAY)
• one-off "tomorrow at noon" → localTime: "12:00", date: "<that date>", no rrule

For the timezone: use the guardian's known timezone if you have it; otherwise ask once in plain terms ("roughly where are you / what timezone?") and convert (e.g. "Pacific" → America/Los_Angeles). Don't ask them to type an IANA name.

Choosing the "Then" (action)

The trigger decides when; the actionName decides what runs. A routine can only bind to an action that already exists — binding to one that isn't registered is rejected at create time (the card won't turn on). So pick the Then deliberately. Three choices, same for event and schedule routines:

• Notify me — pure delivery on a channel you know: actionName: "system:send_message", args { "channel": "<telegram|webchat|...>", "threadId": "<id>", "text": "<message>" }. Only when you actually know the channel + thread.
• Summon — a single judgement/writing pass over what the trigger hands you, where it's fine for the agent to work out the steps fresh each time: actionName: "system:summon", args { "agentName": "core:main", "prompt": "<what to do when this fires>" }. Good for "summarize the email that just arrived", "remind me to …", "decide and reply".
• A workflow action — a fixed multi-step job you'd want run the same way every fire (see the litmus). Bind to its canonical run action, <appId>:run.

Summon or workflow? — the litmus

Default to system:summon when the Then is one act of judgement or writing over what's already in front of the agent. Reach for a workflow when the Then has a fixed multi-step shape you'd want to run identically each time:

• it gathers then acts — "review my emails and pick the critical ones", "pull my calendar and draft a plan" (fetch → judge/score → deliver);
• it pulls from several sources and combines them;
• it fans out over a list — "for each new lead, …";
• you'd otherwise be writing a for/if or several tool calls inside the summon prompt.

A summon re-improvises those steps on every fire (non-deterministic, no parallel/branch/map, pricier and flakier); a workflow crystallizes them as a deterministic DAG. So "every morning, review my emails and select the critical ones" is a workflow, not a summon.

When the Then is a workflow and no <appId>:run action exists yet, build it first with the coding:workflow_creation skill (it scaffolds the app and registers <appId>:run), then come back and propose_routine bound to that action. Don't propose the routine first — the create is rejected until the action exists. If a fitting run action already exists, just bind to it.

Example — event (connector)

Guardian: "Text me when I get an important email from my landlord."

1. Classify → event, third-party (Gmail). Make sure you're signed in and Gmail is connected; if a connector action says otherwise, handle the prereq it names (connector_login, then connector_connect({ toolkit: "gmail" })) and wait for the guardian to finish.
2. Discover + read the trigger:
   • connector_event_search({ toolkit: "gmail", regex: "new.*message" }) → pick GMAIL_NEW_GMAIL_MESSAGE.
   • connector_event_schema({ toolkit: "gmail", slug: "GMAIL_NEW_GMAIL_MESSAGE" }) → note the payload's sender field and the eventName.
3. Confirm, then subscribe:
   • ask_question (single yes/no): "I'll subscribe to Gmail's new email event so Rome can watch your inbox — set that up?"
   • On yes → connector_event_subscribe({ toolkit: "gmail", slug: "GMAIL_NEW_GMAIL_MESSAGE", config: {} }) → returns eventName: "provider:event:gmail.gmail_new_gmail_message".
4. ask_question — "Who's your landlord?" (a single over the addresses you know, or a text question if unsure); "What counts as important?" ("Anything from them" / "Only if it mentions rent").
5. After they pick dana@example.com and "anything from them" (filter field taken from the payload schema):

propose_routine({
  kind: "event",
  sentence: "When you get an email from Dana (your landlord), Rome will summarize it and text you.",
  name: "Landlord emails",
  watchLabel: "Gmail · new email",
  filterSummary: "sender is dana@example.com",
  thenSummary: "summarize it and text you",
  eventName: "provider:event:gmail.gmail_new_gmail_message",
  filter: [{ field: "from.email", equals: "dana@example.com" }],
  actionName: "system:summon",
  args: { agentName: "core:main", prompt: "A new email arrived from the guardian's landlord (dana@example.com). Read it and send the guardian a short summary." }
})

Example — schedule

Guardian: "Remind me every Friday at 9am to send my weekly update."

1. Classify → schedule. Cadence weekly on Friday, 09:00; confirm timezone if unknown.
2. Propose:

propose_routine({
  kind: "schedule",
  sentence: "Every Friday at 9:00 AM, Rome will remind you to send your weekly update.",
  name: "Weekly update reminder",
  watchLabel: "Every Friday at 9:00 AM",
  thenSummary: "remind you to send your weekly update",
  tzid: "America/Los_Angeles",
  localTime: "09:00",
  rrule: "FREQ=WEEKLY;BYDAY=FR",
  actionName: "system:summon",
  args: { agentName: "core:main", prompt: "Remind the guardian to send their weekly update, in a short friendly message." }
})

Example — manual

Guardian: "Put together my morning briefing, but don't schedule it — I want to run it myself when I'm up."

1. Classify → manual (they explicitly don't want a time). No trigger to resolve.
2. Pick the Then like any routine (here a workflow or summon that builds the briefing).
3. Propose:

propose_routine({
  kind: "manual",
  sentence: "A morning briefing you can run by hand whenever you want it.",
  name: "Morning briefing",
  watchLabel: "Run on demand",
  thenSummary: "pull your day and send you a briefing",
  actionName: "system:summon",
  args: { agentName: "core:main", prompt: "Build the guardian's morning briefing — their day's calendar, anything urgent — and send it to them." }
})

Then reply with one short line confirming what you drafted, and stop.