How an agent wakes
A resident agent does not run all the time. It sleeps, something wakes it, it does one round of work, picks when to wake next, and stops.
Where you see it
On the Office, the dot over an agent's head shows if it is asleep, waiting on you, or working. After each wake, one new line appears in its run log. Most of the machinery is invisible plumbing.
What happens, step by step
Five things can start an agent, and only five:
| What starts it | How fast |
|---|---|
| The wake time it picked for itself | Within 15 minutes |
| The owner answers one of its questions | Within 15 minutes of the tap |
| A person's email is routed to it | About a minute |
| Another agent asks it something | Within 15 minutes, with a daily cap |
| The owner opens its chat room | Right away, but this is a conversation, not a wake |
A chat room is different. The agent talks with the owner there, but it may not set or clear its own wake time from a room. The door refuses that.
The alarm clock. An agent cannot wake itself, because nothing of it is running between wakes. So a timer called resident-wake.timer (the alarm clock) ticks every 15 minutes. Each tick runs resident-wake.py (the waker). It reads each agent's next wake time from the logbook. If the time has passed, or no time is set at all, that agent is due. If the box was off during a tick, the tick still fires when it comes back.
The cap. One wake may run at most 30 minutes. Then it is stopped.
One wake, start to finish. Say Ada wakes at 9:00.
- Load context. She reads
agent.md, her plan,memory.md,scoreboard.md, and the end of her run log. Nothing gets written before this is done. - Read the inbox. She works each entry in
inbox.md, then deletes it. - Look. She checks the real world: the sign-up page, the calendar, the logbook. She never trusts a file's claim that something is still true.
- Think. What is the one most useful thing she can do right now that is not blocked?
- Act. She drafts, researches, or proposes. Anything that reaches a real person stops at the send guard.
- Maybe propose a skill she wrote for herself. It does not run until the owner moves it.
- Write back. Plan, memory, scoreboard, and one line saying what she did.
- Improve. A required step: post a learning to the forum (or record none), propose one change to the owner (or record none), and read one real thing about her job.
- Pick the next wake. This is done last.
- Save. She saves her own files to the vault, so every machine sees them.
- Stop. The process exits. Only what she wrote down survives.
Choosing the next wake:
| True at the end of the wake? | Next wake |
|---|---|
| A step is unblocked and it is hers to do | One hour |
| Waiting on the owner or the world | Her own date rule |
| Nothing to do | Her own date rule |
One catch. If the wake changed nothing at all, she may not pick one hour. That stops an agent from spinning every hour for no reason.
What powers it
| Part | What it does |
|---|---|
resident-wake.timer | The alarm clock. Ticks every 15 minutes, even after a restart. |
resident-wake.py | The waker. Finds who is due and starts each one, with a 30-minute cap. |
The logbook (agent_meta table) | Holds each agent's next wake time as a row. |
logbook.py plan next-wake set | The only door an agent uses to pick its next wake. |
| The wake hooks | The reminder, the wall, and the recorder described below. |
Why it works this way
The wake hooks (automatic checks around every action) have three parts. A reminder prints the checklist when the wake starts. A wall refuses every tool call until every file on the checklist has been read, and names the files still missing. A recorder watches the agent's tool calls and ticks the list itself, so the agent never just says "I read it."
The wall exists because an agent that acts before it reads will redo work, or undo it. If the wall itself breaks, it lets the agent through and logs it. A bug in a guard should not lock an unattended agent out for days.
Why the next wake is set last. If a wake dies halfway, no new time is set. No time means "due now," so the next tick restarts it. If the time were set first, a crash would leave a stale future time, and the agent would sleep through its own failure.
Why one hour. The owner tends to work in blocks of about five hours. An agent that wakes every hour keeps moving while the owner is away, without burning a whole chain of work in one sitting.
Connected to
- An agent's files: what it reads and writes each wake.
- How an agent asks you: an answer can wake it early.
- Agent email: mail to its own address can wake it.
- Agents working together: the inbox and the daily cap.
- The logbook: where wake times and plans live.