Auto-Continue After Usage Limit


ID	`usage_limit_auto_continue`
Category	Core
Features	None
Dependencies	None
Risk	Low

Some providers cap usage per subscription window rather than per minute. When a plan usage limit is hit — for example the ChatGPT/Codex 429 usage_limit_reached response — the turn fails and the session goes idle until the limit resets, often hours later. This capability makes the session resume on its own once the window clears, so long-running work is not silently stranded.

It contributes no tools. The behavior is encapsulated behind a reusable platform seam — the capability supplies an LLM error hook (an in-process capability hook, the same family as tool-call hooks and message filters) that the agent runtime invokes generically when a turn fails with a terminal error. The runtime has no special-casing for usage limits; any capability can provide the same kind of error-recovery hook.

How It Works

Classification — The provider error is classified as provider_usage_limit_reached, which captures the absolute reset time (resets_at, unix seconds) reported by the provider. This is driver-agnostic: any driver whose error body carries the usage_limit_reached wording is covered.
Scheduling — When the capability is enabled and a reset time is present, a one-shot session schedule is created to fire delay_seconds after the reset. When it fires, the configured prompt is injected as a user message and the interrupted work resumes.
Message copy — The user-facing error reads “You’re out of LLM usage limits. Your usage limit resets at <time>.” When (and only when) a continuation was actually scheduled, it appends “We’ll continue work automatically once it resets.” — so the copy never promises a resumption that will not happen. Without the capability, the same error stays generic and no continuation is scheduled.

Configuration

Default

{
  "capabilities": ["usage_limit_auto_continue"]
}

Defaults: continuation fires 120 seconds after the reported reset with the prompt “Continue tasks”.

Custom delay and prompt

{
  "capabilities": [
    {
      "ref": "usage_limit_auto_continue",
      "config": {
        "delay_seconds": 300,
        "prompt": "Resume the migration where you left off."
      }
    }
  ]
}

Field	Type	Default	Description
`delay_seconds`	integer (0–86400)	`120`	How long to wait after the reset before resuming. A small buffer avoids racing the provider’s reset clock.
`prompt`	string	`"Continue tasks"`	Message injected to resume work when the limit resets.

When To Enable

Use this capability for agents running long, autonomous, or scheduled work on provider plans that enforce usage-window limits, where a multi-hour stall would otherwise require a human to manually restart the session.

Limitations

Requires a provider whose error reports a concrete reset time; without one the error copy stays generic and no continuation is scheduled.
The continuation is delivered through the session schedule machinery, so it requires both a session schedule store and a schedule poller in the deployment. The hosted platform provides both. The default embedded runtime provides neither, so this capability is not part of the runtime-safe preset — an embedder must wire a SessionScheduleStore (e.g. via a schedule-store factory) and run a poller for it to take effect; otherwise its error hook is a no-op and the error copy stays generic.