fix(llm): honor Retry-After on rate-limited responses

The retry loop used a fixed 1/2/4s exponential backoff and ignored the
server's Retry-After header, so a real rate limit (Retry-After: 20-60s)
burned all three retries in ~7s and failed the turn even though the server
said exactly when to come back. Parse Retry-After (integer seconds or
HTTP-date) on retryable statuses and use it for the next wait, capped at
60s so a pathological value can't wedge a turn (ctx still breaks the wait).

Tests: parseRetryAfter unit cases (seconds, blank, garbage, zero, cap) and
a 429+Retry-After call that retries and succeeds.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jkyberneees

internal/llm/client.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"strconv"
 	"strings"
 	"time"
 
@@ -299,17 +300,19 @@ func (c *Client) postChatWithRetry(ctx context.Context, reqBytes []byte) ([]byte
 
 	const maxRetries = 3
 	var lastErr error
+	var wait time.Duration // how long to sleep before the next attempt
 
 	for attempt := 0; attempt <= maxRetries; attempt++ {
 		if attempt > 0 {
-			// Exponential backoff: 1s, 2s, 4s.
-			backoff := time.Duration(1<<(attempt-1)) * time.Second
 			select {
 			case <-ctx.Done():
 				return nil, ctx.Err()
-			case <-time.After(backoff):
+			case <-time.After(wait):
 			}
 		}
+		// Default backoff for the next attempt if this one fails: 1s, 2s, 4s.
+		// A Retry-After header on a 429/503 overrides it below.
+		wait = time.Duration(1<<attempt) * time.Second
 
 		req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(reqBytes))
 		if err != nil {
@@ -329,6 +332,7 @@ func (c *Client) postChatWithRetry(ctx context.Context, reqBytes []byte) ([]byte
 		}
 
 		respBytes, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseSize+1))
+		retryAfter := resp.Header.Get("Retry-After")
 		resp.Body.Close()
 		if err != nil {
 			lastErr = fmt.Errorf("llm: read response: %w", err)
@@ -346,6 +350,13 @@ func (c *Client) postChatWithRetry(ctx context.Context, reqBytes []byte) ([]byte
 				lastErr = fmt.Errorf("llm: %s (status %d)", resp.Status, resp.StatusCode)
 			}
 			if isRetryableHTTPStatus(resp.StatusCode) {
+				// Honor the server's Retry-After (seconds or HTTP-date) when it
+				// asks us to wait longer than our default backoff — otherwise a
+				// rate-limited turn burns all three retries in ~7s and fails
+				// even though the server told us exactly when to come back.
+				if ra := parseRetryAfter(retryAfter); ra > 0 {
+					wait = ra
+				}
 				continue
 			}
 			return nil, lastErr
@@ -357,6 +368,40 @@ func (c *Client) postChatWithRetry(ctx context.Context, reqBytes []byte) ([]byte
 	return nil, fmt.Errorf("llm: retry exhausted (%d attempts): %w", maxRetries+1, lastErr)
 }
 
+// maxRetryAfter caps how long we'll honor a server's Retry-After. A pathological
+// or hostile value (e.g. "Retry-After: 86400") must not wedge a turn for hours;
+// ctx cancellation can still break the wait sooner.
+const maxRetryAfter = 60 * time.Second
+
+// parseRetryAfter interprets an HTTP Retry-After header, which is either an
+// integer number of seconds or an HTTP-date. Returns 0 when absent or
+// unparseable (callers then fall back to exponential backoff). The result is
+// capped at maxRetryAfter.
+func parseRetryAfter(v string) time.Duration {
+	v = strings.TrimSpace(v)
+	if v == "" {
+		return 0
+	}
+	var d time.Duration
+	if secs, err := strconv.Atoi(v); err == nil {
+		if secs <= 0 {
+			return 0
+		}
+		d = time.Duration(secs) * time.Second
+	} else if t, err := http.ParseTime(v); err == nil {
+		d = time.Until(t)
+		if d <= 0 {
+			return 0
+		}
+	} else {
+		return 0
+	}
+	if d > maxRetryAfter {
+		d = maxRetryAfter
+	}
+	return d
+}
+
 // isRetryableHTTPStatus returns true for HTTP status codes that indicate
 // a transient error safe to retry after a backoff.
 func isRetryableHTTPStatus(code int) bool {

internal/llm/retry_test.go

@@ -9,6 +9,59 @@ import (
 	"time"
 )
 
+func TestParseRetryAfter(t *testing.T) {
+	if d := parseRetryAfter("2"); d != 2*time.Second {
+		t.Errorf("parseRetryAfter(\"2\") = %v, want 2s", d)
+	}
+	if d := parseRetryAfter("  5 "); d != 5*time.Second {
+		t.Errorf("parseRetryAfter trims and parses, got %v", d)
+	}
+	if d := parseRetryAfter(""); d != 0 {
+		t.Errorf("empty header → 0, got %v", d)
+	}
+	if d := parseRetryAfter("garbage"); d != 0 {
+		t.Errorf("unparseable → 0, got %v", d)
+	}
+	if d := parseRetryAfter("0"); d != 0 {
+		t.Errorf("zero/negative → 0, got %v", d)
+	}
+	// Capped at maxRetryAfter.
+	if d := parseRetryAfter("100000"); d != maxRetryAfter {
+		t.Errorf("huge value should cap at %v, got %v", maxRetryAfter, d)
+	}
+}
+
+// TestClient_Call_HonorsRetryAfter verifies a 429 with a Retry-After header is
+// retried (rather than failed) and ultimately succeeds. The 1s value keeps the
+// test fast while exercising the header path.
+func TestClient_Call_HonorsRetryAfter(t *testing.T) {
+	var callCount atomic.Int32
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if int(callCount.Add(1)) == 1 {
+			w.Header().Set("Retry-After", "1")
+			w.WriteHeader(http.StatusTooManyRequests)
+			w.Write([]byte(`{"error":"slow down"}`))
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer ts.Close()
+
+	c := New(ts.URL, "key", "model", "", 0, 10*time.Second)
+	start := time.Now()
+	result, err := c.Call(context.Background(), []Message{{Role: "user", Content: "hi"}}, nil, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.Content != "ok" {
+		t.Errorf("content = %q, want ok", result.Content)
+	}
+	if elapsed := time.Since(start); elapsed < 900*time.Millisecond {
+		t.Errorf("expected to wait ~1s for Retry-After, only waited %v", elapsed)
+	}
+}
+
 // TestClient_SimpleCall_RetryOn429 verifies the lightweight secondary calls
 // share the main loop's retry resilience: a transient 429 no longer aborts a
 // skill-match / memory / title call on the first failure.