codeframe-ai 0.9.0__py3-none-any.whl

codeframe/core/adapters/streaming_chat.py

@@ -0,0 +1,483 @@
+"""Streaming chat adapter — provider-agnostic.
+
+Wraps any :class:`LLMProvider` that implements ``async_stream()`` and emits
+typed ``ChatEvent`` objects for consumption by the WebSocket relay layer.
+
+Supports:
+- Token-by-token text streaming (TEXT_DELTA)
+- Extended thinking tokens (THINKING) on providers that support it
+- Safe read-only tool calls: read_file, list_files, search_codebase
+- Interrupt via asyncio.Event
+- Message persistence to session_messages after each complete turn
+- Context-window management via tiktoken token counting
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import AsyncIterator, Optional
+
+from codeframe.adapters.llm.base import LLMProvider, Tool, ToolCall, ToolResult
+from codeframe.core.tools import (
+    execute_tool,
+    _READ_FILE_SCHEMA,
+    _LIST_FILES_SCHEMA,
+    _SEARCH_CODEBASE_SCHEMA,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Default model (matches DEFAULT_PLANNING_MODEL in base.py)
+# ---------------------------------------------------------------------------
+
+_DEFAULT_MODEL = "claude-sonnet-4-20250514"
+
+# Maximum token budget for conversation history passed to the API.
+# claude-sonnet-4 context window is 200k; leave 20k for response headroom.
+_MAX_HISTORY_TOKENS = 180_000
+
+# ---------------------------------------------------------------------------
+# Event types
+# ---------------------------------------------------------------------------
+
+
+class ChatEventType(str, Enum):
+    TEXT_DELTA = "text_delta"
+    TOOL_USE_START = "tool_use_start"
+    TOOL_RESULT = "tool_result"
+    THINKING = "thinking"
+    COST_UPDATE = "cost_update"
+    DONE = "done"
+    ERROR = "error"
+
+
+@dataclass
+class ChatEvent:
+    type: ChatEventType
+    content: Optional[str] = None
+    tool_name: Optional[str] = None
+    tool_input: Optional[dict] = None
+    cost_usd: Optional[float] = None
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+
+    def to_dict(self) -> dict:
+        """Serialise to a dict suitable for JSON transmission."""
+        d: dict = {"type": self.type.value}
+        if self.content is not None:
+            d["content"] = self.content
+        if self.tool_name is not None:
+            d["tool_name"] = self.tool_name
+        if self.tool_input is not None:
+            d["tool_input"] = self.tool_input
+        if self.cost_usd is not None:
+            d["cost_usd"] = self.cost_usd
+        if self.input_tokens is not None:
+            d["input_tokens"] = self.input_tokens
+        if self.output_tokens is not None:
+            d["output_tokens"] = self.output_tokens
+        return d
+
+
+# ---------------------------------------------------------------------------
+# Safe read-only tool set for interactive sessions
+# ---------------------------------------------------------------------------
+
+STREAMING_SAFE_TOOLS: list[Tool] = [
+    Tool(
+        name="read_file",
+        description=(
+            "Read the contents of a file from the workspace. "
+            "Supports optional line range selection."
+        ),
+        input_schema=_READ_FILE_SCHEMA,
+    ),
+    Tool(
+        name="list_files",
+        description=(
+            "List files in the workspace directory. "
+            "Respects standard ignore rules. Returns file paths with sizes."
+        ),
+        input_schema=_LIST_FILES_SCHEMA,
+    ),
+    Tool(
+        name="search_codebase",
+        description=(
+            "Search for a regex pattern across the codebase. "
+            "Returns matching lines with file paths and line numbers."
+        ),
+        input_schema=_SEARCH_CODEBASE_SCHEMA,
+    ),
+]
+
+_TOOLS_FOR_API: list[dict] = [
+    {
+        "name": t.name,
+        "description": t.description,
+        "input_schema": t.input_schema,
+    }
+    for t in STREAMING_SAFE_TOOLS
+]
+
+
+# ---------------------------------------------------------------------------
+# Adapter
+# ---------------------------------------------------------------------------
+
+
+class StreamingChatAdapter:
+    """Async streaming adapter over any :class:`LLMProvider` with ``async_stream()``.
+
+    Each call to :meth:`send_message` is a single conversational turn.
+    History is loaded from the DB at call time and persisted after the turn
+    completes.
+
+    Only read-only tools (read_file, list_files, search_codebase) are exposed
+    to the model. Write operations and shell execution are intentionally
+    excluded from interactive sessions.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        db_repo,
+        workspace_path: Path,
+        model: str = _DEFAULT_MODEL,
+        api_key: Optional[str] = None,
+        provider: Optional[LLMProvider] = None,
+    ) -> None:
+        """Initialise the adapter.
+
+        Args:
+            session_id: ID of the interactive session (used for DB access).
+            db_repo: ``InteractiveSessionRepository`` instance.
+            workspace_path: Absolute path used to scope file-system tool calls.
+            model: Model identifier passed to the provider's ``async_stream()``.
+            api_key: API key used when constructing the default
+                ``AnthropicProvider`` (when ``provider`` is ``None``).
+            provider: LLM provider to use for streaming.  When ``None``,
+                an ``AnthropicProvider`` is constructed automatically using
+                ``api_key`` or the ``ANTHROPIC_API_KEY`` environment variable.
+
+        Raises:
+            ValueError: If no provider is given and no Anthropic API key is
+                available.
+        """
+        if provider is None:
+            # Backward-compatibility fallback: callers that haven't been
+            # updated to pass an explicit provider (e.g. tests using the old
+            # api_key= constructor argument) still get an AnthropicProvider.
+            # New callers should construct the provider themselves and pass it
+            # in — see session_chat_ws.py for the recommended pattern.
+            from codeframe.adapters.llm.anthropic import AnthropicProvider
+            provider = AnthropicProvider(api_key=api_key)
+
+        self._session_id = session_id
+        self._db_repo = db_repo
+        self._workspace_path = workspace_path
+        self._model = model
+        self._provider = provider
+
+    # ------------------------------------------------------------------
+    # History helpers
+    # ------------------------------------------------------------------
+
+    def _load_history(self) -> list[dict]:
+        """Load conversation history from the DB for this session.
+
+        Returns:
+            List of ``{"role": str, "content": str}`` dicts in chronological order.
+        """
+        rows = self._db_repo.get_messages(self._session_id)
+        return [{"role": r["role"], "content": r["content"]} for r in rows]
+
+    def _truncate_history(self, messages: list[dict]) -> list[dict]:
+        """Drop oldest messages when the history exceeds the token budget.
+
+        Uses tiktoken for counting. If tiktoken is unavailable (e.g., in CI),
+        falls back to a character-based estimate (4 chars ≈ 1 token).
+
+        Args:
+            messages: Full message list (oldest first).
+
+        Returns:
+            Trimmed message list that fits within ``_MAX_HISTORY_TOKENS``.
+        """
+        try:
+            import tiktoken
+            enc = tiktoken.get_encoding("cl100k_base")
+
+            def _count(msgs: list[dict]) -> int:
+                return sum(
+                    len(enc.encode(m.get("content") or ""))
+                    for m in msgs
+                )
+        except Exception:
+            def _count(msgs: list[dict]) -> int:
+                return sum(len(m.get("content") or "") // 4 for m in msgs)
+
+        while messages and _count(messages) > _MAX_HISTORY_TOKENS:
+            # Drop in pairs so we don't strand an assistant message at index 0
+            messages = messages[2:] if len(messages) >= 2 else messages[1:]
+
+        # First message must have role "user"
+        while messages and messages[0].get("role") != "user":
+            messages = messages[1:]
+
+        return messages
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    async def _persist_turn(self, user_content: str, assistant_content: str) -> None:
+        """Persist user message and assistant response to session_messages.
+
+        Args:
+            user_content: The user's message text.
+            assistant_content: The complete assistant response accumulated
+                across all TEXT_DELTA events in this turn.
+        """
+        await asyncio.to_thread(
+            self._db_repo.add_message,
+            session_id=self._session_id,
+            role="user",
+            content=user_content,
+        )
+        await asyncio.to_thread(
+            self._db_repo.add_message,
+            session_id=self._session_id,
+            role="assistant",
+            content=assistant_content,
+        )
+
+    # ------------------------------------------------------------------
+    # Tool execution
+    # ------------------------------------------------------------------
+
+    async def _execute_tool(self, tool_call: ToolCall) -> str:
+        """Execute a safe tool call in a thread pool and return the result string.
+
+        Only tools in ``STREAMING_SAFE_TOOLS`` are permitted. Any attempt to
+        call an unlisted tool returns an error string.
+
+        Args:
+            tool_call: The tool call object from the LLM.
+
+        Returns:
+            String result of the tool execution (may start with "Error:" on
+            failure — the caller should still include it as a tool result so
+            the model can react).
+        """
+        allowed = {t.name for t in STREAMING_SAFE_TOOLS}
+        if tool_call.name not in allowed:
+            return f"Error: tool '{tool_call.name}' is not available in interactive sessions."
+
+        result: ToolResult = await asyncio.to_thread(
+            execute_tool, tool_call, self._workspace_path
+        )
+        return result.content
+
+    # ------------------------------------------------------------------
+    # Main streaming entry point
+    # ------------------------------------------------------------------
+
+    async def send_message(
+        self,
+        content: str,
+        history: list[dict],
+        interrupt_event: Optional[asyncio.Event] = None,
+    ) -> AsyncIterator[ChatEvent]:
+        """Stream a single conversational turn.
+
+        Yields ``ChatEvent`` objects as the model generates.  The caller is
+        responsible for forwarding these to the WebSocket client.
+
+        The method loops internally to handle tool calls (tool_use → tool_result
+        → re-enter stream) until ``stop_reason == "end_turn"`` or the interrupt
+        fires.
+
+        Args:
+            content: The user's message for this turn.
+            history: Prior messages to include as context.  If empty, history
+                is loaded from the DB automatically.
+            interrupt_event: Optional event; when set the stream stops within
+                the current chunk iteration.
+
+        Yields:
+            ``ChatEvent`` with types from ``ChatEventType``.
+        """
+        # Load history from DB if caller didn't supply it
+        if not history:
+            history = self._load_history()
+
+        # Build the message list for this turn
+        messages: list[dict] = list(history) + [{"role": "user", "content": content}]
+        messages = self._truncate_history(messages)
+
+        accumulated_text = ""
+
+        try:
+            async for event in self._stream_turn(
+                messages=messages,
+                interrupt_event=interrupt_event,
+            ):
+                if event.type == ChatEventType.TEXT_DELTA and event.content:
+                    accumulated_text += event.content
+                yield event
+
+        except Exception as exc:
+            logger.error("StreamingChatAdapter error: %s", exc, exc_info=True)
+            yield ChatEvent(type=ChatEventType.ERROR, content=str(exc))
+            return
+
+        # Persist the turn (errors are logged, not raised)
+        try:
+            await self._persist_turn(content, accumulated_text)
+        except Exception as exc:
+            logger.error("StreamingChatAdapter persistence error: %s", exc)
+
+    async def _stream_turn(
+        self,
+        messages: list[dict],
+        interrupt_event: Optional[asyncio.Event],
+    ) -> AsyncIterator[ChatEvent]:
+        """Execute one API turn, handling tool loops internally.
+
+        Yields ``ChatEvent`` objects for all events in the turn, including
+        any tool sub-turns.
+        """
+        current_messages = list(messages)
+
+        system_prompt = (
+            "You are a CodeFrame assistant helping the user understand and navigate "
+            "their codebase. You have read-only access to the current workspace. "
+            "Available tools: read_file, list_files, search_codebase. "
+            "Do not attempt to modify files or execute shell commands."
+        )
+
+        use_extended_thinking = self._provider.supports("extended_thinking")
+
+        while True:
+            pending_tool_calls: list[dict] = []  # {id, name, input}
+            stop_reason = "end_turn"
+
+            async for chunk in self._provider.async_stream(
+                messages=current_messages,
+                system=system_prompt,
+                tools=_TOOLS_FOR_API,
+                model=self._model,
+                max_tokens=4096,
+                interrupt_event=interrupt_event,
+                extended_thinking=use_extended_thinking,
+            ):
+                if interrupt_event and interrupt_event.is_set():
+                    return
+
+                if chunk.type == "text_delta":
+                    yield ChatEvent(type=ChatEventType.TEXT_DELTA, content=chunk.text)
+
+                elif chunk.type == "thinking_delta":
+                    yield ChatEvent(type=ChatEventType.THINKING, content=chunk.text)
+
+                elif chunk.type == "tool_use_start":
+                    pending_tool_calls.append({
+                        "id": chunk.tool_id,
+                        "name": chunk.tool_name,
+                        "input": chunk.tool_input or {},
+                    })
+                    yield ChatEvent(
+                        type=ChatEventType.TOOL_USE_START,
+                        tool_name=chunk.tool_name,
+                        tool_input=chunk.tool_input or {},
+                    )
+
+                elif chunk.type == "message_stop":
+                    stop_reason = chunk.stop_reason or "end_turn"
+
+                    # Back-fill tool inputs from final message (more reliable)
+                    if chunk.tool_inputs_by_id and pending_tool_calls:
+                        for tc in pending_tool_calls:
+                            if tc["id"] in chunk.tool_inputs_by_id:
+                                tc["input"] = chunk.tool_inputs_by_id[tc["id"]]
+
+                    yield ChatEvent(
+                        type=ChatEventType.COST_UPDATE,
+                        input_tokens=chunk.input_tokens,
+                        output_tokens=chunk.output_tokens,
+                        cost_usd=_estimate_cost(
+                            chunk.input_tokens or 0,
+                            chunk.output_tokens or 0,
+                            self._model,
+                        ),
+                    )
+
+                # tool_use_stop is informational only — no ChatEvent needed
+
+            if stop_reason == "end_turn" or not pending_tool_calls:
+                yield ChatEvent(type=ChatEventType.DONE)
+                return
+
+            # Execute pending tool calls and loop for another API turn
+            tool_result_blocks = []
+            for tc in pending_tool_calls:
+                if interrupt_event and interrupt_event.is_set():
+                    yield ChatEvent(type=ChatEventType.DONE)
+                    return
+
+                tool_call = ToolCall(
+                    id=tc["id"],
+                    name=tc["name"],
+                    input=tc.get("input") or {},
+                )
+                result_text = await self._execute_tool(tool_call)
+
+                yield ChatEvent(
+                    type=ChatEventType.TOOL_RESULT,
+                    tool_name=tc["name"],
+                    content=result_text,
+                )
+
+                tool_result_blocks.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tc["id"],
+                        "content": result_text,
+                    }
+                )
+
+            # Append the tool results as a user message for the next turn
+            current_messages = current_messages + [
+                {"role": "user", "content": tool_result_blocks}
+            ]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _estimate_cost(input_tokens: int, output_tokens: int, model: str) -> float:
+    """Rough cost estimate in USD.
+
+    Uses approximate pricing for claude-sonnet-4. Returns 0.0 for unknown models
+    rather than raising — cost tracking is best-effort.
+    """
+    # Per-million-token pricing (input, output) in USD.
+    # Last verified: 2026-03-31. Anthropic pricing changes without notice —
+    # treat these as best-effort estimates, not billing-accurate figures.
+    _PRICING: dict[str, tuple[float, float]] = {
+        "claude-sonnet-4-20250514": (3.0, 15.0),
+        "claude-opus-4-20250514": (15.0, 75.0),
+        "claude-3-5-haiku-20241022": (0.8, 4.0),
+    }
+    # Match by prefix to handle minor model variant suffixes
+    for prefix, (in_price, out_price) in _PRICING.items():
+        if model.startswith(prefix):
+            return (input_tokens * in_price + output_tokens * out_price) / 1_000_000
+    return 0.0

