codeframe-ai 0.9.0__py3-none-any.whl

codeframe/config/rate_limits.py

@@ -0,0 +1,165 @@
+"""Rate limiting configuration for CodeFRAME API.
+
+This module provides configuration for API rate limiting using slowapi.
+It delegates to GlobalConfig in core/config.py as the single source of truth
+for environment variable handling.
+
+Environment Variables (via GlobalConfig):
+    RATE_LIMIT_ENABLED: Enable/disable rate limiting (default: true)
+    RATE_LIMIT_AUTH: Rate limit for authentication endpoints (default: 10/minute)
+    RATE_LIMIT_STANDARD: Rate limit for standard API endpoints (default: 100/minute)
+    RATE_LIMIT_AI: Rate limit for AI/expensive operations (default: 20/minute)
+    RATE_LIMIT_WEBSOCKET: Rate limit for WebSocket connections (default: 30/minute)
+    RATE_LIMIT_STORAGE: Storage backend - memory or redis (default: memory)
+    RATE_LIMIT_TRUSTED_PROXIES: Comma-separated trusted proxy IPs/CIDRs
+    REDIS_URL: Redis connection URL for distributed rate limiting (optional)
+"""
+
+import ipaddress
+import logging
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RateLimitConfig:
+    """Configuration for API rate limiting.
+
+    Attributes:
+        auth_limit: Rate limit for authentication endpoints
+        standard_limit: Rate limit for standard API endpoints
+        ai_limit: Rate limit for AI/expensive operations
+        websocket_limit: Rate limit for WebSocket connections
+        enabled: Whether rate limiting is enabled
+        storage: Storage backend ('memory' or 'redis')
+        redis_url: Redis connection URL for distributed rate limiting
+        trusted_proxies: List of trusted proxy IP addresses/networks
+    """
+
+    auth_limit: str = "10/minute"
+    standard_limit: str = "100/minute"
+    ai_limit: str = "20/minute"
+    websocket_limit: str = "30/minute"
+    enabled: bool = True
+    storage: str = "memory"
+    redis_url: Optional[str] = None
+    trusted_proxies: list = field(default_factory=list)
+
+    def is_trusted_proxy(self, ip: str) -> bool:
+        """Check if an IP address is from a trusted proxy.
+
+        Args:
+            ip: IP address to check
+
+        Returns:
+            True if IP is in trusted_proxies list or matches a trusted network
+        """
+        if not self.trusted_proxies:
+            return False
+
+        try:
+            client_ip = ipaddress.ip_address(ip)
+            for proxy in self.trusted_proxies:
+                try:
+                    # Check if it's a network (CIDR notation)
+                    if "/" in proxy:
+                        network = ipaddress.ip_network(proxy, strict=False)
+                        if client_ip in network:
+                            return True
+                    else:
+                        # Check exact IP match
+                        if client_ip == ipaddress.ip_address(proxy):
+                            return True
+                except ValueError:
+                    # Invalid proxy entry, skip it
+                    continue
+            return False
+        except ValueError:
+            # Invalid IP address
+            return False
+
+    @classmethod
+    def from_global_config(cls) -> "RateLimitConfig":
+        """Create RateLimitConfig from GlobalConfig.
+
+        Uses core/config.py as the single source of truth for
+        environment variable handling.
+
+        Returns:
+            RateLimitConfig instance with values from GlobalConfig
+        """
+        # Import here to avoid circular imports
+        from codeframe.core.config import get_global_config
+
+        global_config = get_global_config()
+
+        enabled = global_config.rate_limit_enabled
+        storage = global_config.rate_limit_storage
+        redis_url = global_config.redis_url
+
+        # Parse trusted proxies from comma-separated string
+        trusted_proxies_str = global_config.rate_limit_trusted_proxies.strip()
+        trusted_proxies = []
+        if trusted_proxies_str:
+            trusted_proxies = [
+                p.strip() for p in trusted_proxies_str.split(",") if p.strip()
+            ]
+
+        # Validate storage type (already validated by Pydantic, but double-check)
+        if storage not in ("memory", "redis"):
+            logger.warning(
+                f"Invalid RATE_LIMIT_STORAGE: {storage}. "
+                f"Must be 'memory' or 'redis'. Defaulting to 'memory'."
+            )
+            storage = "memory"
+
+        # Warn if redis storage is requested but no URL provided
+        if storage == "redis" and not redis_url:
+            logger.warning(
+                "RATE_LIMIT_STORAGE is 'redis' but REDIS_URL is not set. "
+                "Falling back to in-memory storage."
+            )
+            storage = "memory"
+
+        return cls(
+            auth_limit=global_config.rate_limit_auth,
+            standard_limit=global_config.rate_limit_standard,
+            ai_limit=global_config.rate_limit_ai,
+            websocket_limit=global_config.rate_limit_websocket,
+            enabled=enabled,
+            storage=storage,
+            redis_url=redis_url,
+            trusted_proxies=trusted_proxies,
+        )
+
+
+@lru_cache(maxsize=1)
+def get_rate_limit_config() -> RateLimitConfig:
+    """Get the global rate limit configuration.
+
+    Loads from GlobalConfig on first call, cached thereafter.
+    Thread-safe via lru_cache.
+
+    Returns:
+        RateLimitConfig instance
+    """
+    config = RateLimitConfig.from_global_config()
+    logger.info(
+        f"Rate limit config initialized: "
+        f"enabled={config.enabled}, "
+        f"storage={config.storage}, "
+        f"standard={config.standard_limit}, "
+        f"trusted_proxies={len(config.trusted_proxies)} configured"
+    )
+    return config
+
+
+def _reset_rate_limit_config() -> None:
+    """Reset the global rate limit configuration.
+
+    Useful for testing to ensure clean state between tests.
+    """
+    get_rate_limit_config.cache_clear()

