Skip to content

README.md

Latest commit

 

History

History
92 lines (65 loc) · 3.86 KB

README.md

File metadata and controls

92 lines (65 loc) · 3.86 KB

🔁 pi-retry — Retry Hints for Pi Provider Errors

npm Pi extension License: MIT

@narumitw/pi-retry is a native Pi coding agent extension that treats provider responses containing Unknown error (no error details in response), 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 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.
  • Appends Pi's retryable-provider-error hint.
  • Lets Pi's built-in retry path continue the turn.
  • Watches provider requests and assistant stream events for stalls.
  • 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

🚀 What it does

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

After Pi sends a provider request, the extension also starts a stall watchdog. 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.

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 and backoff remain controlled by Pi's built-in auto-retry settings.

🧠 Use cases

  • Reduce manual restarts after transient provider failures.
  • Recover when Codex websocket sessions hit the 60-minute connection limit.
  • 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.