MusePi

Non-compaction auto-retry policy

This document describes the standard API-error retry path in AgentSession.

It explicitly excludes context-overflow recovery via auto-compaction. Overflow is handled by compaction logic and is documented separately in compaction.md.

Implementation files

Scope boundary vs compaction

Retry and compaction are checked from the same agent_end path, but they are intentionally separated:

  1. agent_end inspects the last assistant message.
  2. #isRetryableError(...) runs first.
  3. If retry is initiated, compaction checks are skipped for that turn.
  4. Context-overflow errors are hard-excluded from retry classification (isContextOverflow(...) short-circuits retry).
  5. Overflow therefore falls through to #checkCompaction(...) instead of standard retry.

So: overload/rate/server/network-style failures use this retry policy; context-window overflow uses compaction recovery.

Retry classification

#isRetryableError(...) requires all of the following:

The stale-replay and transient/usage-limit branches additionally require that the stream was not interrupted after already emitting observable output. #streamInterruptedAfterObservableOutput(...) treats a STREAM_INTERRUPTED_AFTER_CONTENT stop detail — or any tool call, non-empty text, thinking, or redacted-thinking block — as non-retryable, so a partially produced turn is not silently replayed. Classifier refusals are checked first and bypass this exclusion.

Current retryable inputs are regex/string-classified:

Transport classification is regex text matching, not typed provider error codes; classifier refusals are the exception, detected from the typed stopDetails field.

Beyond #isRetryableError(...), a narrower trigger feeds the same retry engine: #isRetryableReasonlessAbort(...) routes a content-less aborted stop carrying the generic abort sentinel (GENERIC_ABORT_SENTINEL) — only when no user, dispose, or streaming-edit-guard abort is in progress — into #handleRetryableError(message, { allowModelFallback: false }), i.e. retried without model fallback.

Retry lifecycle and state transitions

Session state used by retry:

Flow (#handleRetryableError):

  1. Read retry settings group.
  2. If retry.enabled === false, stop immediately (false, no retry started).
  3. Increment #retryAttempt.
  4. Create #retryPromise once (first attempt in a chain).
  5. If attempt exceeded retry.maxRetries, emit final failure event and stop.
  6. Compute capped jittered local delay: min(retry.baseDelayMs * 2^(attempt-1), 8000ms) * (75–100% jitter). Stale OpenAI Responses replay errors skip the backoff entirely (delay 0) after resetting the cached provider session.
  7. For usage-limit errors, parse retry hints and call auth storage (markUsageLimitReached(...)); if credential switching succeeds — including spending a banked Codex reset via the opt-in auto-redeem — force delay to 0. Otherwise wait for whichever comes first — the provider’s retry-after/backoff hint, or the earliest moment a temporarily blocked sibling credential frees up (retryAtMs + 1s buffer) so the next attempt can pick it up.
  8. If no credential switch occurred and retry.modelFallback is enabled, suppress the current model selector for cooldown and try configured retry model fallback chains, forcing delay to 0 on model switch. Classifier refusals skip the cooldown and only proceed when a fallback model was actually applied (pinned); with no fallback, the chain ends without an auto_retry_start.
  9. If the final delay exceeds retry.maxDelayMs and no credential/model switch happened, emit final failure and do not sleep.
  10. Emit auto_retry_start.
  11. Remove the trailing assistant error message from agent runtime state (kept in persisted session history).
  12. Sleep with abort support.
  13. Schedule agent.continue() through the post-prompt task scheduler (delayMs: 1) for the same prompt generation.

What resets retry counters

#retryAttempt resets to 0 in these cases:

#retryPromise resolves/clears when retry chain ends (success, cancellation, max-exceeded, max-delay failure, or classifier-refusal stop), via #resolveRetry().

Backoff and max-attempt semantics

Settings:

Attempt numbering:

Backoff sequence with default settings, before jitter:

The actual local sleep is 75–100% of the nominal value, matching Anthropic-style retry jitter so concurrent sessions do not retry in lockstep.

Delay override inputs can come from parsed retry headers (retry-after-ms, retry-after, x-ratelimit-reset-ms, x-ratelimit-reset) or usage-limit backoff. Credential/model fallback switches set delay to 0; otherwise parsed hints can extend the capped local delay. If the computed delay is greater than retry.maxDelayMs and no switch succeeded, retry ends immediately with a final error instead of sleeping.

Abort mechanics

Explicit retry abort

abortRetry():

If abort hits while sleeping, catch path emits:

Global operation abort interaction

abort() calls abortRetry() before aborting the active agent stream. This guarantees retry backoff is cancelled when user issues a general abort.

TUI interaction

On auto_retry_start, EventController (#handleAutoRetryStart):

Esc cancellation dispatches on live session state rather than a swapped handler: the input controller checks viewSession.isRetrying and calls viewSession.abortRetry() (alongside its compaction/handoff abort checks).

On auto_retry_end (#handleAutoRetryEnd), it stops and clears the retryLoader and status container.

Streaming and prompt completion behavior

prompt() ultimately waits on #waitForPostPromptRecovery() after agent.prompt(...) returns; that loop awaits the retry lifecycle promise alongside TTSR resume and deferred post-prompt tasks.

Effect:

This prevents callers from treating a retrying turn as complete too early.

Controls: settings and RPC

Configuration knobs

Defined in settings schema under retry group:

Programmatic toggles in session:

RPC controls

RPC command surface:

Client helpers:

Both commands return success responses; retry progress/failure details come from streamed session events, not command response payloads.

Event emission and failure surfacing

Session-level retry events:

Propagation:

Final failure surfacing:

Permanent stop conditions

Retry stops and will not auto-continue when any of these occur:

A new retry chain can still start later on a future retryable error after counters reset.

Operational caveats