@monotykamary/pi-retry 0.2.0

package/README.md

@@ -0,0 +1,305 @@
+<div align="center">
+
+# 🔄 pi-retry
+
+**Automatic retry for every error in [pi](https://github.com/earendil-works/pi-coding-agent)**
+
+_400/413, connection errors, credit errors, stream exhaustion — retry them all._
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+---
+
+## Overview
+
+This extension automatically detects and retries **all** errors by default, with only a tiny blacklist of known permanent failures (invalid API key, missing model, etc.).
+
+| Error Type | Retry Behavior | Use Case |
+|------------|----------------|----------|
+| **Any retryable error** (catch-all) | **Indefinite** with capped backoff | Everything else — provider hiccups, stream exhaustion, credit issues, unknown errors |
+| HTTP 400/413 | **Indefinite** with capped backoff, NO compaction | Transient context overflow that might resolve |
+| Credit / payment errors | **Indefinite** with capped backoff | "Not Enough Credits", insufficient balance, 402 |
+| Connection errors | **Indefinite** with capped backoff | Network hiccups, connection drops, socket errors, stream exhaustion |
+| Max tokens (`stopReason: "length"`) | **Auto-continue** indefinitely (invisible — no prompt pollution) | Model hits output token limit mid-generation |
+
+---
+
+## The Problem
+
+By default, pi has built-in retry for some errors (rate limits, 5xx, overloaded), but:
+
+1. **400/413 errors** are treated as context overflow → triggers compaction but NO retry
+2. **Connection errors** sometimes get only limited retries before giving up
+3. **Credit errors** ("Not Enough Credits") are never retried
+4. **Stream exhaustion** ("Max outbound streams") and other provider-specific errors are never retried
+5. **Any unknown error** from a new provider is silently ignored
+
+## The Solution
+
+This extension provides **automatic** infinite retry with sensible exponential backoff (2s → 4s → 8s → ... → 60s max).
+
+**Philosophy: retry EVERYTHING by default.** The only things we skip are a tiny blacklist of known permanent failures (invalid API key, model not found, unsupported model, etc.).
+
+**Features:**
+- **Catch-all retry** — Any `stopReason: "error"` is retried, regardless of error message
+- Automatic detection of 400/413, connection, credit, and stream exhaustion errors
+- **Auto-continuation** when the model hits its max output tokens (`stopReason: "length"`) — indefinite, no cap, **invisible** to the LLM
+- **Indefinite retry** — Keeps retrying until success
+- Exponential backoff with cap: max 60s between retries
+- **ALL triggers are invisible** — custom messages with `display: false`, stripped by context handler (no TUI clutter, no conversation pollution)
+- Manual controls via unified `/retry` command
+- Non-retryable errors are explicitly logged so you know why we didn't retry
+
+---
+
+## Installation
+
+### Option 1: Install via pi package (Recommended)
+
+Install directly from GitHub as a pi package:
+
+```bash
+pi install https://github.com/monotykamary/pi-retry
+```
+
+Or add to your `settings.json`:
+
+```json
+{
+  "packages": [
+    "https://github.com/monotykamary/pi-retry"
+  ]
+}
+```
+
+### Option 2: Global Installation
+
+Copy the extension to pi's global extensions directory:
+
+```bash
+cp retry.ts ~/.pi/agent/extensions/
+```
+
+### Option 3: Project-Local Installation
+
+Copy to your project's `.pi/extensions/` directory:
+
+```bash
+mkdir -p .pi/extensions
+cp retry.ts .pi/extensions/
+```
+
+### Option 4: Quick Test
+
+```bash
+pi -e ./retry.ts
+```
+
+---
+
+## Usage
+
+Once loaded, the extension **automatically** detects and retries all errors.
+
+### Manual Controls
+
+| Command | Description |
+|---------|-------------|
+| `/retry` | Manually trigger immediate retry (auto-detects: 400/413, credit, connection, max_tokens, or any other error) |
+| `/retry status` | Show current retry diagnostics for all error types + continuation state |
+| `/retry reset` | Reset all retry counters and state |
+
+---
+
+## Configuration
+
+Edit the constants at the top of `retry.ts`:
+
+```typescript
+const BASE_DELAY_MS = 2000;        // Start with 2 seconds
+const MAX_DELAY_MS = 60000;        // Cap at 60 seconds
+const BACKOFF_MULTIPLIER = 2;      // Double each time
+// Continuation is now invisible — no CONTINUATION_PROMPT needed
+```
+
+---
+
+## How It Works
+
+1. **Listen to `agent_end` event** — Fires after each agent turn completes
+2. **Check for any error** — Examine the last assistant message for `stopReason === "error"`
+3. **Blacklist check** — Skip known permanent failures (invalid API key, model not found, etc.)
+4. **Categorize for messaging** — Classify into 400/413, credit, connection, or other for nice UI notifications
+5. **Retry or continue (both invisible)** — Wait (exponential backoff for errors), then trigger a new turn via `pi.sendMessage()` with `customType`, `display: false`, and `triggerTurn: true`
+6. **Context cleanup** — The `context` event strips all custom-type triggers before the LLM sees them (insurance against custom `convertToLlm` overrides)
+7. **Indefinite continuation** — Max_tokens auto-continues are uncapped; each continuation produces valid output and the model naturally terminates when done
+
+The pi's built-in `transform-messages` already strips aborted/errored assistant messages from the LLM context, so the model never sees the failed attempts.
+
+---
+
+## Detected Error Patterns
+
+### Catch-All (Any Error)
+- **Any** assistant message with `stopReason === "error"` is retried by default
+- Unknown provider errors, stream errors, unexpected failures — all handled automatically
+- Only skipped if it matches a known permanent failure (invalid API key, missing model, etc.)
+
+### Non-Retryable (Permanent Failures)
+These are explicitly **not** retried:
+- Invalid API key / invalid authentication
+- API key not found / missing / revoked
+- Model not found / unknown model / no such model / model does not exist
+- Unsupported model
+
+### Max Tokens (stopReason: "length")
+- The model hit its `max_tokens` / output token limit
+- The model's response was truncated mid-generation
+- Auto-continuation sends an invisible custom message — no visible "Continue" prompt in the conversation
+
+### 400/413 Errors
+- HTTP 400 Bad Request
+- HTTP 413 Payload Too Large
+- "bad request" messages
+- "payload too large" messages
+
+### Credit / Payment Errors
+- "Not Enough Credits"
+- "insufficient credits"
+- "insufficient balance"
+- "out of credits"
+- "Payment Required"
+- HTTP 402 status code
+
+### Connection Errors
+- Connection / network errors
+- Fetch failures
+- Socket hang up / socket errors
+- `ECONNRESET`, `ECONNREFUSED`, `ETIMEDOUT`, `ENOTFOUND`
+- DNS lookup failures
+- "Request ended without sending any chunks"
+- Upstream connect errors
+- TLS handshake errors
+- Timeouts awaiting response
+- Stream exhaustion ("Max outbound streams is 100, 100 open")
+- Stream limit errors
+
+---
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+
+# Type check
+npm run typecheck
+
+# Dead code detection
+npm run lint:dead
+```
+
+### Project Structure
+
+```
+.
+├── retry.ts                   # Main unified extension
+├── src/                       # Shared utilities (testable, DRY)
+│   ├── error-patterns.ts      # Error pattern matching, custom types, hasMaxTokensStop
+│   ├── retry-logic.ts         # Retry utilities (calculateDelay, RetryState, ContinuationState, etc.)
+│   └── index.ts               # Barrel exports
+├── __tests__/                 # Unit tests
+│   └── unit/
+│       ├── error-patterns.test.ts
+│       └── retry-logic.test.ts
+├── vitest.config.ts           # Test configuration
+└── knip.json                  # Dead code detection config
+```
+
+### Code Quality
+
+```bash
+# Run all quality checks
+npm test              # 99 unit tests
+npm run typecheck     # TypeScript type checking
+npm run lint:dead     # Dead code detection with knip
+```
+
+---
+
+## Troubleshooting
+
+### Extension not working?
+
+Check that it's loaded in the startup header:
+```
+Loaded extensions: retry.ts
+```
+
+### Retry not triggering?
+
+Use the status command to diagnose:
+```
+/retry status
+```
+
+### Want to see what's happening?
+
+The extensions send notifications on retry attempts. Look at the footer status line for retry status updates. Non-retryable errors are logged as errors so you know why we stopped.
+
+### Too many retries?
+
+Use `/retry reset` to clear the counters, or press `Ctrl+C` to abort the session.
+
+---
+
+## Comparison with @georgebashi/pi-retry
+
+The npm package `@georgebashi/pi-retry` handles "aborted" streaming errors but explicitly excludes "connection error" (assuming pi's built-in retry handles it). This extension:
+
+1. **Handles ALL errors** via a catch-all — no more playing whack-a-mole with new error patterns
+2. **Handles connection errors** that pi might not retry sufficiently
+3. **Handles 400/413 errors** without compaction
+4. **Handles credit errors** and stream exhaustion
+
+They can work together for maximum coverage:
+
+```bash
+pi install npm:@georgebashi/pi-retry
+# Plus install this extension
+```
+
+---
+
+## Limitations
+
+- Extensions cannot override pi's internal `isRetryableError()` check — they run *after* pi decides not to auto-retry
+- Error messages remain in the session history (but are invisible to the LLM)
+- May hit the same error repeatedly if the issue is persistent (use `Ctrl+C` to abort)
+- **Warning**: Retrying 400/413 without reducing context may fail repeatedly if the payload is genuinely too large
+- Non-retryable errors (invalid API key, missing model) are logged but not retried — you'll need to fix the underlying issue
+
+---
+
+## Related
+
+- [Pi Coding Agent Extensions Docs](https://github.com/badlogic/pi/tree/main/packages/coding-agent/docs/extensions.md)
+- [@georgebashi/pi-retry](https://github.com/georgebashi/pi-retry) — Handles "aborted" streaming errors
+- [Issue #252: Connection error with no retry](https://github.com/badlogic/pi-mono/issues/252)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@monotykamary/pi-retry",
+  "version": "0.2.0",
+  "description": "Extension suite for pi coding agent that handles 400/413 errors and connection errors with automatic retry",
+  "type": "module",
+  "author": "Tom X Nguyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-retry.git"
+  },
+  "homepage": "https://github.com/monotykamary/pi-retry#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/pi-retry/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "retry",
+    "error-handling",
+    "http-400",
+    "http-413",
+    "connection-error",
+    "network-error",
+    "infinite-retry",
+    "cli"
+  ],
+  "files": [
+    "*.ts",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint:dead": "knip --no-gitignore"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.75.4",
+    "@earendil-works/pi-coding-agent": "0.75.4",
+    "@types/node": "25.9.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "knip": "6.14.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
+  },
+  "pi": {
+    "extensions": [
+      "./retry.ts"
+    ]
+  },
+  "overrides": {
+    "brace-expansion": "5.0.6"
+  }
+}

package/retry.ts

@@ -0,0 +1,327 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  RETRY_TRIGGER_CUSTOM_TYPE,
+  CONTINUATION_CUSTOM_TYPE,
+  has400or413Error,
+  hasCreditError,
+  hasConnectionError,
+  hasRetryableError,
+  isNonRetryableError,
+  hasMaxTokensStop,
+  isAssistantMessage,
+  getLastAssistantMessage,
+  calculateDelay,
+  formatDuration,
+  getErrorCategory,
+  RetryState,
+  ContinuationState,
+} from "./src/index.js";
+
+/**
+ * Unified retry extension — retries EVERY error by default.
+ *
+ * Philosophy: any assistant message with stopReason === "error" is retried
+ * indefinitely with exponential backoff, except a tiny blacklist of known
+ * permanent failures (invalid API key, model not found, etc.).
+ *
+ * Specific categories (400/413, credit, connection, stream exhaustion, etc.)
+ * are tracked for diagnostics but all share the same retry mechanism.
+ *
+ * Features:
+ * - Automatic detection and retry for ALL errors (catch-all)
+ * - Indefinite retry with exponential backoff (capped at 60s)
+ * - Auto-continuation when model hits max output tokens (stopReason "length")
+ * - ALL triggers are invisible — custom messages with display:false, stripped by context handler
+ * - Unified manual controls via /retry command
+ *
+ * Silent continue trick (ported from pi-invisible-continue):
+ *   - sendMessage() with customType + display:false + triggerTurn:true
+ *   - pi's default convertToLlm filters custom-role messages → LLM never sees them
+ *   - context event handler strips them as insurance against custom convertToLlm overrides
+ *   - No user-visible "Continue" message pollution in the conversation
+ */
+
+// Per-category retry state (for diagnostics / messaging)
+const state400 = new RetryState();
+const stateCredit = new RetryState();
+const stateConnection = new RetryState();
+const stateOther = new RetryState();
+
+// Max_tokens continuation state (indefinite — no cap needed)
+const stateContinuation = new ContinuationState();
+
+// Sleep helper
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export default function (pi: ExtensionAPI) {
+
+  // Reset retry counters on successful completion (not max_tokens, not error)
+  pi.on("turn_end", async (event, ctx) => {
+    const msg = event.message as any;
+    if (msg.role === "assistant" && msg.stopReason !== "error") {
+      if (msg.stopReason === "aborted") {
+        // User cancelled — reset retry state so it doesn't leak into other
+        // branches of the session tree.
+        state400.reset();
+        stateCredit.reset();
+        stateConnection.reset();
+        stateOther.reset();
+        // Do NOT reset continuation state — a user abort of a continuation
+        // turn is different from aborting an error retry.
+        stateContinuation.endContinuation();
+        return;
+      }
+      if (msg.stopReason !== "length") {
+        // Normal completion — reset everything including continuation count
+        state400.succeed();
+        stateCredit.succeed();
+        stateConnection.succeed();
+        stateOther.succeed();
+        stateContinuation.complete();
+      }
+    }
+  });
+
+  // Handle errors and max_tokens on agent_end
+  pi.on("agent_end", async (event, ctx) => {
+    const entries = ctx.sessionManager.getEntries();
+    const lastAssistant = getLastAssistantMessage(entries);
+    
+    if (!lastAssistant || !isAssistantMessage(lastAssistant)) {
+      return;
+    }
+
+    // Check for max_tokens stop — auto-continue (silent, invisible to LLM)
+    if (hasMaxTokensStop(lastAssistant) && !stateContinuation.getIsContinuing()) {
+      stateContinuation.startContinuation();
+      ctx.ui.notify(
+        `Max tokens reached — auto-continuing (continuation ${stateContinuation.getCount()})...`,
+        "info",
+      );
+      triggerContinuation(pi);
+      stateContinuation.endContinuation();
+      return;
+    }
+
+    // Catch-all: retry ANY error except known permanent failures
+    if (hasRetryableError(lastAssistant)) {
+      const errorMsg = lastAssistant.errorMessage || "Unknown error";
+      const category = getErrorCategory(errorMsg);
+
+      // Pick the right state tracker for diagnostics
+      let state: RetryState;
+      let label: string;
+      if (category === "400-413") {
+        state = state400;
+        label = "400/413";
+      } else if (category === "credit") {
+        state = stateCredit;
+        label = "Credit";
+      } else if (category === "connection") {
+        state = stateConnection;
+        label = "Connection";
+      } else {
+        state = stateOther;
+        label = category === "builtin" ? "Server" : "Other";
+      }
+
+      if (state.getIsRetrying()) return;
+
+      state.startRetry(errorMsg);
+      const delay = calculateDelay(state.getAttempt());
+
+      await sleep(delay);
+      triggerRetry(pi);
+      state.endRetry();
+      return;
+    }
+
+    // Log non-retryable errors so the user knows why we didn't retry
+    if (isNonRetryableError(lastAssistant)) {
+      const errorMsg = lastAssistant.errorMessage || "Unknown error";
+      ctx.ui.notify(`Non-retryable error (not retried): ${errorMsg.substring(0, 100)}`, "error");
+    }
+  });
+
+
+
+  // Strip hidden retry/continuation markers from context before each LLM call.
+  // This is insurance — convertToLlm already filters custom roles, but a
+  // custom convertToLlm override could leak them.  Clean proactively.
+  pi.on("context", async (event) => {
+    const cleaned = event.messages.filter(
+      (msg: any) =>
+        !(
+          msg.role === "custom" &&
+          (msg.customType === RETRY_TRIGGER_CUSTOM_TYPE ||
+            msg.customType === CONTINUATION_CUSTOM_TYPE)
+        ),
+    );
+    if (cleaned.length !== event.messages.length) {
+      return { messages: cleaned };
+    }
+  });
+
+  // Unified /retry command with subcommands
+  pi.registerCommand("retry", {
+    description: "Unified retry controls: /retry (manual trigger), /retry status (diagnostics), /retry reset (clear state)",
+    handler: async (args, ctx) => {
+      const subcommand = args[0]?.toLowerCase();
+
+      // /retry status - Show diagnostics
+      if (subcommand === "status") {
+        const entries = ctx.sessionManager.getEntries();
+        const lastAssistant = getLastAssistantMessage(entries);
+        
+        let status = "=== Retry Status ===\n\n";
+        
+        // 400/413 state
+        status += "400/413 Errors:\n";
+        status += `  Current attempt: ${state400.getAttempt()}\n`;
+        status += `  Is retrying: ${state400.getIsRetrying()}\n`;
+        status += `  Last error: ${state400.getLastErrorMessage().substring(0, 100) || "None"}\n\n`;
+
+        // Credit state
+        status += "Credit Errors:\n";
+        status += `  Current attempt: ${stateCredit.getAttempt()}\n`;
+        status += `  Is retrying: ${stateCredit.getIsRetrying()}\n`;
+        status += `  Last error: ${stateCredit.getLastErrorMessage().substring(0, 100) || "None"}\n\n`;
+
+        // Connection state
+        status += "Connection Errors:\n";
+        status += `  Current attempt: ${stateConnection.getAttempt()}\n`;
+        status += `  Is retrying: ${stateConnection.getIsRetrying()}\n`;
+        status += `  Last error: ${stateConnection.getLastErrorMessage().substring(0, 100) || "None"}\n\n`;
+
+        // Other / catch-all state
+        status += "Other Errors (catch-all):\n";
+        status += `  Current attempt: ${stateOther.getAttempt()}\n`;
+        status += `  Is retrying: ${stateOther.getIsRetrying()}\n`;
+        status += `  Last error: ${stateOther.getLastErrorMessage().substring(0, 100) || "None"}\n\n`;
+        
+        // Continuation state
+        status += "Max Tokens Continuation:\n";
+        status += `  Continuations used: ${stateContinuation.getCount()}\n`;
+        status += `  Is continuing: ${stateContinuation.getIsContinuing()}\n`;
+        status += `  Trigger: invisible (custom message, LLM never sees a prompt)\n\n`;
+        
+        // Config
+        status += "Configuration:\n";
+        status += `  Base delay: 2000ms\n`;
+        status += `  Max delay: 60000ms\n`;
+        status += `  Backoff multiplier: 2\n`;
+        status += `  Continuation: invisible custom message\n\n`;
+        
+        // Last assistant info
+        if (lastAssistant && isAssistantMessage(lastAssistant)) {
+          status += "Last Assistant Message:\n";
+          status += `  Stop reason: ${lastAssistant.stopReason}\n`;
+          status += `  Error message: ${lastAssistant.errorMessage?.substring(0, 100) || "None"}\n`;
+          if (lastAssistant.errorMessage) {
+            status += `  Error category: ${getErrorCategory(lastAssistant.errorMessage)}`;
+          }
+        }
+        
+        ctx.ui.notify(status, "info");
+        return;
+      }
+
+      // /retry reset - Reset all state
+      if (subcommand === "reset") {
+        state400.reset();
+        stateCredit.reset();
+        stateConnection.reset();
+        stateOther.reset();
+        stateContinuation.reset();
+        ctx.ui.notify("All retry counters reset", "info");
+        return;
+      }
+
+      // /retry (no args) - Manual trigger with auto-detection
+      const entries = ctx.sessionManager.getEntries();
+      const lastAssistant = getLastAssistantMessage(entries);
+      
+      if (!lastAssistant || !isAssistantMessage(lastAssistant)) {
+        ctx.ui.notify("No assistant message found to retry", "warning");
+        return;
+      }
+
+      // Auto-detect: max_tokens continuation takes priority
+      if (hasMaxTokensStop(lastAssistant)) {
+        ctx.ui.notify("Manually continuing after max_tokens...", "info");
+        triggerContinuation(pi);
+        return;
+      }
+
+      // Auto-detect error type and trigger appropriate retry
+      if (has400or413Error(lastAssistant)) {
+        ctx.ui.notify("Manually retrying 400/413 error...", "info");
+        state400.reset();
+        triggerRetry(pi);
+        return;
+      }
+
+      if (hasCreditError(lastAssistant)) {
+        ctx.ui.notify("Manually retrying credit error...", "info");
+        stateCredit.reset();
+        triggerRetry(pi);
+        return;
+      }
+
+      if (hasConnectionError(lastAssistant)) {
+        ctx.ui.notify("Manually retrying connection error...", "info");
+        stateConnection.reset();
+        triggerRetry(pi);
+        return;
+      }
+
+      // Catch-all: any other retryable error
+      if (hasRetryableError(lastAssistant)) {
+        ctx.ui.notify("Manually retrying error...", "info");
+        stateOther.reset();
+        triggerRetry(pi);
+        return;
+      }
+
+      // No error detected - show status instead
+      ctx.ui.notify("No retryable error detected. Use '/retry status' for diagnostics.", "warning");
+    }
+  });
+
+  // Initialize
+  pi.on("session_start", async () => {
+    state400.reset();
+    stateCredit.reset();
+    stateConnection.reset();
+    stateOther.reset();
+    stateContinuation.reset();
+  });
+
+  // Helper: send the hidden retry trigger
+  function triggerRetry(pi: ExtensionAPI) {
+    pi.sendMessage(
+      {
+        customType: RETRY_TRIGGER_CUSTOM_TYPE,
+        content: "",
+        display: false,
+        details: {},
+      },
+      { triggerTurn: true },
+    );
+  }
+
+  // Helper: send the hidden continuation trigger (silent — LLM never sees a prompt)
+  function triggerContinuation(pi: ExtensionAPI) {
+    pi.sendMessage(
+      {
+        customType: CONTINUATION_CUSTOM_TYPE,
+        content: "",
+        display: false,
+        details: {},
+      },
+      { triggerTurn: true },
+    );
+  }
+}

package/src/error-patterns.ts

@@ -0,0 +1,156 @@
+/**
+ * Error pattern matching utilities for retry extensions
+ *
+ * Philosophy: retry EVERY error by default.  The only things we skip are a
+ * tiny blacklist of known permanent failures (e.g. invalid API key, model
+ * does not exist).  Everything else — 400s, connection issues, credit errors,
+ * stream exhaustion, provider hiccups, unknown errors — is retried.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+// Custom message types for invisible triggers.
+// These are sent with role="custom" and display=false, so pi's default
+// convertToLlm filters them out.  The context event handler also strips
+// them as insurance.
+
+/** Custom type used for the invisible error-retry trigger. */
+export const RETRY_TRIGGER_CUSTOM_TYPE = "__retry_trigger";
+
+/** Custom type used for the invisible max_tokens continuation trigger. */
+export const CONTINUATION_CUSTOM_TYPE = "__retry_continuation";
+
+// ── Specific pattern groups (used for categorisation / messaging) ──
+
+const ERROR_400_413_PATTERNS = [
+  /\b4(00|13)\b.*status code/i,
+  /bad request/i,
+  /payload too large/i,
+];
+
+const CREDIT_ERROR_PATTERNS = [
+  /not enough credits/i,
+  /insufficient credits/i,
+  /insufficient balance/i,
+  /out of credits/i,
+  /payment required/i,
+  /\b402\b.*status code/i,
+];
+
+export const CONNECTION_ERROR_PATTERNS = [
+  /connection\s*error/i,
+  /network\s*error/i,
+  /fetch\s*failed/i,
+  /socket\s*(hang\s*up|error|timeout)/i,
+  /econnreset/i,
+  /econnrefused/i,
+  /etimedout/i,
+  /enotfound/i,
+  /dns\s*lookup\s*failed/i,
+  /request\s*ended\s*without\s*sending\s*any\s*chunks/i,
+  /upstream\s*connect/i,
+  /other\s*side\s*closed/i,
+  /reset\s*before\s*headers/i,
+  /broken\s*pipe/i,
+  /unexpected\s*end\s*of\s*file/i,
+  /tls\s*handshake\s*(error|timeout)/i,
+  /ssl\s*connection\s*error/i,
+  /timeout\s*(awaiting|waiting\s*for)\s*response/i,
+  /request\s*timeout/i,
+  // Stream exhaustion (e.g. "Max outbound streams is 100, 100 open")
+  /max outbound streams/i,
+  /streams?\s*(exhausted|limit)/i,
+];
+
+// Patterns handled by pi's built-in retry — used for categorisation only
+const BUILTIN_HANDLED_PATTERNS = [
+  /overloaded/i,
+  /rate\s*limit/i,
+  /too\s*many\s*requests/i,
+  /429/i,
+  /5\d{2}/,
+  /service\s*unavailable/i,
+  /server\s*error/i,
+  /internal\s*error/i,
+  /retry\s*delay/i,
+];
+
+// ── Blacklist: errors that are truly permanent and should NOT be retried ──
+
+const NON_RETRYABLE_PATTERNS = [
+  /invalid\s*api\s*key/i,
+  /invalid\s*authentication/i,
+  /api\s*key\s*(not\s*found|missing|revoked)/i,
+  /model\s*not\s*found/i,
+  /unknown\s*model/i,
+  /no\s*such\s*model/i,
+  /model\s*does\s*not\s*exist/i,
+  /unsupported\s*model/i,
+];
+
+// ── Type guard ──
+
+export function isAssistantMessage(message: AgentMessage): message is Extract<AgentMessage, { role: "assistant" }> {
+  return message.role === "assistant";
+}
+
+// ── Specific category checks (for diagnostics / messaging) ──
+
+export function has400or413Error(message: AgentMessage): boolean {
+  if (!isAssistantMessage(message)) return false;
+  if (message.stopReason !== "error" || !message.errorMessage) return false;
+  return ERROR_400_413_PATTERNS.some(p => p.test(message.errorMessage!));
+}
+
+export function hasCreditError(message: AgentMessage): boolean {
+  if (!isAssistantMessage(message)) return false;
+  if (message.stopReason !== "error" || !message.errorMessage) return false;
+  return CREDIT_ERROR_PATTERNS.some(p => p.test(message.errorMessage!));
+}
+
+export function hasConnectionError(message: AgentMessage): boolean {
+  if (!isAssistantMessage(message)) return false;
+  if (message.stopReason !== "error" || !message.errorMessage) return false;
+  return CONNECTION_ERROR_PATTERNS.some(p => p.test(message.errorMessage!));
+}
+
+// ── Universal retry check ──
+
+/**
+ * Returns true for ANY assistant message with stopReason === "error"
+ * except a tiny blacklist of known permanent failures.
+ */
+export function hasRetryableError(message: AgentMessage): boolean {
+  if (!isAssistantMessage(message)) return false;
+  if (message.stopReason !== "error" || !message.errorMessage) return false;
+  return !NON_RETRYABLE_PATTERNS.some(p => p.test(message.errorMessage));
+}
+
+/**
+ * Returns true only for known permanent failures (invalid API key, missing model, etc.)
+ */
+export function isNonRetryableError(message: AgentMessage): boolean {
+  if (!isAssistantMessage(message)) return false;
+  if (message.stopReason !== "error" || !message.errorMessage) return false;
+  return NON_RETRYABLE_PATTERNS.some(p => p.test(message.errorMessage));
+}
+
+// ── Categorisation (for UI messages) ──
+
+export function getErrorCategory(errorMessage: string): '400-413' | 'credit' | 'connection' | 'builtin' | 'other' {
+  if (ERROR_400_413_PATTERNS.some(p => p.test(errorMessage))) return '400-413';
+  if (CREDIT_ERROR_PATTERNS.some(p => p.test(errorMessage))) return 'credit';
+  if (CONNECTION_ERROR_PATTERNS.some(p => p.test(errorMessage))) return 'connection';
+  if (BUILTIN_HANDLED_PATTERNS.some(p => p.test(errorMessage))) return 'builtin';
+  return 'other';
+}
+
+// ── Max tokens (not an error — continuation) ──
+
+export function hasMaxTokensStop(message: AgentMessage): boolean {
+  if (!isAssistantMessage(message)) return false;
+  return message.stopReason === "length";
+}
+
+// Re-export getLastAssistantMessage for convenience
+export { getLastAssistantMessage } from './retry-logic.js';

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared utilities for pi-retry extensions
+ *
+ * This module provides testable pure functions for:
+ * - Error pattern matching (400/413, connection errors, max_tokens)
+ * - Retry logic (exponential backoff, state management)
+ */
+
+export * from './error-patterns.js';
+export * from './retry-logic.js';

package/src/retry-logic.ts

@@ -0,0 +1,141 @@
+/**
+ * Retry logic utilities
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+/**
+ * Configuration for exponential backoff
+ */
+export interface BackoffConfig {
+  baseDelayMs: number;
+  maxDelayMs: number;
+  multiplier: number;
+}
+
+/**
+ * Default backoff configuration
+ */
+export const DEFAULT_BACKOFF_CONFIG: BackoffConfig = {
+  baseDelayMs: 2000,
+  maxDelayMs: 60000,
+  multiplier: 2,
+};
+
+/**
+ * Calculate delay with exponential backoff and cap
+ */
+export function calculateDelay(attempt: number, config: BackoffConfig = DEFAULT_BACKOFF_CONFIG): number {
+  const delay = config.baseDelayMs * Math.pow(config.multiplier, attempt - 1);
+  return Math.min(delay, config.maxDelayMs);
+}
+
+/**
+ * Format duration for display
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(ms / 60000);
+  const seconds = ((ms % 60000) / 1000).toFixed(0);
+  return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * Get the last assistant message from session entries
+ */
+export function getLastAssistantMessage(entries: unknown[]): AgentMessage | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i] as { type?: string; message?: AgentMessage };
+    if (entry.type === "message" && entry.message?.role === "assistant") {
+      return entry.message;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Retry state manager for tracking attempts
+ */
+export class RetryState {
+  private attempt = 0;
+  private isRetrying = false;
+  private lastErrorMessage = "";
+
+  getAttempt(): number {
+    return this.attempt;
+  }
+
+  getIsRetrying(): boolean {
+    return this.isRetrying;
+  }
+
+  getLastErrorMessage(): string {
+    return this.lastErrorMessage;
+  }
+
+  startRetry(errorMessage: string): void {
+    this.isRetrying = true;
+    this.attempt++;
+    this.lastErrorMessage = errorMessage;
+  }
+
+  endRetry(): void {
+    this.isRetrying = false;
+  }
+
+  reset(): void {
+    this.attempt = 0;
+    this.isRetrying = false;
+    this.lastErrorMessage = "";
+  }
+
+  succeed(): void {
+    this.attempt = 0;
+    this.isRetrying = false;
+    this.lastErrorMessage = "";
+  }
+}
+
+/**
+ * State manager for tracking max_tokens continuations.
+ *
+ * Unlike RetryState (which caps nothing but counts retries), continuations are
+ * also uncapped — each one produces valid output and the model naturally
+ * terminates when done, so there is no reason to impose a limit.
+ */
+export class ContinuationState {
+  private count = 0;
+  private isContinuing = false;
+
+  getCount(): number {
+    return this.count;
+  }
+
+  getIsContinuing(): boolean {
+    return this.isContinuing;
+  }
+
+  startContinuation(): void {
+    this.isContinuing = true;
+    this.count++;
+  }
+
+  endContinuation(): void {
+    this.isContinuing = false;
+  }
+
+  /**
+   * Called when a turn completes without hitting max_tokens.
+   * Resets the counter since the model finished normally.
+   */
+  complete(): void {
+    this.count = 0;
+    this.isContinuing = false;
+  }
+
+  reset(): void {
+    this.count = 0;
+    this.isContinuing = false;
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['__tests__/**/*.test.ts'],
+    exclude: ['node_modules', 'dist', '.idea', '.git', '.cache'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', '**/*.d.ts', '**/*.test.ts'],
+    },
+  },
+});