🔁 pi-retry — Retry Hints for Pi Provider Errors

@narumitw/pi-retry is a native Pi coding agent extension that treats provider responses containing Unknown error (no error details in response), Codex backend errors that explicitly say the request can be retried, Codex websocket_connection_limit_reached, and stalled provider streams as retryable.

Use it to make Pi sessions more resilient when an upstream AI provider returns a transient unknown error without useful details, Codex reports an explicitly retryable backend failure or asks for a fresh websocket, or a provider stops streaming after Pi has sent a request.

✨ Features

• Detects assistant messages that end with stopReason: "error".
• Matches the known provider error text Unknown error (no error details in response).
• Matches Codex websocket_connection_limit_reached after a websocket hits its 60-minute limit.
• Matches Codex backend failures that explicitly include You can retry your request.
• Appends Pi's retryable-provider-error hint.
• Lets Pi's built-in retry path continue the turn when retry.enabled is true.
• Warns once when Pi's agent-level retry policy is disabled without changing the setting.
• Watches provider requests and assistant stream events for stalls while Pi retries are enabled.
• Aborts and rewrites watchdog-triggered aborts as retryable provider errors.
• Shows receiving in the statusline while provider/stream events are arriving.
• Shows retrying when a matching error or stall triggers retry; @narumitw/pi-statusline adds the default 🔁 icon unless configured otherwise.
• Supports --retry-stall-timeout-ms <ms> and PI_RETRY_STALL_TIMEOUT_MS=<ms>.
• Works as a small, focused npm Pi extension package.

📦 Install

pi install npm:@narumitw/pi-retry

Try without installing permanently:

pi -e npm:@narumitw/pi-retry

Try this package locally from the repository root:

pi -e ./extensions/pi-retry

Pi's agent-level retry policy must be enabled (the default):

{
  "retry": {
    "enabled": true
  }
}

pi-retry warns when this policy is disabled, but it never changes the setting automatically.

🚀 What it does

When an assistant message ends with stopReason: "error" and the error message matches Unknown error (no error details in response), Codex websocket_connection_limit_reached, or a Codex processing error that explicitly says You can retry your request, the extension appends Pi's retryable-provider-error hint so Pi's built-in retry path can continue the turn.

Pi owns retry attempts, the retry budget, and exponential backoff. pi-retry only adds provider-specific classifications and stall detection; it does not implement or enable a separate retry loop. The extension reads Pi's global and trusted-project settings at session start and before provider requests. Current Pi extension contexts do not expose SDK-only in-memory retry overrides, so those overrides cannot be detected yet.

When Pi's retry policy is enabled, the extension also starts a stall watchdog after a provider request. Provider responses and assistant stream events briefly refresh a receiving statusline item, so you can tell that data is still arriving while Pi shows its normal working indicator. If no provider response or assistant stream event is observed for 90s, it briefly shows retrying, calls ctx.abort(), and rewrites the resulting assistant abort/error as a retryable provider error. When retry.enabled is false, the extension disables this watchdog rather than aborting a request that Pi cannot retry.

Configure the watchdog with:

pi -e npm:@narumitw/pi-retry --retry-stall-timeout-ms 10000
PI_RETRY_STALL_TIMEOUT_MS=10000 pi -e npm:@narumitw/pi-retry

Use 0, off, or false to disable the watchdog. Retry attempts, budget, and backoff remain controlled by Pi's built-in auto-retry settings.

🧠 Use cases

• Reduce manual restarts after transient provider failures.
• Recover from explicitly retryable Codex backend failures or websocket connection limits.
• Improve reliability during long Pi coding agent sessions.
• Keep tool-heavy implementation tasks moving when a provider returns an unknown error or stream stalls.
• Pair with @narumitw/pi-goal for more robust autonomous task loops.

🗂️ Package layout

extensions/pi-retry/
├── src/
│   └── retry.ts
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

The package exposes its Pi extension through package.json:

{
  "pi": {
    "extensions": ["./src/retry.ts"]
  }
}

🔎 Keywords

Pi extension, Pi coding agent, retry, provider error, unknown error, stream stall, watchdog, AI provider reliability, agent resilience, TypeScript Pi package, npm Pi extension.

📄 License

MIT. See LICENSE.