ctrlcode 0.1.0__py3-none-any.whl

ctrlcode/paths.py

@@ -0,0 +1,68 @@
+"""Cross-platform path resolution for ctrl+code.
+
+Provides platform-aware directory paths following OS conventions:
+- Linux: XDG Base Directory Specification
+- macOS: ~/Library/Application Support and ~/Library/Caches
+- Windows: AppData directories
+
+Environment variable overrides:
+- CTRLCODE_CONFIG_DIR: Override config directory
+- CTRLCODE_DATA_DIR: Override data directory
+- CTRLCODE_CACHE_DIR: Override cache directory
+"""
+
+import os
+from pathlib import Path
+
+from platformdirs import user_cache_dir, user_config_dir, user_data_dir
+
+APP_NAME = "ctrlcode"
+APP_AUTHOR = "ctrlcode"  # Required for Windows paths
+
+
+def get_config_dir() -> Path:
+    """Get platform-specific config directory.
+
+    Returns:
+        Path to config directory (contains config.toml, skills/, etc.)
+
+    Platform defaults:
+        Linux:   ~/.config/ctrlcode/
+        macOS:   ~/Library/Application Support/ctrlcode/
+        Windows: %APPDATA%\\ctrlcode\\
+    """
+    if override := os.getenv("CTRLCODE_CONFIG_DIR"):
+        return Path(override).expanduser()
+    return Path(user_config_dir(APP_NAME, APP_AUTHOR))
+
+
+def get_data_dir() -> Path:
+    """Get platform-specific data directory.
+
+    Returns:
+        Path to data directory (contains sessions/, persistent data)
+
+    Platform defaults:
+        Linux:   ~/.local/share/ctrlcode/
+        macOS:   ~/Library/Application Support/ctrlcode/
+        Windows: %LOCALAPPDATA%\\ctrlcode\\
+    """
+    if override := os.getenv("CTRLCODE_DATA_DIR"):
+        return Path(override).expanduser()
+    return Path(user_data_dir(APP_NAME, APP_AUTHOR))
+
+
+def get_cache_dir() -> Path:
+    """Get platform-specific cache directory.
+
+    Returns:
+        Path to cache directory (contains conversations/, temp files)
+
+    Platform defaults:
+        Linux:   ~/.cache/ctrlcode/
+        macOS:   ~/Library/Caches/ctrlcode/
+        Windows: %LOCALAPPDATA%\\ctrlcode\\Cache\\
+    """
+    if override := os.getenv("CTRLCODE_CACHE_DIR"):
+        return Path(override).expanduser()
+    return Path(user_cache_dir(APP_NAME, APP_AUTHOR))

ctrlcode/permissions.py

