ouroboros-ai 0.27.2.dev1__tar.gz → 0.27.2.dev2__tar.gz

{ouroboros_ai-0.27.2.dev1 → ouroboros_ai-0.27.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.27.2.dev1
+Version: 0.27.2.dev2
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.27.2.dev1 → ouroboros_ai-0.27.2.dev2}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.27.2.dev1'
-__version_tuple__ = version_tuple = (0, 27, 2, 'dev1')
+__version__ = version = '0.27.2.dev2'
+__version_tuple__ = version_tuple = (0, 27, 2, 'dev2')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.27.2.dev1 → ouroboros_ai-0.27.2.dev2}/src/ouroboros/core/errors.py

@@ -99,6 +99,34 @@ class ProviderError(OuroborosError):
         error.__cause__ = exc  # Preserve original traceback
         return error
 
+    def format_details(self) -> str:
+        """Render error details in a compact, user-visible form.
+
+        Formats the error message along with key diagnostic fields from
+        the details dict (error_type, session_id, environment markers,
+        stderr tail). Useful for surfacing rich diagnostics in tool
+        error responses.
+        """
+        if not isinstance(self.details, dict) or not self.details:
+            return self.message
+
+        rendered: list[str] = [self.message]
+        for key in (
+            "error_type",
+            "session_id",
+            "claudecode_present",
+            "claude_code_entrypoint",
+            "stderr",
+        ):
+            value = self.details.get(key)
+            if value is None:
+                continue
+            if key == "stderr" and value:
+                rendered.append(f"stderr tail:\n{value}")
+            elif key != "stderr":
+                rendered.append(f"{key}: {value}")
+        return "\n".join(rendered)
+
 
 class ConfigError(OuroborosError):
     """Error from configuration operations.

{ouroboros_ai-0.27.2.dev1 → ouroboros_ai-0.27.2.dev2}/src/ouroboros/mcp/tools/evaluation_handlers.py

@@ -408,12 +408,28 @@ class EvaluateHandler:
             )
             working_dir_str = arguments.get("working_dir")
             working_dir = Path(working_dir_str).resolve() if working_dir_str else Path.cwd()
+            log.info(
+                "mcp.tool.evaluate.started",
+                session_id=session_id,
+                artifact_type=artifact_type,
+                working_dir=str(working_dir),
+                llm_backend=self.llm_backend,
+                adapter_type=type(llm_adapter).__name__,
+            )
 
             # Collect file-based artifacts for richer semantic evaluation.
             # working_dir is used as the project root for artifact resolution.
             from ouroboros.evaluation.artifact_collector import ArtifactCollector
 
-            artifact_bundle = ArtifactCollector().collect(artifact, str(working_dir))
+            try:
+                artifact_bundle = ArtifactCollector().collect(artifact, str(working_dir))
+            except Exception as exc:
+                log.warning(
+                    "mcp.tool.evaluate.artifact_collection_failed",
+                    error=str(exc),
+                    working_dir=str(working_dir),
+                )
+                artifact_bundle = None
 
             context = EvaluationContext(
                 execution_id=session_id,
@@ -435,9 +451,21 @@ class EvaluateHandler:
             result = await pipeline.evaluate(context)
 
             if result.is_err:
+                rendered_error = (
+                    result.error.format_details()
+                    if hasattr(result.error, "format_details")
+                    else str(result.error)
+                )
+                log.warning(
+                    "mcp.tool.evaluate.pipeline_failed",
+                    session_id=session_id,
+                    working_dir=str(working_dir),
+                    llm_backend=self.llm_backend,
+                    error=rendered_error,
+                )
                 return Result.err(
                     MCPToolError(
-                        f"Evaluation failed: {result.error}",
+                        f"Evaluation failed: {rendered_error}",
                         tool_name="ouroboros_evaluate",
                     )
                 )

{ouroboros_ai-0.27.2.dev1 → ouroboros_ai-0.27.2.dev2}/src/ouroboros/providers/claude_code_adapter.py

@@ -293,6 +293,12 @@ class ClaudeCodeAdapter:
             prompt_preview=prompt[:100],
             message_count=len(messages),
             has_system_prompt=system_prompt is not None,
+            max_turns=self._max_turns,
+            model=config.model,
+            cwd=str(self._cwd) if self._cwd else None,
+            cli_path=str(self._cli_path) if self._cli_path else None,
+            claudecode_present=bool(os.environ.get("CLAUDECODE")),
+            claude_code_entrypoint=os.environ.get("CLAUDE_CODE_ENTRYPOINT"),
         )
 
         result = await self._complete_with_transient_retry(prompt, config, system_prompt)
@@ -552,8 +558,9 @@ class ClaudeCodeAdapter:
         # session check).  The Agent SDK sets CLAUDE_CODE_ENTRYPOINT=sdk-py
         # to signal it's an SDK call, but the older check on CLAUDECODE fires
         # first, causing silent empty responses.  Strip it via env override.
+        claudecode_present = bool(os.environ.get("CLAUDECODE"))
         env_overrides: dict[str, str] = {}
-        if os.environ.get("CLAUDECODE"):
+        if claudecode_present:
             env_overrides["CLAUDECODE"] = ""
 
         stderr_lines: list[str] = []
@@ -602,6 +609,20 @@ class ClaudeCodeAdapter:
 
         options = ClaudeAgentOptions(**options_kwargs)
 
+        log.debug(
+            "claude_code_adapter.sdk_request_configured",
+            max_turns=self._max_turns,
+            model=options_kwargs.get("model"),
+            cwd=str(self._cwd) if self._cwd else None,
+            cli_path=str(self._cli_path) if self._cli_path else None,
+            permission_mode=self._permission_mode,
+            allowed_tools=self._allowed_tools,
+            disallowed_tools=disallowed,
+            claudecode_present=claudecode_present,
+            claude_code_entrypoint=os.environ.get("CLAUDE_CODE_ENTRYPOINT"),
+            env_override_keys=sorted(env_overrides.keys()),
+        )
+
         # Collect the response - let the generator run to completion
         content = ""
         session_id = None
@@ -623,58 +644,96 @@ class ClaudeCodeAdapter:
                 except StopAsyncIteration:
                     break
 
-        async for sdk_message in _safe_query():
-            class_name = type(sdk_message).__name__
-
-            if class_name == "SystemMessage":
-                # Capture session ID from init
-                msg_data = getattr(sdk_message, "data", {})
-                session_id = msg_data.get("session_id")
-
-            elif class_name == "AssistantMessage":
-                # Extract text content and tool use
-                content_blocks = getattr(sdk_message, "content", [])
-                for block in content_blocks:
-                    block_type = type(block).__name__
-                    if block_type == "TextBlock":
-                        text = getattr(block, "text", "")
-                        content += text
-                        # Callback for thinking/reasoning
-                        if self._on_message and text.strip():
-                            self._on_message("thinking", text.strip())
-                    elif block_type == "ToolUseBlock":
-                        tool_name = getattr(block, "name", "unknown")
-                        tool_input = getattr(block, "input", {})
-                        # Format tool info with key details
-                        tool_info = self._format_tool_info(tool_name, tool_input)
-                        # Callback for tool usage
-                        if self._on_message:
-                            self._on_message("tool", tool_info)
-
-            elif class_name == "ResultMessage":
-                # Check for structured output first (from json_schema output_format)
-                structured = getattr(sdk_message, "structured_output", None)
-                if structured is not None:
-                    content = (
-                        json.dumps(structured) if not isinstance(structured, str) else structured
-                    )
+        try:
+            async for sdk_message in _safe_query():
+                class_name = type(sdk_message).__name__
+
+                if class_name == "SystemMessage":
+                    # Capture session ID from init
+                    msg_data = getattr(sdk_message, "data", {})
+                    session_id = msg_data.get("session_id")
+
+                elif class_name == "AssistantMessage":
+                    # Extract text content and tool use
+                    content_blocks = getattr(sdk_message, "content", [])
+                    for block in content_blocks:
+                        block_type = type(block).__name__
+                        if block_type == "TextBlock":
+                            text = getattr(block, "text", "")
+                            content += text
+                            # Callback for thinking/reasoning
+                            if self._on_message and text.strip():
+                                self._on_message("thinking", text.strip())
+                        elif block_type == "ToolUseBlock":
+                            tool_name = getattr(block, "name", "unknown")
+                            tool_input = getattr(block, "input", {})
+                            # Format tool info with key details
+                            tool_info = self._format_tool_info(tool_name, tool_input)
+                            # Callback for tool usage
+                            if self._on_message:
+                                self._on_message("tool", tool_info)
+
+                elif class_name == "ResultMessage":
+                    # Check for structured output first (from json_schema output_format)
+                    structured = getattr(sdk_message, "structured_output", None)
+                    if structured is not None:
+                        content = (
+                            json.dumps(structured)
+                            if not isinstance(structured, str)
+                            else structured
+                        )
 
-                # Final result - use result content if we don't have content yet
-                elif not content:
-                    content = getattr(sdk_message, "result", "") or ""
+                    # Final result - use result content if we don't have content yet
+                    elif not content:
+                        content = getattr(sdk_message, "result", "") or ""
 
-                # Check for errors - don't break, just record
-                is_error = getattr(sdk_message, "is_error", False)
-                if is_error:
-                    error_msg = content or "Unknown error from Claude Agent SDK"
-                    log.warning(
-                        "claude_code_adapter.sdk_error",
-                        error=error_msg,
-                    )
-                    error_result = ProviderError(
-                        message=error_msg,
-                        details={"session_id": session_id},
-                    )
+                    # Check for errors - don't break, just record
+                    is_error = getattr(sdk_message, "is_error", False)
+                    if is_error:
+                        error_msg = (
+                            getattr(sdk_message, "result", "")
+                            or "Unknown error from Claude Agent SDK"
+                        )
+                        log.warning(
+                            "claude_code_adapter.sdk_error",
+                            error=error_msg,
+                            session_id=session_id,
+                            stderr_lines=len(stderr_lines),
+                        )
+                        error_result = ProviderError(
+                            message=error_msg,
+                            details={
+                                "session_id": session_id,
+                                "stderr": "\n".join(stderr_lines[-20:]) if stderr_lines else "",
+                                "claudecode_present": claudecode_present,
+                                "claude_code_entrypoint": os.environ.get("CLAUDE_CODE_ENTRYPOINT"),
+                            },
+                        )
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            stderr_tail = "\n".join(stderr_lines[-20:]) if stderr_lines else ""
+            log.exception(
+                "claude_code_adapter.sdk_request_failed",
+                error=str(exc),
+                error_type=type(exc).__name__,
+                session_id=session_id,
+                stderr_lines=len(stderr_lines),
+                claudecode_present=claudecode_present,
+                claude_code_entrypoint=os.environ.get("CLAUDE_CODE_ENTRYPOINT"),
+            )
+            return Result.err(
+                ProviderError(
+                    message=f"Claude Agent SDK request failed: {exc}",
+                    details={
+                        "error_type": type(exc).__name__,
+                        "session_id": session_id,
+                        "stderr": stderr_tail,
+                        "claudecode_present": claudecode_present,
+                        "claude_code_entrypoint": os.environ.get("CLAUDE_CODE_ENTRYPOINT"),
+                    },
+                )
+            )
 
         # After generator completes naturally, check for errors
         if error_result:

{ouroboros_ai-0.27.2.dev1 → ouroboros_ai-0.27.2.dev2}/tests/unit/providers/test_claude_code_adapter.py

@@ -7,10 +7,12 @@ being embedded as XML in the user prompt.
 
 from __future__ import annotations
 
+import asyncio
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
+from ouroboros.core.errors import ProviderError
 from ouroboros.core.types import Result
 from ouroboros.providers.base import (
     CompletionConfig,
@@ -561,3 +563,279 @@ class TestExecuteSingleRequestSystemPrompt:
         options_call_kwargs = mock_options_cls.call_args.kwargs
         assert options_call_kwargs["allowed_tools"] == []
         assert "Read" in options_call_kwargs["disallowed_tools"]
+
+
+class TestErrorDiagnostics:
+    """Tests for error diagnostic paths in _execute_single_request."""
+
+    @pytest.mark.asyncio
+    async def test_sdk_exception_produces_provider_error_with_details(self) -> None:
+        """SDK exception is caught and returns ProviderError with diagnostic details."""
+        adapter = ClaudeCodeAdapter()
+        config = CompletionConfig(model="claude-sonnet-4-6")
+
+        mock_options_cls = MagicMock()
+
+        async def failing_query(*args, **kwargs):
+            if False:
+                yield
+            raise RuntimeError("SDK connection lost")
+
+        sdk_module = _make_sdk_mock(mock_options_cls, MagicMock(side_effect=failing_query))
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "claude_agent_sdk": sdk_module,
+                "claude_agent_sdk._errors": sdk_module._errors,
+            },
+        ):
+            result = await adapter._execute_single_request("test prompt", config)
+
+        assert result.is_err
+        error = result.error
+        assert isinstance(error, ProviderError)
+        assert "SDK connection lost" in error.message
+        assert error.details["error_type"] == "RuntimeError"
+
+    @pytest.mark.asyncio
+    async def test_sdk_exception_includes_stderr_in_details(self) -> None:
+        """SDK exception captures stderr lines in error details."""
+        import subprocess
+
+        adapter = ClaudeCodeAdapter()
+        config = CompletionConfig(model="claude-sonnet-4-6")
+
+        captured_stderr: dict = {}
+
+        def capture_options(**kwargs):
+            captured_stderr["fn"] = kwargs.get("stderr")
+            return MagicMock()
+
+        mock_options_cls = MagicMock(side_effect=capture_options)
+
+        async def failing_query(*args, **kwargs):
+            # Simulate stderr output before the SDK exception
+            if captured_stderr.get("fn"):
+                captured_stderr["fn"]("error: connection refused")
+                captured_stderr["fn"]("fatal: SDK process died")
+            if False:
+                yield
+            raise subprocess.CalledProcessError(1, "claude")
+
+        sdk_module = _make_sdk_mock(mock_options_cls, MagicMock(side_effect=failing_query))
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "claude_agent_sdk": sdk_module,
+                "claude_agent_sdk._errors": sdk_module._errors,
+            },
+        ):
+            result = await adapter._execute_single_request("test prompt", config)
+
+        assert result.is_err
+        assert "stderr" in result.error.details
+        assert "connection refused" in result.error.details["stderr"]
+
+    @pytest.mark.asyncio
+    async def test_cancelled_error_is_not_swallowed(self) -> None:
+        """asyncio.CancelledError propagates instead of being wrapped."""
+        adapter = ClaudeCodeAdapter()
+        config = CompletionConfig(model="claude-sonnet-4-6")
+
+        mock_options_cls = MagicMock()
+
+        async def cancelled_query(*args, **kwargs):
+            if False:
+                yield
+            raise asyncio.CancelledError()
+
+        sdk_module = _make_sdk_mock(mock_options_cls, MagicMock(side_effect=cancelled_query))
+
+        with (
+            patch.dict(
+                "sys.modules",
+                {
+                    "claude_agent_sdk": sdk_module,
+                    "claude_agent_sdk._errors": sdk_module._errors,
+                },
+            ),
+            pytest.raises(asyncio.CancelledError),
+        ):
+            await adapter._execute_single_request("test prompt", config)
+
+    @pytest.mark.asyncio
+    async def test_empty_response_with_session_id(self) -> None:
+        """Empty response with session_id returns descriptive error."""
+        adapter = ClaudeCodeAdapter()
+        config = CompletionConfig(model="claude-sonnet-4-6")
+
+        mock_options_cls = MagicMock()
+
+        async def empty_query(*args, **kwargs):
+            # SystemMessage with session_id but no content
+            sys_msg = MagicMock()
+            type(sys_msg).__name__ = "SystemMessage"
+            sys_msg.data = {"session_id": "sess_abc123"}
+            yield sys_msg
+            # ResultMessage with empty content
+            result_msg = MagicMock()
+            type(result_msg).__name__ = "ResultMessage"
+            result_msg.structured_output = None
+            result_msg.result = ""
+            result_msg.is_error = False
+            yield result_msg
+
+        sdk_module = _make_sdk_mock(mock_options_cls, MagicMock(side_effect=empty_query))
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "claude_agent_sdk": sdk_module,
+                "claude_agent_sdk._errors": sdk_module._errors,
+            },
+        ):
+            result = await adapter._execute_single_request("test prompt", config)
+
+        assert result.is_err
+        assert "sess_abc123" in result.error.details.get("session_id", "")
+        assert "Empty response" in result.error.message
+
+    @pytest.mark.asyncio
+    async def test_empty_response_without_session_id(self) -> None:
+        """Empty response without session_id suggests retry."""
+        adapter = ClaudeCodeAdapter()
+        config = CompletionConfig(model="claude-sonnet-4-6")
+
+        mock_options_cls = MagicMock()
+
+        async def empty_no_session_query(*args, **kwargs):
+            result_msg = MagicMock()
+            type(result_msg).__name__ = "ResultMessage"
+            result_msg.structured_output = None
+            result_msg.result = ""
+            result_msg.is_error = False
+            yield result_msg
+
+        sdk_module = _make_sdk_mock(mock_options_cls, MagicMock(side_effect=empty_no_session_query))
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "claude_agent_sdk": sdk_module,
+                "claude_agent_sdk._errors": sdk_module._errors,
+            },
+        ):
+            result = await adapter._execute_single_request("test prompt", config)
+
+        assert result.is_err
+        assert "retry" in result.error.message.lower()
+
+    @pytest.mark.asyncio
+    async def test_sdk_error_message_includes_stderr(self) -> None:
+        """SDK is_error result includes stderr in ProviderError details."""
+        adapter = ClaudeCodeAdapter()
+        config = CompletionConfig(model="claude-sonnet-4-6")
+
+        captured_stderr: dict = {}
+
+        def capture_options(**kwargs):
+            captured_stderr["fn"] = kwargs.get("stderr")
+            return MagicMock()
+
+        mock_options_cls = MagicMock(side_effect=capture_options)
+
+        async def error_query(*args, **kwargs):
+            # Simulate stderr before error result
+            if captured_stderr.get("fn"):
+                captured_stderr["fn"]("warning: rate limit hit")
+            result_msg = MagicMock()
+            type(result_msg).__name__ = "ResultMessage"
+            result_msg.structured_output = None
+            result_msg.result = "Rate limit exceeded"
+            result_msg.is_error = True
+            yield result_msg
+
+        sdk_module = _make_sdk_mock(mock_options_cls, MagicMock(side_effect=error_query))
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "claude_agent_sdk": sdk_module,
+                "claude_agent_sdk._errors": sdk_module._errors,
+            },
+        ):
+            result = await adapter._execute_single_request("test prompt", config)
+
+        assert result.is_err
+        assert "Rate limit exceeded" in result.error.message
+        assert "stderr" in result.error.details
+        assert "rate limit hit" in result.error.details["stderr"]
+
+
+class TestProviderErrorFormatDetails:
+    """Tests for ProviderError.format_details method."""
+
+    def test_format_details_with_all_fields(self) -> None:
+        """format_details renders all diagnostic fields."""
+        error = ProviderError(
+            message="SDK failed",
+            details={
+                "error_type": "RuntimeError",
+                "session_id": "sess_abc",
+                "claudecode_present": True,
+                "claude_code_entrypoint": "sdk-py",
+                "stderr": "error: auth failed",
+            },
+        )
+        rendered = error.format_details()
+        assert "SDK failed" in rendered
+        assert "error_type: RuntimeError" in rendered
+        assert "session_id: sess_abc" in rendered
+        assert "stderr tail:\nerror: auth failed" in rendered
+
+    def test_format_details_without_details(self) -> None:
+        """format_details falls back to message when no details."""
+        error = ProviderError(message="Simple error")
+        rendered = error.format_details()
+        assert rendered == "Simple error"
+
+    def test_format_details_skips_none_values(self) -> None:
+        """format_details skips fields with None values."""
+        error = ProviderError(
+            message="Partial error",
+            details={
+                "error_type": "ValueError",
+                "session_id": None,
+                "stderr": "",
+            },
+        )
+        rendered = error.format_details()
+        assert "error_type: ValueError" in rendered
+        assert "session_id:" not in rendered
+        # Empty stderr string should not render stderr tail
+        assert "stderr tail:" not in rendered
+
+    def test_format_details_preserves_falsy_values(self) -> None:
+        """format_details renders False and 0 instead of dropping them."""
+        error = ProviderError(
+            message="Diagnostic error",
+            details={
+                "claudecode_present": False,
+                "error_type": "RuntimeError",
+            },
+        )
+        rendered = error.format_details()
+        assert "claudecode_present: False" in rendered
+        assert "error_type: RuntimeError" in rendered
+
+    def test_format_details_does_not_duplicate_details_dict(self) -> None:
+        """format_details uses message, not str(self) which appends raw details."""
+        error = ProviderError(
+            message="SDK failed",
+            details={"error_type": "RuntimeError", "session_id": "sess_1"},
+        )
+        rendered = error.format_details()
+        # Should not contain the raw dict representation
+        assert "(details:" not in rendered