codeframe-ai 0.9.0__py3-none-any.whl

codeframe/core/blocker_detection.py

@@ -0,0 +1,218 @@
+"""Blocker detection — reusable pattern matching for agent blocker creation.
+
+Classifies error text to determine whether a blocker should be created
+(requires human intervention) or the agent should self-correct.
+
+Pattern constants are defined here and imported by agent.py and react_agent.py.
+"""
+
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Pattern constants (authoritative location — imported by agent.py)
+# ---------------------------------------------------------------------------
+
+# TRUE requirements ambiguity - create blocker immediately
+# These are situations where the agent genuinely cannot proceed without human input
+REQUIREMENTS_AMBIGUITY_PATTERNS = [
+    # True requirements conflicts
+    "conflicting requirements",
+    "spec unclear",
+    "specification unclear",
+    "requirements conflict",
+    "contradictory requirements",
+    # Business logic requiring domain knowledge
+    "business decision",
+    "business logic unclear",
+    "domain knowledge required",
+    "stakeholder decision",
+    # Security policy ambiguity
+    "security policy unclear",
+    "compliance requirement unclear",
+    "regulatory requirement",
+]
+
+# Access/credentials issues - always create blocker
+# These truly require human intervention
+ACCESS_PATTERNS = [
+    "permission denied",
+    "access denied",
+    "authentication required",
+    "api key",  # Covers "api key missing", "api key not configured", etc.
+    "credentials",  # Covers "credentials missing", "credentials required", etc.
+    "secret required",
+    "token required",
+    "unauthorized",
+    "forbidden",
+]
+
+# External service issues - create blocker after retry
+EXTERNAL_SERVICE_PATTERNS = [
+    "service unavailable",
+    "rate limited",
+    "quota exceeded",
+    "connection refused",
+    "timeout exceeded",
+]
+
+# TACTICAL decisions - agent should resolve autonomously, NEVER block
+# These patterns indicate the agent is asking about implementation details
+# it should decide on its own using project preferences or best practices
+TACTICAL_DECISION_PATTERNS = [
+    # Implementation choices
+    "which approach",
+    "should i use",
+    "multiple options",
+    "design decision",
+    "please clarify",
+    "need clarification",
+    # File handling
+    "file already exists",
+    "overwrite",
+    "should i create",
+    "should i delete",
+    # Tooling choices
+    "which version",
+    "which package",
+    "which framework",
+    "install method",
+    "package manager",
+    # Configuration choices
+    "which configuration",
+    "which setting",
+    "default value",
+    "fixture scope",
+    "loop scope",
+    # Generic decision patterns
+    "what do you",
+    "do you want",
+    "would you like",
+    "prefer",
+]
+
+# Combined pattern for human input (requirements + access + external)
+# NOTE: Tactical patterns are explicitly EXCLUDED - agent handles these autonomously
+HUMAN_INPUT_PATTERNS = (
+    REQUIREMENTS_AMBIGUITY_PATTERNS + ACCESS_PATTERNS + EXTERNAL_SERVICE_PATTERNS
+)
+
+# Error patterns that are technical and the agent should self-correct
+# These are coding/execution errors the agent can fix by trying a different approach
+TECHNICAL_ERROR_PATTERNS = [
+    # File/path issues - agent can find correct path or create file
+    "file not found",
+    "no such file",
+    "directory not found",
+    "path does not exist",
+    "filenotfounderror",
+    # Import/module issues - agent can fix imports
+    "module not found",
+    "import error",
+    "no module named",
+    "cannot find module",
+    "modulenotfounderror",
+    # Syntax/code issues - agent can fix code
+    "syntax error",
+    "syntaxerror",
+    "indentation error",
+    "name error",
+    "nameerror",
+    "type error",
+    "typeerror",
+    "attribute error",
+    "attributeerror",
+    "undefined",
+    "not defined",
+    # Command execution issues - agent can try different command
+    "command not found",
+    "exit code",
+    "non-zero exit",
+    # General coding issues
+    "missing",  # usually missing import, argument, etc.
+    "expected",
+    "invalid",
+]
+
+# ---------------------------------------------------------------------------
+# Classification functions
+# ---------------------------------------------------------------------------
+
+
+def classify_error_for_blocker(text: str) -> Optional[str]:
+    """Classify error text into a blocker category.
+
+    Returns:
+        "requirements" | "access" | "external_service" if a blocker is warranted.
+        None if the agent should handle it autonomously (tactical/technical/unknown).
+
+    Priority order:
+        1. Tactical patterns → None (agent resolves autonomously)
+        2. Requirements ambiguity → "requirements"
+        3. Access/credentials → "access"
+        4. External service → "external_service"
+        5. Technical error patterns → None (agent self-corrects)
+        6. No match → None
+    """
+    lower = text.lower()
+
+    # Tactical decisions — agent handles autonomously, never block
+    for pattern in TACTICAL_DECISION_PATTERNS:
+        if pattern in lower:
+            return None
+
+    # Requirements ambiguity — immediate blocker
+    for pattern in REQUIREMENTS_AMBIGUITY_PATTERNS:
+        if pattern in lower:
+            return "requirements"
+
+    # Access/credentials — immediate blocker
+    for pattern in ACCESS_PATTERNS:
+        if pattern in lower:
+            return "access"
+
+    # External service issues — deferred blocker (caller decides retry threshold)
+    for pattern in EXTERNAL_SERVICE_PATTERNS:
+        if pattern in lower:
+            return "external_service"
+
+    # Technical errors — agent self-corrects (checked after blocker categories
+    # since some technical patterns like "missing" overlap with access patterns)
+    for pattern in TECHNICAL_ERROR_PATTERNS:
+        if pattern in lower:
+            return None
+
+    return None
+
+
+def should_create_blocker(text: str, attempt_count: int = 0) -> tuple[bool, str]:
+    """Decide whether to create a blocker for the given error text.
+
+    This is the retry-aware public API for blocker decisions.  Use it in
+    contexts where the caller tracks attempt counts (e.g., verification
+    retry loops).  For one-shot detection — such as scanning an LLM
+    text-only response — use :func:`classify_error_for_blocker` directly
+    and treat any non-None category as an immediate blocker.
+
+    Args:
+        text: Error or status text to evaluate.
+        attempt_count: Number of prior attempts. External service blockers
+            are only created when attempt_count > 1.
+
+    Returns:
+        (True, reason) if a blocker should be created.
+        (False, "") otherwise.
+    """
+    category = classify_error_for_blocker(text)
+
+    if category == "requirements":
+        return True, "Requirements ambiguity detected — human clarification needed"
+
+    if category == "access":
+        return True, "Access or credentials issue — human intervention needed"
+
+    if category == "external_service":
+        if attempt_count > 1:
+            return True, "External service issue persists after retries — human intervention needed"
+        return False, ""
+
+    return False, ""

