fix: classify agent chat errors so upstream failures don't surface as HTTP 500

[cursor]

Summary

A Sentry HTTP 500 alert was triggered on POST /api/v1/agents/chats/{chat_id}/messages (issue 7540987063). The handler currently returns codes.Internal (HTTP 500) for every non-gorm.ErrRecordNotFound error returned by the agent service, which means:

• Anthropic rate-limiting (429) → HTTP 500
• Anthropic transient outages (5xx) → HTTP 500
• Caller cancellation (browser navigated away, context.Canceled) → HTTP 500
• Caller deadline exceeded → HTTP 500

Each of these gets captured as an HTTP 500 message by the LoggingMiddleware's captureHTTPError and pollutes the Sentry 500 issue feed even though none of them is a SuperPlane server bug.

Changes

• Add agents.ProviderHTTPError interface in pkg/agents/provider.go, implemented by anthropic.apiError, so the gRPC layer can classify upstream HTTP failures without taking a dependency on a specific provider's internal types.
• Add translateAgentServiceError(err, fallback) in pkg/grpc/actions/agents/common.go that maps:
  • context.Canceled → codes.Canceled (HTTP 499)
  • context.DeadlineExceeded → codes.DeadlineExceeded (HTTP 504)
  • gorm.ErrRecordNotFound / agents.ErrSessionAlreadyTerminated → codes.NotFound
  • agents.ErrSessionForbidden → codes.PermissionDenied
  • Upstream 429 → codes.ResourceExhausted (HTTP 429)
  • Upstream 401/403 → codes.FailedPrecondition
  • Upstream 408/504 → codes.DeadlineExceeded
  • Upstream 5xx → codes.Unavailable (HTTP 503)
  • Upstream 4xx (other) → codes.InvalidArgument
  • Anything else → codes.Internal (kept for genuine bugs)
• Wire the helper into SendAgentChatMessage, InterruptAgentChat, and DefineAgentOutcome. Internal errors keep their Error-level log so genuine bugs remain loud; everything else logs at Warn so the operator still sees the underlying error.
• In agents.Service.SendMessage, stop flipping the session to AgentSessionStatusFailed when the only reason the provider call failed is that the caller cancelled the request — otherwise a navigated-away tab leaves the chat stuck in "failed".

Tests

pkg/grpc/actions/agents/error_translation_test.go covers each translation case for the three affected handlers using a stub service and a fake ProviderHTTPError.

go test -count=1 -run "^(TestSendAgentChatMessage_Maps...|TestInterruptAgentChat_MapsUpstreamErrors|TestDefineAgentOutcome_MapsContextCanceled)$" ./pkg/grpc/actions/agents/

Also ran:

• go vet ./pkg/grpc/... ./pkg/agents/... ./pkg/models/... ./pkg/workers/... ./pkg/server/... ./pkg/public/...
• go test -count=1 ./pkg/agents/anthropic/...
• gofmt -s -l pkg/agents pkg/grpc/actions/agents (clean)

Notes

Without Sentry credentials in the cloud agent environment I couldn't introspect the originating exception payload, but the only error path that could produce HTTP 500 on this endpoint without an explicit codes.NotFound mapping is the one fixed here. The fix is intentionally a defensive widening that also reduces Sentry noise from future upstream-only incidents.

  

[superplanehq-integration]

👋 Commands for maintainers:

• /sp start - Start an ephemeral machine (takes ~30s)
• /sp stop - Stop a running machine (auto-executed on pr close)

[superplane-gh-integration-9000]

❌ OSS Guard found dependency licenses that are not permitted for this project.

Project license (from repository): Apache-2.0

Permitted dependency licenses: MIT,Apache-2.0,BSD-2-Clause,BSD-3-Clause,ISC,0BSD,Unlicense,CC0-1.0,CC-BY-4.0,Zlib,MPL-2.0,OpenSSL,BlueOak-1.0.0

Reason: One or more dependencies use licenses that are not compatible with the project license.

osv-scanner report:

argparse 2.0.1 (npm) - Python-2.0
csv 3.3.5 (RubyGems) - Ruby, BSD-2-Clause
elkjs 0.10.0 (npm) - EPL-2.0
khroma 2.1.0 (npm) - UNKNOWN
posthog-js 1.368.2 (npm) - non-standard
stdlib 1.26.2 (Go) - UNKNOWN

Add approved exceptions in your repository's osv-scanner.toml.