errors: improve rate limit error messages for AI agents

[danmoseley]

When the GitHub API returns a rate limit error, agents currently receive raw Go HTTP error strings:

search code: GET https://api.github.com/search/code: 403 API rate limit exceeded for user ID 12345. [rate reset in 2m59s]

These are hard for agents to reliably parse. Without a clear signal to stop and wait, agents may retry immediately — burning through quota faster — or misread the retry delay and either wait too short (triggering another error) or too long (wasting time).

This PR makes NewGitHubAPIErrorResponse intercept *github.RateLimitError and *github.AbuseRateLimitError and return clean, actionable messages instead:

search code: GitHub API rate limit exceeded. Retry after 2m59s.
create issue: GitHub secondary rate limit exceeded. Retry after 47s.
create issue: GitHub secondary rate limit exceeded. Wait before retrying.

Edge cases handled:

• Reset time already expired or zero → "Wait before retrying."
• AbuseRateLimitError.RetryAfter is nil or zero → "Wait before retrying."
• Wrapped errors (unwrapped via errors.As)

Backward compatibility: The original error is stored in context via addGitHubAPIErrorToContext before the rate-limit check, so any middleware reading from context is unaffected — only the text returned to the MCP client changes.

Fixes #2385.

Note

This PR description was drafted with GitHub Copilot.

[Copilot]

Pull request overview

This PR improves agent-facing tool error messages when GitHub API calls hit primary (RateLimitError) or secondary (AbuseRateLimitError) rate limits, replacing noisy raw HTTP error strings with concise “Retry after …” / “Wait before retrying” guidance.

Changes:

• Add rate-limit specific formatting in NewGitHubAPIErrorResponse using errors.As for wrapped errors.
• Add unit tests covering primary/secondary rate limit messages, wrapped errors, and edge cases (reset time expired/zero, missing retry-after).

Show a summary per file

File	Description
pkg/errors/error.go	Adds rate-limit error detection and returns clean, actionable messages while still recording the original error in context.
pkg/errors/error_test.go	Adds coverage for the new rate-limit formatting behavior and edge cases.

Copilot's findings

Comments suppressed due to low confidence (1)

pkg/errors/error_test.go:614

• This wrapped-rate-limit test has the same flakiness risk as the earlier one: expectedRetryIn is calculated after the call, so the rounded value may not match what the function formatted. Consider computing the expected value before invoking NewGitHubAPIErrorResponse or relaxing the assertion to tolerate small timing deltas.

		result := NewGitHubAPIErrorResponse(ctx, "search code", resp, wrappedErr)
		expectedRetryIn := time.Until(resetTime).Round(time.Second)

• Files reviewed: 2/2 changed files
• Comments generated: 2

[Copilot]

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 3