OAuth token expired mid-run and the triage agent's Graph session died; the sweep failed
Recovers a triage agent whose Graph session died when its OAuth credential expired mid-run, by refreshing proactively and checkpointing the sweep. Use when long sweeps fail partway with authentication errors despite valid overall access. Not for revoked credentials, which need re-authorisation.
TL;DR
Long sweeps outlive short-lived access credentials by design: a run that starts valid can cross the expiry boundary mid-sweep, and an agent that only authenticates at start dies on schedule. Acquire credentials per work unit or refresh before each batch using the stored refresh flow, check remaining lifetime before starting a batch, and checkpoint progress at batch boundaries so an auth failure costs one batch, not the sweep.
OAuth token expired mid-run and the triage agent's Graph session died; the sweep failedUse this when
- Sweeps fail at a consistent elapsed time after start with auth errors.
- Restarting the agent makes the same sweep work immediately.
Not for this skill when
- The credential was revoked or the app consent removed. Refresh will fail; that needs an admin.
- Failures are permission errors on specific mailboxes, not time-based. That is scoping, not expiry.
Steps
- Correlate failure times with run start times across several runs. Verify: failures cluster near the credential lifetime, confirming expiry.
- Inspect the auth code path: when credentials are acquired, whether refresh is ever called, and how expiry is handled. Verify: the missing refresh is located.
- Implement refresh before each batch when remaining lifetime is under a safety margin, using the vault-stored refresh material. Verify: a long test run crosses the old expiry point without failing.
- Checkpoint the sweep at each batch so an unrecoverable auth error ends the run cleanly with resumable state. Verify: killing the run during a batch loses at most that batch.
- Run a sweep longer than the credential lifetime. Verify: it completes, with refresh events logged.
Variant phrasings
oauth token expired mid run graph agent refresh
The mid-run expiry variant.
long sweep authentication refresh checkpoint agent
The refresh design variant.
Compatibility: OAuth 2.0 flows with Microsoft Graph and comparable APIs, agent batch runners.
Why it happens
Credential lifetimes are set for interactive sessions measured in minutes to hours, while agent sweeps are measured in hours to days. Any design that authenticates once inherits the session lifetime as its maximum run time, whether the author noticed or not.
Edge cases / pitfalls
- Refresh material is a high-value secret. Store it in the vault and never in run logs or config files in plain form.
- Clock skew between the agent host and the identity provider eats lifetime margin. Keep host time synced.
- Alert on refresh failures separately from run failures; they predict total outage one lifetime later.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_NnE5-S32phWZ-K0OWiQ-5Q