codebuddy-agent-sdk 0.1.27__py3-none-macosx_11_0_arm64.whl

codebuddy_agent_sdk/transport/subprocess.py

@@ -0,0 +1,171 @@
+"""Subprocess transport for CLI communication."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import AsyncIterable, AsyncIterator
+from typing import Any
+
+from .._binary import get_cli_path
+from ..types import AppendSystemPrompt, CodeBuddyAgentOptions
+from .base import Transport
+
+
+class SubprocessTransport(Transport):
+    """Transport that communicates with CLI via subprocess."""
+
+    def __init__(
+        self,
+        options: CodeBuddyAgentOptions,
+        prompt: str | AsyncIterable[dict[str, Any]] | None = None,
+    ):
+        self.options = options
+        self.prompt = prompt
+        self._process: asyncio.subprocess.Process | None = None
+        self._closed = False
+
+    def _get_cli_path(self) -> str:
+        """Get the path to CLI executable."""
+        # User-specified path takes highest precedence
+        if self.options.codebuddy_code_path:
+            return str(self.options.codebuddy_code_path)
+
+        # Use the binary resolver (env var -> package binary -> monorepo)
+        return get_cli_path()
+
+    def _build_args(self) -> list[str]:
+        """Build CLI arguments from options."""
+        args = [
+            "--input-format",
+            "stream-json",
+            "--verbose",
+            "--output-format",
+            "stream-json",
+        ]
+        opts = self.options
+
+        # Model options
+        if opts.model:
+            args.extend(["--model", opts.model])
+        if opts.fallback_model:
+            args.extend(["--fallback-model", opts.fallback_model])
+
+        # Permission options
+        if opts.permission_mode:
+            args.extend(["--permission-mode", opts.permission_mode])
+
+        # Turn limits
+        if opts.max_turns:
+            args.extend(["--max-turns", str(opts.max_turns)])
+
+        # Session options
+        if opts.continue_conversation:
+            args.append("--continue")
+        if opts.resume:
+            args.extend(["--resume", opts.resume])
+        if opts.fork_session:
+            args.append("--fork-session")
+
+        # Tool options
+        if opts.allowed_tools:
+            args.extend(["--allowedTools", ",".join(opts.allowed_tools)])
+        if opts.disallowed_tools:
+            args.extend(["--disallowedTools", ",".join(opts.disallowed_tools)])
+
+        # MCP options
+        if opts.mcp_servers and isinstance(opts.mcp_servers, dict):
+            args.extend(["--mcp-config", json.dumps({"mcpServers": opts.mcp_servers})])
+
+        # Settings
+        # SDK default: don't load any filesystem settings for clean environment isolation
+        # When setting_sources is explicitly provided (including empty list), use it
+        # When not provided (None), default to 'none' for SDK isolation
+        if opts.setting_sources is not None:
+            setting_value = (
+                "none" if len(opts.setting_sources) == 0 else ",".join(opts.setting_sources)
+            )
+            args.extend(["--setting-sources", setting_value])
+        else:
+            # SDK default behavior: no filesystem settings loaded
+            args.extend(["--setting-sources", "none"])
+
+        # Output options
+        if opts.include_partial_messages:
+            args.append("--include-partial-messages")
+
+        # System prompt options
+        if opts.system_prompt is not None:
+            if isinstance(opts.system_prompt, str):
+                args.extend(["--system-prompt", opts.system_prompt])
+            elif isinstance(opts.system_prompt, AppendSystemPrompt):
+                args.extend(["--append-system-prompt", opts.system_prompt.append])
+
+        # Extra args (custom flags)
+        for flag, value in opts.extra_args.items():
+            if value is None:
+                args.append(f"--{flag}")
+            else:
+                args.extend([f"--{flag}", value])
+
+        return args
+
+    async def connect(self) -> None:
+        """Start the subprocess."""
+        cli_path = self._get_cli_path()
+        args = self._build_args()
+        cwd = str(self.options.cwd) if self.options.cwd else os.getcwd()
+
+        env = {
+            **os.environ,
+            **self.options.env,
+            "CODEBUDDY_CODE_ENTRYPOINT": "sdk-py",
+        }
+
+        self._process = await asyncio.create_subprocess_exec(
+            cli_path,
+            *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+            env=env,
+        )
+
+        # Start stderr reader if callback provided
+        if self.options.stderr and self._process.stderr:
+            asyncio.create_task(self._read_stderr())
+
+    async def _read_stderr(self) -> None:
+        """Read stderr and call callback."""
+        if self._process and self._process.stderr and self.options.stderr:
+            async for line in self._process.stderr:
+                self.options.stderr(line.decode())
+
+    async def read(self) -> AsyncIterator[str]:
+        """Read lines from stdout."""
+        if not self._process or not self._process.stdout:
+            return
+
+        async for line in self._process.stdout:
+            if self._closed:
+                break
+            yield line.decode().strip()
+
+    async def write(self, data: str) -> None:
+        """Write data to stdin."""
+        if self._process and self._process.stdin:
+            self._process.stdin.write((data + "\n").encode())
+            await self._process.stdin.drain()
+
+    async def close(self) -> None:
+        """Close the subprocess."""
+        if self._closed:
+            return
+
+        self._closed = True
+
+        if self._process:
+            self._process.kill()
+            await self._process.wait()

codebuddy_agent_sdk/types.py

@@ -0,0 +1,330 @@
+"""Type definitions for CodeBuddy Agent SDK."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, NotRequired, TypedDict
+
+if TYPE_CHECKING:
+    from .mcp.types import SdkMcpServer
+
+# ============= AskUserQuestion Types =============
+
+
+@dataclass
+class AskUserQuestionOption:
+    """Option for AskUserQuestion tool."""
+
+    label: str
+    description: str
+
+
+@dataclass
+class AskUserQuestionQuestion:
+    """Question for AskUserQuestion tool."""
+
+    question: str
+    header: str
+    options: list[AskUserQuestionOption]
+    multi_select: bool
+
+
+@dataclass
+class AskUserQuestionInput:
+    """Input for AskUserQuestion tool."""
+
+    questions: list[AskUserQuestionQuestion]
+    answers: dict[str, str] | None = None
+
+
+# ============= Permission Types =============
+
+
+@dataclass
+class CanUseToolOptions:
+    """Options passed to canUseTool callback."""
+
+    tool_use_id: str
+    signal: Any | None = None
+    agent_id: str | None = None
+    suggestions: list[dict[str, Any]] | None = None
+    blocked_path: str | None = None
+    decision_reason: str | None = None
+
+
+@dataclass
+class PermissionResultAllow:
+    """Allow permission result."""
+
+    updated_input: dict[str, Any]
+    behavior: Literal["allow"] = "allow"
+    updated_permissions: list[dict[str, Any]] | None = None
+
+
+@dataclass
+class PermissionResultDeny:
+    """Deny permission result."""
+
+    message: str
+    behavior: Literal["deny"] = "deny"
+    interrupt: bool = False
+
+
+PermissionResult = PermissionResultAllow | PermissionResultDeny
+
+# CanUseTool callback type
+CanUseTool = Callable[
+    [str, dict[str, Any], CanUseToolOptions],
+    Awaitable[PermissionResult],
+]
+
+
+# Permission modes
+PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"]
+
+# Hook events
+HookEvent = (
+    Literal["PreToolUse"]
+    | Literal["PostToolUse"]
+    | Literal["UserPromptSubmit"]
+    | Literal["Stop"]
+    | Literal["SubagentStop"]
+    | Literal["PreCompact"]
+)
+
+# Setting sources
+SettingSource = Literal["user", "project", "local"]
+
+
+# Agent definition
+@dataclass
+class AgentDefinition:
+    """Agent definition configuration."""
+
+    description: str
+    prompt: str
+    tools: list[str] | None = None
+    disallowed_tools: list[str] | None = None
+    model: str | None = None
+
+
+# Content block types
+@dataclass
+class TextBlock:
+    """Text content block."""
+
+    text: str
+
+
+@dataclass
+class ThinkingBlock:
+    """Thinking content block."""
+
+    thinking: str
+    signature: str
+
+
+@dataclass
+class ToolUseBlock:
+    """Tool use content block."""
+
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+@dataclass
+class ToolResultBlock:
+    """Tool result content block."""
+
+    tool_use_id: str
+    content: str | list[dict[str, Any]] | None = None
+    is_error: bool | None = None
+
+
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+
+
+# Message types
+@dataclass
+class UserMessage:
+    """User message."""
+
+    content: str | list[ContentBlock]
+    uuid: str | None = None
+    parent_tool_use_id: str | None = None
+
+
+@dataclass
+class AssistantMessage:
+    """Assistant message with content blocks."""
+
+    content: list[ContentBlock]
+    model: str
+    parent_tool_use_id: str | None = None
+    error: str | None = None
+
+
+@dataclass
+class SystemMessage:
+    """System message with metadata."""
+
+    subtype: str
+    data: dict[str, Any]
+
+
+@dataclass
+class ResultMessage:
+    """Result message with cost and usage information."""
+
+    subtype: str
+    duration_ms: int
+    duration_api_ms: int
+    is_error: bool
+    num_turns: int
+    session_id: str
+    total_cost_usd: float | None = None
+    usage: dict[str, Any] | None = None
+    result: str | None = None
+    errors: list[str] | None = None
+
+
+@dataclass
+class StreamEvent:
+    """Stream event for partial message updates during streaming."""
+
+    uuid: str
+    session_id: str
+    event: dict[str, Any]
+    parent_tool_use_id: str | None = None
+
+
+@dataclass
+class ErrorMessage:
+    """Error message from CLI."""
+
+    error: str
+    session_id: str | None = None
+
+
+Message = (
+    UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | ErrorMessage
+)
+
+
+# Hook types
+class HookContext(TypedDict):
+    """Context information for hook callbacks."""
+
+    signal: Any | None
+
+
+class SyncHookJSONOutput(TypedDict):
+    """Synchronous hook output with control and decision fields."""
+
+    continue_: NotRequired[bool]
+    suppressOutput: NotRequired[bool]
+    stopReason: NotRequired[str]
+    decision: NotRequired[Literal["block"]]
+    reason: NotRequired[str]
+
+
+HookJSONOutput = SyncHookJSONOutput
+
+HookCallback = Callable[
+    [Any, str | None, HookContext],
+    Awaitable[HookJSONOutput],
+]
+
+
+@dataclass
+class HookMatcher:
+    """Hook matcher configuration."""
+
+    matcher: str | None = None
+    hooks: list[HookCallback] = field(default_factory=list)
+    timeout: float | None = None
+
+
+# MCP Server config
+class McpStdioServerConfig(TypedDict):
+    """MCP stdio server configuration."""
+
+    type: NotRequired[Literal["stdio"]]
+    command: str
+    args: NotRequired[list[str]]
+    env: NotRequired[dict[str, str]]
+
+
+class McpSdkServerConfig(TypedDict):
+    """
+    SDK MCP Server configuration - for servers running within the SDK process.
+    Created via create_sdk_mcp_server().
+    """
+
+    type: Literal["sdk"]
+    name: str
+    server: SdkMcpServer
+
+
+McpServerConfig = McpStdioServerConfig | McpSdkServerConfig
+
+
+# System prompt configuration
+@dataclass
+class AppendSystemPrompt:
+    """Append to the default system prompt."""
+
+    append: str
+
+
+# Main configuration
+@dataclass
+class CodeBuddyAgentOptions:
+    """Query options for CodeBuddy Agent SDK."""
+
+    allowed_tools: list[str] = field(default_factory=list)
+    """
+    List of tool names that are auto-allowed without prompting for permission.
+    These tools will execute automatically without asking the user for approval.
+    """
+
+    disallowed_tools: list[str] = field(default_factory=list)
+    """
+    List of tool names that are disallowed. When the model attempts to use
+    these tools, the request will be denied. MCP tools matching this list
+    are also filtered from the model's context.
+    """
+
+    system_prompt: str | AppendSystemPrompt | None = None
+    """
+    System prompt configuration.
+
+    - `str`: Override the entire system prompt
+    - `AppendSystemPrompt`: Append to the default system prompt
+    """
+
+    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
+    permission_mode: PermissionMode | None = None
+    continue_conversation: bool = False
+    resume: str | None = None
+    max_turns: int | None = None
+    model: str | None = None
+    fallback_model: str | None = None
+    cwd: str | Path | None = None
+    codebuddy_code_path: str | Path | None = None
+    env: dict[str, str] = field(default_factory=dict)
+    extra_args: dict[str, str | None] = field(default_factory=dict)
+    stderr: Callable[[str], None] | None = None
+    hooks: dict[HookEvent, list[HookMatcher]] | None = None
+    include_partial_messages: bool = False
+    fork_session: bool = False
+    agents: dict[str, AgentDefinition] | None = None
+    setting_sources: list[SettingSource] | None = None
+    can_use_tool: CanUseTool | None = None
+    """
+    Custom permission handler callback.
+    Called when a tool requires permission approval.
+    """