@@ -0,0 +1,179 @@
+"""User permission system for file operations."""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Callable, Optional
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PermissionRequest:
+    """Request for user permission."""
+
+    operation: str  # "write_file", "read_file", etc.
+    path: str  # Path being accessed
+    reason: str  # Why permission is needed
+    details: Optional[dict] = None  # Additional context
+
+
+class PermissionManager:
+    """Manages user permissions for file operations."""
+
+    def __init__(self, approval_callback: Optional[Callable[[str, PermissionRequest], None]] = None):
+        """Initialize permission manager.
+
+        Args:
+            approval_callback: Async function to send permission request to TUI
+                             Called with (request_id, request)
+                             If None, all requests are auto-approved (dev mode)
+        """
+        self.approval_callback = approval_callback
+        self._approved_paths: set[str] = set()  # Paths approved this session
+        self._pending_requests: dict[str, asyncio.Future] = {}  # request_id -> Future[bool]
+
+    async def request_permission_async(
+        self,
+        operation: str,
+        path: str,
+        reason: str,
+        details: Optional[dict] = None,
+        remember: bool = False,
+        timeout: float = 60.0
+    ) -> bool:
+        """Request user permission for an operation (async).
+
+        Args:
+            operation: Operation name
+            path: File/directory path
+            reason: Human-readable reason
+            details: Additional context
+            remember: If True, remember approval for this path
+            timeout: Timeout in seconds (default 60)
+
+        Returns:
+            True if approved, False if denied
+        """
+        # Check if already approved this session
+        cache_key = f"{operation}:{path}"
+        if cache_key in self._approved_paths:
+            logger.debug(f"Permission cached for {operation} on {path}")
+            return True
+
+        # No callback = auto-approve (dev mode)
+        if not self.approval_callback:
+            logger.warning(f"Auto-approving {operation} on {path} (no callback)")
+            return True
+
+        # Create permission request
+        request = PermissionRequest(
+            operation=operation,
+            path=path,
+            reason=reason,
+            details=details
+        )
+
+        # Generate unique request ID
+        request_id = str(uuid4())
+
+        # Create future for response
+        future: asyncio.Future[bool] = asyncio.Future()
+        self._pending_requests[request_id] = future
+
+        try:
+            # Send request to TUI via callback
+            await self.approval_callback(request_id, request)
+
+            # Wait for response with timeout
+            approved = await asyncio.wait_for(future, timeout=timeout)
+
+            if approved and remember:
+                self._approved_paths.add(cache_key)
+                logger.info(f"Cached approval for {operation} on {path}")
+
+            return approved
+
+        except asyncio.TimeoutError:
+            logger.warning(f"Permission request timed out for {operation} on {path}")
+            return False  # Deny on timeout
+
+        except Exception as e:
+            logger.error(f"Permission request error: {e}")
+            return False  # Fail closed
+
+        finally:
+            # Clean up pending request
+            self._pending_requests.pop(request_id, None)
+
+    def handle_permission_response(self, request_id: str, approved: bool) -> None:
+        """Handle permission response from TUI.
+
+        Args:
+            request_id: Request ID
+            approved: Whether user approved
+        """
+        future = self._pending_requests.get(request_id)
+
+        if not future:
+            logger.warning(f"No pending request for ID {request_id}")
+            return
+
+        if future.done():
+            logger.warning(f"Request {request_id} already completed")
+            return
+
+        # Set result to unblock waiting task
+        future.set_result(approved)
+        logger.info(f"Permission {'approved' if approved else 'denied'} for request {request_id}")
+
+    def clear_cache(self):
+        """Clear all cached approvals."""
+        self._approved_paths.clear()
+
+
+# Global instance (set by server on init)
+_permission_manager: Optional[PermissionManager] = None
+
+
+def set_permission_manager(manager: PermissionManager):
+    """Set global permission manager."""
+    global _permission_manager
+    _permission_manager = manager
+
+
+def get_permission_manager() -> Optional[PermissionManager]:
+    """Get global permission manager."""
+    return _permission_manager
+
+
+async def request_permission(
+    operation: str,
+    path: str,
+    reason: str,
+    details: Optional[dict] = None,
+    remember: bool = False,
+    timeout: float = 60.0
+) -> bool:
+    """Request permission using global manager (async).
+
+    Args:
+        operation: Operation name
+        path: File/directory path
+        reason: Human-readable reason
+        details: Additional context
+        remember: Cache approval for session
+        timeout: Timeout in seconds
+
+    Returns:
+        True if approved, False if denied
+    """
+    manager = get_permission_manager()
+
+    if not manager:
+        # No manager = dev mode, auto-approve
+        logger.warning(f"No permission manager, auto-approving {operation} on {path}")
+        return True
+
+    return await manager.request_permission_async(operation, path, reason, details, remember, timeout)

ctrlcode/providers/__init__.py

@@ -0,0 +1,15 @@
+"""Provider implementations for ctrl-code."""
+
+from .base import Provider, StreamEvent
+from .anthropic import AnthropicProvider
+from .openai import OpenAIProvider
+from .parallel import ParallelExecutor, ProviderOutput
+
+__all__ = [
+    "Provider",
+    "StreamEvent",
+    "AnthropicProvider",
+    "OpenAIProvider",
+    "ParallelExecutor",
+    "ProviderOutput",
+]

ctrlcode/providers/anthropic.py

