devcopilot 0.2.0__py3-none-any.whl

api/app.py

@@ -0,0 +1,194 @@
+"""FastAPI application factory and configuration."""
+
+import os
+import traceback
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exception_handlers import request_validation_exception_handler
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from loguru import logger
+from starlette.types import Receive, Scope, Send
+
+from config.logging_config import configure_logging
+from config.paths import server_log_path
+from config.settings import get_settings
+from core.trace import extract_claude_session_id_from_headers, trace_event
+from providers.exceptions import ProviderError
+
+from .admin_routes import router as admin_router
+from .routes import router
+from .runtime import AppRuntime, startup_failure_message
+from .validation_log import summarize_request_validation_body
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager."""
+    runtime = AppRuntime.for_app(app, settings=get_settings())
+    await runtime.startup()
+
+    yield
+
+    await runtime.shutdown()
+
+
+class GracefulLifespanApp:
+    """ASGI wrapper that reports startup failures without Starlette tracebacks."""
+
+    def __init__(self, app: FastAPI):
+        self.app = app
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.app, name)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "lifespan":
+            await self.app(scope, receive, send)
+            return
+        await self._lifespan(receive, send)
+
+    async def _lifespan(self, receive: Receive, send: Send) -> None:
+        settings = get_settings()
+        runtime = AppRuntime.for_app(self.app, settings=settings)
+        startup_complete = False
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                try:
+                    await runtime.startup()
+                except Exception as exc:
+                    await send(
+                        {
+                            "type": "lifespan.startup.failed",
+                            "message": startup_failure_message(settings, exc),
+                        }
+                    )
+                    return
+                startup_complete = True
+                await send({"type": "lifespan.startup.complete"})
+                continue
+
+            if message["type"] == "lifespan.shutdown":
+                if startup_complete:
+                    try:
+                        await runtime.shutdown()
+                    except Exception as exc:
+                        logger.error("Shutdown failed: exc_type={}", type(exc).__name__)
+                        await send({"type": "lifespan.shutdown.failed", "message": ""})
+                        return
+                await send({"type": "lifespan.shutdown.complete"})
+                return
+
+
+def create_app(*, lifespan_enabled: bool = True) -> FastAPI:
+    """Create and configure the FastAPI application."""
+    settings = get_settings()
+    log_path = Path(os.getenv("LOG_FILE", server_log_path()))
+    configure_logging(log_path, verbose_third_party=settings.log_raw_api_payloads)
+
+    app_kwargs: dict[str, Any] = {
+        "title": "Claude Code Proxy",
+        "version": "2.1.0",
+    }
+    if lifespan_enabled:
+        app_kwargs["lifespan"] = lifespan
+    app = FastAPI(**app_kwargs)
+
+    @app.middleware("http")
+    async def trace_http_correlation(request: Request, call_next):
+        """Attach HTTP identifiers and optional Claude session id to logs."""
+        claude_sid = extract_claude_session_id_from_headers(request.headers)
+        with logger.contextualize(
+            http_method=request.method,
+            http_path=request.url.path,
+            claude_session_id=claude_sid,
+        ):
+            response = await call_next(request)
+        return response
+
+    # Register routes
+    app.include_router(admin_router)
+    app.include_router(router)
+
+    # Exception handlers
+    @app.exception_handler(RequestValidationError)
+    async def validation_error_handler(request: Request, exc: RequestValidationError):
+        """Log request shape for 422 debugging without content values."""
+        body: Any
+        try:
+            body = await request.json()
+        except Exception as e:
+            body = {"_json_error": type(e).__name__}
+
+        message_summary, tool_names = summarize_request_validation_body(body)
+
+        trace_event(
+            stage="ingress",
+            event="server.request.validation_failed",
+            source="api",
+            path=request.url.path,
+            query=dict(request.query_params),
+            error_locs=[list(error.get("loc", ())) for error in exc.errors()],
+            error_types=[str(error.get("type", "")) for error in exc.errors()],
+            message_summary=message_summary,
+            tool_names=tool_names,
+        )
+        return await request_validation_exception_handler(request, exc)
+
+    @app.exception_handler(ProviderError)
+    async def provider_error_handler(request: Request, exc: ProviderError):
+        """Handle provider-specific errors and return Anthropic format."""
+        err_settings = get_settings()
+        if err_settings.log_api_error_tracebacks:
+            logger.error(
+                "Provider Error: error_type={} status_code={} message={}",
+                exc.error_type,
+                exc.status_code,
+                exc.message,
+            )
+        else:
+            logger.error(
+                "Provider Error: error_type={} status_code={}",
+                exc.error_type,
+                exc.status_code,
+            )
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=exc.to_anthropic_format(),
+        )
+
+    @app.exception_handler(Exception)
+    async def general_error_handler(request: Request, exc: Exception):
+        """Handle general errors and return Anthropic format."""
+        settings = get_settings()
+        if settings.log_api_error_tracebacks:
+            logger.error("General Error: {}", exc)
+            logger.error(traceback.format_exc())
+        else:
+            logger.error(
+                "General Error: path={} method={} exc_type={}",
+                request.url.path,
+                request.method,
+                type(exc).__name__,
+            )
+        return JSONResponse(
+            status_code=500,
+            content={
+                "type": "error",
+                "error": {
+                    "type": "api_error",
+                    "message": "An unexpected error occurred.",
+                },
+            },
+        )
+
+    return app
+
+
+def create_asgi_app() -> GracefulLifespanApp:
+    """Create the server ASGI app with graceful lifespan failure reporting."""
+    return GracefulLifespanApp(create_app(lifespan_enabled=False))

api/command_utils.py

@@ -0,0 +1,164 @@
+"""Command parsing utilities for API optimizations."""
+
+import re
+import shlex
+
+_ENV_ASSIGNMENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=.*$")
+
+
+def _is_env_assignment(part: str) -> bool:
+    """Return True when a token is a shell-style env assignment."""
+    return bool(_ENV_ASSIGNMENT_RE.match(part))
+
+
+def _strip_env_assignments(parts: list[str]) -> list[str]:
+    """Return command parts after leading shell-style env assignments."""
+    cmd_start = 0
+    for i, part in enumerate(parts):
+        if _is_env_assignment(part):
+            cmd_start = i + 1
+        else:
+            break
+    return parts[cmd_start:]
+
+
+def extract_command_prefix(command: str) -> str:
+    """Extract the command prefix for fast prefix detection.
+
+    Parses a shell command safely, handling environment variables and
+    command injection attempts. Returns the command prefix suitable
+    for quick identification.
+
+    Returns:
+        Command prefix (e.g., "git", "git commit", "npm install")
+        or "none" if no valid command found
+    """
+    if "`" in command or "$(" in command:
+        return "command_injection_detected"
+
+    try:
+        parts = shlex.split(command, posix=False)
+        if not parts:
+            return "none"
+
+        env_prefix = []
+        cmd_start = 0
+        for i, part in enumerate(parts):
+            if _is_env_assignment(part):
+                env_prefix.append(part)
+                cmd_start = i + 1
+            else:
+                break
+
+        if cmd_start >= len(parts):
+            return "none"
+
+        cmd_parts = parts[cmd_start:]
+        if not cmd_parts:
+            return "none"
+
+        first_word = cmd_parts[0]
+        two_word_commands = {
+            "git",
+            "npm",
+            "docker",
+            "kubectl",
+            "cargo",
+            "go",
+            "pip",
+            "yarn",
+        }
+
+        if first_word in two_word_commands and len(cmd_parts) > 1:
+            second_word = cmd_parts[1]
+            if not second_word.startswith("-"):
+                return f"{first_word} {second_word}"
+            return first_word
+        return first_word if not env_prefix else " ".join(env_prefix) + " " + first_word
+
+    except ValueError:
+        parts = command.split()
+        if not parts:
+            return "none"
+        cmd_parts = _strip_env_assignments(parts)
+        return cmd_parts[0] if cmd_parts else "none"
+
+
+def extract_filepaths_from_command(command: str, output: str) -> str:
+    """Extract file paths from a command locally without API call.
+
+    Determines if the command reads file contents and extracts paths accordingly.
+    Commands like ls/dir/find just list files, so return empty.
+    Commands like cat/head/tail actually read contents, so extract the file path.
+
+    Returns:
+        Filepath extraction result in <filepaths> format
+    """
+    listing_commands = {
+        "ls",
+        "dir",
+        "find",
+        "tree",
+        "pwd",
+        "cd",
+        "mkdir",
+        "rmdir",
+        "rm",
+    }
+
+    reading_commands = {"cat", "head", "tail", "less", "more", "bat", "type"}
+
+    try:
+        parts = shlex.split(command, posix=False)
+        if not parts:
+            return "<filepaths>\n</filepaths>"
+
+        cmd_parts = _strip_env_assignments(parts)
+        if not cmd_parts:
+            return "<filepaths>\n</filepaths>"
+
+        base_cmd = cmd_parts[0].split("/")[-1].split("\\")[-1].lower()
+
+        if base_cmd in listing_commands:
+            return "<filepaths>\n</filepaths>"
+
+        if base_cmd in reading_commands:
+            filepaths = []
+            for part in cmd_parts[1:]:
+                if part.startswith("-"):
+                    continue
+                filepaths.append(part)
+
+            if filepaths:
+                paths_str = "\n".join(filepaths)
+                return f"<filepaths>\n{paths_str}\n</filepaths>"
+            return "<filepaths>\n</filepaths>"
+
+        if base_cmd == "grep":
+            flags_with_args = {"-e", "-f", "-m", "-A", "-B", "-C"}
+            pattern_provided_via_flag = False
+            positional = []
+
+            skip_next = False
+            for part in cmd_parts[1:]:
+                if skip_next:
+                    skip_next = False
+                    continue
+                if part.startswith("-"):
+                    if part in flags_with_args:
+                        if part in {"-e", "-f"}:
+                            pattern_provided_via_flag = True
+                        skip_next = True
+                    continue
+                positional.append(part)
+
+            filepaths = positional if pattern_provided_via_flag else positional[1:]
+            if filepaths:
+                paths_str = "\n".join(filepaths)
+                return f"<filepaths>\n{paths_str}\n</filepaths>"
+            return "<filepaths>\n</filepaths>"
+
+        return "<filepaths>\n</filepaths>"
+
+    except ValueError:
+        return "<filepaths>\n</filepaths>"

api/dependencies.py

@@ -0,0 +1,144 @@
+"""Dependency injection for FastAPI."""
+
+import secrets
+
+from fastapi import Depends, HTTPException, Request
+from loguru import logger
+from starlette.applications import Starlette
+
+from config.settings import Settings
+from config.settings import get_settings as _get_settings
+from core.anthropic import get_user_facing_error_message
+from providers.base import BaseProvider
+from providers.exceptions import (
+    AuthenticationError,
+    ServiceUnavailableError,
+    UnknownProviderTypeError,
+)
+from providers.registry import PROVIDER_DESCRIPTORS, ProviderRegistry
+
+# Process-level cache: only for :func:`get_provider_for_type` / :func:`get_provider`
+# when there is no ``Request``/``app`` (unit tests, scripts). HTTP handlers must pass
+# ``app`` to :func:`resolve_provider` so the app-scoped registry is used.
+_providers: dict[str, BaseProvider] = {}
+
+
+def get_settings() -> Settings:
+    """Return cached :class:`~config.settings.Settings` (FastAPI-friendly alias)."""
+    return _get_settings()
+
+
+def resolve_provider(
+    provider_type: str,
+    *,
+    app: Starlette | None,
+    settings: Settings,
+) -> BaseProvider:
+    """Resolve a provider using the app-scoped registry when ``app`` is set.
+
+    When ``app`` is not ``None``, the app-owned :attr:`app.state.provider_registry`
+    must exist (installed by :class:`~api.runtime.AppRuntime` during startup).
+    Callers that construct a bare ``FastAPI`` without lifespan must set
+    ``app.state.provider_registry`` explicitly.
+
+    When ``app`` is ``None`` (no HTTP context), uses the process-level
+    :data:`_providers` cache only.
+    """
+    if app is not None:
+        reg = getattr(app.state, "provider_registry", None)
+        if reg is None:
+            raise ServiceUnavailableError(
+                "Provider registry is not configured. Ensure AppRuntime startup ran "
+                "or assign app.state.provider_registry for test apps."
+            )
+        return _resolve_with_registry(reg, provider_type, settings)
+    return _resolve_with_registry(ProviderRegistry(_providers), provider_type, settings)
+
+
+def _resolve_with_registry(
+    registry: ProviderRegistry, provider_type: str, settings: Settings
+) -> BaseProvider:
+    should_log_init = not registry.is_cached(provider_type)
+    try:
+        provider = registry.get(provider_type, settings)
+    except AuthenticationError as e:
+        # Provider :class:`~providers.exceptions.AuthenticationError` messages are
+        # curated configuration hints (env var names, docs links), not upstream noise.
+        detail = str(e).strip() or get_user_facing_error_message(e)
+        raise HTTPException(status_code=503, detail=detail) from e
+    except UnknownProviderTypeError:
+        logger.error(
+            "Unknown provider_type: '{}'. Supported: {}",
+            provider_type,
+            ", ".join(f"'{key}'" for key in PROVIDER_DESCRIPTORS),
+        )
+        raise
+    if should_log_init:
+        logger.info("Provider initialized: {}", provider_type)
+    return provider
+
+
+def get_provider_for_type(provider_type: str) -> BaseProvider:
+    """Get or create a provider in the process-level cache (no ``app``/Request).
+
+    HTTP route handlers should call :func:`resolve_provider` with the active
+    :attr:`request.app` (via :class:`~api.runtime.AppRuntime`) instead of this
+    process-wide cache.
+    """
+    return resolve_provider(provider_type, app=None, settings=get_settings())
+
+
+def require_api_key(
+    request: Request, settings: Settings = Depends(get_settings)
+) -> None:
+    """Require a server API key (Anthropic-style).
+
+    Checks `x-api-key` header or `Authorization: Bearer ...` against
+    `Settings.anthropic_auth_token`. If `ANTHROPIC_AUTH_TOKEN` is empty, this is a no-op.
+    """
+    anthropic_auth_token = settings.anthropic_auth_token.strip()
+    if not anthropic_auth_token:
+        # No API key configured -> allow
+        return
+
+    header = (
+        request.headers.get("x-api-key")
+        or request.headers.get("authorization")
+        or request.headers.get("anthropic-auth-token")
+    )
+    if not header:
+        raise HTTPException(status_code=401, detail="Missing API key")
+
+    # Support both raw key in X-API-Key and Bearer token in Authorization
+    token = header.strip()
+    if header.lower().startswith("bearer "):
+        token = header.split(" ", 1)[1].strip()
+
+    # Strip anything after the first colon to handle tokens with appended model names
+    if token and ":" in token:
+        token = token.split(":", 1)[0].strip()
+
+    # Constant-time comparison to avoid leaking the configured token via
+    # response-time differences on a per-byte mismatch (CWE-208).
+    if not secrets.compare_digest(
+        token.encode("utf-8"), anthropic_auth_token.encode("utf-8")
+    ):
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+
+def get_provider() -> BaseProvider:
+    """Get or create the default provider (``MODEL`` / ``provider_type``).
+
+    Process-cache helper for scripts, unit tests, and non-FastAPI callers. HTTP
+    handlers must use :func:`resolve_provider` with :attr:`request.app` so the
+    app-scoped :class:`~providers.registry.ProviderRegistry` is used.
+    """
+    return get_provider_for_type(get_settings().provider_type)
+
+
+async def cleanup_provider():
+    """Cleanup all provider resources."""
+    global _providers
+    await ProviderRegistry(_providers).cleanup()
+    _providers = {}
+    logger.debug("Provider cleanup completed")

api/detection.py

@@ -0,0 +1,152 @@
+"""Request detection utilities for API optimizations.
+
+Detects quota checks, title generation, prefix detection, safety classifier,
+suggestion mode, and filepath extraction requests to enable targeted handling.
+"""
+
+from core.anthropic import extract_text_from_content
+
+from .models.anthropic import MessagesRequest
+
+
+def is_quota_check_request(request_data: MessagesRequest) -> bool:
+    """Check if this is a quota probe request.
+
+    Quota checks are typically simple requests with max_tokens=1
+    and a single message containing the word "quota".
+    """
+    if (
+        request_data.max_tokens == 1
+        and len(request_data.messages) == 1
+        and request_data.messages[0].role == "user"
+    ):
+        text = extract_text_from_content(request_data.messages[0].content)
+        if "quota" in text.lower():
+            return True
+    return False
+
+
+def is_title_generation_request(request_data: MessagesRequest) -> bool:
+    """Check if this is a conversation title generation request.
+
+    Title generation requests are detected by a system prompt containing
+    title extraction instructions, no tools, and a single user message.
+
+    Matches Claude Code session title prompts (sentence-case title, JSON
+    \"title\" field, etc.).
+    """
+    if not request_data.system or request_data.tools:
+        return False
+    system_text = extract_text_from_content(request_data.system).lower()
+    if "title" not in system_text:
+        return False
+    return "sentence-case title" in system_text or (
+        "return json" in system_text
+        and "field" in system_text
+        and ("coding session" in system_text or "this session" in system_text)
+    )
+
+
+def is_prefix_detection_request(request_data: MessagesRequest) -> tuple[bool, str]:
+    """Check if this is a fast prefix detection request.
+
+    Prefix detection requests contain a policy_spec block and
+    a Command: section for extracting shell command prefixes.
+
+    Returns:
+        Tuple of (is_prefix_request, command_string)
+    """
+    if len(request_data.messages) != 1 or request_data.messages[0].role != "user":
+        return False, ""
+
+    content = extract_text_from_content(request_data.messages[0].content)
+
+    if "<policy_spec>" in content and "Command:" in content:
+        try:
+            cmd_start = content.rfind("Command:") + len("Command:")
+            return True, content[cmd_start:].strip()
+        except TypeError:
+            return False, ""
+
+    return False, ""
+
+
+def is_safety_classifier_request(request_data: MessagesRequest) -> bool:
+    """Return whether this is Claude Code's auto-mode safety classifier prompt."""
+    if request_data.tools:
+        return False
+
+    system_text = (
+        extract_text_from_content(request_data.system) if request_data.system else ""
+    )
+    messages_text = "".join(
+        extract_text_from_content(message.content) for message in request_data.messages
+    )
+    combined = f"{system_text}\n{messages_text}"
+    has_verdict_instruction = "yes</block>" in combined or "no</block>" in combined
+    return "<transcript>" in combined and has_verdict_instruction
+
+
+def is_suggestion_mode_request(request_data: MessagesRequest) -> bool:
+    """Check if this is a suggestion mode request.
+
+    Suggestion mode requests contain "[SUGGESTION MODE:" in the user's message,
+    used for auto-suggesting what the user might type next.
+    """
+    for msg in request_data.messages:
+        if msg.role == "user":
+            text = extract_text_from_content(msg.content)
+            if "[SUGGESTION MODE:" in text:
+                return True
+    return False
+
+
+def is_filepath_extraction_request(
+    request_data: MessagesRequest,
+) -> tuple[bool, str, str]:
+    """Check if this is a filepath extraction request.
+
+    Filepath extraction requests have a single user message with
+    "Command:" and "Output:" sections, asking to extract file paths
+    from command output.
+
+    Returns:
+        Tuple of (is_filepath_request, command, output)
+    """
+    if len(request_data.messages) != 1 or request_data.messages[0].role != "user":
+        return False, "", ""
+    if request_data.tools:
+        return False, "", ""
+
+    content = extract_text_from_content(request_data.messages[0].content)
+
+    if "Command:" not in content or "Output:" not in content:
+        return False, "", ""
+
+    # Match if user content OR system block indicates filepath extraction
+    user_has_filepaths = (
+        "filepaths" in content.lower() or "<filepaths>" in content.lower()
+    )
+    system_text = (
+        extract_text_from_content(request_data.system) if request_data.system else ""
+    )
+    system_has_extract = (
+        "extract any file paths" in system_text.lower()
+        or "file paths that this command" in system_text.lower()
+    )
+    if not user_has_filepaths and not system_has_extract:
+        return False, "", ""
+
+    cmd_start = content.find("Command:") + len("Command:")
+    output_marker = content.find("Output:", cmd_start)
+    if output_marker == -1:
+        return False, "", ""
+
+    command = content[cmd_start:output_marker].strip()
+    output = content[output_marker + len("Output:") :].strip()
+
+    for marker in ["<", "\n\n"]:
+        if marker in output:
+            output = output.split(marker)[0].strip()
+
+    return True, command, output