codebuddy_agent_sdk-0.1.27.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: codebuddy-agent-sdk
+Version: 0.1.27
+Summary: CodeBuddy Code SDK for Python
+Author-email: ninoyi <ninoyi@tencent.com>
+Keywords: agent,ai,codebuddy,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CodeBuddy Agent SDK for Python
+
+SDK for building AI agents with CodeBuddy Code's capabilities. Programmatically interact with AI to build autonomous agents that can understand codebases, edit files, and execute workflows.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add codebuddy-agent-sdk
+
+# Using pip
+pip install codebuddy-agent-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from codebuddy_agent_sdk import query
+
+async def main():
+    async for message in query(
+        prompt="What files are in this directory?",
+        permission_mode="bypassPermissions",
+    ):
+        if message.type == "assistant":
+            for block in message.content:
+                if hasattr(block, "text"):
+                    print(block.text)
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `query(prompt, **options)`
+
+Create a query to interact with the agent.
+
+```python
+async for message in query(
+    prompt="Your prompt here",
+    model="sonnet",                    # Model to use
+    permission_mode="bypassPermissions",  # Permission mode
+    max_turns=10,                      # Maximum conversation turns
+    cwd="/path/to/project",            # Working directory
+):
+    # Handle message
+    pass
+```
+
+### Message Types
+
+- `system` - Session initialization info
+- `assistant` - Agent responses (text, tool calls)
+- `result` - Query completion status
+
+## Related Links
+
+- [CodeBuddy Code CLI](https://www.npmjs.com/package/@tencent-ai/codebuddy-code)
+- [Documentation](https://cnb.cool/codebuddy/codebuddy-code/-/blob/main/docs)
+- [Issues](https://cnb.cool/codebuddy/codebuddy-code/-/issues)
+
+## Feedback
+
+- Submit issues at [Issues](https://cnb.cool/codebuddy/codebuddy-code/-/issues)
+- Contact: codebuddy@tencent.com

codebuddy_agent_sdk-0.1.27.dist-info/RECORD

@@ -0,0 +1,20 @@
+codebuddy_agent_sdk/__init__.py,sha256=GKrVvH2KKyuA9ht-7uMVHJJn7eWBKOi0_DKc2Ef5RCU,2690
+codebuddy_agent_sdk/_binary.py,sha256=rQFj2B__X7zHMxFazp_0vgXQFsqPi578f8g4jSkLUBc,4338
+codebuddy_agent_sdk/_errors.py,sha256=bLmyebUowNlbUomXyuS1L6J6ZbwHohvzqH_1GmN4_oM,1248
+codebuddy_agent_sdk/_message_parser.py,sha256=vtyeuwIFdl9Wz1WrWEg7G6E3OECDZT4G6bvpH15Q3VY,3504
+codebuddy_agent_sdk/_version.py,sha256=PuGt-TG_y-epKt7rwV96SbTWUkhFlvkyVOJnLXXGVW8,75
+codebuddy_agent_sdk/client.py,sha256=JfdA0wq4KOOrP4mZXfVuF4uwdrEbVHGIUrzpt4Bt_ZM,10803
+codebuddy_agent_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebuddy_agent_sdk/query.py,sha256=tCfFomCNGS1Sygbk0U9j25JLsF2azWa-3AuckThYaII,17341
+codebuddy_agent_sdk/types.py,sha256=rw5jrIg8LWtZN1Km_7TzY7SP_wFRJwKNGwPxgRcQ47A,7473
+codebuddy_agent_sdk/bin/codebuddy,sha256=u0t0idfxMHpMFBhg8-w6Xyc1eleqz_VlMxTDP8Pz7yU,77940417
+codebuddy_agent_sdk/mcp/__init__.py,sha256=0aCmHN0MnMCCUU0bdTWBRlxAblnxA-vR5Og0y3BA480,764
+codebuddy_agent_sdk/mcp/create_sdk_mcp_server.py,sha256=ig0b0ghf0T8GGjltFBRSmQSTFsaJ6fBI8S1Pjupqhps,4959
+codebuddy_agent_sdk/mcp/sdk_control_server_transport.py,sha256=CIG3h5gULubGcQPHPVd-GG9cLswwVDfgDlLba6ZPQbs,2944
+codebuddy_agent_sdk/mcp/types.py,sha256=CPEBUW5vCt93cBgu3HvAacXMsa5FdRWwWxPeicQ0PWw,8578
+codebuddy_agent_sdk/transport/__init__.py,sha256=zv_8OJHgnWjCInqOiu3GOFby4XVGvDwICHpOsymOlko,166
+codebuddy_agent_sdk/transport/base.py,sha256=XtLquCmt4yzPhTBHcVU0XFb016uG0E-12ETc-N9tzIk,662
+codebuddy_agent_sdk/transport/subprocess.py,sha256=VHoGXoP0qm597bhIE_mTV9xyIDUM-nMk7fwZwntx94c,5701
+codebuddy_agent_sdk-0.1.27.dist-info/METADATA,sha256=7I6H0xtclNvPAkqs79en6VZFVEQgzoFPia6Me2z0C8c,2539
+codebuddy_agent_sdk-0.1.27.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+codebuddy_agent_sdk-0.1.27.dist-info/RECORD,,

codebuddy_agent_sdk-0.1.27.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: false
+Tag: py3-none-macosx_11_0_arm64