@@ -0,0 +1,138 @@
+"""Anthropic (Claude) provider implementation."""
+
+import logging
+from typing import Any, AsyncIterator
+from anthropic import AsyncAnthropic
+
+from .base import StreamEvent
+
+logger = logging.getLogger(__name__)
+
+
+class AnthropicProvider:
+    """Anthropic Claude provider with streaming support."""
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "claude-sonnet-4-5-20250929",
+        base_url: str | None = None
+    ):
+        """
+        Initialize Anthropic provider.
+
+        Args:
+            api_key: Anthropic API key
+            model: Model to use (default: claude-sonnet-4.5)
+            base_url: Optional base URL for API endpoint (for proxies/alternative endpoints)
+        """
+        self.client = AsyncAnthropic(api_key=api_key, base_url=base_url)
+        self.model = model
+
+    async def stream(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any
+    ) -> AsyncIterator[StreamEvent]:
+        """Stream completion with normalized events."""
+        logger.info(f"AnthropicProvider.stream called with {len(tools or [])} tools")
+        if tools:
+            logger.debug(f"Tool names: {[t.get('name') for t in tools]}")
+
+        async with self.client.messages.stream(  # type: ignore[arg-type]
+            model=self.model,
+            messages=messages,  # type: ignore[arg-type]
+            tools=tools or [],  # type: ignore[arg-type]
+            max_tokens=kwargs.pop("max_tokens", 4096),
+            **kwargs
+        ) as stream:
+            async for event in stream:
+                if event.type == "content_block_delta":
+                    if event.delta.type == "text_delta":
+                        yield StreamEvent(
+                            type="text",
+                            data={"text": event.delta.text}
+                        )
+                    elif event.delta.type == "input_json_delta":
+                        # Tool call in progress
+                        yield StreamEvent(
+                            type="tool_call_delta",
+                            data={"delta": event.delta.partial_json}
+                        )
+
+                elif event.type == "content_block_start":
+                    if event.content_block.type == "tool_use":
+                        yield StreamEvent(
+                            type="tool_call_start",
+                            data={
+                                "tool": event.content_block.name,
+                                "call_id": event.content_block.id
+                            }
+                        )
+                    elif event.content_block.type == "text":
+                        # Text block starting
+                        yield StreamEvent(
+                            type="content_block_start",
+                            data={"block_type": "text"}
+                        )
+
+                elif event.type == "content_block_stop":
+                    # Content block (text or tool_use) is complete
+                    yield StreamEvent(
+                        type="content_block_stop",
+                        data={"index": event.index}
+                    )
+
+                elif event.type == "message_stop":
+                    # Final message with usage
+                    message = await stream.get_final_message()
+                    yield StreamEvent(
+                        type="usage",
+                        data={
+                            "usage": {
+                                "prompt_tokens": message.usage.input_tokens,
+                                "completion_tokens": message.usage.output_tokens,
+                                "total_tokens": message.usage.input_tokens + message.usage.output_tokens
+                            }
+                        }
+                    )
+
+    async def generate(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any
+    ) -> dict[str, Any]:
+        """Generate non-streaming completion."""
+        response = await self.client.messages.create(  # type: ignore[arg-type]
+            model=self.model,
+            messages=messages,  # type: ignore[arg-type]
+            tools=tools or [],  # type: ignore[arg-type]
+            max_tokens=kwargs.pop("max_tokens", 4096),
+            **kwargs
+        )
+
+        # Extract text content
+        text_content = ""
+        for block in response.content:
+            if block.type == "text":
+                text_content += block.text
+
+        return {
+            "text": text_content,
+            "usage": {
+                "prompt_tokens": response.usage.input_tokens,
+                "completion_tokens": response.usage.output_tokens,
+                "total_tokens": response.usage.input_tokens + response.usage.output_tokens
+            },
+            "model": response.model,
+        }
+
+    def normalize_tool_call(self, raw: dict[str, Any]) -> dict[str, Any]:
+        """Normalize Anthropic tool call format."""
+        return {
+            "name": raw.get("name"),
+            "call_id": raw.get("id"),
+            "input": raw.get("input", {})
+        }

