fix(api): resolve F-04 sanitize backend failures

Author: Aitomates

src/cas_reference_product/app.py

@@ -7,7 +7,7 @@
 from .config import Settings, get_settings
 from .models import PromptEnvelope, WorkflowResult
 from .telemetry import configure_telemetry
-from .workflow import WorkflowOrchestrator, build_workflow_agent_service
+from .workflow import WorkflowAgentServiceError, WorkflowOrchestrator, build_workflow_agent_service
 
 
 def create_app(settings: Settings | None = None) -> FastAPI:
@@ -37,7 +37,10 @@ def execute(envelope: PromptEnvelope, request: Request) -> WorkflowResult:
             raise HTTPException(status_code=503, detail="Workflow backend is not ready")
         request.state.correlation_id = envelope.correlationId
         orchestrator = WorkflowOrchestrator(service, app_settings.repository)
-        return orchestrator.execute(envelope)
+        try:
+            return orchestrator.execute(envelope)
+        except WorkflowAgentServiceError:
+            raise HTTPException(status_code=502, detail="Workflow backend request failed") from None
 
     @app.get("/")
     def root() -> dict[str, Any]:

src/cas_reference_product/workflow.py

@@ -20,6 +20,10 @@ class WorkflowAgentService(Protocol):
     def run(self, envelope: PromptEnvelope) -> str: ...
 
 
+class WorkflowAgentServiceError(RuntimeError):
+    """Stable application error raised when an external workflow backend fails."""
+
+
 class LocalWorkflowAgentService:
     def run(self, envelope: PromptEnvelope) -> str:
         return (
@@ -42,15 +46,18 @@ def __init__(self, settings: Settings) -> None:
 
     def run(self, envelope: PromptEnvelope) -> str:
         with tracer.start_as_current_span("foundry.responses.create"):
-            response = self._client.responses.create(
-                input=envelope.prompt,
-                extra_body={
-                    "agent_reference": {
-                        "name": self._agent_name,
-                        "type": "agent_reference",
-                    }
-                },
-            )
+            try:
+                response = self._client.responses.create(
+                    input=envelope.prompt,
+                    extra_body={
+                        "agent_reference": {
+                            "name": self._agent_name,
+                            "type": "agent_reference",
+                        }
+                    },
+                )
+            except Exception:
+                raise WorkflowAgentServiceError("Foundry workflow invocation failed") from None
         return response.output_text
 
 

tests/test_api.py

@@ -1,7 +1,15 @@
+from unittest.mock import patch
+
 from fastapi.testclient import TestClient
 
 from cas_reference_product.app import create_app
 from cas_reference_product.config import Settings
+from cas_reference_product.workflow import WorkflowAgentServiceError
+
+
+class FailingExternalService:
+    def run(self, envelope) -> str:
+        raise WorkflowAgentServiceError("sensitive provider detail")
 
 
 def test_workflow_api_emits_canonical_events(envelope) -> None:
@@ -31,3 +39,17 @@ def test_incomplete_foundry_configuration_is_not_ready() -> None:
     assert client.get("/health/live").status_code == 200
     assert client.get("/health/ready").status_code == 503
     assert client.post("/api/v1/workflows", json={}).status_code == 422
+
+
+def test_workflow_api_sanitizes_external_service_failures(envelope) -> None:
+    with patch(
+        "cas_reference_product.app.build_workflow_agent_service",
+        return_value=FailingExternalService(),
+    ):
+        client = TestClient(create_app(Settings()))
+
+    response = client.post("/api/v1/workflows", json=envelope.model_dump(mode="json"))
+
+    assert response.status_code == 502
+    assert response.json() == {"detail": "Workflow backend request failed"}
+    assert "sensitive" not in response.text

tests/test_service_factory.py

@@ -1,9 +1,12 @@
 from unittest.mock import patch
 
+import pytest
+
 from cas_reference_product.config import Settings
 from cas_reference_product.workflow import (
     FoundryWorkflowAgentService,
     LocalWorkflowAgentService,
+    WorkflowAgentServiceError,
     build_workflow_agent_service,
 )
 
@@ -54,3 +57,23 @@ def test_foundry_service_uses_next_gen_agent_reference(envelope) -> None:
         },
     )
     assert result == "Foundry result"
+
+
+def test_foundry_service_sanitizes_sdk_failure(envelope) -> None:
+    settings = Settings(
+        environment="prod",
+        workflow_backend="foundry",
+        foundry_project_endpoint="https://example.services.ai.azure.com/api/projects/example",
+        foundry_agent_name="cas-reference-agent",
+    )
+    with (
+        patch("cas_reference_product.workflow.build_credential"),
+        patch("cas_reference_product.workflow.AIProjectClient") as project_client,
+    ):
+        project_client.return_value.get_openai_client.return_value.responses.create.side_effect = (
+            RuntimeError("sensitive provider detail")
+        )
+        service = FoundryWorkflowAgentService(settings)
+
+        with pytest.raises(WorkflowAgentServiceError, match="Foundry workflow invocation failed"):
+            service.run(envelope)