docs/proactive-routines.md
Rama main · réplica de lectura del repositorio original.
# Proactive routines
MausBot keeps an eye on the person's day with one ordinary routine,
"Keep an eye on my day". It is made once, with no button, on a personal install
or Cloud that can reach connected apps, and it is built from four upgrades every
routine can use, plus the helper models for the inbox.
The bot that is proactive is the one `proactiveOwner` names
(`server/host/proactive-owner.ts`): the place's MausBot, shown in the sidebar or
not, and the main Chief only where there is no MausBot. A Team Cloud member's
MausBot is never the one. There is no second bot and no separate watcher: the
routine engine (`server/routines.ts`) runs it like any other routine, on the
desktop, headless and on a Cloud.
## Who owns it
- **A new install.** Its first bot is MausBot, which is also its Chief. The
routine, the brief, the add-a-key card and the intro's line about the day are
MausBot's.
- **An install that had a Chief before MausBot.** The Chief stays the Chief.
The first time the server starts with MausBot there, the Chief's "Keep an eye
on my day" becomes MausBot's. It is the same routine, moved, so everything
the person set stays: on or paused, the instructions they edited, the checks'
cursors and seen ids, and the day's run count. The brief's chat becomes
MausBot's own conversation, and its next card says again what it does. Cards
already posted stay where they were.
- **The handover is safe to repeat.** It waits while a run of the routine is
queued or working. `watch.json` records which bot each briefing routine was
handed to, so it happens once: a routine the person later puts back on the
Chief stays there. A restart between the steps finishes them at the next
start, and a computer frozen by a move to My Cloud hands nothing over.
- **One on at a time.** When a briefing routine lands on MausBot, handed over
or arrived with it in a move, it is the one. Every other briefing routine is
paused, never deleted, so the inbox is never read twice and a paused routine
stays paused.
- **Hidden from the sidebar.** MausBot keeps working: the brief is posted to its
chat, and the notification and the first open of the day open that chat.
## What the person sees
- **The brief.** One card a day in a fixed chat of MausBot's, edited in
place, built with no AI. It exists only once it has something for the person
(something that needs them, an important email or a meeting today); an empty
brief is never posted. It opens on the first open of the day and after three
hours away. Any other moment, it never takes the screen from the chat in use.
Its first appearance says what it does and that the person can tell MausBot
to stop or change it. Sections:
1. **Needs you**: emails waiting on a reply, failed or missed routines,
meetings that clash, an app that can't be read ("Couldn't read Gmail ·
Reconnect Gmail in Connected apps"), a signed-out AI, a usage limit, a
question a bot is waiting on;
2. **Your day**: today's meetings, with Join for an https meeting link;
3. **Important emails**: what the watch picked, each with a one-line why,
**Draft a reply**, **Open in Gmail** and **Dismiss**;
4. **Routines**: other routines' results today.
- **Meeting prep**: a card in the same chat when a meeting with other people is
within four hours.
- **The 10-minute reminder**: a card posted by the server, with no AI.
- One notification per update that adds something that needs the person.
Pausing or deleting the routine in Automations is the off switch: with it off
there is no brief at all. Its row says
"reads and drafts only" and "checked … , nothing new".
## The four routine upgrades, and the helper models
1. **Checks before the model.** A routine can name `checks`: `calendar` (the
next 36 hours), `mail` (new inbox mail since the cursor) and `runs` (other
routines' finished runs). They are plain code over one connected-apps
session per tick, as the default account of each app, and only for apps the
bot's own app switches let it read. Nothing new starts no turn and leaves no
run, only "checked at". Reminders, clashes and Your day need no AI. Email
triage and meeting prep go to **one** batched run, each item in a records
block. The cursor moves only once that run's answer is kept, and items are
deduplicated by id. A failed or misshapen read is never "nothing new": it
keeps the cursor, backs off and shows its trouble.
2. **Nothing to report, structured.** A routine that delivers to the brief
answers with one small JSON object: `{"quiet": true}`, or important emails
and preps by item id. The server reads it. An answer it cannot read fails the
run and is never posted, and its items wait for the next check. Every other
routine keeps the NOTHING NEW convention in `server/automation-reports.ts`.
3. **Read-and-draft runs** (`access: "read-and-draft"`), in
`server/read-and-draft.ts`. Everything is allow-only:
- the run runs at Ask, and the server refuses every request in it outright,
never as a card;
- its OpenMausBot routes are conversation reads, its own results, the
engine's hooks and the connected-apps relay;
- through the relay it reads Gmail and Google Calendar, and may write one
draft per thread, replying to that thread's sender, in a thread its checks
handed it;
- Gmail's and Calendar's answers reach it as records;
- no web search, browser, computer, phone or other tools; no memory, recent
work, team notes or skills in its prompt; nothing captured into memory;
- its conversation stays out of recall, recent work, `list_threads` and Chief
notices.
The model work needs an engine whose every tool use reaches OpenMausBot's
answerer (Claude today). On any other engine the watch prepares no meeting,
says so in the brief, and still does what needs no AI.
5. **Helper models sort the inbox** (`server/host/inbox-triage.ts`). With a
decision model set up (Settings → Decision and extraction: the person's own
Cloudflare Workers AI or Jev key, or Cloud's included one), new mail is
sorted with no AI turn, on every engine: Clairic reads each email (sender,
the ask, any deadline or amount, whether it waits on a reply, what kind of
mail it is) and Clef decides important, needs a reply, or skip, hearing the
senders the person recently dismissed. Only important and needs-a-reply
mail becomes rows; the why is built in plain code from what was read. The
helper models can't act, so no fence is needed. If they fail, the mail
waits for the next check. A full AI turn runs only for meeting prep, or when
the person presses Draft a reply. Without any helper model, the AI run sorts
mail as above, on Claude only.
4. **Deliver to the brief** (`deliver: "brief"`): results become brief rows,
not chat lines of their own.
## Reliability, for every routine with checks
- **Overlap.** While a run works, checks still run (reminders stay on time), but
hand the AI nothing until it ends.
- **Catch-up.** However late the computer wakes, missed checks merge into one,
never a missed run.
- **Backoff.** After a failed run the next waits 15 minutes, doubled each time,
at most 4 hours, with jitter. The owner hears once per failure streak.
- **Busy.** A run of checked items waits for a busy bot without a notice and
never fails for being busy.
- **Throttle.** At most 24 AI runs in any 24 hours; then items wait.
- **Boot.** The first checks wait two minutes after start.
- **Wake.** Only the checks' next on-time job (a reminder, a prep) keeps the
desktop awake or wakes a sleeping Cloud. Plain mail checks run whenever the
machine is awake anyway.
- Every other routine keeps main's rules: one quick automatic retry, usage
limits waited out, one notice per owner cause.
## State and privacy
- `routine-checks.json`: per routine, cursors, judged ids, meetings prepped and
reminded, and the items a run holds. Ids and times only.
- `brief.json`: the brief's home chat and today's card, presence, the zone of
record (from the person's device, so a Cloud is not stuck on UTC), the
important rows by id, and recent dismissals with the sender's address. The
senders and subjects it shows are read back from Gmail by id after a restart.
- `watch.json`: that the default routine was made, so it is never made again,
and the bot each briefing routine was handed to.
- A card the server built carries `serverCard`. A bot can't edit it, and it
replays into a turn only as records. Dismiss works only for the owner or an
admin, only on the brief, checks thread ownership before reading a widget, and
starts no turn. Recent dismissals go into the next triage as records.
- A hosted team workspace or Team Cloud gets no watch and no brief. Presence is
recorded for the owner only.
- A personal Cloud that began with its first hour (`server/host/first-hour.ts`)
also has a morning time, 8:00 in the person's zone: the day's brief is posted
or refreshed then and pushed, with its first line saying what was done since
the person was last here (emails sorted, reply drafts written, meetings
prepared, from `value.json`), and only what was. A watch run still sorting
the night's mail gets 20 minutes first, and a sleeping Cloud is woken at 7:50
for it (`nextWakeAt`). The very first morning push says it is the first brief.
- An install that can't reach connected apps gets no watch, and so no brief,
until it can. It checks once a minute, since a Cloud's access arrives after
start. A scripted test install without the fake connected-apps service
behaves as before.
- Routines carry `checks`, `access` and `deliver` through Cloud moves and team
backups. The watch moves to My Cloud with MausBot. A move carries MausBot
when it has a routine the person set up, paused or changed, even if nobody
has opened MausBot; the watch exactly as the server made it does not count.
On My Cloud the arrived watch pauses My Cloud's own. The move freeze pauses the watch like any routine, so two
homes never watch the same inbox. MausBot never moves into a team.
## Not in v1
- More than one account per app.
- Phone push when the app is closed (there is no caller of the push relay yet).
- Quiet hours.
- A sweep of old run conversations.
- A run against a real Google account: the Composio slugs and answer shapes
follow its documentation and the fixtures in `server/testing/fixtures/`.