codeframe/core/__init__.py

@@ -0,0 +1,15 @@
+"""Core components for CodeFRAME orchestration."""
+
+from codeframe.core.config import Config
+from codeframe.core.models import Task, TaskStatus, AgentMaturity
+from codeframe.core.stall_detector import StallAction, StallDetectedError, StallDetector
+
+__all__ = [
+    "Config",
+    "Task",
+    "TaskStatus",
+    "AgentMaturity",
+    "StallAction",
+    "StallDetectedError",
+    "StallDetector",
+]

codeframe/core/adapters/__init__.py

@@ -0,0 +1,43 @@
+from codeframe.core.adapters.streaming_chat import (
+    ChatEvent,
+    ChatEventType,
+    StreamingChatAdapter,
+    STREAMING_SAFE_TOOLS,
+)
+from codeframe.core.adapters.agent_adapter import (
+    AdapterTokenUsage,
+    AgentAdapter,
+    AgentContext,
+    AgentEvent,
+    AgentResult,
+    AgentResultStatus,
+)
+from codeframe.core.adapters.builtin import (
+    BuiltinPlanAdapter,
+    BuiltinReactAdapter,
+)
+from codeframe.core.adapters.claude_code import ClaudeCodeAdapter
+from codeframe.core.adapters.codex import CodexAdapter
+from codeframe.core.adapters.opencode import OpenCodeAdapter
+from codeframe.core.adapters.subprocess_adapter import SubprocessAdapter
+from codeframe.core.adapters.verification_wrapper import VerificationWrapper
+
+__all__ = [
+    "ChatEvent",
+    "ChatEventType",
+    "StreamingChatAdapter",
+    "STREAMING_SAFE_TOOLS",
+    "AdapterTokenUsage",
+    "AgentAdapter",
+    "AgentContext",
+    "AgentEvent",
+    "AgentResult",
+    "AgentResultStatus",
+    "BuiltinPlanAdapter",
+    "BuiltinReactAdapter",
+    "ClaudeCodeAdapter",
+    "CodexAdapter",
+    "OpenCodeAdapter",
+    "SubprocessAdapter",
+    "VerificationWrapper",
+]

codeframe/core/adapters/agent_adapter.py

