Proposal: wake-up schedules — resume an agent automatically when its usage limit resets

[yuruiz]

Problem

Claude Code and Codex enforce rolling usage limits — a 5-hour window, plus weekly caps. A long-running task that hits the limit dies mid-turn, and the agent sits idle until the window resets. Today your options are:

• Watch the clock and resume manually — which defeats the point of remote monitoring.
• Create a recurring schedule that blindly sends "continue" every N hours — it fires whether or not the limit actually reset, keeps firing after the task is done, and is invisible while it waits.

The information needed to do better already exists: the daemon's quota fetcher knows the exact reset time for Claude's 5h/weekly windows and Codex's primary/secondary windows. It just never reaches the agent lifecycle.

Proposal

When a turn fails because of a usage limit, the composer offers a one-tap wake-up:

1. Detection — the daemon classifies the failed turn as rate-limited (error heuristics, cross-checked against a forced quota refresh, which also yields the authoritative reset time).

2. Banner above the composer — instead of a bare error state, the composer shows:

   ┌────────────────────────────────────────────────┐
   │ ⚠ Usage limit reached — resets at 14:32        │
   │   Resume this agent automatically?             │
   │           [ Create wake-up schedule ]          │
   ├────────────────────────────────────────────────┤
   │  [ composer …                           ⬆ ]   │
   └────────────────────────────────────────────────┘
   

3. One tap creates the schedule — a one-shot schedule targeting this agent, firing at the reset time (plus a small buffer), sending a continue prompt into the same session.

4. It stays visible while it waits — until it fires, the pending wake-up floats above the composer as a chip with a countdown, one tap to cancel:

   ┌────────────────────────────────────────────────┐
   │ ⏳ Wake-up scheduled · fires in 1h 42m     ✕   │
   ├────────────────────────────────────────────────┤
   │  [ composer …                           ⬆ ]   │
   └────────────────────────────────────────────────┘
   

Consent happens once, at the moment of failure. No setting to discover in advance, no quota burned unattended by default — and unlike a blind cron, you can always see that the agent will wake itself, and how to stop it.

Why a schedule, and not a timer inside the agent

A wake-up should survive daemon restarts, be inspectable in the schedules list, and be cancellable from the same place as every other schedule. The schedule service already is that: persisted storage, a tick loop, and an existing target type that delivers a prompt to an existing agent (ScheduleTarget type agent). The feature composes two things Paseo already has, rather than adding a third way to resume an agent.

What exists today

• Reset times — the quota fetcher retrieves resetsAt for Claude's 5h window and weekly limits, and Codex's primary/secondary windows (packages/server/src/services/quota-fetcher/). Currently feeds the quota UI only.
• Schedules — the schedule service can target an existing agent and deliver a prompt, with persisted storage.
• Session continuity — agent sessions are resumable; failed turns are already resumable, and the system-envelope mechanism (formatSystemNotificationPrompt) exists for injected "continue" prompts.

What's missing

1. Rate-limit classification — turn errors aren't classified today. The heuristic guesses from error text, then confirms with a forced quota refresh. This avoids parsing "resets 3:04pm" out of an error string and handles provider wording drift.
2. One-shot cadence — ScheduleCadence only supports every and cron. A wake-up wants "fire once at time X, then complete" — likely a third cadence variant rather than a fake cron expression.
3. The composer surfaces — the banner CTA and the persistent pending chip. The composer already reacts to per-agent pending state (e.g. pending permission prompts change send behavior), so the slot concept exists.
4. Auto-cancel — if you manually prompt the agent before the wake-up fires, the schedule should probably cancel itself (see open questions).

Open questions

• Weekly caps. When the weekly limit is what's exhausted, resetsAt may be null or days away — a wake-up doesn't help. Degrade to a plain notification ("limit reset, tap to resume") in that case?
• Shared accounts. Multiple agents on one account share the quota. Should wake-ups for the same account be staggered so three agents don't wake at once and immediately re-exhaust the window?
• What the wake-up sends. Re-send the interrupted prompt verbatim, or a system envelope ("you were interrupted by a usage limit — continue where you left off")? The envelope seems safer when the turn died mid-task.
• Buffer and verification. Fire at resetsAt + a minute or two, and re-check the quota before sending — if the window hasn't actually reset, recompute the next wake-up instead of sending into a wall.
• Notification variant. Some users won't want unattended quota burn at all. The push variant ("limit reset, tap to resume") is nearly free once detection exists — worth shipping both?

[Herbrant]

Opened #4494 for the plumbing this proposal needs: pointing a schedule at an agent session that already exists. This proposal is a superset — it also asks for limit detection, the composer banner, and the pending-wake-up chip, and none of that is in #4494. Keeping them separate so the smaller piece can be discussed without deciding the detection design.

[paseo-bot[bot]]

You can build the resume half of this as a plugin today. providers.listUsage() is part of the public SDK as of v0.8.0, so a plugin can read the same quota windows the Settings usage screen shows, including each window's resetsAt, and then prompt the agent itself.

const usage = await paseo.providers.listUsage();
// usage.providers[].windows[].resetsAt
await paseo.agents.ref(agentId).send("continue");

That is not the proposal. There is still no rate-limit classification on a failed turn, no composer banner, and no pending wake-up chip, so a plugin has to decide for itself which agent to resume and when.

The method is documented in the SDK reference and landed in #4062. NaruForge's Provider Usage plugin already reads usage through it if you want a working example of the read side.

Thanks for writing this up with the quota-fetcher detail. It made it easy to check what was already reachable from outside the daemon.

[InfinityMod]

I built a plugin recently for this:

https://github.com/InfinityMod/paseo-wakeup

Feel free to use it.

[kotusenka]

I implemented a related approach in #7193, and am exploring whether it could move into a plugin. I saw the existing paseo-wakeup plugin linked above; it is useful context for that decision.

There are a few differences from the original proposal:

• Detection uses Claude's structured rejected-limit event and its reported reset time, without account-quota polling or parsing a reset time from localized error text. Claude is currently the only adapter supplying this metadata.
• The composer has an off-by-default per-chat switch. Once enabled, it remains enabled for later limit failures in that chat, rather than creating a new one-shot schedule for each failure.
• The daemon persists the pending wait and resumes the same session after the reset plus a one-minute buffer. Manual input, disabling the switch, or archiving cancels the pending continuation. A missing reset time leaves continuation manual.

The main question for a plugin version is access to the structured failed-turn metadata: the current lifecycle hook exposes the error message/code, but not the limit/reset payload. Is there an existing plugin route to this data, or would a small SDK extension be useful for this and similar automation?