bot-routines.md

Bot routines and scheduled check-ins

A Bot can send a new message in its own chat at a scheduled time. Ask it for a one-time wake-up or a recurring check-in, or open the Bot's Routines page to add one directly. In chat, the Bot uses routines to show an Add routine card. Accepting that card saves the schedule; the proposal alone does not start future work.

The Bot's Schedules capability must be available. Full access includes it while scheduled tasks are enabled. With Custom access, select Schedules in the Bot's Advanced access settings. The global scheduled-tasks switch must also be on. If the Bot lacks this capability, it cannot offer the routines tool for that turn. A Bot can list its routines and pause one, but editing or deleting a routine happens in the Routines page.

Aiden's desktop scheduler owns the timer. At each fire, it submits the saved prompt to that Bot's Pi Durable conversation. The scheduled turn uses the Bot's current model and current access, rechecking authority before model and tool work; it does not inherit a saved ordinary automation's workspace or connector grants. The reply lands in the same chat. A visible result can also appear as a desktop notification, in the paired phone's Bot routine feed, or in a bound Telegram chat. A Bot can reply [SILENT] when there is nothing worth reporting.

Before advancing a Bot routine, Aiden saves the fire's time, request ID, and original message with the task. If the app stops during submission or delivery, startup reconciles that fire against the same Pi request ID. While Aiden stays open, it also retries pending reconciliation with bounded backoff, starting at one minute and capping at 15 minutes. An admitted turn is observed rather than generated again; a completed run is handed to Telegram's durable outbox without rerunning the Bot. An uncertain admission stays pending for recovery; a failure known to have happened before Pi accepted the request is saved as a visible error. Pausing a recurring routine prevents an unsubmitted claimed fire from starting after restart. The Routines page shows Finishing an earlier run while a fire remains unresolved and Overdue since when an enabled schedule is more than 15 minutes late. On the CLI host, aiden schedule status reports overdue task IDs and pending Bot fires; aiden serve status reports whether its daemon is running.

The Bot chat and routine run history keep completed answers. Desktop banners are best effort: a crash after the run is saved can prevent its banner from appearing. Telegram delivery is queued durably when a Bot is bound to a chat; an uncertain send gets one duplicate-labelled retry, after which the outbox records a delivery failure rather than sending repeatedly. The answer remains available in the Bot chat and paired phone's routine feed.

The desktop app must be running and the computer awake for a routine to run on time. If the Bot has an interrupted turn, a routine never resumes that turn itself; Aiden records the missed fire and can catch up after the person resumes the turn. This includes a one-time routine whose scheduled fire has already switched it off; that exact missed fire can still run once within the seven-day catch-up window. If the person pauses the whole Bot, new fires are skipped without automatic catch-up. A fire already admitted to Pi remains pending until the Bot resumes so Aiden can observe its answer without resubmission. Ordinary scheduled tasks are separate from Bot routines and use their own chats and approval settings.

Nobody is watching a routine run, so by default a step set to Ask first is skipped and the Bot says in its reply that it needs the person's OK, and a connection tool that changes something waits under Needs you until the person answers. On the desktop, Settings → Bots → Go ahead without asking lets every Bot's routines take those steps without asking. Passwords, codes, money, Hand off to me rules and Computer Use on the person's Mac still come back to the person. See Bot rules.

Wake-ups a Bot sets for itself

A Bot can also come back to its chat on its own, for example "I'll check whether the flight got rebooked in two hours". It uses the wake_up tool, which needs no approval card:

• set takes either in_minutes (1 to 1440) or a local at time (HH:MM, its next occurrence within 24 hours in this Mac's timezone), plus a note of at most 500 characters saying what to do.
• A Bot can have at most 3 wake-ups waiting. A fourth is refused with the three that are pending, so the Bot can cancel one or fold the work into an existing one.
• list shows the pending wake-ups, and cancel removes one by id.
• A delay that lands in the hour a daylight-saving change repeats (for example the second 1:30 AM on the night clocks fall back) is refused, because the routine would fire at the first one; the Bot picks a time after it.

The tool is offered only in turns the person started: from the desktop chat, the paired phone or a bound Telegram chat. A routine run, an event routine, a catch-up or a wake-up itself cannot set another wake-up, so a Bot cannot keep itself awake in a loop. Repeated checking belongs in a routine the person accepts.

A wake-up is saved as a one-time routine named Wake-up. It fires through the same claim, recovery, catch-up and delivery path as any other one-time routine, so pause, quiet hours, the daily interruption limit and [SILENT] all apply. The Bot receives "You set this wake-up at 3:10 PM: " in the same chat and answers with its current model; the tool cannot pick a model. Once it has fired, the wake-up no longer appears in the list; Aiden keeps its record for the seven-day catch-up window, and the next wake-up the Bot sets after that removes it.

The chat shows each wake-up as one line, Wake-up at 3:10 PM · Cancel, and the Bot's profile lists it among its routines with the note and a Cancel button. Cancel deletes the wake-up. The paired phone sees it as an ordinary one-time routine named Wake-up; no Remote contract changed.

Each Bot has Let set its own wake-ups in Advanced → Chat, on by default. Turning it off stops offering the tool and removes every wake-up the Bot set, including one that came due while the Bot was paused and would otherwise catch up on Resume, so nothing the Bot set fires after the person said no. The person's own routines stay. Turning it back on does not restore the cancelled wake-ups.

When a routine fails

Desktop Bots heal their own routines (spec: docs/superpowers/specs/2026-10-27-bot-autonomy-design.md §5).

• Why it failed. Every failed run records a kind: temporary (the AI service was unreachable or busy), sign-in, access changed, model setup, a step that didn't work, stalled, or other. The provider's message is kept, with credentials redacted.
• Retries. After a temporary failure or a 10-minute watchdog stop, Aiden retries only if the durable Bot session confirms the attempt ended before it requested any tool. If a tool may have run, the person receives the failure and can check the Bot chat before choosing Run now. Eligible retries run after 5 minutes and then another 20 minutes, unless the next regular fire comes first. A retry is saved like any claimed fire, so it survives a restart and still runs for a one-time routine.
• Needs you. A sign-in, access or model problem raises one "Needs you" card at once, in the Bot's chat, in the sidebar, as a Mac notification and in Telegram. Phones that negotiate bot:issues show the same card.
• Pause after three. Three failed fires in a row of the same kind pause the routine and leave one card with Resume. If delivery of the final retry result is interrupted, Aiden finishes delivery from the saved result after restart. A success resolves the routine's cards.
• Before a fire. About 30 minutes before each enabled routine fires, Aiden checks the Bot once: its state, its model setting (repaired when only the stored details went stale), its AI sign-in (refreshed early), the connections a Custom grant names, and its Bot computer (read only; nothing is started). A problem becomes a card; a later passing check resolves it. Profile → Health shows the newest check and offers Check now.
• A reply that claims a failed step worked. The result still reaches the person, with the line "One step didn't work: {step}. Check the chat.", and it counts toward the pause.
• Stuck runs the person started. They are never stopped automatically. After 10 minutes without progress, a card asks Stop or Keep waiting.
• Sleep is not a stall. When the computer wakes, every running Bot run gets a fresh 10 minutes, so time spent asleep never stops a routine run or raises a card. Aiden notices the wake from the system, or from a gap of more than 2 minutes between its once-a-minute checks.
• Waiting out a usage limit. A run whose request waits for a provider's usage limit to clear is not stuck: the watchdog neither stops it nor raises a card while it waits, and its 10 minutes start again when the limit clears. Once the test request has gone out, a reply that hangs is caught as usual. See usage limits and spending limits.

The standalone CLI records failure kinds but does not yet retry, pause routines, run pre-fire checks or raise cards.

Proactive without being pushy

• Quiet hours and a daily limit. Each Bot has Advanced → Interruptions: quiet hours (default 10:00 PM to 7:00 AM, in the Mac's time zone) and a cap on proactive notifications a day (default 5, 0 to 20). During quiet hours, routine results, suggestions and "Needs you" cards wait, and what waited arrives as one digest per Bot when quiet hours end. Past the cap, results stay in the chat and one note says more are there. "Needs you" cards skip the cap. Replies to the person's own messages are never held.
• Learning from Not now. "Not now" on a suggested routine offers four optional reasons (Not useful, Wrong time, Already have this, Something else) or Skip. The Bot's routines list reports recent answers. After three declines in the last five suggestions it stops suggesting for a week, and a routine with the same name declined in the last 30 days is refused unless you asked for it again. Asking does not end the week off; you can still add a routine yourself. A follow-up on a promise always gets its card, and one that expires unanswered never counts as a decline.
• Follow-ups on promises. When the Bot promised to follow up on a date (between tomorrow and 60 days ahead), the memory review notes it and the Bot suggests a one-time routine for that day (9:00 AM unless a time was promised). At most two suggestions wait at a time; the next follows when one is answered. The Bot can revise a card you haven't answered: the old card reads "Replaced by a newer suggestion" and doesn't count as a decline. A revised follow-up expires on the revised card's day, and one revised into a repeating schedule or a trigger stays until you answer it. A scheduled card shows the time zone it runs in. A promise past its date expires.
• When something happens. Profile → When something happens adds routines that run when files change in a folder inside the Bot's folder (changes are collected for 30 seconds, up to 50 paths), or when the routine's own link is called on this Mac's network or Tailscale while Aiden On The Go is on. The link is shown once. Files the routine's run writes with its file tools don't fire it again while they are still exactly as the Bot left them, so a Bot writing into its watched folder doesn't wake itself; a file someone else drops in, edits or deletes during the run (including one the Bot just wrote) is held and fires the routine once the run ends (after 5 seconds, so late folder notices are sorted too). Files written by a shell command are not told apart and can fire the routine again. A folder that is missing, outside the Bot's folder, or can't be watched raises a card for that routine only; the other routines keep watching. Quitting stops a running event routine and waits up to 3 seconds for it to be recorded as uncertain; its event runs again on the next start. Each routine runs at most once every 5 minutes and 24 times a day; an event that arrives early waits and the newest one wins. What happened reaches the Bot as data, never as instructions. The Bot can also suggest one of these with the same Add routine card; when you add a link routine on this Mac, the card shows Copy link once (a link routine added from a phone shows New link on the Mac's card). The Bot never sees the link. These routines are managed on the desktop only for now: phones show and answer the suggestion card but don't list the routines, and email and calendar triggers are not built yet.
• Watch routines. The same section can add a routine that checks a web address or a script in the Bot's folder every 5 minutes to 24 hours, and runs the Bot only when the answer is different from the last check. A check never uses the model, so an unchanged page or script costs nothing.
  • The check. An address is one GET over https (plain http only to this Mac) with no sign-in, cookies or referrer, at most 256 KB, for 30 seconds. Aiden does not follow redirects: a redirect is a failed check that asks for the address the page ends up at. A script must be a file inside the Bot's folder (a link that points outside it is never run); it runs there for at most 60 seconds and 1 MB of output, with the same environment as run_command (Aiden's own secrets are withheld), and a non-zero exit is a failed check. Anything the script leaves running in the background while still holding its output is stopped 1 second after the script exits, unless it left the script's process group (setsid or a daemon). A script runs only while the Bot has Shell access: with Shell off the check fails without starting it, and turning Shell off stops a script that is running.
  • What wakes the Bot. The output is hashed. The first check after you add or change a watch only records what it looks like. When a later check differs, the new hash is saved first (so a failed run never re-alerts), then the Bot gets a short diff and the new output as data, through the same limits as other event routines (once every 5 minutes, 24 a day).
  • Failures. A failed check is never a change and leaves the saved output alone. Three failed checks in a row turn the watch off and raise one "Needs you" card; turning it back on tries again soon. Fixing the address or script and turning it back on starts over with a fresh first check, and that check clears the card. An open profile updates its rows as checks finish. The row shows when it last checked ("No change since …") or why it couldn't.
  • When it runs. Only while Aiden is open and the Bot isn't paused; nothing is checked at startup beyond scheduling the next check. Each address or script is one the person added or accepted on the Bot's suggestion card.

Bots that learn

• Lessons from a routine's runs. After every fifth finished run of a routine, the Bot reviews those runs once on its own model and may suggest one lesson (or to stop one that made things worse). It cites the runs it rests on. When the setup changed between runs or one run is all the evidence, it suggests nothing. A lesson appears as a card, and only Keep this adds it to that routine's instructions, after its notes.
• Corrections. When you correct how the Bot did something ("no, put the totals first"), the memory review keeps one how-to lesson for the whole Bot, separate from what it knows about you. It applies at once, and the chat shows "Learned: … · Undo".
• Skills. On turns you are part of, the Bot can propose a skill for a procedure you liked. The card shows exactly what would load, and Add skill writes it into the Bot's folder. A skill placed in the Bot's folder by hand, or by the Bot's own file tools, never loads until you say Use skill: the Bot's file tools cannot write skill folders, and a home skill loads only when its exact content was approved.
• Memory tidying. When a memory file passes 80% of its limit or holds more than 56 entries, the Bot merges, drops or shortens entries, at most once a day, never adding a fact and always shrinking. The chat shows "Tidied memory · Undo".
• What I've learned. Profile → What I've learned lists active lessons, waiting follow-ups and recent changes (memory adds, tidies, lessons, added skills). Undo restores the earlier state unless it changed since.
• Budget. Background learning (the memory review, reflection and tidying) uses at most 12 model requests and 24,000 output tokens per Bot per day.

Phones show these cards read-only for now and have no learning page.