ref(pr-metrics): Type signal_details for delegated-agent attributions; add run_id (#117519)

## What this does

Introduces `DelegatedAgentSignalDetails`, a Pydantic model that replaces
the ad-hoc `dict` used for `signal_details` on `SEER_DELEGATED_*`
attribution signals:

```python
class DelegatedAgentSignalDetails(BaseModel):
    agent_id: str | None = None
    pr_url: str
    run_id: int | None = None
```

`run_id` is threaded through both paths that write these signals:

- **Polling path** (`poll_github_copilot_agents`,
`poll_claude_code_agents` → `poll_claude_agent`): reads
`autofix_state.run_id` and passes it to
`attribute_delegated_agent_pull_request`.
- **Seer RPC callback** (`record_pr_attribution`): validates the
incoming `signal_details` dict through `DelegatedAgentSignalDetails`
when the signal type is any `SEER_DELEGATED_*` value. Missing `pr_url`
raises a `ParseError`; nullable fields default to `None`.

The Cursor webhook has no autofix state at webhook time, so `run_id`
remains `None` there.

## Why

`run_id` is the natural join key back to Seer's run state and to
`SeerRun` in Sentry's DB — having it in `signal_details` makes post-hoc
attribution debugging much easier. The typed model enforces the contract
explicitly so future callers can't silently omit fields.

Refs CW-1493

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>

Author: 3 people

src/sentry/pr_metrics/attribution.py

@@ -15,6 +15,7 @@
 from typing import Any
 
 from django.db.models import Q
+from pydantic import BaseModel
 
 from sentry import features
 from sentry.constants import ObjectStatus
@@ -60,6 +61,25 @@
 }
 
 
+class DelegatedAgentSignalDetails(BaseModel):
+    """Typed signal_details for SEER_DELEGATED_* attribution signals."""
+
+    agent_id: str | None = None
+    pr_url: str
+    run_id: int | None = None
+
+
+# Signal types that use DelegatedAgentSignalDetails for their signal_details.
+DELEGATED_SIGNAL_TYPES = frozenset(
+    {
+        PullRequestAttributionSignalType.SEER_DELEGATED_CURSOR,
+        PullRequestAttributionSignalType.SEER_DELEGATED_GITHUB_COPILOT,
+        PullRequestAttributionSignalType.SEER_DELEGATED_CLAUDE_CODE,
+        PullRequestAttributionSignalType.SEER_DELEGATED_UNKNOWN,
+    }
+)
+
+
 def record_attribution_signal(
     *,
     pull_request: PullRequest,
@@ -260,6 +280,7 @@ def attribute_delegated_agent_pull_request(
     repo_provider: str,
     pr_url: str,
     agent_id: str | None = None,
+    run_id: int | None = None,
 ) -> None:
     """Attribute a PR opened by a Seer-delegated coding agent (Cursor/Copilot/Claude).
 
@@ -303,7 +324,11 @@ def attribute_delegated_agent_pull_request(
         pr_number=pr_number,
         signal_type=signal_type,
         source=PullRequestAttributionSource.SEER_DATA,
-        signal_details={"agent_id": agent_id, "pr_url": pr_url},
+        signal_details=DelegatedAgentSignalDetails(
+            agent_id=agent_id,
+            pr_url=pr_url,
+            run_id=run_id,
+        ).dict(),
         log_context=log_context,
     )
 

src/sentry/seer/autofix/coding_agent.py

@@ -148,6 +148,7 @@ def poll_github_copilot_agents(
     user_id: int = 0,
     coding_agents: dict[str, Any] | None = None,
     organization_id: int = 0,
+    run_id: int | None = None,
 ) -> None:
     agents = coding_agents or (autofix_state.coding_agents if autofix_state else None)
     if not agents:
@@ -158,6 +159,7 @@ def poll_github_copilot_agents(
     organization_id = organization_id or (
         autofix_state.request.organization_id if autofix_state else 0
     )
+    run_id = run_id if run_id is not None else (autofix_state.run_id if autofix_state else None)
 
     user_access_token: str | None = None
 
@@ -242,6 +244,7 @@ def poll_github_copilot_agents(
                                 repo_provider="github",
                                 pr_url=pr_url,
                                 agent_id=agent_id,
+                                run_id=run_id,
                             )
                         except Exception:
                             logger.exception(
@@ -280,6 +283,7 @@ def poll_claude_code_agents(
     autofix_state: AutofixState | None = None,
     organization_id: int | None = None,
     coding_agents: dict[str, Any] | None = None,
+    run_id: int | None = None,
 ) -> None:
     """
     Poll Claude Code Agent sessions for status updates.
@@ -307,11 +311,15 @@ def poll_claude_code_agents(
         logger.warning("coding_agent.claude_code.no_client_class_configured")
         return
 
+    run_id = run_id if run_id is not None else (autofix_state.run_id if autofix_state else None)
+
     for agent_id, agent_state in agents.items():
-        poll_claude_agent(clients, agent_id, org_id, agent_state)
+        poll_claude_agent(clients, agent_id, org_id, agent_state, run_id=run_id)
 
 
-def poll_claude_agent(clients, agent_id, org_id, agent_state: CodingAgentState) -> None:
+def poll_claude_agent(
+    clients, agent_id, org_id, agent_state: CodingAgentState, run_id: int | None = None
+) -> None:
     if agent_state.provider != CodingAgentProviderType.CLAUDE_CODE_AGENT:
         return
 
@@ -357,6 +365,7 @@ def poll_claude_agent(clients, agent_id, org_id, agent_state: CodingAgentState)
                         repo_provider=result.repo_provider,
                         pr_url=result.pr_url,
                         agent_id=agent_id,
+                        run_id=run_id,
                     )
                 except Exception:
                     logger.exception(

src/sentry/seer/endpoints/group_ai_autofix.py

@@ -383,11 +383,13 @@ def get(self, request: Request, group: Group) -> Response[AutofixStateResponse]:
                     coding_agents=state.coding_agents,
                     user_id=request.user.id,
                     organization_id=group.organization.id,
+                    run_id=state.run_id,
                 )
             if CodingAgentProviderType.CLAUDE_CODE_AGENT in agent_providers:
                 poll_claude_code_agents(
                     coding_agents=state.coding_agents,
                     organization_id=group.organization.id,
+                    run_id=state.run_id,
                 )
 
         run = get_seer_run(state.run_id, group.organization)

src/sentry/seer/endpoints/seer_rpc.py

@@ -58,7 +58,11 @@
     PullRequestAttributionSource,
 )
 from sentry.models.repository import Repository
