Send activity failure details as envelopes

Author: durable-workflow-ops

src/durable_workflow/client.py

@@ -915,6 +915,8 @@ async def fail_activity_task(
         failure_type: str | None = None,
         stack_trace: str | None = None,
         non_retryable: bool = False,
+        details: Any | None = None,
+        codec: str = serializer.AVRO_CODEC,
     ) -> Any:
         failure: dict[str, Any] = {"message": message}
         if failure_type is not None:
@@ -923,6 +925,8 @@ async def fail_activity_task(
             failure["stack_trace"] = stack_trace
         if non_retryable:
             failure["non_retryable"] = True
+        if details is not None:
+            failure["details"] = serializer.envelope(details, codec=codec)
         body: dict[str, Any] = {
             "activity_attempt_id": activity_attempt_id,
             "lease_owner": lease_owner,

tests/test_client.py

@@ -300,6 +300,24 @@ async def test_body_shape(self, client: Client) -> None:
             assert body["failure"]["message"] == "activity error"
             assert body["failure"]["non_retryable"] is True
 
+    @pytest.mark.asyncio
+    async def test_details_are_sent_as_payload_envelope(self, client: Client) -> None:
+        resp = _mock_response(200, {"task_id": "t1", "outcome": "failed"})
+        with patch.object(client._http, "request", new_callable=AsyncMock, return_value=resp) as mock:
+            await client.fail_activity_task(
+                task_id="t1",
+                activity_attempt_id="a1",
+                lease_owner="w1",
+                message="activity error",
+                details={"retry_after": 30},
+                codec=serializer.JSON_CODEC,
+            )
+            body = mock.call_args.kwargs.get("json") or mock.call_args[1].get("json")
+            envelope = body["failure"]["details"]
+
+            assert envelope["codec"] == serializer.JSON_CODEC
+            assert serializer.decode_envelope(envelope) == {"retry_after": 30}
+
 
 class TestHeartbeatActivityTask:
     @pytest.mark.asyncio