ouroboros-ai 0.28.8.dev4__tar.gz → 0.28.8.dev9__tar.gz

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.28.8.dev4
+Version: 0.28.8.dev9
 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.28.8.dev4 → ouroboros_ai-0.28.8.dev9}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.28.8.dev4'
-__version_tuple__ = version_tuple = (0, 28, 8, 'dev4')
+__version__ = version = '0.28.8.dev9'
+__version_tuple__ = version_tuple = (0, 28, 8, 'dev9')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev9}/src/ouroboros/mcp/client/adapter.py

@@ -258,12 +258,31 @@ class MCPClientAdapter:
 
             import httpx
             from mcp.client.streamable_http import streamable_http_client
-            from mcp.shared._httpx_utils import create_mcp_http_client
+
+            from ouroboros import __version__ as _ouroboros_version
 
             timeout = httpx.Timeout(config.timeout, read=max(config.timeout, 300.0))
-            http_client = create_mcp_http_client(
-                headers=config.headers if config.headers else None,
+
+            # Compose headers with a stable User-Agent for observability.
+            # Now that we own the httpx client (no longer going through the
+            # mcp SDK's private helper), set the UA explicitly so that MCP
+            # servers can still identify the ouroboros client in their logs.
+            # Caller-supplied headers take precedence.
+            default_headers = {
+                "User-Agent": f"ouroboros-mcp-client/{_ouroboros_version}",
+            }
+            if config.headers:
+                merged_headers: dict[str, str] = {**default_headers, **config.headers}
+            else:
+                merged_headers = default_headers
+
+            http_client = httpx.AsyncClient(
+                headers=merged_headers,
                 timeout=timeout,
+                # SSRF hardening: do not follow redirects. An attacker-controlled
+                # server could otherwise 302 us into a loopback / metadata URL
+                # that bypasses the static URL validation in MCPServerConfig.
+                follow_redirects=False,
             )
             self._http_client = http_client
 

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev9}/src/ouroboros/mcp/tools/definitions.py