-from sentry.pr_metrics.attribution import record_attribution_signal
+from sentry.pr_metrics.attribution import (
+    DELEGATED_SIGNAL_TYPES,
+    DelegatedAgentSignalDetails,
+    record_attribution_signal,
+)
 from sentry.pr_metrics.judge import update_pr_metrics
 from sentry.replays.usecases.summarize import rpc_get_replay_summary_logs
 from sentry.search.eap.resolver import SearchResolver
@@ -954,6 +958,14 @@ def record_pr_attribution(
             f"PullRequest {pull_request_id} not found in org {organization_id}"
         )
 
+    if signal in DELEGATED_SIGNAL_TYPES:
+        try:
+            signal_details = DelegatedAgentSignalDetails.parse_obj(signal_details or {}).dict()
+        except Exception:
+            raise ParseError(
+                detail="signal_details does not match DelegatedAgentSignalDetails schema"
+            )
+
     attribution = record_attribution_signal(
         pull_request=pull_request,
         signal_type=signal,

tests/sentry/pr_metrics/test_attribution.py

@@ -199,6 +199,7 @@ def _attribute(
         repo_provider: str = "github",
         pr_url: str = "https://github.com/getsentry/sentry/pull/42",
         agent_id: str | None = "agent-1",
+        run_id: int | None = None,
         organization_id: int | None = None,
         has_feature: bool = True,
     ) -> None:
@@ -212,6 +213,7 @@ def _attribute(
                 repo_provider=repo_provider,
                 pr_url=pr_url,
                 agent_id=agent_id,
+                run_id=run_id,
             )
 
     def test_records_the_given_signal_type(self) -> None:
@@ -234,8 +236,23 @@ def test_records_the_given_signal_type(self) -> None:
             assert attribution.signal_details == {
                 "agent_id": "agent-1",
                 "pr_url": f"https://github.com/getsentry/sentry/pull/{pr_number}",
+                "run_id": None,
             }
 
+    def test_includes_run_id_in_signal_details(self) -> None:
+        self._attribute(
+            pr_url="https://github.com/getsentry/sentry/pull/77",
+            run_id=9999,
+        )
+
+        pull_request = PullRequest.objects.get(repository_id=self.repo.id, key="77")
+        attribution = PullRequestAttribution.objects.get(pull_request=pull_request)
+        assert attribution.signal_details == {
+            "agent_id": "agent-1",
+            "pr_url": "https://github.com/getsentry/sentry/pull/77",
+            "run_id": 9999,
+        }
+
     def test_noop_when_feature_disabled(self) -> None:
         self._attribute(has_feature=False)
 

tests/sentry/seer/autofix/test_coding_agent.py

@@ -232,6 +232,7 @@ def test_poll_attributes_pr_when_task_complete(
             repo_provider="github",
             pr_url="https://github.com/getsentry/sentry/pull/12345",
             agent_id="getsentry:sentry:task-123",
+            run_id=self.run_id,
         )
 
     @patch("sentry.seer.autofix.coding_agent.attribute_delegated_agent_pull_request")
@@ -691,6 +692,7 @@ def test_attributes_pr_on_completion(
             repo_provider="github",
             pr_url="https://github.com/getsentry/sentry/pull/999",
             agent_id="claude-session-123",
+            run_id=self.run_id,
         )
 
     @patch("sentry.seer.autofix.coding_agent.attribute_delegated_agent_pull_request")

tests/sentry/seer/endpoints/test_seer_rpc.py

@@ -1693,11 +1693,14 @@ def setUp(self) -> None:
             key="10",
         )
 
