codebuddy-agent-sdk 0.1.15__py3-none-any.whl

codebuddy_agent_sdk/__init__.py

@@ -0,0 +1,97 @@
+"""CodeBuddy Agent SDK for Python."""
+
+from ._errors import (
+    CLIConnectionError,
+    CLIJSONDecodeError,
+    CLINotFoundError,
+    CodeBuddySDKError,
+    ProcessError,
+)
+from ._version import __version__
+from .client import CodeBuddySDKClient
+from .query import query
+from .transport import Transport
+from .types import (
+    AgentDefinition,
+    AppendSystemPrompt,
+    AskUserQuestionInput,
+    AskUserQuestionOption,
+    AskUserQuestionQuestion,
+    AssistantMessage,
+    CanUseTool,
+    CanUseToolOptions,
+    CodeBuddyAgentOptions,
+    ContentBlock,
+    HookCallback,
+    HookContext,
+    HookEvent,
+    HookJSONOutput,
+    HookMatcher,
+    McpServerConfig,
+    Message,
+    PermissionMode,
+    PermissionResult,
+    PermissionResultAllow,
+    PermissionResultDeny,
+    ResultMessage,
+    SettingSource,
+    StreamEvent,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+__all__ = [
+    # Main API
+    "query",
+    "CodeBuddySDKClient",
+    "Transport",
+    "__version__",
+    # Types - Permission
+    "PermissionMode",
+    # Types - Messages
+    "Message",
+    "UserMessage",
+    "AssistantMessage",
+    "SystemMessage",
+    "ResultMessage",
+    "StreamEvent",
+    # Types - Content blocks
+    "ContentBlock",
+    "TextBlock",
+    "ThinkingBlock",
+    "ToolUseBlock",
+    "ToolResultBlock",
+    # Types - Configuration
+    "CodeBuddyAgentOptions",
+    "AgentDefinition",
+    "AppendSystemPrompt",
+    "SettingSource",
+    # Types - Permission
+    "CanUseTool",
+    "CanUseToolOptions",
+    "PermissionResult",
+    "PermissionResultAllow",
+    "PermissionResultDeny",
+    # Types - AskUserQuestion
+    "AskUserQuestionOption",
+    "AskUserQuestionQuestion",
+    "AskUserQuestionInput",
+    # Types - Hooks
+    "HookEvent",
+    "HookCallback",
+    "HookMatcher",
+    "HookJSONOutput",
+    "HookContext",
+    # Types - MCP
+    "McpServerConfig",
+    # Errors
+    "CodeBuddySDKError",
+    "CLIConnectionError",
+    "CLINotFoundError",
+    "CLIJSONDecodeError",
+    "ProcessError",
+]

codebuddy_agent_sdk/_binary.py

@@ -0,0 +1,148 @@
+"""
+Binary locator for CodeBuddy CLI.
+
+This module provides functions to locate the CodeBuddy CLI binary.
+The binary is bundled in platform-specific wheels.
+"""
+
+import os
+import platform
+import sys
+from pathlib import Path
+
+from ._errors import CLINotFoundError
+
+__all__ = ["get_cli_path", "try_cli_path", "get_platform_info"]
+
+
+# Platform mapping for goreleaser output directories (for monorepo development)
+# Note: For musl (Alpine), the correct binary is bundled in the wheel at build time
+_PLATFORM_DIRS: dict[tuple[str, str], str] = {
+    ("Darwin", "arm64"): "darwin-arm64_bun-darwin-arm64",
+    ("Darwin", "x86_64"): "darwin-x64_bun-darwin-x64",
+    ("Linux", "x86_64"): "linux-x64_bun-linux-x64",
+    ("Linux", "aarch64"): "linux-arm64_bun-linux-arm64",
+    ("Windows", "AMD64"): "windows-x64_bun-windows-x64",
+}
+
+# Binary name per platform
+_BINARY_NAMES: dict[str, str] = {
+    "Darwin": "codebuddy",
+    "Linux": "codebuddy",
+    "Windows": "codebuddy.exe",
+}
+
+
+def _get_package_binary_path() -> Path | None:
+    """Get the binary path bundled in the package."""
+    # Binary is bundled at package_root/bin/codebuddy
+    pkg_root = Path(__file__).parent
+    system = platform.system()
+    binary_name = _BINARY_NAMES.get(system, "codebuddy")
+    bin_path = pkg_root / "bin" / binary_name
+
+    if bin_path.exists() and bin_path.is_file():
+        return bin_path
+
+    return None
+
+
+def _get_monorepo_binary_path() -> Path | None:
+    """Get the binary path from monorepo development structure."""
+    system = platform.system()
+    machine = platform.machine()
+    key = (system, machine)
+
+    dir_name = _PLATFORM_DIRS.get(key)
+    if not dir_name:
+        return None
+
+    binary_name = _BINARY_NAMES.get(system, "codebuddy")
+
+    # Try relative to this package (agent-sdk-python -> agent-cli)
+    pkg_root = Path(__file__).parent
+    monorepo_path = pkg_root.parent.parent.parent / "agent-cli" / "out" / dir_name / binary_name
+
+    if monorepo_path.exists() and monorepo_path.is_file():
+        return monorepo_path
+
+    return None
+
+
+def get_cli_path() -> str:
+    """
+    Get the path to the CodeBuddy CLI binary.
+
+    Resolution order:
+    1. CODEBUDDY_CODE_PATH environment variable
+    2. Binary bundled in the package (wheel)
+    3. Monorepo development path
+
+    Returns:
+        The absolute path to the CLI binary.
+
+    Raises:
+        CLINotFoundError: If the binary cannot be found.
+    """
+    system = platform.system()
+    machine = platform.machine()
+
+    # 1. Environment variable takes precedence
+    env_path = os.environ.get("CODEBUDDY_CODE_PATH")
+    if env_path:
+        path = Path(env_path)
+        if path.exists():
+            return str(path)
+        # Warn but continue to try other methods
+        print(
+            f"Warning: CODEBUDDY_CODE_PATH is set to '{env_path}' but file does not exist. "
+            "Falling back to other resolution methods.",
+            file=sys.stderr,
+        )
+
+    # 2. Try package bundled binary
+    pkg_path = _get_package_binary_path()
+    if pkg_path:
+        return str(pkg_path)
+
+    # 3. Try monorepo development path
+    monorepo_path = _get_monorepo_binary_path()
+    if monorepo_path:
+        return str(monorepo_path)
+
+    # 4. Nothing found - raise helpful error
+    supported = ", ".join(f"{s}-{m}" for s, m in _PLATFORM_DIRS)
+    raise CLINotFoundError(
+        f"CodeBuddy CLI binary not found for platform '{system}-{machine}'.\n\n"
+        f"Possible solutions:\n"
+        f"  1. Reinstall the package to get the correct platform wheel:\n"
+        f"     pip install --force-reinstall codebuddy-agent-sdk\n\n"
+        f"  2. Set CODEBUDDY_CODE_PATH environment variable to the CLI binary path\n\n"
+        f"  3. Install the CLI separately and set the path\n\n"
+        f"Supported platforms: {supported}",
+        system,
+        machine,
+    )
+
+
+def try_cli_path() -> str | None:
+    """
+    Try to get the CLI path without raising an exception.
+
+    Returns:
+        The CLI path if found, None otherwise.
+    """
+    try:
+        return get_cli_path()
+    except CLINotFoundError:
+        return None
+
+
+def get_platform_info() -> tuple[str, str]:
+    """
+    Get the current platform information.
+
+    Returns:
+        A tuple of (system, machine).
+    """
+    return platform.system(), platform.machine()

codebuddy_agent_sdk/_errors.py

@@ -0,0 +1,39 @@
+"""Error definitions for CodeBuddy Agent SDK."""
+
+
+class CodeBuddySDKError(Exception):
+    """Base exception for CodeBuddy SDK errors."""
+
+    pass
+
+
+class CLIConnectionError(CodeBuddySDKError):
+    """Raised when connection to CLI fails or is not established."""
+
+    pass
+
+
+class CLINotFoundError(CodeBuddySDKError):
+    """Raised when CLI executable is not found."""
+
+    def __init__(
+        self,
+        message: str,
+        platform: str | None = None,
+        arch: str | None = None,
+    ):
+        super().__init__(message)
+        self.platform = platform
+        self.arch = arch
+
+
+class CLIJSONDecodeError(CodeBuddySDKError):
+    """Raised when JSON decoding from CLI output fails."""
+
+    pass
+
+
+class ProcessError(CodeBuddySDKError):
+    """Raised when CLI process encounters an error."""
+
+    pass

codebuddy_agent_sdk/_message_parser.py

@@ -0,0 +1,112 @@
+"""Message parser for CLI output."""
+
+from typing import Any
+
+from .types import (
+    AssistantMessage,
+    ContentBlock,
+    Message,
+    ResultMessage,
+    StreamEvent,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+
+def parse_content_block(data: dict[str, Any]) -> ContentBlock | None:
+    """Parse a content block from raw data."""
+    block_type = data.get("type")
+
+    if block_type == "text":
+        return TextBlock(text=data.get("text", ""))
+
+    if block_type == "thinking":
+        return ThinkingBlock(
+            thinking=data.get("thinking", ""),
+            signature=data.get("signature", ""),
+        )
+
+    if block_type == "tool_use":
+        return ToolUseBlock(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            input=data.get("input", {}),
+        )
+
+    if block_type == "tool_result":
+        return ToolResultBlock(
+            tool_use_id=data.get("tool_use_id", ""),
+            content=data.get("content"),
+            is_error=data.get("is_error"),
+        )
+
+    return None
+
+
+def parse_content_blocks(content: list[dict[str, Any]]) -> list[ContentBlock]:
+    """Parse a list of content blocks."""
+    blocks: list[ContentBlock] = []
+    for item in content:
+        block = parse_content_block(item)
+        if block:
+            blocks.append(block)
+    return blocks
+
+
+def parse_message(data: dict[str, Any]) -> Message | None:
+    """Parse a message from raw JSON data."""
+    msg_type = data.get("type")
+
+    if msg_type == "user":
+        message_data = data.get("message", {})
+        content = message_data.get("content", "")
+        if isinstance(content, list):
+            content = parse_content_blocks(content)
+        return UserMessage(
+            content=content,
+            uuid=data.get("uuid"),
+            parent_tool_use_id=data.get("parent_tool_use_id"),
+        )
+
+    if msg_type == "assistant":
+        message_data = data.get("message", {})
+        content = message_data.get("content", [])
+        return AssistantMessage(
+            content=parse_content_blocks(content) if isinstance(content, list) else [],
+            model=data.get("model", ""),
+            parent_tool_use_id=data.get("parent_tool_use_id"),
+            error=data.get("error"),
+        )
+
+    if msg_type == "system":
+        return SystemMessage(
+            subtype=data.get("subtype", ""),
+            data=data,
+        )
+
+    if msg_type == "result":
+        return ResultMessage(
+            subtype=data.get("subtype", ""),
+            duration_ms=data.get("duration_ms", 0),
+            duration_api_ms=data.get("duration_api_ms", 0),
+            is_error=data.get("is_error", False),
+            num_turns=data.get("num_turns", 0),
+            session_id=data.get("session_id", ""),
+            total_cost_usd=data.get("total_cost_usd"),
+            usage=data.get("usage"),
+            result=data.get("result"),
+        )
+
+    if msg_type == "stream_event":
+        return StreamEvent(
+            uuid=data.get("uuid", ""),
+            session_id=data.get("session_id", ""),
+            event=data.get("event", {}),
+            parent_tool_use_id=data.get("parent_tool_use_id"),
+        )
+
+    return None

codebuddy_agent_sdk/_version.py

@@ -0,0 +1,3 @@
+"""Version information for CodeBuddy Agent SDK."""
+
+__version__ = "0.1.15"

codebuddy_agent_sdk/client.py

@@ -0,0 +1,298 @@
+"""CodeBuddy SDK Client for interactive conversations."""
+
+import json
+import os
+from collections.abc import AsyncIterable, AsyncIterator
+from typing import Any
+
+from ._errors import CLIConnectionError
+from ._message_parser import parse_message
+from .transport import SubprocessTransport, Transport
+from .types import CanUseToolOptions, CodeBuddyAgentOptions, Message, ResultMessage
+
+
+class CodeBuddySDKClient:
+    """
+    Client for bidirectional, interactive conversations with CodeBuddy.
+
+    This client provides full control over the conversation flow with support
+    for streaming, interrupts, and dynamic message sending. For simple one-shot
+    queries, consider using the query() function instead.
+
+    Key features:
+    - Bidirectional: Send and receive messages at any time
+    - Stateful: Maintains conversation context across messages
+    - Interactive: Send follow-ups based on responses
+    - Control flow: Support for interrupts and session management
+
+    Example:
+        ```python
+        async with CodeBuddySDKClient() as client:
+            await client.query("Hello!")
+            async for msg in client.receive_response():
+                print(msg)
+        ```
+    """
+
+    def __init__(
+        self,
+        options: CodeBuddyAgentOptions | None = None,
+        transport: Transport | None = None,
+    ):
+        """Initialize CodeBuddy SDK client."""
+        self.options = options or CodeBuddyAgentOptions()
+        self._custom_transport = transport
+        self._transport: Transport | None = None
+        self._connected = False
+
+        os.environ["CODEBUDDY_CODE_ENTRYPOINT"] = "sdk-py-client"
+
+    async def connect(
+        self, prompt: str | AsyncIterable[dict[str, Any]] | None = None
+    ) -> None:
+        """Connect to CodeBuddy with an optional initial prompt."""
+        if self._custom_transport:
+            self._transport = self._custom_transport
+        else:
+            self._transport = SubprocessTransport(
+                options=self.options,
+                prompt=prompt,
+            )
+
+        await self._transport.connect()
+        self._connected = True
+        await self._send_initialize()
+
+    async def _send_initialize(self) -> None:
+        """Send initialization control request."""
+        if not self._transport:
+            return
+
+        request = {
+            "type": "control_request",
+            "request_id": f"init_{id(self)}",
+            "request": {"subtype": "initialize"},
+        }
+        await self._transport.write(json.dumps(request))
+
+    async def query(
+        self,
+        prompt: str | AsyncIterable[dict[str, Any]],
+        session_id: str = "default",
+    ) -> None:
+        """
+        Send a new request.
+
+        Args:
+            prompt: Either a string message or an async iterable of message dicts
+            session_id: Session identifier for the conversation
+        """
+        if not self._connected or not self._transport:
+            raise CLIConnectionError("Not connected. Call connect() first.")
+
+        if isinstance(prompt, str):
+            message = {
+                "type": "user",
+                "message": {"role": "user", "content": prompt},
+                "parent_tool_use_id": None,
+                "session_id": session_id,
+            }
+            await self._transport.write(json.dumps(message))
+        else:
+            async for msg in prompt:
+                if "session_id" not in msg:
+                    msg["session_id"] = session_id
+                await self._transport.write(json.dumps(msg))
+
+    async def receive_messages(self) -> AsyncIterator[Message]:
+        """Receive all messages from CodeBuddy."""
+        if not self._transport:
+            raise CLIConnectionError("Not connected.")
+
+        async for line in self._transport.read():
+            if not line:
+                continue
+
+            try:
+                data = json.loads(line)
+
+                # Handle control requests (permissions, hooks)
+                if data.get("type") == "control_request":
+                    await self._handle_control_request(data)
+                    continue
+
+                message = parse_message(data)
+                if message:
+                    yield message
+            except json.JSONDecodeError:
+                continue
+
+    async def _handle_control_request(self, data: dict[str, Any]) -> None:
+        """Handle control request from CLI."""
+        if not self._transport:
+            return
+
+        request_id = data.get("request_id", "")
+        request = data.get("request", {})
+        subtype = request.get("subtype", "")
+
+        if subtype == "can_use_tool":
+            await self._handle_permission_request(request_id, request)
+        elif subtype == "hook_callback":
+            # Default: continue
+            response = {
+                "type": "control_response",
+                "response": {
+                    "subtype": "success",
+                    "request_id": request_id,
+                    "response": {"continue": True},
+                },
+            }
+            await self._transport.write(json.dumps(response))
+
+    async def _handle_permission_request(
+        self, request_id: str, request: dict[str, Any]
+    ) -> None:
+        """Handle permission request from CLI."""
+        if not self._transport:
+            return
+
+        tool_name = request.get("tool_name", "")
+        input_data = request.get("input", {})
+        tool_use_id = request.get("tool_use_id", "")
+        agent_id = request.get("agent_id")
+
+        can_use_tool = self.options.can_use_tool
+
+        # Default deny if no callback provided
+        if not can_use_tool:
+            response = {
+                "type": "control_response",
+                "response": {
+                    "subtype": "success",
+                    "request_id": request_id,
+                    "response": {
+                        "allowed": False,
+                        "reason": "No permission handler provided",
+                        "tool_use_id": tool_use_id,
+                    },
+                },
+            }
+            await self._transport.write(json.dumps(response))
+            return
+
+        try:
+            callback_options = CanUseToolOptions(
+                tool_use_id=tool_use_id,
+                signal=None,
+                agent_id=agent_id,
+                suggestions=request.get("permission_suggestions"),
+                blocked_path=request.get("blocked_path"),
+                decision_reason=request.get("decision_reason"),
+            )
+
+            result = await can_use_tool(tool_name, input_data, callback_options)
+
+            if result.behavior == "allow":
+                response_data = {
+                    "allowed": True,
+                    "updatedInput": result.updated_input,
+                    "tool_use_id": tool_use_id,
+                }
+            else:
+                response_data = {
+                    "allowed": False,
+                    "reason": result.message,
+                    "interrupt": result.interrupt,
+                    "tool_use_id": tool_use_id,
+                }
+
+            response = {
+                "type": "control_response",
+                "response": {
+                    "subtype": "success",
+                    "request_id": request_id,
+                    "response": response_data,
+                },
+            }
+            await self._transport.write(json.dumps(response))
+
+        except Exception as e:
+            response = {
+                "type": "control_response",
+                "response": {
+                    "subtype": "success",
+                    "request_id": request_id,
+                    "response": {
+                        "allowed": False,
+                        "reason": str(e),
+                        "tool_use_id": tool_use_id,
+                    },
+                },
+            }
+            await self._transport.write(json.dumps(response))
+
+    async def receive_response(self) -> AsyncIterator[Message]:
+        """
+        Receive messages until and including a ResultMessage.
+
+        Yields each message as it's received and terminates after
+        yielding a ResultMessage.
+        """
+        async for message in self.receive_messages():
+            yield message
+            if isinstance(message, ResultMessage):
+                return
+
+    async def interrupt(self) -> None:
+        """Send interrupt signal."""
+        if not self._transport:
+            raise CLIConnectionError("Not connected.")
+
+        request = {
+            "type": "control_request",
+            "request_id": f"interrupt_{id(self)}",
+            "request": {"subtype": "interrupt"},
+        }
+        await self._transport.write(json.dumps(request))
+
+    async def set_permission_mode(self, mode: str) -> None:
+        """Change permission mode during conversation."""
+        if not self._transport:
+            raise CLIConnectionError("Not connected.")
+
+        request = {
+            "type": "control_request",
+            "request_id": f"perm_{id(self)}",
+            "request": {"subtype": "set_permission_mode", "mode": mode},
+        }
+        await self._transport.write(json.dumps(request))
+
+    async def set_model(self, model: str | None = None) -> None:
+        """Change the AI model during conversation."""
+        if not self._transport:
+            raise CLIConnectionError("Not connected.")
+
+        request = {
+            "type": "control_request",
+            "request_id": f"model_{id(self)}",
+            "request": {"subtype": "set_model", "model": model},
+        }
+        await self._transport.write(json.dumps(request))
+
+    async def disconnect(self) -> None:
+        """Disconnect from CodeBuddy."""
+        if self._transport:
+            await self._transport.close()
+            self._transport = None
+        self._connected = False
+
+    async def __aenter__(self) -> "CodeBuddySDKClient":
+        """Enter async context - automatically connects."""
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *args: Any) -> bool:
+        """Exit async context - always disconnects."""
+        await self.disconnect()
+        return False