codeframe/core/blockers.py

@@ -0,0 +1,433 @@
+"""Blocker management for CodeFRAME v2.
+
+Blockers represent human-in-the-loop questions that pause task execution
+until answered by a human.
+
+This module is headless - no FastAPI or HTTP dependencies.
+"""
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional, Union
+
+from codeframe.core.workspace import Workspace, get_db_connection
+from codeframe.core import events, runtime, tasks
+from codeframe.core.state_machine import TaskStatus
+
+
+def _utc_now() -> datetime:
+    """Get current UTC time as timezone-aware datetime."""
+    return datetime.now(timezone.utc)
+
+
+class BlockerStatus(str, Enum):
+    """Status of a blocker."""
+
+    OPEN = "OPEN"
+    ANSWERED = "ANSWERED"
+    RESOLVED = "RESOLVED"
+
+
+class BlockerOrigin(str, Enum):
+    """Who created the blocker."""
+
+    SYSTEM = "system"
+    AGENT = "agent"
+    HUMAN = "human"
+
+
+@dataclass
+class Blocker:
+    """Represents a blocker (human-in-the-loop question).
+
+    Attributes:
+        id: Unique blocker identifier (UUID)
+        workspace_id: Workspace this blocker belongs to
+        task_id: Optional task this blocker is associated with
+        question: The question being asked
+        answer: The answer provided (if answered)
+        status: Current blocker status
+        created_at: When the blocker was created
+        answered_at: When the blocker was answered (if answered)
+        created_by: Origin of the blocker (system, agent, or human)
+    """
+
+    id: str
+    workspace_id: str
+    task_id: Optional[str]
+    question: str
+    answer: Optional[str]
+    status: BlockerStatus
+    created_at: datetime
+    answered_at: Optional[datetime]
+    created_by: BlockerOrigin = BlockerOrigin.HUMAN
+
+
+def create(
+    workspace: Workspace,
+    question: str,
+    task_id: Optional[str] = None,
+    created_by: Union[BlockerOrigin, str] = BlockerOrigin.HUMAN,
+) -> Blocker:
+    """Create a new blocker.
+
+    Args:
+        workspace: Target workspace
+        question: The question to ask
+        task_id: Optional associated task ID
+        created_by: Origin of the blocker ("system", "agent", or "human")
+
+    Returns:
+        Created Blocker
+    """
+    origin = BlockerOrigin(created_by)
+    blocker_id = str(uuid.uuid4())
+    now = _utc_now().isoformat()
+
+    conn = get_db_connection(workspace)
+    cursor = conn.cursor()
+
+    cursor.execute(
+        """
+        INSERT INTO blockers (id, workspace_id, task_id, question, status, created_at, created_by)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        """,
+        (blocker_id, workspace.id, task_id, question, BlockerStatus.OPEN.value, now, origin.value),
+    )
+    conn.commit()
+    conn.close()
+
+    blocker = Blocker(
+        id=blocker_id,
+        workspace_id=workspace.id,
+        task_id=task_id,
+        question=question,
+        answer=None,
+        status=BlockerStatus.OPEN,
+        created_at=datetime.fromisoformat(now),
+        answered_at=None,
+        created_by=origin,
+    )
+
+    # Emit blocker created event
+    events.emit_for_workspace(
+        workspace,
+        events.EventType.BLOCKER_CREATED,
+        {"blocker_id": blocker_id, "task_id": task_id, "question": question[:100]},
+        print_event=True,
+    )
+
+    # Outbound webhook dispatch (issue #560) — fire-and-forget, never blocks
+    # blocker creation. A misconfigured webhook must not break the workflow.
+    _dispatch_blocker_webhook(workspace, blocker_id, task_id)
+
+    return blocker
+
+
+def _dispatch_blocker_webhook(
+    workspace: Workspace, blocker_id: str, task_id: Optional[str]
+) -> None:
+    """Best-effort outbound webhook for ``blocker.created``."""
+    try:
+        from codeframe.core.notifications_config import is_webhook_active
+        from codeframe.notifications.webhook import (
+            WebhookNotificationService,
+            format_blocker_payload,
+        )
+
+        url = is_webhook_active(workspace)
+        if url is None:
+            return
+        svc = WebhookNotificationService(webhook_url=url, timeout=5)
+        svc.send_event_background(format_blocker_payload(blocker_id, task_id))
+    except Exception:
+        import logging
+
+        logging.getLogger(__name__).warning(
+            "Failed to dispatch blocker.created webhook for %s", blocker_id,
+            exc_info=True,
+        )
+
+
+def get(workspace: Workspace, blocker_id: str) -> Optional[Blocker]:
+    """Get a blocker by ID.
+
+    Supports partial ID matching.
+
+    Args:
+        workspace: Workspace to query
+        blocker_id: Blocker identifier (can be partial)
+
+    Returns:
+        Blocker if found, None otherwise
+    """
+    conn = get_db_connection(workspace)
+    cursor = conn.cursor()
+
+    # Try exact match first
+    cursor.execute(
+        """
+        SELECT id, workspace_id, task_id, question, answer, status, created_at, answered_at,
+               COALESCE(created_by, 'human') as created_by
+        FROM blockers
+        WHERE workspace_id = ? AND id = ?
+        """,
+        (workspace.id, blocker_id),
+    )
+    row = cursor.fetchone()
+
+    # If no exact match, try prefix match
+    if not row:
+        cursor.execute(
+            """
+            SELECT id, workspace_id, task_id, question, answer, status, created_at, answered_at,
+                   COALESCE(created_by, 'human') as created_by
+            FROM blockers
+            WHERE workspace_id = ? AND id LIKE ?
+            """,
+            (workspace.id, f"{blocker_id}%"),
+        )
+        rows = cursor.fetchall()
+        if len(rows) == 1:
+            row = rows[0]
+        elif len(rows) > 1:
+            conn.close()
+            raise ValueError(f"Multiple blockers match '{blocker_id}'")
+
+    conn.close()
+
+    if not row:
+        return None
+
+    return _row_to_blocker(row)
+
+
+def list_open(workspace: Workspace) -> list[Blocker]:
+    """List open blockers.
+
+    Args:
+        workspace: Workspace to query
+
+    Returns:
+        List of open Blockers, oldest first
+    """
+    return list_all(workspace, status=BlockerStatus.OPEN)
+
+
+def list_all(
+    workspace: Workspace,
+    status: Optional[BlockerStatus] = None,
+    task_id: Optional[str] = None,
+    limit: int = 100,
+) -> list[Blocker]:
+    """List blockers with optional filters.
+
+    Args:
+        workspace: Workspace to query
+        status: Optional status filter
+        task_id: Optional task filter
+        limit: Maximum blockers to return
+
+    Returns:
+        List of Blockers, oldest first
+    """
+    conn = get_db_connection(workspace)
+    cursor = conn.cursor()
+
+    query = """
+        SELECT id, workspace_id, task_id, question, answer, status, created_at, answered_at,
+               COALESCE(created_by, 'human') as created_by
+        FROM blockers
+        WHERE workspace_id = ?
+    """
+    params: list = [workspace.id]
+
+    if status:
+        query += " AND status = ?"
+        params.append(status.value)
+
+    if task_id:
+        query += " AND task_id = ?"
+        params.append(task_id)
+
+    query += " ORDER BY created_at ASC LIMIT ?"
+    params.append(limit)
+
+    cursor.execute(query, params)
+    rows = cursor.fetchall()
+    conn.close()
+
+    return [_row_to_blocker(row) for row in rows]
+
+
+def list_for_task(workspace: Workspace, task_id: str) -> list[Blocker]:
+    """List all blockers for a specific task.
+
+    Args:
+        workspace: Workspace to query
+        task_id: Task to filter by
+
+    Returns:
+        List of Blockers for the task
+    """
+    return list_all(workspace, task_id=task_id)
+
+
+def answer(workspace: Workspace, blocker_id: str, text: str) -> Blocker:
+    """Answer a blocker.
+
+    Args:
+        workspace: Target workspace
+        blocker_id: Blocker to answer (can be partial ID)
+        text: Answer text
+
+    Returns:
+        Updated Blocker
+
+    Raises:
+        ValueError: If blocker not found or already resolved
+    """
+    blocker = get(workspace, blocker_id)
+    if not blocker:
+        raise ValueError(f"Blocker not found: {blocker_id}")
+
+    if blocker.status == BlockerStatus.RESOLVED:
+        raise ValueError(f"Blocker already resolved: {blocker_id}")
+
+    now = _utc_now().isoformat()
+
+    conn = get_db_connection(workspace)
+    cursor = conn.cursor()
+
+    cursor.execute(
+        """
+        UPDATE blockers
+        SET answer = ?, status = ?, answered_at = ?
+        WHERE id = ?
+        """,
+        (text, BlockerStatus.ANSWERED.value, now, blocker.id),
+    )
+    conn.commit()
+    conn.close()
+
+    # Emit blocker answered event
+    events.emit_for_workspace(
+        workspace,
+        events.EventType.BLOCKER_ANSWERED,
+        {"blocker_id": blocker.id, "task_id": blocker.task_id},
+        print_event=True,
+    )
+
+    blocker.answer = text
+    blocker.status = BlockerStatus.ANSWERED
+    blocker.answered_at = datetime.fromisoformat(now)
+
+    # Automatically reset the associated task to READY so it can be restarted
+    # This eliminates the need for separate "work stop" and "work resume" commands
+    if blocker.task_id:
+        try:
+            # Stop the blocked run (marks it as FAILED)
+            active_run = runtime.get_active_run(workspace, blocker.task_id)
+            if active_run and active_run.status == runtime.RunStatus.BLOCKED:
+                runtime.stop_run(workspace, blocker.task_id)
+            # Task is now READY and can be restarted with `cf work start <id> --execute`
+        except ValueError:
+            # No active run found, just ensure task is READY
+            task = tasks.get(workspace, blocker.task_id)
+            if task and task.status == TaskStatus.BLOCKED:
+                tasks.update_status(workspace, blocker.task_id, TaskStatus.READY)
+
+    return blocker
+
+
+def resolve(workspace: Workspace, blocker_id: str) -> Blocker:
+    """Mark a blocker as resolved.
+
+    Args:
+        workspace: Target workspace
+        blocker_id: Blocker to resolve (can be partial ID)
+
+    Returns:
+        Updated Blocker
+
+    Raises:
+        ValueError: If blocker not found or not answered
+    """
+    blocker = get(workspace, blocker_id)
+    if not blocker:
+        raise ValueError(f"Blocker not found: {blocker_id}")
+
+    if blocker.status == BlockerStatus.OPEN:
+        raise ValueError(f"Blocker must be answered before resolving: {blocker_id}")
+
+    if blocker.status == BlockerStatus.RESOLVED:
+        raise ValueError(f"Blocker already resolved: {blocker_id}")
+
+    conn = get_db_connection(workspace)
+    cursor = conn.cursor()
+
+    cursor.execute(
+        """
+        UPDATE blockers
+        SET status = ?
+        WHERE id = ?
+        """,
+        (BlockerStatus.RESOLVED.value, blocker.id),
+    )
+    conn.commit()
+    conn.close()
+
+    # Emit blocker resolved event
+    events.emit_for_workspace(
+        workspace,
+        events.EventType.BLOCKER_RESOLVED,
+        {"blocker_id": blocker.id, "task_id": blocker.task_id},
+        print_event=True,
+    )
+
+    blocker.status = BlockerStatus.RESOLVED
+    return blocker
+
+
+def count_by_status(workspace: Workspace) -> dict[str, int]:
+    """Count blockers by status.
+
+    Args:
+        workspace: Workspace to query
+
+    Returns:
+        Dict mapping status string to count
+    """
+    conn = get_db_connection(workspace)
+    cursor = conn.cursor()
+
+    cursor.execute(
+        """
+        SELECT status, COUNT(*) as count
+        FROM blockers
+        WHERE workspace_id = ?
+        GROUP BY status
+        """,
+        (workspace.id,),
+    )
+    rows = cursor.fetchall()
+    conn.close()
+
+    return {row[0]: row[1] for row in rows}
+
+
+def _row_to_blocker(row: tuple) -> Blocker:
+    """Convert a database row to a Blocker object."""
+    return Blocker(
+        id=row[0],
+        workspace_id=row[1],
+        task_id=row[2],
+        question=row[3],
+        answer=row[4],
+        status=BlockerStatus(row[5]),
+        created_at=datetime.fromisoformat(row[6]),
+        answered_at=datetime.fromisoformat(row[7]) if row[7] else None,
+        created_by=BlockerOrigin(row[8]),
+    )