@@ -26,6 +26,7 @@ from ouroboros.mcp.tools.authoring_handlers import (
 )
 from ouroboros.mcp.tools.channel_workflow_handler import ChannelWorkflowHandler
 from ouroboros.mcp.tools.evaluation_handlers import (
+    ChecklistVerifyHandler,
     EvaluateHandler,
     LateralThinkHandler,
     MeasureDriftHandler,
@@ -186,6 +187,18 @@ def evaluate_handler(*, llm_backend: str | None = None) -> EvaluateHandler:
     return EvaluateHandler(llm_backend=llm_backend)
 
 
+def checklist_verify_handler(
+    *,
+    evaluate_handler: EvaluateHandler | None = None,
+    llm_backend: str | None = None,
+) -> ChecklistVerifyHandler:
+    """Create a ChecklistVerifyHandler instance."""
+    return ChecklistVerifyHandler(
+        evaluate_handler=evaluate_handler,
+        llm_backend=llm_backend,
+    )
+
+
 def evolve_step_handler() -> EvolveStepHandler:
     """Create an EvolveStepHandler instance."""
     return EvolveStepHandler()
@@ -226,6 +239,7 @@ OuroborosToolHandlers = tuple[
     | MeasureDriftHandler
     | InterviewHandler
     | EvaluateHandler
+    | ChecklistVerifyHandler
     | LateralThinkHandler
     | EvolveStepHandler
     | StartEvolveStepHandler
@@ -265,6 +279,7 @@ def get_ouroboros_tools(
     job_result = JobResultHandler()
     interview = InterviewHandler(llm_backend=llm_backend)
     generate_seed = GenerateSeedHandler(llm_backend=llm_backend)
+    evaluate = EvaluateHandler(llm_backend=llm_backend)
     return (
         execute_seed,
         start_execute,
@@ -278,7 +293,8 @@ def get_ouroboros_tools(
         generate_seed,
         MeasureDriftHandler(),
         interview,
-        EvaluateHandler(llm_backend=llm_backend),
+        evaluate,
+        ChecklistVerifyHandler(evaluate_handler=evaluate, llm_backend=llm_backend),
         LateralThinkHandler(),
         EvolveStepHandler(),
         StartEvolveStepHandler(),

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev9}/src/ouroboros/mcp/tools/evaluation_handlers.py

@@ -874,6 +874,199 @@ class EvaluateHandler:
         return "\n".join(lines)
 
 
+@dataclass
+class ChecklistVerifyHandler:
+    """Handler for the ``ouroboros_checklist_verify`` tool (#366).
+
+    Given a seed (containing ``acceptance_criteria``) and an execution
+    artifact, this handler routes each AC through the Stage 2 evaluation
+    pipeline and returns an aggregated checklist.  It is intentionally
+    thin — it composes ``EvaluateHandler`` rather than reimplementing
+    pipeline orchestration, so it stays in sync with any future changes
+    to the main evaluator.
+
+    Why this is a separate tool instead of a flag on ``ouroboros_execute_seed``:
+
+    - ``ExecuteSeed`` is already complex (background execution, resume,
+      delegation) and has a stable public contract.  Adding a retry
+      loop inside it would entangle with Ralph mode and the Job system.
+    - This tool lets the *caller* (a human, a ``/ralph`` loop, or a
+      channel workflow) decide when and how to retry.  No decisions
+      are hidden inside background tasks.
+    - It is opt-in: existing callers are unaffected.
+    """
+
+    evaluate_handler: EvaluateHandler | None = field(default=None, repr=False)
+    llm_backend: str | None = field(default=None, repr=False)
+
+    @property
+    def definition(self) -> MCPToolDefinition:
+        """Return the tool definition."""
+        return MCPToolDefinition(
+            name="ouroboros_checklist_verify",
+            description=(
+                "Verify that a Run artifact satisfies every acceptance criterion "
+                "in a Seed.  Returns a per-AC checklist (pass/fail with evidence "
+                "and failure reasons) plus ready-to-use run_feedback strings the "
+                "caller can inject into a re-run prompt.  Does NOT automatically "
+                "re-execute — the caller (Ralph, workflow, or human) decides."
+            ),
+            parameters=(
+                MCPToolParameter(
+                    name="session_id",
+                    type=ToolInputType.STRING,
+                    description="The execution session ID being verified",
+                    required=True,
+                ),
+                MCPToolParameter(
+                    name="seed_content",
+                    type=ToolInputType.STRING,
+                    description=(
+                        "Seed YAML containing acceptance_criteria, goal, constraints. "
+                        "The seed's acceptance_criteria list is evaluated in full."
+                    ),
+                    required=True,
+                ),
+                MCPToolParameter(
+                    name="artifact",
+                    type=ToolInputType.STRING,
+                    description="The Run output/artifact to verify against the seed's ACs",
+                    required=True,
+                ),
+                MCPToolParameter(
+                    name="artifact_type",
+                    type=ToolInputType.STRING,
+                    description="Type of artifact: code, docs, config. Default: code",
+                    required=False,
+                    default="code",
+                    enum=("code", "docs", "config"),
+                ),
+                MCPToolParameter(
+                    name="working_dir",
+                    type=ToolInputType.STRING,
+                    description="Project working directory (for language auto-detection).",
+                    required=False,
+                ),
+            ),
+        )
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+    ) -> Result[MCPToolResult, MCPServerError]:
+        """Verify the seed's full AC list against the artifact."""
+        session_id = arguments.get("session_id")
+        if not session_id:
+            return Result.err(
+                MCPToolError(
+                    "session_id is required",
+                    tool_name="ouroboros_checklist_verify",
+                )
+            )
+
+        seed_content = arguments.get("seed_content")
+        if not seed_content:
+            return Result.err(
+                MCPToolError(
+                    "seed_content is required",
+                    tool_name="ouroboros_checklist_verify",
+                )
+            )
+
+        artifact = arguments.get("artifact")
+        if not artifact:
+            return Result.err(
+                MCPToolError(
+                    "artifact is required",
+                    tool_name="ouroboros_checklist_verify",
+                )
+            )
+
+        # Extract acceptance criteria from seed.
+        try:
+            seed_dict = yaml.safe_load(seed_content)
+            seed = Seed.from_dict(seed_dict)
+        except yaml.YAMLError as exc:
+            log.warning("mcp.tool.checklist_verify.yaml_error", error=str(exc))
+            return Result.err(
+                MCPToolError(
+                    f"Failed to parse seed YAML: {exc}",
+                    tool_name="ouroboros_checklist_verify",
+                )
+            )
+        except (ValidationError, PydanticValidationError) as exc:
+            log.warning("mcp.tool.checklist_verify.seed_validation_error", error=str(exc))
+            return Result.err(
+                MCPToolError(
+                    f"Seed validation failed: {exc}",
+                    tool_name="ouroboros_checklist_verify",
+                )
+            )
+
+        acceptance_criteria = tuple(
+            text.strip() for text in seed.acceptance_criteria if text and text.strip()
+        )
+        if not acceptance_criteria:
+            return Result.err(
+                MCPToolError(
+                    "Seed has no acceptance_criteria — cannot build checklist.",
+                    tool_name="ouroboros_checklist_verify",
+                )
+            )
+
+        # Delegate to EvaluateHandler in multi-AC mode.  Re-using the
+        # evaluator means language detection, artifact bundling, event
+        # logging, and LLM backend handling stay consistent.
+        evaluator = self.evaluate_handler or EvaluateHandler(llm_backend=self.llm_backend)
+
+        evaluate_args = {
+            "session_id": session_id,
+            "artifact": artifact,
+            "seed_content": seed_content,
+            "acceptance_criteria": list(acceptance_criteria),
+            "artifact_type": arguments.get("artifact_type", "code"),
+        }
+        if "working_dir" in arguments:
+            evaluate_args["working_dir"] = arguments["working_dir"]
+
+        log.info(
+            "mcp.tool.checklist_verify.started",
+            session_id=session_id,
+            ac_count=len(acceptance_criteria),
+        )
+
+        result = await evaluator.handle(evaluate_args)
+
+        if result.is_err:
+            log.warning(
+                "mcp.tool.checklist_verify.evaluate_failed",
+                session_id=session_id,
+                error=str(result.error),
+            )
+            return result
+
+        # Augment the MCP result meta so callers can distinguish the
+        # verify path from a plain multi-AC evaluate call.
+        meta = dict(result.value.meta or {})
+        meta["checklist_verify"] = True
+        meta["seed_goal"] = seed.goal
+        augmented = MCPToolResult(
+            content=result.value.content,
+            is_error=result.value.is_error,
+            meta=meta,
+        )
+
+        log.info(
+            "mcp.tool.checklist_verify.completed",
+            session_id=session_id,
+            all_passed=meta.get("final_approved"),
+            passed_count=meta.get("passed_count"),
+            ac_count=meta.get("ac_count"),
+        )
+
+        return Result.ok(augmented)
+
+
 @dataclass
 class LateralThinkHandler:
     """Handler for the lateral_think tool.

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev9}/src/ouroboros/mcp/types.py

@@ -8,7 +8,110 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from enum import StrEnum
+import ipaddress
+import os
 from typing import Any
+from urllib.parse import urlparse
+
+# Schemes permitted for SSE / HTTP / STREAMABLE_HTTP transports.
+_ALLOWED_URL_SCHEMES = frozenset({"http", "https"})
+
+# Environment flag that intentionally re-enables loopback / private / link-local
+# IP literals for local development. Leave unset in production.
+_ALLOW_LOCAL_TRANSPORT_ENV = "OUROBOROS_ALLOW_LOCAL_TRANSPORT"
+
+# Well-known hostnames that resolve to loopback addresses.  These bypass the
+# ``ipaddress.ip_address()`` check (they raise ``ValueError`` because they are
+# not IP literals), so we must block them explicitly.
+_LOOPBACK_HOSTNAMES = frozenset({"localhost"})
+
+
+def _validate_transport_url(url: str, transport: str) -> None:
+    """Validate a transport URL against common SSRF vectors.
+
+    The MCP client will dial whatever URL is configured for SSE, HTTP, or
+    STREAMABLE_HTTP transports. Without hardening, that turns any untrusted
+    caller that can influence the ``url`` field into an SSRF primitive able to
+    reach cloud metadata services (169.254.169.254), loopback services, or
+    private RFC1918 ranges. This helper rejects the common vectors before a
+    connection is attempted.
+
+    Blocks:
+        * Non-http(s) schemes (``file://``, ``gopher://``, ``ftp://`` ...).
+        * URLs carrying userinfo (``user:pass@host``) used for credential
+          smuggling / host confusion.
+        * URLs with an empty hostname (e.g. bare ``http://``).
+        * Literal IPs resolving to loopback, link-local, or private ranges,
+          unless the ``OUROBOROS_ALLOW_LOCAL_TRANSPORT=1`` dev escape is set.
+
+    DNS resolution is intentionally out of scope for this static validation;
+    runtime code that follows redirects should be hardened separately (the
+    adapter sets ``follow_redirects=False``).
+
+    Args:
+        url: The transport URL to validate.
+        transport: Name of the transport (used only in error messages).
+
+    Raises:
+        ValueError: If any SSRF guard is triggered.
+    """
+
+    parsed = urlparse(url)
+    scheme = parsed.scheme.lower()
+
+    if scheme not in _ALLOWED_URL_SCHEMES:
+        msg = (
+            f"Only http:// and https:// URLs are supported for {transport} "
+            f"transport, got: {parsed.scheme}://"
+        )
+        raise ValueError(msg)
+
+    if parsed.username or parsed.password:
+        msg = "Transport URL must not contain userinfo (credentials)"
+        raise ValueError(msg)
+
+    hostname = parsed.hostname
+    if not hostname:
+        msg = "Transport URL must include a hostname"
+        raise ValueError(msg)
+
+    allow_local = os.environ.get(_ALLOW_LOCAL_TRANSPORT_ENV, "0") == "1"
+
+    # Strip IPv6 brackets (urlparse already does, but be defensive).
+    host_literal = hostname.strip("[]")
+
+    # Check for well-known loopback hostnames before attempting IP parsing.
+    # These bypass the IP-literal checks because they are DNS names, but
+    # they resolve to loopback addresses and must be blocked unless the
+    # dev escape hatch is enabled.
+    if host_literal in _LOOPBACK_HOSTNAMES:
+        if allow_local:
+            return
+        msg = (
+            f"Transport URL points to a local hostname: "
+            f"{hostname}. Set {_ALLOW_LOCAL_TRANSPORT_ENV}=1 for local dev."
+        )
+        raise ValueError(msg)
+
+    try:
+        ip = ipaddress.ip_address(host_literal)
+    except ValueError:
+        # Not an IP literal -- a DNS name. Static validation ends here.
+        return
+
+    if allow_local:
+        return
+
+    if ip.is_loopback or ip.is_link_local or ip.is_private or ip.is_multicast:
+        msg = (
+            f"Transport URL points to loopback/link-local/private IP: "
+            f"{hostname}. Set {_ALLOW_LOCAL_TRANSPORT_ENV}=1 for local dev."
+        )
+        raise ValueError(msg)
+
+    if ip.is_reserved or ip.is_unspecified:
+        msg = f"Transport URL points to reserved/unspecified IP: {hostname}"
+        raise ValueError(msg)
 
 
 class TransportType(StrEnum):
@@ -71,6 +174,8 @@ class MCPServerConfig:
         ):
             msg = f"url is required for {self.transport} transport"
             raise ValueError(msg)
+        if self.url:
+            _validate_transport_url(self.url, str(self.transport))
 
 
 @dataclass(frozen=True, slots=True)

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev9}/tests/unit/mcp/client/test_adapter.py

@@ -1,5 +1,6 @@
 """Tests for MCP client adapter."""
 
+import inspect
 from unittest.mock import AsyncMock, MagicMock
 
 from ouroboros.mcp.client.adapter import MCPClientAdapter
@@ -134,3 +135,19 @@ class TestMCPClientAdapterRetry:
         assert adapter._max_retries == 5
         assert adapter._retry_wait_initial == 2.0
         assert adapter._retry_wait_max == 20.0
+
+
+class TestNoPrivateAPIImport:
+    """Verify private MCP SDK imports are not used."""
+
+    def test_no_private_httpx_utils_import(self) -> None:
+        """adapter.py must not import from mcp.shared._httpx_utils (private API)."""
+        import ouroboros.mcp.client.adapter as adapter_module
+
+        source = inspect.getsource(adapter_module)
+        assert "_httpx_utils" not in source, (
+            "adapter.py still references the private mcp.shared._httpx_utils module"
+        )
+        assert "create_mcp_http_client" not in source, (
+            "adapter.py still references the private create_mcp_http_client helper"
+        )

{ouroboros_ai-0.28.8.dev4 → ouroboros_ai-0.28.8.dev9}/tests/unit/mcp/client/test_adapter_transport_lifecycle.py

@@ -17,6 +17,12 @@ from ouroboros.mcp.client.adapter import MCPClientAdapter
 from ouroboros.mcp.types import MCPServerConfig, TransportType
 
 
+@pytest.fixture(autouse=True)
+def _allow_local_transport(monkeypatch: pytest.MonkeyPatch) -> None:
+    """These tests use localhost URLs — enable the local transport escape hatch."""
+    monkeypatch.setenv("OUROBOROS_ALLOW_LOCAL_TRANSPORT", "1")
+
+
 def _make_stdio_config(name: str = "test") -> MCPServerConfig:
     return MCPServerConfig(
         name=name,
@@ -311,7 +317,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client"),
+            patch("httpx.AsyncClient"),
         ):
             result = await adapter.connect(_make_http_config())
 
@@ -329,7 +335,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client"),
+            patch("httpx.AsyncClient"),
         ):
             result = await adapter.connect(
                 _make_http_config(transport=TransportType.STREAMABLE_HTTP)
@@ -355,7 +361,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client"),
+            patch("httpx.AsyncClient"),
         ):
             result = await adapter.connect(_make_http_config())
 
@@ -366,7 +372,7 @@ class TestHTTPTransportConnect:
 
     @pytest.mark.asyncio
     async def test_http_connect_passes_headers(self):
-        """When config has headers, create_mcp_http_client called with them."""
+        """When config has headers, httpx.AsyncClient is called with them."""
         adapter = MCPClientAdapter()
         transport_cm = _mock_http_transport_cm()
         session = _mock_session()
@@ -383,17 +389,22 @@ class TestHTTPTransportConnect:
                 "mcp.client.streamable_http.streamable_http_client", return_value=transport_cm
             ) as mock_http,
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client") as mock_factory,
+            patch("httpx.AsyncClient") as mock_async_client,
         ):
             result = await adapter.connect(config)
 
         assert result.is_ok
-        mock_factory.assert_called_once()
-        call_kwargs = mock_factory.call_args
-        assert call_kwargs.kwargs["headers"] == {"Authorization": "Bearer token123"}
+        mock_async_client.assert_called_once()
+        call_kwargs = mock_async_client.call_args
+        # Caller-supplied headers must survive merging with the default UA.
+        headers = call_kwargs.kwargs["headers"]
+        assert headers["Authorization"] == "Bearer token123"
+        assert headers["User-Agent"].startswith("ouroboros-mcp-client/")
+        # SSRF hardening: redirects disabled on the transport httpx client.
+        assert call_kwargs.kwargs["follow_redirects"] is False
         mock_http.assert_called_once_with(
             "http://localhost:3000",
-            http_client=mock_factory.return_value,
+            http_client=mock_async_client.return_value,
         )
 
     @pytest.mark.asyncio
@@ -413,7 +424,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client") as mock_factory,
+            patch("httpx.AsyncClient") as mock_async_client,
             patch("httpx.Timeout") as mock_timeout,
         ):
             result = await adapter.connect(config)
@@ -421,10 +432,13 @@ class TestHTTPTransportConnect:
         assert result.is_ok
         # read timeout should be max(config.timeout, 300.0) for SSE streaming
         mock_timeout.assert_called_once_with(15.0, read=300.0)
-        mock_factory.assert_called_once_with(
-            headers=None,
-            timeout=mock_timeout.return_value,
-        )
+        mock_async_client.assert_called_once()
+        call_kwargs = mock_async_client.call_args.kwargs
+        # With no caller headers, we still set a default User-Agent so
+        # MCP servers can identify the ouroboros client in their logs.
+        assert call_kwargs["headers"]["User-Agent"].startswith("ouroboros-mcp-client/")
+        assert call_kwargs["timeout"] is mock_timeout.return_value
+        assert call_kwargs["follow_redirects"] is False
 
     @pytest.mark.asyncio
     async def test_http_disconnect_cleans_transport_on_error(self):
@@ -436,7 +450,7 @@ class TestHTTPTransportConnect:
         with (
             patch("mcp.client.streamable_http.streamable_http_client", return_value=transport_cm),
             patch("mcp.ClientSession", return_value=session),
-            patch("mcp.shared._httpx_utils.create_mcp_http_client"),
+            patch("httpx.AsyncClient"),
         ):
             result = await adapter.connect(_make_http_config())