@@ -0,0 +1,114 @@
+"""Agent adapter protocol for delegating task execution to external coding agents.
+
+Defines the interface that any coding agent (Claude Code, Codex, Aider, built-in)
+must implement to be used as a CodeFrame execution engine, plus the supporting
+types for context, results, events, and token tracking.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Callable, Literal, Protocol, runtime_checkable
+
+
+class AgentResultStatus(str, Enum):
+    """Terminal status from an agent execution."""
+
+    COMPLETED = "completed"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+    TIMEOUT = "timeout"
+
+
+@dataclass
+class AdapterTokenUsage:
+    """Lightweight token usage for adapter results."""
+
+    input_tokens: int
+    output_tokens: int
+    model: str | None = None
+    cost_usd: float | None = None
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+@dataclass
+class AgentContext:
+    """Everything CodeFrame provides to an execution engine."""
+
+    task_id: str
+    task_title: str
+    task_description: str
+    prd_content: str | None = None
+    tech_stack: str | None = None
+    project_preferences: str | None = None
+    relevant_files: list[str] = field(default_factory=list)
+    file_contents: dict[str, str] = field(default_factory=dict)
+    blocker_history: list[str] = field(default_factory=list)
+    dependency_context: str | None = None
+    verification_gates: list[str] = field(default_factory=list)
+    attempt: int = 0
+    previous_errors: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AgentResult:
+    """Result from an agent adapter execution."""
+
+    status: Literal["completed", "failed", "blocked"]
+    output: str = ""
+    modified_files: list[str] = field(default_factory=list)
+    error: str | None = None
+    blocker_question: str | None = None
+    token_usage: AdapterTokenUsage | None = None
+    duration_ms: int = 0
+    cloud_metadata: dict | None = None
+
+
+@dataclass
+class AgentEvent:
+    """Progress event emitted during agent execution."""
+
+    type: str  # "progress", "tool_call", "output", "error"
+    data: dict = field(default_factory=dict)
+    message: str = ""
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+@runtime_checkable
+class AgentAdapter(Protocol):
+    """Protocol for agent execution engines.
+
+    Any coding agent (Claude Code, OpenCode, Codex, etc.) must implement
+    this interface to be used as a CodeFRAME execution engine.
+    """
+
+    @property
+    def name(self) -> str:
+        """Engine name (e.g., 'claude-code', 'opencode')."""
+        ...
+
+    def run(
+        self,
+        task_id: str,
+        prompt: str,
+        workspace_path: Path,
+        on_event: Callable[[AgentEvent], None] | None = None,
+    ) -> AgentResult:
+        """Execute a task and return the result.
+
+        Args:
+            task_id: CodeFRAME task identifier
+            prompt: Rich context prompt assembled by TaskContextPackager
+            workspace_path: Path to the workspace/repo root
+            on_event: Optional callback for streaming progress events
+
+        Returns:
+            AgentResult with status, output, and modified files
+        """
+        ...

codeframe/core/adapters/builtin.py

@@ -0,0 +1,326 @@
+"""Builtin adapter shims wrapping ReactAgent and Agent behind AgentAdapter protocol.
+
+These adapters encapsulate all engine-specific behavior (stall retry for React,
+supervisor retry for Plan) so the runtime can treat all engines uniformly.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable, Optional
+
+from codeframe.core.adapters.agent_adapter import AgentEvent, AgentResult
+
+if TYPE_CHECKING:
+    from codeframe.adapters.llm.base import LLMProvider
+    from codeframe.core.conductor import GlobalFixCoordinator
+    from codeframe.core.stall_detector import StallAction
+    from codeframe.core.streaming import EventPublisher, RunOutputLogger
+    from codeframe.core.workspace import Workspace
+
+logger = logging.getLogger(__name__)
+
+_MAX_STALL_RETRIES = 1
+
+
+class BuiltinReactAdapter:
+    """Wraps the existing ReactAgent behind the AgentAdapter interface.
+
+    Handles stall detection and retry internally so the runtime
+    doesn't need engine-specific branching.
+    """
+
+    def __init__(
+        self,
+        workspace: Workspace,
+        llm_provider: LLMProvider,
+        *,
+        stall_timeout_s: float = 300,
+        stall_action: Optional[StallAction] = None,
+        event_publisher: Optional[EventPublisher] = None,
+        dry_run: bool = False,
+        verbose: bool = False,
+        debug: bool = False,
+        output_logger: Optional[RunOutputLogger] = None,
+        fix_coordinator: Optional[GlobalFixCoordinator] = None,
+    ) -> None:
+        self._workspace = workspace
+        self._llm_provider = llm_provider
+        self._stall_timeout_s = stall_timeout_s
+        self._stall_action = stall_action
+        self._event_publisher = event_publisher
+        self._dry_run = dry_run
+        self._verbose = verbose
+        self._debug = debug
+        self._output_logger = output_logger
+        self._fix_coordinator = fix_coordinator
+
+    @property
+    def name(self) -> str:
+        return "react"
+
+    @classmethod
+    def requirements(cls) -> dict[str, str]:
+        """Return requirement names and descriptions."""
+        return {"ANTHROPIC_API_KEY": "Anthropic API key for LLM calls"}
+
+    def run(
+        self,
+        task_id: str,
+        prompt: str,
+        workspace_path: Path,
+        on_event: Callable[[AgentEvent], None] | None = None,
+    ) -> AgentResult:
+        """Run the ReactAgent with stall retry, map AgentStatus to AgentResult."""
+        from codeframe.core.react_agent import ReactAgent
+        from codeframe.core.stall_detector import StallDetectedError
+
+        def _bridge_event(event_type: str, data: dict) -> None:
+            if on_event:
+                on_event(AgentEvent(type=event_type, data=data))
+
+        def _build_agent() -> ReactAgent:
+            kwargs: dict = {
+                "workspace": self._workspace,
+                "llm_provider": self._llm_provider,
+                "stall_timeout_s": self._stall_timeout_s,
+                "event_publisher": self._event_publisher,
+                "dry_run": self._dry_run,
+                "verbose": self._verbose,
+                "on_event": _bridge_event,
+                "debug": self._debug,
+                "output_logger": self._output_logger,
+                "fix_coordinator": self._fix_coordinator,
+            }
+            if self._stall_action is not None:
+                kwargs["stall_action"] = self._stall_action
+            return ReactAgent(**kwargs)
+
+        for stall_attempt in range(1 + _MAX_STALL_RETRIES):
+            try:
+                agent = _build_agent()
+                status = agent.run(task_id)
+                return self._map_status(status)
+            except StallDetectedError as exc:
+                logger.warning(
+                    "Stall detected (attempt %d): %s",
+                    stall_attempt + 1, exc,
+                )
+                if stall_attempt >= _MAX_STALL_RETRIES:
+                    logger.error("Max stall retries exceeded, failing task")
+                    return AgentResult(
+                        status="failed",
+                        error=f"Stall detected after {stall_attempt + 1} attempts: {exc}",
+                    )
+                logger.info("Retrying after stall (attempt %d)", stall_attempt + 2)
+
+        return AgentResult(status="failed", error="Unexpected: stall retry loop exhausted")
+
+    @staticmethod
+    def _map_status(status: object) -> AgentResult:
+        """Map AgentStatus enum to AgentResult."""
+        from codeframe.core.agent import AgentStatus
+
+        status_map = {
+            AgentStatus.COMPLETED: "completed",
+            AgentStatus.FAILED: "failed",
+            AgentStatus.BLOCKED: "blocked",
+        }
+        result_status = status_map.get(status, "failed")  # type: ignore[arg-type]
+        return AgentResult(
+            status=result_status,
+            output=f"ReactAgent finished with status: {status.value}",  # type: ignore[union-attr]
+        )
+
+
+class BuiltinPlanAdapter:
+    """Wraps the existing plan-based Agent behind the AgentAdapter interface.
+
+    Handles supervisor BLOCKED-retry and tactical failure recovery internally.
+    """
+
+    def __init__(
+        self,
+        workspace: Workspace,
+        llm_provider: LLMProvider,
+        *,
+        dry_run: bool = False,
+        verbose: bool = False,
+        debug: bool = False,
+        output_logger: Optional[RunOutputLogger] = None,
+        fix_coordinator: Optional[GlobalFixCoordinator] = None,
+        event_publisher: Optional[EventPublisher] = None,
+    ) -> None:
+        self._workspace = workspace
+        self._llm_provider = llm_provider
+        self._dry_run = dry_run
+        self._verbose = verbose
+        self._debug = debug
+        self._output_logger = output_logger
+        self._fix_coordinator = fix_coordinator
+        self._event_publisher = event_publisher
+
+    @property
+    def name(self) -> str:
+        return "plan"
+
+    @classmethod
+    def requirements(cls) -> dict[str, str]:
+        """Return requirement names and descriptions."""
+        return {"ANTHROPIC_API_KEY": "Anthropic API key for LLM calls"}
+
+    def run(
+        self,
+        task_id: str,
+        prompt: str,
+        workspace_path: Path,
+        on_event: Callable[[AgentEvent], None] | None = None,
+    ) -> AgentResult:
+        """Run the plan-based Agent with supervisor retry, map to AgentResult."""
+        from codeframe.core.agent import Agent, AgentStatus
+
+        def _bridge_event(event_type: str, data: dict) -> None:
+            if on_event:
+                on_event(AgentEvent(type=event_type, data=data))
+
+        def _build_agent() -> Agent:
+            return Agent(
+                workspace=self._workspace,
+                llm_provider=self._llm_provider,
+                dry_run=self._dry_run,
+                on_event=_bridge_event,
+                debug=self._debug,
+                verbose=self._verbose,
+                fix_coordinator=self._fix_coordinator,
+                output_logger=self._output_logger,
+                event_publisher=self._event_publisher,
+            )
+
+        agent = _build_agent()
+        state = agent.run(task_id)
+
+        # Supervisor BLOCKED-retry (best-effort — failures don't affect result)
+        if state.status == AgentStatus.BLOCKED:
+            try:
+                state = self._try_supervisor_unblock(state, task_id, _build_agent)
+            except Exception:
+                logger.debug("Supervisor unblock failed, returning original state", exc_info=True)
+
+        # Supervisor tactical failure recovery (best-effort)
+        if state.status == AgentStatus.FAILED:
+            try:
+                state = self._try_tactical_recovery(state, task_id, _build_agent)
+            except Exception:
+                logger.debug("Supervisor tactical recovery failed, returning original state", exc_info=True)
+
+        return self._map_state(state)
+
+    def _try_supervisor_unblock(self, state, task_id: str, build_agent):
+        """Try supervisor resolution for BLOCKED tasks."""
+        from codeframe.core.conductor import get_supervisor
+
+        supervisor = get_supervisor(self._workspace)
+        if supervisor.try_resolve_blocked_task(task_id):
+            logger.info("[Supervisor] Retrying task after auto-resolution...")
+            agent = build_agent()
+            state = agent.run(task_id)
+        return state
+
+    def _try_tactical_recovery(self, state, task_id: str, build_agent):
+        """Try supervisor tactical recovery for FAILED tasks."""
+        from codeframe.core.conductor import get_supervisor, SUPERVISOR_TACTICAL_PATTERNS
+
+        error_msg = self._extract_error(state)
+
+        if not error_msg:
+            return state
+
+        error_msg_lower = error_msg.lower()
+        matched_patterns = [p for p in SUPERVISOR_TACTICAL_PATTERNS if p in error_msg_lower]
+
+        if not matched_patterns:
+            return state
+
+        supervisor = get_supervisor(self._workspace)
+        resolution = supervisor._generate_tactical_resolution(error_msg)
+        logger.info(
+            "Supervisor detected recoverable error, providing guidance: %s...",
+            resolution[:100],
+        )
+
+        from codeframe.core import blockers
+        blocker = blockers.create(
+            self._workspace,
+            task_id=task_id,
+            question=f"Technical error: {error_msg[:500]}",
+            created_by="agent",
+        )
+        blockers.answer(self._workspace, blocker.id, resolution)
+
+        logger.info("Supervisor retrying task with guidance...")
+        agent = build_agent()
+        return agent.run(task_id)
+
+    @staticmethod
+    def _extract_error(state) -> str:
+        """Extract error message from AgentState for supervisor analysis."""
+        blocker = getattr(state, "blocker", None)
+        if blocker:
+            return getattr(blocker, "reason", None) or getattr(blocker, "question", None) or ""
+
+        step_results = getattr(state, "step_results", None) or []
+        if step_results:
+            last_result = step_results[-1]
+            if hasattr(last_result, "error") and last_result.error:
+                return last_result.error
+            if hasattr(last_result, "output") and last_result.output:
+                return last_result.output
+
+        gate_results = getattr(state, "gate_results", None) or []
+        for gate in gate_results:
+            if not gate.passed:
+                for check in gate.checks:
+                    if check.output:
+                        return check.output
+
+        return ""
+
+    @staticmethod
+    def _map_state(state: object) -> AgentResult:
+        """Map AgentState dataclass to AgentResult."""
+        from codeframe.core.agent import AgentStatus
+
+        status_map = {
+            AgentStatus.COMPLETED: "completed",
+            AgentStatus.FAILED: "failed",
+            AgentStatus.BLOCKED: "blocked",
+        }
+        result_status = status_map.get(state.status, "failed")  # type: ignore[union-attr]
+
+        blocker_question = None
+        if state.status == AgentStatus.BLOCKED:  # type: ignore[union-attr]
+            blocker = getattr(state, "blocker", None)
+            if blocker:
+                blocker_question = getattr(blocker, "question", None) or getattr(
+                    blocker, "reason", None
+                )
+
+        error = None
+        if state.status == AgentStatus.FAILED:  # type: ignore[union-attr]
+            gate_results = getattr(state, "gate_results", None) or []
+            error_parts: list[str] = []
+            for gr in gate_results:
+                for check in getattr(gr, "checks", []):
+                    output = getattr(check, "output", None)
+                    if output:
+                        error_parts.append(output)
+            if error_parts:
+                error = "\n".join(error_parts[:3])
+
+        return AgentResult(
+            status=result_status,
+            output=f"PlanAgent finished with status: {state.status.value}",  # type: ignore[union-attr]
+            blocker_question=blocker_question,
+            error=error,
+        )