+    _DEFAULT_PR_URL = "https://github.com/getsentry/sentry/pull/99"
+
     def _call(self, **overrides: Any) -> dict[str, Any]:
         kwargs: dict[str, Any] = {
             "organization_id": self.organization.id,
             "pull_request_id": self.pr.id,
             "signal_type": PullRequestAttributionSignalType.SEER_DELEGATED_CLAUDE_CODE,
+            "signal_details": {"pr_url": self._DEFAULT_PR_URL},
         }
         kwargs.update(overrides)
         return record_pr_attribution(**kwargs)
@@ -1710,14 +1713,43 @@ def test_creates_attribution(self) -> None:
         assert attr.is_valid is True
         assert result == {"attribution_id": attr.id}
 
-    def test_stores_signal_details(self) -> None:
-        self._call(signal_details={"agent_id": "agent-abc-123"})
+    def test_stores_typed_signal_details_for_delegated_signals(self) -> None:
+        self._call(
+            signal_details={
+                "agent_id": "agent-abc-123",
+                "pr_url": self._DEFAULT_PR_URL,
+                "run_id": 42,
+            }
+        )
 
         attr = PullRequestAttribution.objects.get(pull_request=self.pr)
-        assert attr.signal_details == {"agent_id": "agent-abc-123"}
+        assert attr.signal_details == {
+            "agent_id": "agent-abc-123",
+            "pr_url": self._DEFAULT_PR_URL,
+            "run_id": 42,
+        }
 
-    def test_no_signal_details_leaves_signal_details_null(self) -> None:
-        self._call()
+    def test_delegated_signal_details_defaults_nullable_fields(self) -> None:
+        self._call(signal_details={"pr_url": self._DEFAULT_PR_URL})
+
+        attr = PullRequestAttribution.objects.get(pull_request=self.pr)
+        assert attr.signal_details == {
+            "agent_id": None,
+            "pr_url": self._DEFAULT_PR_URL,
+            "run_id": None,
+        }
+
+    def test_invalid_delegated_signal_details_raises(self) -> None:
+        from rest_framework.exceptions import ParseError
+
+        with pytest.raises(ParseError):
+            self._call(signal_details={"agent_id": "x"})  # missing required pr_url
+
+    def test_no_signal_details_for_non_delegated_type_leaves_null(self) -> None:
+        self._call(
+            signal_type=PullRequestAttributionSignalType.SENTRY_APP,
+            signal_details=None,
+        )
 
         attr = PullRequestAttribution.objects.get(pull_request=self.pr)
         assert attr.signal_details is None