@monotykamary/pi-retry 0.8.6 → 0.9.0

package/README.md

@@ -21,11 +21,11 @@ This extension automatically detects and retries **all** errors by default, with
 
 | 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 — top up and the retry loop auto-resumes |
+| **Any retryable error** (catch-all) | **Capped exponential retry** | Everything else — provider hiccups, stream exhaustion, credit issues, unknown errors |
+| HTTP 400/413 | **Capped** with exponential backoff, NO compaction | Transient context overflow that might resolve |
+| Credit / payment errors | **Capped** with exponential backoff | "Not Enough Credits", insufficient balance, 402 — top up and the retry loop auto-resumes |
 | **Quota / session-limit / budget exhaustion** | **Not retried** — notify + stop | "You've hit your limit", `insufficient_quota`, "out of budget", suspended accounts |
-| Connection errors | **Indefinite** with capped backoff | Network hiccups, connection drops, socket errors, stream exhaustion |
+| Connection errors | **Capped** with exponential backoff | Network hiccups, connection drops, socket errors, stream exhaustion |
 | Max tokens (`stopReason: "length"`) | **Auto-continue** indefinitely with hidden continuation turns | Model hits output token limit mid-generation |
 | Empty / think-only stop (`stopReason: "stop"` with no text or tool calls) | **Nudge once** with a hidden continuation, then give up | Model ends its turn with no usable output (Anthropic empty responses with end_turn, thinking-only turns) |
 
@@ -43,7 +43,7 @@ By default, pi has built-in retry for some errors (rate limits, 5xx, overloaded)
 
 ## The Solution
 
-This extension provides **automatic** infinite retry with sensible exponential backoff (2s → 4s → 8s → ... → 60s max).
+This extension provides automatic retry for all errors with configurable exponential backoff and a maximum-delay failure limit (2s → 4s → 8s → ... → 60s by default).
 
 **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.).
 
@@ -51,9 +51,9 @@ This extension provides **automatic** infinite retry with sensible exponential b
 - **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, hidden from the TUI
-- **Indefinite retry** — Keeps retrying until success
+- **Retry cutoff** — Keeps retrying until success, abort, or the configured number of failures at the maximum delay
 - **Auto-stop on quota/budget exhaustion** — Session limits, plan quotas, and budget caps ("You've hit your limit", "out of budget", `insufficient_quota`, suspended accounts) are detected and **not** retried, with a notification explaining why
-- Exponential backoff with cap: max 60s between retries
+- Exponential backoff with configurable base delay, cap, multiplier, and maximum-delay failure count
 - **Hidden triggers** — provider-valid custom messages use `display: false`, so retries do not add TUI clutter
 - Manual controls via unified `/retry` command
 - Non-retryable errors are explicitly logged so you know why we didn't retry
@@ -121,15 +121,35 @@ Once loaded, the extension **automatically** detects and retries all errors.
 
 ## Configuration
 
-Edit the constants at the top of `retry.ts`:
+The extension reads a `piRetry` object from Pi's settings files:
 
-```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
-// Continuations use a hidden provider-valid custom message
+- `~/.pi/agent/settings.json` applies globally.
+- `.pi/settings.json` overrides matching global values for the current project.
+
+```json
+{
+  "piRetry": {
+    "baseDelayMs": 10000,
+    "maxDelayMs": 3600000,
+    "multiplier": 2,
+    "maxRetriesAtMaxDelay": 3
+  }
+}
 ```
 
+The example above waits 10 seconds before the first retry, doubles each delay, caps the delay at one hour, and stops after three failed retries at that cap. Supported values are:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `baseDelayMs` | `2000` | Delay before the first retry, in milliseconds |
+| `maxDelayMs` | `60000` | Maximum delay between retries, in milliseconds |
+| `multiplier` | `2` | Exponential backoff multiplier; must be at least `1` |
+| `maxRetriesAtMaxDelay` | `3` | Failed ordinary retries allowed after the delay reaches `maxDelayMs` |
+
+`piRetry` is separate from Pi's built-in `retry` object so the two retry policies do not share ambiguous settings. The extension disables Pi's native retry scheduler while it is loaded, while preserving Pi's compaction handling, so only one retry loop owns the backoff schedule.
+
+Settings are read when the extension starts. Restart pi or use `/reload` after editing them.
+
 ---
 
 ## How It Works
@@ -234,11 +254,13 @@ npm run lint:dead
 .
 ├── retry.ts                   # Main unified extension
 ├── src/                       # Shared utilities (testable, DRY)
+│   ├── config.ts             # Settings-backed retry configuration
 │   ├── 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/
+│       ├── config.test.ts
 │       ├── error-patterns.test.ts
 │       └── retry-logic.test.ts
 ├── vitest.config.ts           # Test configuration
@@ -249,7 +271,7 @@ npm run lint:dead
 
 ```bash
 # Run all quality checks