ctrlcode/providers/base.py

@@ -0,0 +1,77 @@
+"""Base provider protocol and types for LLM providers."""
+
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator
+from dataclasses import dataclass
+
+
+@dataclass
+class StreamEvent:
+    """Normalized event from provider streaming."""
+
+    type: str  # "text", "tool_call", "usage", "error"
+    data: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to JSON-serializable dict."""
+        return {
+            "type": self.type,
+            "data": self.data
+        }
+
+
+class Provider(ABC):
+    """Base class for LLM providers with streaming support."""
+
+    @abstractmethod
+    async def stream(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any
+    ) -> AsyncIterator[StreamEvent]:
+        """
+        Stream completion with normalized events.
+
+        Args:
+            messages: Conversation messages in provider format
+            tools: Optional tool definitions
+            **kwargs: Provider-specific parameters (temperature, etc.)
+
+        Yields:
+            StreamEvent: Normalized streaming events
+        """
+        ...
+
+    @abstractmethod
+    async def generate(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any
+    ) -> dict[str, Any]:
+        """
+        Generate non-streaming completion.
+
+        Args:
+            messages: Conversation messages
+            tools: Optional tool definitions
+            **kwargs: Provider-specific parameters
+
+        Returns:
+            Complete response with text and metadata
+        """
+        ...
+
+    @abstractmethod
+    def normalize_tool_call(self, raw: dict[str, Any]) -> dict[str, Any]:
+        """
+        Normalize provider-specific tool call format.
+
+        Args:
+            raw: Provider-specific tool call data
+
+        Returns:
+            Normalized tool call dict with keys: name, call_id, input
+        """
+        ...

ctrlcode/providers/openai.py

@@ -0,0 +1,197 @@
+"""OpenAI provider implementation."""
+
+import json
+import logging
+from typing import Any, AsyncIterator
+from openai import AsyncOpenAI
+
+from .base import StreamEvent
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAIProvider:
+    """OpenAI GPT provider with streaming support."""
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "gpt-4",
+        base_url: str | None = None
+    ):
+        """
+        Initialize OpenAI provider.
+
+        Args:
+            api_key: OpenAI API key
+            model: Model to use (default: gpt-4)
+            base_url: Optional base URL for API endpoint (for proxies/alternative endpoints)
+        """
+        self.api_key = api_key
+        self.base_url = base_url
+        self.client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self.model = model
+
+    def _convert_tools_to_openai_format(self, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Convert Anthropic tool format to OpenAI format."""
+        openai_tools = []
+        for tool in tools:
+            # Anthropic format: {name, description, input_schema}
+            # OpenAI format: {type: "function", function: {name, description, parameters}}
+            openai_tools.append({
+                "type": "function",
+                "function": {
+                    "name": tool["name"],
+                    "description": tool["description"],
+                    "parameters": tool["input_schema"]  # OpenAI calls it "parameters" not "input_schema"
+                }
+            })
+        return openai_tools
+
+    async def stream(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any
+    ) -> AsyncIterator[StreamEvent]:
+        """Stream completion with normalized events."""
+        # Convert tools to OpenAI format
+        openai_tools = []
+        if tools:
+            openai_tools = self._convert_tools_to_openai_format(tools)
+            logger.info(f"OpenAIProvider.stream called with {len(openai_tools)} tools")
+            logger.debug(f"Tool names: {[t['function']['name'] for t in openai_tools]}")
+
+        # Log message structure and first tool schema for diagnostics
+        for i, msg in enumerate(messages):
+            role = msg.get("role", "?")
+            content = msg.get("content", "") or ""
+            logger.info(f"Message[{i}] role={role} len={len(content)} preview={repr(content[:80])}")
+        if openai_tools:
+            logger.info(f"First tool schema: {json.dumps(openai_tools[0])}")
+
+        create_kwargs: dict[str, Any] = dict(
+            model=self.model,
+            messages=messages,  # type: ignore[arg-type]
+            stream=True,
+            stream_options={"include_usage": True},
+            **kwargs
+        )
+        if openai_tools:
+            create_kwargs["tools"] = openai_tools  # type: ignore[assignment]
+            create_kwargs["tool_choice"] = "auto"
+
+        # Qwen3 models default to thinking mode which interferes with tool calling.
+        # Disable thinking mode so vLLM's tool call parser sees clean JSON output.
+        if "qwen" in self.model.lower() and "extra_body" not in create_kwargs:
+            create_kwargs["extra_body"] = {"chat_template_kwargs": {"enable_thinking": False}}
+            logger.info("Qwen model detected: disabled thinking mode for reliable tool calling")
+
+        stream = await self.client.chat.completions.create(**create_kwargs)  # type: ignore[arg-type]
+
+        tool_calls_seen = set()
+
+        async for chunk in stream:  # type: ignore[union-attr]
+            # Check for usage info (OpenAI sends this in a final chunk with no choices)
+            if chunk.usage:
+                yield StreamEvent(
+                    type="usage",
+                    data={
+                        "usage": {
+                            "prompt_tokens": chunk.usage.prompt_tokens,
+                            "completion_tokens": chunk.usage.completion_tokens,
+                            "total_tokens": chunk.usage.total_tokens
+                        }
+                    }
+                )
+
+            if not chunk.choices:
+                continue
+
+            delta = chunk.choices[0].delta
+
+            # Text content
+            if delta.content:
+                yield StreamEvent(
+                    type="text",
+                    data={"text": delta.content}
+                )
+
+            # Tool calls
+            if delta.tool_calls:
+                logger.info(f"tool_call delta received: {delta.tool_calls}")
+                for tool_call in delta.tool_calls:
+                    # OpenAI sends multiple deltas for same tool call
+                    # Track which ones we've seen to emit start event only once
+                    if tool_call.function and tool_call.function.name:
+                        if tool_call.id not in tool_calls_seen:
+                            tool_calls_seen.add(tool_call.id)
+                            # Tool call start
+                            yield StreamEvent(
+                                type="tool_call_start",
+                                data={
+                                    "tool": tool_call.function.name,
+                                    "call_id": tool_call.id
+                                }
+                            )
+
+                    if tool_call.function and tool_call.function.arguments:
+                        # Tool arguments (may be partial)
+                        yield StreamEvent(
+                            type="tool_call_delta",
+                            data={"delta": tool_call.function.arguments}
+                        )
+
+            # Completion
+            if chunk.choices[0].finish_reason:
+                logger.info(f"finish_reason: {chunk.choices[0].finish_reason}")
+                # Emit content_block_stop for tool calls
+                if chunk.choices[0].finish_reason == "tool_calls":
+                    yield StreamEvent(
+                        type="content_block_stop",
+                        data={}
+                    )
+
+    async def generate(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        **kwargs: Any
+    ) -> dict[str, Any]:
+        """Generate non-streaming completion."""
+        # Convert tools to OpenAI format
+        openai_tools = None
+        if tools:
+            openai_tools = self._convert_tools_to_openai_format(tools)
+
+        response = await self.client.chat.completions.create(  # type: ignore[arg-type]
+            model=self.model,
+            messages=messages,  # type: ignore[arg-type]
+            tools=openai_tools,  # type: ignore[arg-type]
+            **kwargs
+        )
+
+        choice = response.choices[0]
+        text_content = choice.message.content or ""
+
+        usage_dict = {}
+        if response.usage:
+            usage_dict = {
+                "prompt_tokens": response.usage.prompt_tokens,
+                "completion_tokens": response.usage.completion_tokens,
+                "total_tokens": response.usage.total_tokens
+            }
+
+        return {
+            "text": text_content,
+            "usage": usage_dict,
+            "model": response.model,
+        }
+
+    def normalize_tool_call(self, raw: dict[str, Any]) -> dict[str, Any]:
+        """Normalize OpenAI tool call format."""
+        return {
+            "name": raw.get("function", {}).get("name"),
+            "call_id": raw.get("id"),
+            "input": json.loads(raw.get("function", {}).get("arguments", "{}"))
+        }