codeframe/core/adapters/subprocess_adapter.py

@@ -0,0 +1,213 @@
+"""Base subprocess adapter for external coding agents."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import threading
+from pathlib import Path
+from typing import Callable
+
+from codeframe.core.adapters.agent_adapter import AgentEvent, AgentResult
+from codeframe.core.adapters.git_utils import detect_modified_files
+from codeframe.core.blocker_detection import classify_error_for_blocker
+
+
+class SubprocessAdapter:
+    """Base adapter for coding agents invoked as subprocesses.
+
+    Provides shared infrastructure: binary availability check, subprocess
+    execution with stdout streaming, and exit code to AgentResult mapping.
+
+    Subclasses override build_command() to customize CLI invocation.
+    """
+
+    # Default timeout: 30 minutes (coding agents can be long-running)
+    DEFAULT_TIMEOUT_S = 1800
+
+    def __init__(
+        self,
+        binary: str,
+        cli_args: list[str] | None = None,
+        timeout_s: int | None = None,
+    ) -> None:
+        """Initialize with the binary name and default CLI args.
+
+        Args:
+            binary: Name of the CLI binary (e.g., 'claude', 'opencode')
+            cli_args: Default CLI arguments appended to every invocation
+            timeout_s: Max execution time in seconds (default: 1800, None = no limit)
+
+        Raises:
+            EnvironmentError: If the binary is not found on PATH
+        """
+        self._binary = binary
+        self._cli_args = cli_args or []
+        self._timeout_s = timeout_s if timeout_s is not None else self.DEFAULT_TIMEOUT_S
+
+        resolved = shutil.which(binary)
+        if resolved is None:
+            raise EnvironmentError(
+                f"'{binary}' not found on PATH. "
+                f"Install it or ensure it is available in your environment."
+            )
+        self._binary_path = resolved
+
+    @property
+    def name(self) -> str:
+        """Engine name derived from the binary."""
+        return self._binary
+
+    def build_command(self, prompt: str, workspace_path: Path) -> list[str]:
+        """Build the subprocess command list.
+
+        Override in subclasses for custom CLI invocation.
+        Default: [binary, *cli_args] with prompt on stdin.
+
+        Args:
+            prompt: The task prompt to send to the agent
+            workspace_path: Path to the workspace root
+
+        Returns:
+            Command list for subprocess.Popen
+        """
+        return [self._binary_path, *self._cli_args]
+
+    def get_stdin(self, prompt: str) -> str | None:
+        """Return stdin content for the subprocess, or None to not pipe stdin.
+
+        Override in subclasses if the agent reads prompt from a file instead.
+        Default: returns the prompt string (piped via stdin).
+        """
+        return prompt
+
+    def run(
+        self,
+        task_id: str,
+        prompt: str,
+        workspace_path: Path,
+        on_event: Callable[[AgentEvent], None] | None = None,
+    ) -> AgentResult:
+        """Execute the agent subprocess and return the result."""
+        cmd = self.build_command(prompt, workspace_path)
+        stdin_content = self.get_stdin(prompt)
+
+        stdout_lines: list[str] = []
+        stderr_chunks: list[str] = []
+
+        try:
+            process = subprocess.Popen(
+                cmd,
+                stdin=subprocess.PIPE if stdin_content else None,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                cwd=str(workspace_path),
+                text=True,
+            )
+
+            # Write stdin and close
+            if stdin_content and process.stdin:
+                process.stdin.write(stdin_content)
+                process.stdin.close()
+
+            # Drain stderr in a background thread to prevent deadlock.
+            # Without this, if the child fills the stderr pipe buffer (~64KB)
+            # before finishing stdout, both processes block indefinitely.
+            def _drain_stderr() -> None:
+                if process.stderr:
+                    stderr_chunks.append(process.stderr.read())
+
+            stderr_thread = threading.Thread(target=_drain_stderr, daemon=True)
+            stderr_thread.start()
+
+            # Stream stdout line-by-line
+            if process.stdout:
+                for line in process.stdout:
+                    stripped = line.rstrip("\n")
+                    stdout_lines.append(stripped)
+                    if on_event:
+                        on_event(AgentEvent(type="output", data={"line": stripped}))
+
+            # Wait for stderr thread and process to finish
+            stderr_thread.join(timeout=10)
+            try:
+                process.wait(timeout=self._timeout_s)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+                return AgentResult(
+                    status="failed",
+                    output="\n".join(stdout_lines),
+                    error=f"Process timed out after {self._timeout_s}s",
+                )
+
+        except FileNotFoundError:
+            return AgentResult(
+                status="failed",
+                error=f"Binary '{self._binary}' not found during execution",
+            )
+        except OSError as e:
+            return AgentResult(
+                status="failed",
+                error=f"Failed to start '{self._binary}': {e}",
+            )
+
+        stderr_output = "".join(stderr_chunks)
+
+        modified_files = self._detect_modified_files(workspace_path)
+
+        result = self._map_result(
+            exit_code=process.returncode,
+            stdout="\n".join(stdout_lines),
+            stderr=stderr_output,
+            workspace_path=workspace_path,
+        )
+        result.modified_files = modified_files
+        return result
+
+    def _map_result(
+        self,
+        exit_code: int,
+        stdout: str,
+        stderr: str,
+        workspace_path: Path,
+    ) -> AgentResult:
+        """Map subprocess exit code and output to AgentResult.
+
+        Override in subclasses for custom exit code interpretation.
+        Default: 0 = completed, non-zero = failed.
+        Uses blocker_detection.classify_error_for_blocker for blocker detection.
+        """
+        if exit_code == 0:
+            return AgentResult(
+                status="completed",
+                output=stdout,
+            )
+
+        # Check if the error looks like a blocker using the shared classifier
+        combined_output = f"{stdout}\n{stderr}".strip()
+        category = classify_error_for_blocker(combined_output)
+        if category is not None:
+            return AgentResult(
+                status="blocked",
+                output=stdout,
+                error=stderr or None,
+                blocker_question=self._extract_blocker_question(combined_output),
+            )
+
+        return AgentResult(
+            status="failed",
+            output=stdout,
+            error=stderr or f"Process exited with code {exit_code}",
+        )
+
+    def _detect_modified_files(self, workspace_path: Path) -> list[str]:
+        """Detect files modified by the subprocess via git diff."""
+        return detect_modified_files(workspace_path)
+
+    def _extract_blocker_question(self, output: str) -> str:
+        """Extract a meaningful blocker question from output."""
+        lines = [line.strip() for line in output.splitlines() if line.strip()]
+        if lines:
+            return lines[-1]
+        return "Agent encountered a blocker but no details were provided."