-npm test              # 99 unit tests
+npm test              # 224 tests
 npm run typecheck     # TypeScript type checking
 npm run lint:dead     # Dead code detection with knip
 ```
@@ -302,7 +324,7 @@ pi install npm:@georgebashi/pi-retry
 
 ## Limitations
 
-- Extensions cannot override pi's internal `isRetryableError()` check — they run *after* pi decides not to auto-retry
+- Pi's native retry scheduler is disabled while this extension is loaded so native and extension retries cannot interleave; Pi's compaction check still runs normally
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-retry",
-  "version": "0.8.6",
+  "version": "0.9.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",

package/retry.ts

@@ -16,6 +16,7 @@ import {
   isAssistantMessage,
   getLastAssistantMessage,
   calculateDelay,
+  loadPiRetryConfig,
   formatDuration,
   getErrorCategory,
   RetryState,
@@ -32,7 +33,8 @@ const RETRY_CANCELLED_EVENT = "pi-retry:cancelled";
  * Unified retry extension — retries EVERY error by default.
  *
  * Philosophy: any assistant message with stopReason === "error" is retried
- * indefinitely with exponential backoff, except a small blacklist of known
+ * with exponential backoff capped by settings, then stops after the configured
+ * number of failures at the maximum delay, except a small blacklist of known
  * permanent failures and hard-stop conditions (invalid API key, model not
  * found, quota/session-limit/budget exhaustion, suspended accounts, etc.).
  *
@@ -41,7 +43,7 @@ const RETRY_CANCELLED_EVENT = "pi-retry:cancelled";
  *
  * Features:
  * - Automatic detection and retry for ALL errors (catch-all)
- * - Indefinite retry with exponential backoff (capped at 60s)
+ * - Retry with exponential backoff and a configurable cap/failure limit
  * - Auto-continuation when model hits max output tokens (stopReason "length")
  * - Retry triggers are hidden in the TUI and serialized as provider-valid user turns
  * - Unified manual controls via /retry command
@@ -73,25 +75,15 @@ Agent.prototype.subscribe = function (this: Agent, ...args: any[]) {
   return _origSubscribe.apply(this, args);
 };
 
-// Monkey-patch AgentSession._prepareRetry to suppress the built-in retry
-// when pi-retry's loop is driving. Without this, both the built-in retry
-// and pi-retry race to handle the same error: the built-in retry counts
-// 3 failed attempts and shows "Retry failed after 3 attempts: ...",
-// while pi-retry is still looping indefinitely in the background.
-//
-// When _continueInProgress is true (pi-retry is running), _prepareRetry
-// returns false immediately, so _handlePostAgentRun falls through to
-// the compaction check and the while loop in _runAgentPrompt exits
-// cleanly. No auto_retry_start/end events, no "Retry failed" message.
-//
-// When _continueInProgress is false (pi-retry is not active), the
-// built-in retry works normally as a fallback.
+// AgentSession runs _prepareRetry inside _runAgentPrompt before it emits
+// agent_end. If native retry remains enabled, the first error is retried
+// before pi-retry can claim it, so the two retry loops interleave and produce
+// non-monotonic delays. pi-retry owns retry scheduling for the whole session;
+// returning false still lets AgentSession run its compaction check.
+let _piRetryActive = false;
 const _origPrepareRetry = (AgentSession.prototype as any)._prepareRetry;
 (AgentSession.prototype as any)._prepareRetry = function(this: any, message: any) {
-  if (
-    _continueInProgress &&
-    _continueInputGeneration === _inputGeneration
-  ) {
+  if (_piRetryActive) {
     return Promise.resolve(false);
   }
   return _origPrepareRetry.call(this, message);
@@ -170,20 +162,20 @@ function interruptibleSleep(
 // Same technique used by the built-in retry in _prepareRetry — the error
 // message stays in the session journal for history but is removed from the
 // agent's live transcript so the LLM receives a clean context on retry.
-function removeErrorFromAgentState(): void {
-  if (!_agent) return;
-  const messages = _agent.state.messages;
+function removeErrorFromAgentState(agent: Agent | null = _agent): void {
+  if (!agent) return;
+  const messages = agent.state.messages;
   const lastMsg = messages[messages.length - 1];
   if (lastMsg?.role === 'assistant' && lastMsg.stopReason === 'error') {
-    _agent.state.messages = messages.slice(0, -1);
+    agent.state.messages = messages.slice(0, -1);
   }
 }
 
 type HiddenTurnKind = "retry" | "continue" | "empty";
 
-function getHiddenTurnKind(): HiddenTurnKind | null {
-  if (!_agent) return null;
-  const messages = _agent.state.messages;
+function getHiddenTurnKind(agent: Agent | null = _agent): HiddenTurnKind | null {
+  if (!agent) return null;
+  const messages = agent.state.messages;
   const lastMsg = messages[messages.length - 1];
   if (lastMsg?.role !== "assistant") return null;
   if (lastMsg.stopReason === "error") return "retry";
@@ -197,6 +189,11 @@ function lastMessageIsRetryableError(): boolean {
 }
 
 export default function (pi: ExtensionAPI) {
+  let _notifyFn: ((message: string, level: "info" | "warning" | "error") => void) | null = null;
+
+  // Mark native retry as owned by this extension before the first agent turn.
+  _piRetryActive = true;
+  const retryConfig = loadPiRetryConfig();
 
   pi.on("input", () => {
     _inputGeneration++;
@@ -423,10 +420,11 @@ export default function (pi: ExtensionAPI) {
 
         // Config
         status += "Configuration:\n";
-        status += `  Base delay: 2000ms\n`;
-        status += `  Max delay: 60000ms\n`;
-        status += `  Backoff multiplier: 2\n`;
-        status += `  Retry loop: infinite (triggerInvisibleContinue loops until success or abort)\n\n`;
+        status += `  Base delay: ${retryConfig.baseDelayMs}ms\n`;
+        status += `  Max delay: ${retryConfig.maxDelayMs}ms\n`;
+        status += `  Backoff multiplier: ${retryConfig.multiplier}\n`;
+        status += `  Max-delay failures: ${retryConfig.maxRetriesAtMaxDelay}\n`;
+        status += "  Retry loop: until success, abort, or the max-delay failure limit\n\n";
 
         // Last assistant info
         if (lastAssistant && isAssistantMessage(lastAssistant)) {
@@ -541,6 +539,21 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
+  // Handle session replacement before Pi invalidates this extension runtime.
+  // A retry loop may still be awaiting a timer or AgentSession turn when the
+  // old session shuts down, so release its ownership and invalidate its
+  // generation before the captured pi object becomes stale.
+  pi.on("session_shutdown", () => {
+    _sessionGeneration++;
+    _userAborted = true;
+    _continueInProgress = false;
+    _continueGeneration = null;
+    _continueInputGeneration = null;
+    _notifyFn = null;
+    _terminalInputUnsubscribe?.();
+    _terminalInputUnsubscribe = null;
+  });
+
   // Initialize
   pi.on("session_start", async (_event, ctx) => {
     // Bump the generation counter so any in-flight retry loop from a
@@ -558,6 +571,7 @@ export default function (pi: ExtensionAPI) {
     // finally block releases its owner token. Resetting it here could allow
     // a second loop to start before the old one has settled.
     _userAborted = false;
+    _notifyFn = null;
 
     _terminalInputUnsubscribe?.();
     _terminalInputUnsubscribe = null;
@@ -600,7 +614,10 @@ export default function (pi: ExtensionAPI) {
   // agent.state.messages so the LLM receives a clean context (same
   // technique as the built-in retry's _prepareRetry).
   async function triggerInvisibleContinue(initialKind: HiddenTurnKind) {
-    if (!_agent) return;
+    // Keep the AgentSession that started this loop. A replacement session can
+    // update the module-level reference before an old loop has unwound.
+    const myAgent = _agent;
+    if (!myAgent) return;
 
     // Guard: if the user aborted, do not queue another retry turn.
     if (_userAborted) return;
@@ -610,7 +627,6 @@ export default function (pi: ExtensionAPI) {
     _continueInProgress = true;
     const retryLifecycleId = ++_retryLifecycleId;
     let didRetryComplete = false;
-    pi.events.emit(RETRY_STARTED_EVENT, { retryId: retryLifecycleId });
 
     // Capture the current session generation. If /new fires while we're
     // looping, _sessionGeneration will increment and the loop will exit.
@@ -620,9 +636,11 @@ export default function (pi: ExtensionAPI) {
     _continueInputGeneration = myInputGeneration;
 
     try {
+      emitRetryLifecycleEvent(RETRY_STARTED_EVENT, retryLifecycleId);
+
       // Wait for the current run to finish (activeRun resolves in
       // finishRun() after agent_end listeners return).
-      await _agent.waitForIdle();
+      await myAgent.waitForIdle();
 
       // Re-check after waitForIdle: the user may have aborted or the
       // session may have changed while we were waiting.
@@ -634,9 +652,13 @@ export default function (pi: ExtensionAPI) {
 
       let attempt = 0;
       let hiddenTurnKind: HiddenTurnKind | null = initialKind;
-      // Empty-stop nudges are bounded: MAX_EMPTY_CONTINUATIONS total
-      // continuation requests, then we give up (the model decided it is done).
+      // Empty-stop nudges are bounded: a model that produced no usable output
+      // and answers the nudge with another empty turn is decided, not stalled.
+      // Stop after MAX_EMPTY_CONTINUATIONS rather than looping forever.
       let emptyNudges = 0;
+      // Only ordinary retries count toward the maximum-delay cutoff; token
+      // continuations intentionally remain uncapped.
+      let maxDelayRetries = 0;
 
       // Loop until success, abort, or session change.
       while (true) {
@@ -653,14 +675,14 @@ export default function (pi: ExtensionAPI) {
           didRetryComplete = true;
           return;
         }
-        removeErrorFromAgentState();
+        removeErrorFromAgentState(myAgent);
 
         // Empty-stop cap: a model that produced no usable output and answers
         // the nudge with another empty turn is decided, not stalled. Stop
         // after MAX_EMPTY_CONTINUATIONS rather than looping forever.
         if (hiddenTurnKind === "empty") {
           if (emptyNudges >= MAX_EMPTY_CONTINUATIONS) {
-            _notifyFn?.(
+            notifySafely(
               `Empty response after ${emptyNudges} continuation(s) - giving up (model keeps ending the turn with no output).`,
               "warning",
             );
@@ -670,7 +692,11 @@ export default function (pi: ExtensionAPI) {
         }
 
         attempt++;
-        const delay = calculateDelay(attempt);
+        const delay = calculateDelay(attempt, retryConfig);
+        const isMaxDelay = delay >= retryConfig.maxDelayMs;
+        if (hiddenTurnKind === "retry" && isMaxDelay) {
+          maxDelayRetries++;
+        }
 
         // Notify the user about the upcoming retry attempt.
         _notifyRetryAttempt(attempt, delay);
@@ -678,7 +704,7 @@ export default function (pi: ExtensionAPI) {
         // Interruptible sleep with backoff BEFORE the retry attempt.
         // Polls _userAborted and _sessionGeneration every 100ms so ESC
         // and /new take effect within 100ms instead of waiting for the
-        // full backoff (up to 60s).
+        // full backoff (up to the configured maximum delay).
         const interrupted = await interruptibleSleep(
           delay,
           myGeneration,
@@ -707,7 +733,7 @@ export default function (pi: ExtensionAPI) {
           // low-level run synchronously before returning. Waiting on Agent
           // keeps this retry loop intact without bypassing session state.
           await Promise.resolve();
-          await _agent.waitForIdle();
+          await myAgent.waitForIdle();
         } catch {
           return;
         }
@@ -722,21 +748,41 @@ export default function (pi: ExtensionAPI) {
 
         // The hidden AgentSession turn completed. Both errors and output
         // length stops need another turn; all other terminal states are done.
-        hiddenTurnKind = getHiddenTurnKind();
+        hiddenTurnKind = getHiddenTurnKind(myAgent);
         if (!hiddenTurnKind) {
           didRetryComplete = true;
           return;
         }
+
+        // Stop ordinary retries after the configured number of failures at
+        // the cap. The failed capped turns have already been delivered; this
+        // check prevents scheduling one more capped request.
+        if (
+          hiddenTurnKind === "retry" &&
+          maxDelayRetries >= retryConfig.maxRetriesAtMaxDelay
+        ) {
+          notifySafely(
+            `Retry failed ${retryConfig.maxRetriesAtMaxDelay} times at the maximum backoff (${formatDuration(retryConfig.maxDelayMs)}); giving up.`,
+            "warning",
+          );
+          return;
+        }
       }
     } finally {
-      // Release the mutex only if this loop still owns it.
+      // Release the mutex only if this loop still owns it. If the session was
+      // replaced, session_shutdown clears ownership and suppresses the event
+      // because the captured pi.events bus is stale by this point.
       if (_continueGeneration === myGeneration) {
-        pi.events.emit(didRetryComplete ? RETRY_COMPLETED_EVENT : RETRY_CANCELLED_EVENT, {
-          retryId: retryLifecycleId,
-        });
+        const sessionIsCurrent = _sessionGeneration === myGeneration;
         _continueInProgress = false;
         _continueGeneration = null;
         _continueInputGeneration = null;
+        if (sessionIsCurrent) {
+          emitRetryLifecycleEvent(
+            didRetryComplete ? RETRY_COMPLETED_EVENT : RETRY_CANCELLED_EVENT,
+            retryLifecycleId,
+          );
+        }
       }
     }
   }
@@ -745,7 +791,34 @@ export default function (pi: ExtensionAPI) {
   // ctx.ui.notify is only available inside event handlers, not inside
   // triggerInvisibleContinue. We capture a fresh reference from the
   // most recent handler invocation so it's always current.
-  let _notifyFn: ((message: string, level: "info" | "warning" | "error") => void) | null = null;
+
+  function isStaleContextError(error: unknown): boolean {
+    return error instanceof Error && error.message.includes("This extension ctx is stale");
+  }
+
+  function emitRetryLifecycleEvent(event: string, retryId: number): void {
+    try {
+      pi.events.emit(event, { retryId });
+    } catch (error) {
+      // Session replacement invalidates the old event bus while a retry loop
+      // can still be unwinding. There is no live listener to notify then.
+      if (!isStaleContextError(error)) throw error;
+    }
+  }
+
+  function notifySafely(message: string, level: "info" | "warning" | "error"): void {
+    if (!_notifyFn) return;
+    try {
+      _notifyFn(message, level);
+    } catch (error) {
+      // The notification closure can outlive the session that supplied its ctx.
+      if (isStaleContextError(error)) {
+        _notifyFn = null;
+        return;
+      }
+      throw error;
+    }
+  }
 
   // Refresh on every handler that carries a ctx — stale references
   // break after session switches (the old ctx becomes invalid).
@@ -760,9 +833,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   function _notifyRetryAttempt(attempt: number, delayMs: number) {
-    if (_notifyFn) {
-      const duration = formatDuration(delayMs);
-      _notifyFn(`Retry attempt ${attempt} (backoff ${duration})...`, "info");
-    }
+    const duration = formatDuration(delayMs);
+    notifySafely(`Retry attempt ${attempt} (backoff ${duration})...`, "info");
   }
 }

package/src/config.ts

@@ -0,0 +1,172 @@
+/**
+ * Settings-backed configuration for the pi-retry extension.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_BACKOFF_CONFIG,
+  type BackoffConfig,
+} from "./retry-logic.js";
+
+/**
+ * Complete retry configuration used by the extension.
+ */
+export interface PiRetryConfig extends BackoffConfig {
+  /** Number of failed retries allowed after the delay reaches maxDelayMs. */
+  maxRetriesAtMaxDelay: number;
+}
+
+/**
+ * Default values preserve the extension's existing behavior while making it
+ * possible to tune the schedule through settings.json.
+ */
+export const DEFAULT_RETRY_CONFIG: PiRetryConfig = {
+  ...DEFAULT_BACKOFF_CONFIG,
+  maxRetriesAtMaxDelay: 3,
+};
+
+/** Root settings key owned by this extension. */
+export const PI_RETRY_SETTINGS_KEY = "piRetry";
+
+type SettingsObject = Record<string, unknown>;
+
+/**
+ * Check whether a decoded JSON value can be read as a settings object.
+ *
+ * @param value Decoded JSON value to inspect.
+ * @returns True when the value is a non-array object.
+ */
+function isSettingsObject(value: unknown): value is SettingsObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read one numeric setting and fall back when it fails validation.
+ *
+ * @param settings Settings namespace to inspect.
+ * @param key Setting name to read.
+ * @param fallback Default value used for invalid or missing input.
+ * @param isValid Predicate for the accepted numeric range.
+ * @returns A validated number.
+ */
+function readNumberSetting(
+  settings: SettingsObject,
+  key: string,
+  fallback: number,
+  isValid: (value: number) => boolean,
+): number {
+  const value = settings[key];
+  if (value === undefined) return fallback;
+  if (typeof value === "number" && Number.isFinite(value) && isValid(value)) {
+    return value;
+  }
+
+  // Invalid settings should not prevent pi from starting; use the field's
+  // default and make the configuration error visible to the user.
+  console.warn(
+    `[pi-retry] Ignoring invalid ${PI_RETRY_SETTINGS_KEY}.${key} value: ${String(value)}`,
+  );
+  return fallback;
+}
+
+/**
+ * Extract the extension namespace from a decoded settings file.
+ *
+ * @param settings Decoded settings file contents.
+ * @returns The piRetry namespace, or an empty object when absent/invalid.
+ */
+function getRetrySettings(settings: unknown): SettingsObject {
+  if (!isSettingsObject(settings)) return {};
+  const retrySettings = settings[PI_RETRY_SETTINGS_KEY];
+  return isSettingsObject(retrySettings) ? retrySettings : {};
+}
+
+/**
+ * Merge global and project namespaces, then validate every supported field.
+ *
+ * @param globalSettings Decoded global settings.json contents.
+ * @param projectSettings Decoded project settings.json contents.
+ * @returns The validated effective retry configuration.
+ *
+ * TEST:__tests__/unit/config.test.ts[resolvePiRetryConfig]
+ */
+export function resolvePiRetryConfig(
+  globalSettings: unknown,
+  projectSettings: unknown,
+): PiRetryConfig {
+  const mergedSettings = {
+    ...getRetrySettings(globalSettings),
+    ...getRetrySettings(projectSettings),
+  };
+
+  return {
+    baseDelayMs: readNumberSetting(
+      mergedSettings,
+      "baseDelayMs",
+      DEFAULT_RETRY_CONFIG.baseDelayMs,
+      value => value >= 0,
+    ),
+    maxDelayMs: readNumberSetting(
+      mergedSettings,
+      "maxDelayMs",
+      DEFAULT_RETRY_CONFIG.maxDelayMs,
+      value => value >= 0,
+    ),
+    multiplier: readNumberSetting(
+      mergedSettings,
+      "multiplier",
+      DEFAULT_RETRY_CONFIG.multiplier,
+      value => value >= 1,
+    ),
+    maxRetriesAtMaxDelay: readNumberSetting(
+      mergedSettings,
+      "maxRetriesAtMaxDelay",
+      DEFAULT_RETRY_CONFIG.maxRetriesAtMaxDelay,
+      value => Number.isInteger(value) && value >= 1,
+    ),
+  };
+}
+
+/**
+ * Load and merge Pi's global and project settings files.
+ *
+ * @param cwd Project working directory containing .pi/settings.json.
+ * @param homeDirectory Home directory containing .pi/agent/settings.json.
+ * @returns The validated effective retry configuration.
+ *
+ * TEST:__tests__/unit/config.test.ts[loadPiRetryConfig]
+ */
+export function loadPiRetryConfig(
+  cwd: string = process.cwd(),
+  homeDirectory: string = homedir(),
+): PiRetryConfig {
+  const globalSettings = readSettingsFile(
+    join(homeDirectory, ".pi", "agent", "settings.json"),
+  );
+  const projectSettings = readSettingsFile(join(cwd, ".pi", "settings.json"));
+  return resolvePiRetryConfig(globalSettings, projectSettings);
+}
+
+/**
+ * Read a settings file without making startup dependent on optional files.
+ *
+ * @param filePath Absolute settings file path.
+ * @returns Decoded JSON contents, or an empty object when unavailable.
+ */
+function readSettingsFile(filePath: string): unknown {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8")) as unknown;
+  } catch (error) {
+    const code = isSettingsObject(error) && typeof error.code === "string"
+      ? error.code
+      : undefined;
+    if (code !== "ENOENT") {
+      console.warn(
+        `[pi-retry] Could not read settings file ${filePath}: ${String(error)}`,
+      );
+    }
+    return {};
+  }
+}

package/src/index.ts

@@ -6,5 +6,6 @@
  * - Retry logic (exponential backoff, state management)
  */
 
+export * from './config.js';
 export * from './error-patterns.js';
 export * from './retry-logic.js';