agent-cli-sdk 0.0.1a1__py3-none-any.whl

agent_cli_sdk-0.0.1a1.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: agent-cli-sdk
+Version: 0.0.1a1
+Summary: Universal SDK for interacting with AI Agent CLIs (Gemini, Copilot, etc.)
+Project-URL: Homepage, https://github.com/rbbtsn0w/agent-cli-sdk
+Project-URL: Repository, https://github.com/rbbtsn0w/agent-cli-sdk
+Project-URL: Issues, https://github.com/rbbtsn0w/agent-cli-sdk/issues
+Author-email: Agent CLI SDK Contributors <noreply@github.com>
+License: MIT License
+        
+        Copyright (c) 2026 Agent CLI SDK Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: vulture; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-timeout; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Agent CLI SDK
+
+[![CI](https://github.com/rbbtsn0w/agent-cli-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/rbbtsn0w/agent-cli-sdk/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+> **Note:** This project is currently in **Technical Preview**.
+
+The `agent-cli-sdk` provides a **universal, programmable interface** for interacting with AI Agent CLIs like **GitHub Copilot** and **Google Gemini**. 
+
+By leveraging your local CLI tools as the "runtime engine," this SDK allows you to build sophisticated agentic applications while reusing existing authentication, session persistence, and local context without managing complex API keys or HTTP clients manually.
+
+## 🚀 Key Features
+
+*   **Universal Agent Interface:** Write your business logic once using `UniversalAgent` and switch between drivers (`CopilotDriver`, `GeminiDriver`, `MockDriver`) seamlessly.
+*   **CLI as a Runtime:** Reuses local binary capabilities (auth, tool execution, context awareness).
+*   **Full Protocol Support:**
+    *   **GitHub Copilot:** Full JSON-RPC support (LSP-style framing) with bidirectional tool execution.
+    *   **Google Gemini:** Robust CLI wrapper with streaming JSON event parsing.
+*   **ReAct Loop & Custom Tools:** Register any Python function as a tool; the SDK handles the thought-action-observation loop automatically.
+*   **Stateful Sessions:** Built-in support for capturing and resuming CLI session IDs across application restarts.
+
+## 📦 Installation
+
+```bash
+pip install agent-cli-sdk
+```
+
+*Ensure you have the corresponding CLI installed:*
+- **Gemini:**  `brew install gemini-cli` shoud be login
+- **Copilot:** `brew install copilot-cli` shoud be login
+
+## 🛠 Quick Start
+
+One logic, any engine. Here is how you run a simple chat with Gemini:
+
+```python
+import asyncio
+from agent_sdk.core.agent import UniversalAgent
+from agent_sdk.drivers.gemini_driver import GeminiDriver
+
+async def main():
+    # 1. Choose your engine
+    driver = GeminiDriver() 
+    
+    # 2. Initialize the Universal Agent
+    agent = UniversalAgent(driver)
+
+    # 3. Stream responses
+    print("User: Explain quantum computing.")
+    async for event in agent.stream("Explain quantum computing."):
+        if event.type.name == "CONTENT":
+            print(event.payload, end="", flush=True)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 🎮 Explore Universal Demos
+
+We provide a **Guided Launcher** to explore all SDK capabilities across different drivers.
+
+```bash
+python3 examples/demo_launcher.py
+```
+
+The launcher will:
+1.  **Auto-detect** your environment (checking if `gemini` or `copilot` is installed).
+2.  Allow you to **select a Driver Engine**.
+3.  Let you **select a Task** (Chat, Custom Tools, Session Persistence, etc.) to run on that engine.
+
+## 🏗 Architecture
+
+The SDK follows a modular "Driver-Controller" pattern:
+
+- **`UniversalAgent`**: The high-level controller. Manages message history, tool registration, and the ReAct execution loop.
+- **`AgentDriver`**: The abstraction layer.
+    - **`CopilotDriver`**: Implements JSON-RPC 2.0 over Stdio (LSP framing). Supports server-side requests (the CLI asking the SDK to run a tool).
+    - **`GeminiDriver`**: Implements the CLI wrapper pattern with `-o stream-json` support.
+- **`JsonRpcClient`**: A robust, async-first JSON-RPC client designed for high-concurrency CLI communication.
+
+## 🧪 Development & Testing
+
+We maintain a high-quality codebase with extensive test coverage.
+
+*   **Unit & Integration Tests:** 100% pass rate across 29 core test cases.
+*   **Code Coverage:** **82%** (targeting 90%+).
+*   **Stability:** Built-in execution timeouts and automated cleanup for subprocesses.
+
+### Running Tests
+```bash
+# Run all tests with coverage report
+pytest --cov=src/agent_sdk tests/ --ignore=tests/e2e --cov-report=term-missing --timeout=5
+```
+
+### E2E Testing
+E2E tests require authenticated local CLIs:
+```bash
+# Run Gemini E2E
+pytest tests/e2e/test_gemini_e2e.py
+```
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.

agent_cli_sdk-0.0.1a1.dist-info/RECORD

@@ -0,0 +1,14 @@
+agent_sdk/__init__.py,sha256=vJQ-cPjPzpZ9SVJhTbE3WlkpJwfi7wFiKtV5UlaItRw,637
+agent_sdk/core/agent.py,sha256=gCcNl-Vzki3xpiEgR2Qr9h5zq6UufDyalnnkweqZfCE,4345
+agent_sdk/core/driver.py,sha256=ziaFzzljhbK8OahECYB7YwJIooJBTNm6dbwSdSWy9yk,1321
+agent_sdk/core/types.py,sha256=iX6EG415aUjYolaqy3PXqgFYyBe-r18g5cSLhtkzXXk,833
+agent_sdk/drivers/cli_json_driver.py,sha256=gS7FxYuoEe4JXKnBg4DkUCdqQhq2aCqfrz0CGpq0Ru4,4099
+agent_sdk/drivers/copilot_driver.py,sha256=UfeQkGNj84zlpnARCJaSY2ZguL2dShwXGEmM-mxmyxk,11284
+agent_sdk/drivers/gemini_driver.py,sha256=9g614JU0pOW7K34MDNhI1P_goHk6ENKqyevGjXECMhE,2624
+agent_sdk/drivers/mock_driver.py,sha256=886li_zzrbyGThBFNKaHjyd9dRMcnqScCixUlVcspvA,2819
+agent_sdk/utils/jsonrpc.py,sha256=-geN11En2NqiupOJIeA27PbQHEMwSVLycLoFg8jzBxU,6952
+agent_sdk/utils/schema.py,sha256=lWHUPn6pKMTvnVN0ioHqpk5gDuaD9VUnal_gLEf2u6E,1384
+agent_cli_sdk-0.0.1a1.dist-info/METADATA,sha256=WOP49OnNMwChwiI5Ylb5O8fSseNcLQ3Tq2l5LKrbPEM,6792
+agent_cli_sdk-0.0.1a1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+agent_cli_sdk-0.0.1a1.dist-info/licenses/LICENSE,sha256=6s8XT3wuJnvVrT9Gw_9YXJRtUWGku4YTjNC66pxxw8U,1083
+agent_cli_sdk-0.0.1a1.dist-info/RECORD,,

agent_cli_sdk-0.0.1a1.dist-info/WHEEL

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

agent_cli_sdk-0.0.1a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent CLI SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""
+Agent CLI SDK - Universal interface for AI Agent CLIs (Copilot, Gemini, etc.)
+"""
+
+__version__ = "0.0.1a1"
+
+from agent_sdk.core.agent import UniversalAgent
+from agent_sdk.core.driver import AgentDriver
+from agent_sdk.core.types import AgentEvent, EventType, ToolDefinition
+from agent_sdk.drivers.copilot_driver import CopilotDriver
+from agent_sdk.drivers.gemini_driver import GeminiDriver
+from agent_sdk.drivers.mock_driver import MockDriver
+
+__all__ = [
+    "__version__",
+    "UniversalAgent",
+    "AgentDriver",
+    "AgentEvent",
+    "EventType",
+    "ToolDefinition",
+    "CopilotDriver",
+    "GeminiDriver",
+    "MockDriver",
+]

agent_sdk/core/agent.py

@@ -0,0 +1,124 @@
+import inspect
+import json
+from typing import Any, AsyncGenerator, Callable, Dict, List
+
+from ..utils.schema import generate_tool_schema
+from .driver import AgentDriver
+from .types import AgentEvent, Message, Role, StreamEvent, ToolDefinition
+
+
+class UniversalAgent:
+    """
+    The main entry point for the SDK. Developers interact with this class.
+    It delegates the actual execution to a specific 'driver'.
+    """
+
+    def __init__(self, driver: AgentDriver, system_instruction: str = ""):
+        self._driver = driver
+        self._system_instruction = system_instruction
+        self._tools: List[ToolDefinition] = []
+        self._history: List[Message] = []
+
+        # Initialize driver configuration
+        self._driver.set_system_prompt(system_instruction)
+
+    def tool(self, func: Callable):
+        """
+        Decorator to register a function as a tool.
+        """
+        schema = generate_tool_schema(func)
+
+        tool_def = ToolDefinition(
+            name=func.__name__,
+            description=func.__doc__ or "",
+            parameters=schema,
+            function=func,
+        )
+        self._tools.append(tool_def)
+        self._driver.set_tools(self._tools)
+        return func
+
+    async def chat(self, user_input: str) -> str:
+        """
+        Simple non-streaming chat interface.
+        Returns the final assistant response text.
+        """
+        response_text = ""
+        async for event in self.stream(user_input):
+            if event.type == AgentEvent.CONTENT:
+                response_text += event.payload
+        return response_text
+
+    async def stream(self, user_input: str) -> AsyncGenerator[StreamEvent, None]:
+        """
+        Streaming interface that yields events (thoughts, tool calls, content).
+        Handles the ReAct loop (Agent -> Tool Call -> Execute -> Tool Result -> Agent).
+        """
+        # 1. Add user message to history
+        self._history.append(Message(role=Role.USER, content=user_input))
+
+        # ReAct loop: continues as long as there are tool calls to process
+        max_turns = 10
+        for _ in range(max_turns):
+            has_tool_calls = False
+
+            async for event in self._driver.chat(self._history):
+                yield event
+
+                if event.type == AgentEvent.TOOL_CALL:
+                    has_tool_calls = True
+                    result = await self._execute_tool(event.payload)
+
+                    try:
+                        await self._driver.send_tool_result(event.payload, result)
+                    except NotImplementedError:
+                        pass
+
+                    self._history.append(
+                        Message(
+                            role=Role.TOOL,
+                            content=str(result),
+                            name=event.payload.get("name"),
+                        )
+                    )
+
+                    yield StreamEvent(
+                        type=AgentEvent.TOOL_RESULT,
+                        payload={"call_id": event.payload.get("id"), "result": result},
+                    )
+
+                if event.type == AgentEvent.DONE or event.type == AgentEvent.ERROR:
+                    break
+
+            # If the last stream didn't result in more tool calls,
+            # the conversation turn is complete
+            if not has_tool_calls:
+                break
+
+    async def _execute_tool(self, call_info: Dict[str, Any]) -> Any:
+        """Executes a tool based on the call info."""
+        name = call_info.get("name")
+        args = call_info.get("arguments", {})
+
+        # Find the tool
+        tool = next((t for t in self._tools if t.name == name), None)
+        if not tool:
+            return {"error": f"Tool '{name}' not found", "status": "error"}
+
+        try:
+            # Handle if args is a JSON string or dict
+            if isinstance(args, str):
+                args = json.loads(args)
+
+            # Call the function
+            # Check if it's a coroutine
+            if inspect.iscoroutinefunction(tool.function):
+                result = await tool.function(**args)
+            else:
+                result = tool.function(**args)
+            return result
+        except Exception as e:
+            return {
+                "error": f"Error executing tool '{name}': {str(e)}",
+                "status": "error",
+            }

agent_sdk/core/driver.py

@@ -0,0 +1,46 @@
+from abc import ABC, abstractmethod
+from typing import Any, AsyncGenerator, List
+
+from .types import Message, StreamEvent, ToolDefinition
+
+
+class AgentDriver(ABC):
+    """
+    The abstract base class that all specific CLI drivers must implement.
+    This acts as the 'Adapter' in our architecture.
+    """
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Initialize the underlying CLI process or connection."""
+        pass
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Terminate the underlying CLI process or connection."""
+        pass
+
+    @abstractmethod
+    def set_tools(self, tools: List[ToolDefinition]) -> None:
+        """Register tools with the underlying agent."""
+        pass
+
+    @abstractmethod
+    def set_system_prompt(self, prompt: str) -> None:
+        """Set the system instruction."""
+        pass
+
+    @abstractmethod
+    async def chat(self, messages: List[Message]) -> AsyncGenerator[StreamEvent, None]:
+        """
+        Send a conversation history to the agent and yield events back.
+        """
+        pass
+
+    @abstractmethod
+    async def send_tool_result(self, call_id: str, result: Any) -> None:
+        """
+        Send the result of a tool execution back to the agent
+        (required by some protocols like JSON-RPC).
+        """
+        pass

agent_sdk/core/types.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class Role(Enum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+@dataclass
+class Message:
+    role: Role
+    content: str
+    name: Optional[str] = None
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+
+
+@dataclass
+class ToolDefinition:
+    name: str
+    description: str
+    parameters: Dict[str, Any]  # JSON Schema
+    function: callable = field(repr=False)
+
+
+class AgentEvent(Enum):
+    START = "start"
+    THOUGHT = "thought"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    CONTENT = "content"
+    DONE = "done"
+    ERROR = "error"
+
+
+@dataclass
+class StreamEvent:
+    type: AgentEvent
+    payload: Any
+
+
+# Backward-compatible alias
+EventType = AgentEvent

agent_sdk/drivers/cli_json_driver.py

@@ -0,0 +1,116 @@
+import asyncio
+import json
+from typing import Any, AsyncGenerator, Dict, List, Optional
+
+from ..core.driver import AgentDriver
+from ..core.types import AgentEvent, Message, Role, StreamEvent, ToolDefinition
+
+
+class CliJsonDriver(AgentDriver):
+    """
+    A generic driver for AI CLIs that output Newline-Delimited JSON (JSONL).
+    Examples: gemini -o stream-json, copilot --stream-json (hypothetical)
+    """
+
+    def __init__(
+        self,
+        executable_path: str,
+        base_args: List[str] = None,
+        session_id: Optional[str] = None,
+    ):
+        self.executable_path = executable_path
+        self.base_args = base_args or []
+        self.session_id = session_id
+        self.tools: List[ToolDefinition] = []
+        self.system_instruction: str = ""
+
+    async def start(self) -> None:
+        try:
+            process = await asyncio.create_subprocess_exec(
+                self.executable_path,
+                "--version",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            await process.wait()
+        except FileNotFoundError as e:
+            raise RuntimeError(f"CLI not found at '{self.executable_path}'") from e
+
+    async def stop(self) -> None:
+        pass
+
+    def set_tools(self, tools: List[ToolDefinition]) -> None:
+        self.tools = tools
+
+    def set_system_prompt(self, prompt: str) -> None:
+        self.system_instruction = prompt
+
+    async def chat(self, messages: List[Message]) -> AsyncGenerator[StreamEvent, None]:
+        last_message = messages[-1]
+        if last_message.role != Role.USER:
+            return
+
+        cmd = [self.executable_path] + self.base_args
+
+        # This part is still a bit tool-specific (session resume)
+        # But we can generalize it with a hook or specific args
+        if self.session_id:
+            # Standardizing on --resume if possible, or skip
+            cmd.extend(["--resume", self.session_id])
+
+        cmd.append(last_message.content)
+
+        process = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+
+        if process.stdout:
+            async for line in process.stdout:
+                line_text = line.decode("utf-8").strip()
+                if not line_text:
+                    continue
+
+                try:
+                    data = json.loads(line_text)
+                    # We expect the CLI to follow a standard event format:
+                    # {"type": "content|tool_use|...", "content": "..."}
+                    # If it follows Gemini's format, we map it:
+                    for event in self._map_event(data):
+                        yield event
+                except json.JSONDecodeError:
+                    pass
+        await process.wait()
+        if process.returncode != 0:
+            stderr = await process.stderr.read()
+            yield StreamEvent(
+                type=AgentEvent.ERROR, payload=f"CLI failed: {stderr.decode()}"
+            )
+
+    def _map_event(self, data: Dict[str, Any]) -> List[StreamEvent]:
+        # Mapping logic (can be overridden by subclasses)
+        # For now, default to Gemini-style
+        res = []
+        t = data.get("type")
+        if t == "init":
+            self.session_id = data.get("session_id")
+        elif t == "message" and data.get("role") == "assistant":
+            res.append(
+                StreamEvent(type=AgentEvent.CONTENT, payload=data.get("content"))
+            )
+        elif t == "tool_use":
+            res.append(
+                StreamEvent(
+                    type=AgentEvent.TOOL_CALL,
+                    payload={
+                        "name": data.get("tool_name"),
+                        "arguments": data.get("parameters"),
+                        "id": data.get("tool_id"),
+                    },
+                )
+            )
+        elif t == "result":
+            res.append(StreamEvent(type=AgentEvent.DONE, payload=None))
+        return res
+
+    async def send_tool_result(self, call_id: str, result: Any) -> None:
+        pass

agent_sdk/drivers/copilot_driver.py

@@ -0,0 +1,281 @@
+import asyncio
+from typing import Any, AsyncGenerator, Callable, List, Optional
+
+from ..core.driver import AgentDriver
+from ..core.types import AgentEvent, Message, StreamEvent, ToolDefinition
+from ..utils.jsonrpc import JsonRpcClient
+
+
+class CopilotDriver(AgentDriver):
+    """
+    Driver for GitHub Copilot CLI, strictly aligned with Official SDK logic.
+    """
+
+    def __init__(
+        self,
+        executable_path: str = "copilot",
+        cli_path: Optional[str] = None,
+        session_id: Optional[str] = None,
+        model: Optional[str] = None,
+        cwd: Optional[str] = None,
+        env: Optional[dict] = None,
+        mcp_servers: Optional[dict] = None,
+        custom_agents: Optional[List[dict]] = None,
+        on_permission_request: Optional[Callable] = None,
+        skill_directories: Optional[List[str]] = None,
+        excluded_tools: Optional[List[str]] = None,
+        system_message: Optional[dict] = None,
+    ):
+        # Allow either executable_path or cli_path for flexibility
+        path = cli_path or executable_path
+        # Official SDK uses: --server --log-level info --stdio
+        full_command = f"{path} --server --log-level info --stdio"
+        self.client = JsonRpcClient(full_command, cwd=cwd, env=env)
+        self.tools: List[ToolDefinition] = []
+        self.session_id = session_id
+        self.model = model
+        self.system_prompt: str = ""
+        self._is_resumed = False if session_id is None else True
+
+        # Extended configuration
+        self.mcp_servers = mcp_servers
+        self.custom_agents = custom_agents
+        self.on_permission_request = on_permission_request
+        self.skill_directories = skill_directories
+        self.excluded_tools = excluded_tools
+        self.system_message = system_message
+
+    async def start(self) -> None:
+        # 1. Start Subprocess
+        await self.client.start()
+
+        # 2. Ping (Official Handshake)
+        try:
+            await self.client.request("ping", {"message": "hello"})
+        except Exception as e:
+            raise RuntimeError(f"Failed to connect to Copilot CLI: {e}") from e
+
+    async def create_session(self) -> str:
+        """Explicitly create a new session."""
+        payload = {}
+        if self.system_message:
+            payload["system_message"] = self.system_message
+        elif self.system_prompt:
+            payload["config"] = {"system_prompt": self.system_prompt}
+        else:
+            payload["config"] = {"system_prompt": ""}
+
+        if self.model:
+            payload["model"] = self.model
+        if self.tools:
+            payload["tools"] = [
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "parameters": t.parameters,
+                }
+                for t in self.tools
+            ]
+        if self.mcp_servers:
+            payload["mcp_servers"] = self.mcp_servers
+        if self.custom_agents:
+            payload["custom_agents"] = self.custom_agents
+        if self.skill_directories:
+            payload["skill_directories"] = self.skill_directories
+        if self.excluded_tools:
+            payload["excluded_tools"] = self.excluded_tools
+
+        res = await self.client.request("session.create", payload)
+        self.session_id = res.get("sessionId")
+        self._is_resumed = False
+        return self.session_id
+
+    async def destroy_session(self, session_id: str) -> None:
+        """Explicitly destroy a session."""
+        await self.client.request("session.destroy", {"sessionId": session_id})
+        if self.session_id == session_id:
+            self.session_id = None
+
+    async def get_messages(self, session_id: str) -> List[dict]:
+        """Get messages for a session."""
+        res = await self.client.request(
+            "session.getMessages", {"sessionId": session_id}
+        )
+        return res.get("messages", [])
+
+    async def _ensure_session(self):
+        """Internal helper to ensure session is active."""
+        if self.session_id and self._is_resumed:
+            # We already have a session ID and it was intended to be resumed.
+            # Official SDK calls 'session.resume'
+            payload = {"sessionId": self.session_id}
+            if self.tools:
+                payload["tools"] = [
+                    {
+                        "name": t.name,
+                        "description": t.description,
+                        "parameters": t.parameters,
+                    }
+                    for t in self.tools
+                ]
+            if self.mcp_servers:
+                payload["mcp_servers"] = self.mcp_servers
+            if self.custom_agents:
+                payload["custom_agents"] = self.custom_agents
+            if self.skill_directories:
+                payload["skill_directories"] = self.skill_directories
+            if self.excluded_tools:
+                payload["excluded_tools"] = self.excluded_tools
+            if self.system_message:
+                payload["system_message"] = self.system_message
+
+            try:
+                res = await self.client.request("session.resume", payload)
+                self.session_id = res.get("sessionId")
+                self._is_resumed = False  # Mark as active
+            except Exception as e:
+                print(
+                    f"[CopilotDriver] Warning: Failed to resume session "
+                    f"{self.session_id}: {e}"
+                )
+                # Fallback to create
+                self.session_id = None
+
+        if not self.session_id:
+            await self.create_session()
+
+    async def stop(self) -> None:
+        if self.session_id:
+            try:
+                await self.client.request(
+                    "session.destroy", {"sessionId": self.session_id}
+                )
+            except Exception:
+                pass
+        await self.client.stop()
+
+    def set_tools(self, tools: List[ToolDefinition]) -> None:
+        self.tools = tools
+
+    def set_system_prompt(self, prompt: str) -> None:
+        self.system_prompt = prompt
+
+    async def chat(self, messages: List[Message]) -> AsyncGenerator[StreamEvent, None]:
+        # Ensure we have an active session
+        await self._ensure_session()
+
+        last_message = messages[-1]
+
+        # 3. session.send (Official Request)
+        # Official SDK returns messageId
+        await self.client.request(
+            "session.send",
+            {"sessionId": self.session_id, "prompt": last_message.content},
+        )
+
+        # 4. Event Loop (Official Events)
+        # Events come as notifications with method 'session.event'
+        while True:
+            notification = await self.client.get_notification()
+            print(f"[CopilotDriver] Received notification: {notification}")
+
+            # Handle Server Requests (Tools)
+            if notification.get("type") == "server_request":
+                payload = notification.get("payload")
+                method = payload.get("method")
+                req_id = payload.get("id")
+                params = payload.get("params", {})
+
+                if method == "tool.call":
+                    # Official method name is 'tool.call'
+                    # The 'id' must be the RPC request ID so we can respond correctly.
+
+                    # Handle permission if callback is provided
+                    if self.on_permission_request:
+                        req = {
+                            "kind": params.get("toolName"),  # Simplified for now
+                            "toolCallId": params.get("toolCallId"),
+                        }
+                        # Add more details if it's a known tool type
+                        if params.get("toolName") in ["edit", "create", "delete"]:
+                            req["kind"] = "write"
+                        elif params.get("toolName") == "shell":
+                            req["kind"] = "shell"
+
+                        # Call the handler (could be sync or async)
+                        if asyncio.iscoroutinefunction(self.on_permission_request):
+                            perm_res = await self.on_permission_request(
+                                req, {"session_id": self.session_id}
+                            )
+                        else:
+                            perm_res = self.on_permission_request(
+                                req, {"session_id": self.session_id}
+                            )
+
+                        if perm_res.get("kind") != "approved":
+                            # If not approved, we send a failure response immediately
+                            await self.client.send_response(
+                                req_id,
+                                result={
+                                    "toolCallId": params.get("toolCallId"),
+                                    "result": {
+                                        "resultType": "failure",
+                                        "error": "Permission denied by user",
+                                    },
+                                },
+                            )
+                            continue
+
+                    yield StreamEvent(
+                        type=AgentEvent.TOOL_CALL,
+                        payload={
+                            "name": params.get("toolName"),
+                            "arguments": params.get("arguments"),
+                            "id": req_id,
+                            "toolCallId": params.get("toolCallId"),
+                        },
+                    )
+                continue
+
+            # Handle Notifications
+            method = notification.get("method")
+            params = notification.get("params", {})
+
+            if method == "session.event":
+                event = params.get("event", {})
+                event_type = event.get("type")
+                data = event.get("data", {})
+
+                if event_type == "assistant.message":
+                    content = data.get("content", "")
+                    if content:
+                        yield StreamEvent(type=AgentEvent.CONTENT, payload=content)
+
+                elif event_type == "session.idle":
+                    yield StreamEvent(type=AgentEvent.DONE, payload={})
+                    break
+
+                elif event_type == "session.error":
+                    yield StreamEvent(
+                        type=AgentEvent.ERROR, payload=data.get("message")
+                    )
+                    break
+
+            elif method == "log":
+                yield StreamEvent(
+                    type=AgentEvent.THOUGHT, payload=params.get("message")
+                )
+
+    async def send_tool_result(self, call_info: Any, result: Any) -> None:
+        """Official SDK requirement: send tool execution result back via RPC."""
+        # call_info is the payload from AgentEvent.TOOL_CALL
+        req_id = call_info.get("id")
+        tool_call_id = call_info.get("toolCallId")
+
+        # Official protocol nesting:
+        # { result: { toolCallId: ..., result: { resultType: success, ... } } }
+        wrapped_result = {
+            "toolCallId": tool_call_id,
+            "result": {"resultType": "success", "textResultForLlm": str(result)},
+        }
+        await self.client.send_response(req_id, result=wrapped_result)

agent_sdk/drivers/gemini_driver.py

@@ -0,0 +1,77 @@
+from typing import Any, Dict, List, Optional
+
+from ..core.types import AgentEvent, StreamEvent
+from .cli_json_driver import CliJsonDriver
+
+
+class GeminiDriver(CliJsonDriver):
+    """
+    Driver for Gemini CLI (The "Agentic" CLI).
+    Fully leverages the local 'gemini' binary as the runtime engine.
+    """
+
+    def __init__(
+        self, executable_path: str = "gemini", session_id: Optional[str] = None
+    ):
+        # We use -o stream-json to get machine-readable output from the CLI
+        super().__init__(
+            executable_path, base_args=["-o", "stream-json"], session_id=session_id
+        )
+
+    def _map_event(self, data: Dict[str, Any]) -> List[StreamEvent]:
+        """
+        Maps Gemini CLI's specific JSONL events to universal SDK events.
+        """
+        res = []
+        t = data.get("type")
+
+        if t == "init":
+            self.session_id = data.get("session_id")
+
+        elif t == "message":
+            if data.get("role") == "assistant" and data.get("content"):
+                res.append(
+                    StreamEvent(type=AgentEvent.CONTENT, payload=data.get("content"))
+                )
+
+        elif t == "tool_use":
+            # Surfacing Gemini's internal tool usage as a THOUGHT or TOOL_CALL
+            # In Gemini CLI, the CLI executes the tool itself.
+            # We report it so the SDK user knows what's happening.
+            res.append(
+                StreamEvent(
+                    type=AgentEvent.THOUGHT,
+                    payload=f"Executing built-in tool: {data.get('tool_name')}",
+                )
+            )
+            res.append(
+                StreamEvent(
+                    type=AgentEvent.TOOL_CALL,
+                    payload={
+                        "name": data.get("tool_name"),
+                        "arguments": data.get("parameters"),
+                        "id": data.get("tool_id"),
+                    },
+                )
+            )
+
+        elif t == "tool_result":
+            # Report the result of the built-in tool
+            res.append(
+                StreamEvent(
+                    type=AgentEvent.TOOL_RESULT,
+                    payload={"id": data.get("tool_id"), "result": data.get("output")},
+                )
+            )
+
+        elif t == "result":
+            res.append(StreamEvent(type=AgentEvent.DONE, payload=None))
+
+        return res
+
+    async def send_tool_result(self, call_id: str, result: Any) -> None:
+        """
+        Gemini CLI handles its own tools. This is a no-op for the CLI driver.
+        (If we want custom Python tools, we'd use GeminiRestDriver).
+        """
+        pass

agent_sdk/drivers/mock_driver.py

@@ -0,0 +1,80 @@
+import asyncio
+from typing import Any, AsyncGenerator, List
+
+from ..core.driver import AgentDriver
+from ..core.types import AgentEvent, Message, Role, StreamEvent, ToolDefinition
+
+
+class MockDriver(AgentDriver):
+    """
+    A simple Echo driver for testing the SDK without a real CLI.
+    """
+
+    def __init__(self):
+        self.tools = []
+        self.system_prompt = ""
+
+    async def start(self) -> None:
+        print("[MockDriver] Starting...")
+
+    async def stop(self) -> None:
+        print("[MockDriver] Stopping...")
+
+    def set_tools(self, tools: List[ToolDefinition]) -> None:
+        self.tools = tools
+        print(f"[MockDriver] Registered {len(tools)} tools.")
+
+    def set_system_prompt(self, prompt: str) -> None:
+        self.system_prompt = prompt
+        print(f"[MockDriver] System prompt set: {prompt[:20]}...")
+
+    async def chat(self, messages: List[Message]) -> AsyncGenerator[StreamEvent, None]:
+        last_message = messages[-1]
+
+        # If the last message was a tool result, acknowledge it
+        if last_message.role == Role.TOOL:
+            yield StreamEvent(type=AgentEvent.START, payload=None)
+            yield StreamEvent(
+                type=AgentEvent.THOUGHT, payload="I received the tool output."
+            )
+            response = f"The tool result was: {last_message.content}"
+            yield StreamEvent(type=AgentEvent.CONTENT, payload=response)
+            yield StreamEvent(type=AgentEvent.DONE, payload=None)
+            return
+
+        content = last_message.content.lower()
+
+        yield StreamEvent(type=AgentEvent.START, payload=None)
+
+        # Simulate "thinking"
+        yield StreamEvent(type=AgentEvent.THOUGHT, payload="Processing request...")
+        await asyncio.sleep(0.2)
+
+        # Basic logic to simulate tool calling behavior
+        if "weather" in content:
+            # Simulate a tool call request from the agent
+            tool_call_id = "call_123"
+            yield StreamEvent(
+                type=AgentEvent.THOUGHT, payload="I need to check the weather."
+            )
+
+            # Yield a tool call event
+            # In a real driver, this comes from the model
+            yield StreamEvent(
+                type=AgentEvent.TOOL_CALL,
+                payload={
+                    "id": tool_call_id,
+                    "name": "get_weather",
+                    "arguments": {"location": "New York"},
+                },
+            )
+            return
+
+        # Default Echo behavior
+        response = f"Echo: {last_message.content}"
+        yield StreamEvent(type=AgentEvent.CONTENT, payload=response)
+
+        yield StreamEvent(type=AgentEvent.DONE, payload=None)
+
+    async def send_tool_result(self, call_id: str, result: Any) -> None:
+        print(f"[MockDriver] Received tool result for {call_id}: {result}")

agent_sdk/utils/jsonrpc.py

@@ -0,0 +1,178 @@
+import asyncio
+import json
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class JsonRpcClient:
+    """
+    A generic async JSON-RPC 2.0 client that communicates over stdio with a subprocess.
+    """
+
+    def __init__(
+        self, command: str, cwd: Optional[str] = None, env: Optional[dict] = None
+    ):
+        self.command = command
+        self.cwd = cwd
+        self.env = env
+        self.process: Optional[asyncio.subprocess.Process] = None
+        self._request_id = 0
+        self._pending_requests: Dict[int, asyncio.Future] = {}
+        self._read_task: Optional[asyncio.Task] = None
+        self._notification_queue = asyncio.Queue()
+
+    async def start(self):
+        """Starts the subprocess."""
+        self.process = await asyncio.create_subprocess_shell(
+            self.command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=self.cwd,
+            env=self.env,
+        )
+        self._read_task = asyncio.create_task(self._read_loop())
+        logger.info(f"Started JSON-RPC process: {self.command}")
+
+    async def stop(self):
+        """Stops the subprocess."""
+        if self.process:
+            if self.process.returncode is None:
+                self.process.terminate()
+                try:
+                    await asyncio.wait_for(self.process.wait(), timeout=2.0)
+                except asyncio.TimeoutError:
+                    self.process.kill()
+            self.process = None
+
+        if self._read_task:
+            self._read_task.cancel()
+            try:
+                await self._read_task
+            except asyncio.CancelledError:
+                pass
+
+    async def request(self, method: str, params: Any = None) -> Any:
+        """Sends a JSON-RPC request and awaits the result."""
+        if not self.process:
+            raise RuntimeError("Process not running")
+
+        req_id = self._request_id
+        self._request_id += 1
+
+        payload = {"jsonrpc": "2.0", "method": method, "params": params, "id": req_id}
+
+        future = asyncio.get_running_loop().create_future()
+        self._pending_requests[req_id] = future
+
+        await self._send(payload)
+        return await future
+
+    async def notify(self, method: str, params: Any = None):
+        """Sends a JSON-RPC notification (no response expected)."""
+        payload = {"jsonrpc": "2.0", "method": method, "params": params}
+        await self._send(payload)
+
+    async def get_notification(self) -> Dict[str, Any]:
+        """Waits for the next notification from the server."""
+        return await self._notification_queue.get()
+
+    async def _send(self, payload: Dict[str, Any]):
+        json_body = json.dumps(payload).encode("utf-8")
+        # LSP-style framing: Content-Length header + \r\n\r\n + body
+        header = f"Content-Length: {len(json_body)}\r\n\r\n".encode("ascii")
+
+        print(f"[JsonRpc] Sending: {payload}")
+        if self.process and self.process.stdin:
+            self.process.stdin.write(header + json_body)
+            await self.process.stdin.drain()
+
+    async def _read_loop(self):
+        """Reads stdout using Hybrid framing (LSP or NDJSON)."""
+        if not self.process or not self.process.stdout:
+            return
+
+        try:
+            while True:
+                line = await self.process.stdout.readline()
+                if not line:
+                    logger.info("[JsonRpc] EOF reached")
+                    break
+
+                line_str = line.decode("utf-8", errors="ignore").strip()
+                if not line_str:
+                    continue
+
+                # 1. Check for LSP Header
+                if line_str.lower().startswith("content-length:"):
+                    try:
+                        content_length = int(line_str.split(":", 1)[1].strip())
+                        # Skip the following empty line (\r\n)
+                        await self.process.stdout.readline()
+                        # Read exact body
+                        body_bytes = await self.process.stdout.readexactly(
+                            content_length
+                        )
+                        message = json.loads(body_bytes.decode("utf-8"))
+                        self._handle_message(message)
+                    except Exception as e:
+                        logger.error(f"[JsonRpc] Error parsing LSP: {e}")
+                    continue
+
+                # 2. Check for NDJSON (Line starting with {)
+                if line_str.startswith("{"):
+                    try:
+                        message = json.loads(line_str)
+                        self._handle_message(message)
+                    except json.JSONDecodeError:
+                        logger.warning(f"[JsonRpc] Failed to decode NDJSON: {line_str}")
+                    continue
+
+                # 3. Otherwise, treat as log or noise
+                logger.debug(f"[JsonRpc] Log/Noise: {line_str}")
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error(f"[JsonRpc] Read loop error: {e}")
+        finally:
+            # Cleanup pending requests to avoid permanent hangs
+            for _, future in self._pending_requests.items():
+                if not future.done():
+                    future.set_exception(RuntimeError("Connection closed"))
+            self._pending_requests.clear()
+            # Also put a sentinel in notification queue if needed?
+            # Better to let the consumer handle the closed process.
+
+    def _handle_message(self, message: Dict[str, Any]):
+        print(f"[JsonRpc] Internal handle: {message}")
+        if "id" in message:
+            req_id = message["id"]
+            if req_id in self._pending_requests:
+                # It's a response to OUR request
+                future = self._pending_requests.pop(req_id)
+                if "error" in message:
+                    future.set_exception(Exception(message["error"]))
+                else:
+                    future.set_result(message.get("result"))
+            else:
+                # It's a request FROM the server (Client-side tool execution)
+                # We need to handle this. For now, we put it in the notification queue
+                # but mark it as a request so the consumer knows to reply.
+                self._notification_queue.put_nowait(
+                    {"type": "server_request", "payload": message}
+                )
+        else:
+            # It's a notification or log
+            self._notification_queue.put_nowait(message)
+
+    async def send_response(self, req_id: Any, result: Any = None, error: Any = None):
+        """Sends a JSON-RPC response back to the server."""
+        payload = {"jsonrpc": "2.0", "id": req_id}
+        if error:
+            payload["error"] = error
+        else:
+            payload["result"] = result
+
+        await self._send(payload)

agent_sdk/utils/schema.py

@@ -0,0 +1,48 @@
+import inspect
+from typing import Any, Callable, Dict, get_type_hints
+
+
+def python_type_to_json_type(py_type: Any) -> str:
+    if py_type is str:
+        return "string"
+    elif py_type is int:
+        return "integer"
+    elif py_type is float:
+        return "number"
+    elif py_type is bool:
+        return "boolean"
+    elif py_type is list:
+        return "array"
+    elif py_type is dict:
+        return "object"
+    # Default fallback
+    return "string"
+
+
+def generate_tool_schema(func: Callable) -> Dict[str, Any]:
+    """
+    Generates a JSON Schema for a Python function's arguments.
+    Follows the OpenAI/Gemini tool definition convention.
+    """
+    sig = inspect.signature(func)
+    type_hints = get_type_hints(func)
+
+    properties = {}
+    required = []
+
+    for param_name, param in sig.parameters.items():
+        if param_name == "self" or param_name == "cls":
+            continue
+
+        param_type = type_hints.get(param_name, str)  # Default to string if no hint
+        json_type = python_type_to_json_type(param_type)
+
+        properties[param_name] = {
+            "type": json_type,
+            "description": f"Parameter {param_name}",  # Ideally parse from docstring
+        }
+
+        if param.default == inspect.Parameter.empty:
+            required.append(param_name)
+
+    return {"type": "object", "properties": properties, "required": required}