agent-shell-py 0.1.0__tar.gz

agent_shell_py-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: agent-shell-py
+Version: 0.1.0
+Summary: A lightweight abstraction for executing CLI coding agents headlessly
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Agent Shell
+Agent Shell is a light weight abstraction for executing a cli coding agent headlessly
+and returning the output that can be used programatically as a unified contract
+
+## Examples
+
+### Execute
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Can you tell me about this project?",
+    allowed_tools=["Read", "Glob", "Grep"],
+    model="sonnet",
+)
+
+print(response.response)
+print(f"Cost: ${response.cost:.4f}")
+```
+
+### Stream
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+async for event in shell.stream(
+    cwd="/path/to/project",
+    prompt="Refactor the auth module",
+    allowed_tools=["Read", "Edit", "Bash"],
+    model="sonnet",
+    effort="high",
+    include_thinking=True,
+):
+    print(f"[{event.type}] {event.content}")
+```
+
+## Supported CLI Agents:
+
+- [x] Claude Code
+- [ ] OpenCode
+- [ ] Gemini CLI
+- [ ] Copilot CLI
+- [ ] Codex
+
+
+
+

agent_shell_py-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Agent Shell
+Agent Shell is a light weight abstraction for executing a cli coding agent headlessly
+and returning the output that can be used programatically as a unified contract
+
+## Examples
+
+### Execute
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Can you tell me about this project?",
+    allowed_tools=["Read", "Glob", "Grep"],
+    model="sonnet",
+)
+
+print(response.response)
+print(f"Cost: ${response.cost:.4f}")
+```
+
+### Stream
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+async for event in shell.stream(
+    cwd="/path/to/project",
+    prompt="Refactor the auth module",
+    allowed_tools=["Read", "Edit", "Bash"],
+    model="sonnet",
+    effort="high",
+    include_thinking=True,
+):
+    print(f"[{event.type}] {event.content}")
+```
+
+## Supported CLI Agents:
+
+- [x] Claude Code
+- [ ] OpenCode
+- [ ] Gemini CLI
+- [ ] Copilot CLI
+- [ ] Codex
+
+
+
+

agent_shell_py-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "agent-shell-py"
+version = "0.1.0"
+description = "A lightweight abstraction for executing CLI coding agents headlessly"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "e2e: end-to-end tests that call real CLI agents (requires credentials, costs money)",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+]

agent_shell_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_shell_py-0.1.0/src/agent_shell/adapters/agent_adapter_protocol.py

@@ -0,0 +1,28 @@
+from typing import Protocol, AsyncIterator
+from agent_shell.models.agent import AgentResponse, StreamEvent
+
+class AgentAdapter(Protocol):
+    async def execute(
+            self, 
+            cwd: str, 
+            prompt: str, 
+            allowed_tools: list[str] | None = None, 
+            model: str | None = None,
+            effort: str | None = None,
+            include_thinking: bool = False,
+    ) -> AgentResponse:
+        ...
+
+    def stream(
+            self, 
+            cwd: str, 
+            prompt: str, 
+            allowed_tools: list[str] | None = None, 
+            model: str | None = None,
+            effort: str | None = None,
+            include_thinking: bool = False,
+    ) -> AsyncIterator[StreamEvent]:
+        ...
+
+    async def cancel(self) -> None:
+        ...

agent_shell_py-0.1.0/src/agent_shell/adapters/claude_code_adapter.py

@@ -0,0 +1,140 @@
+import asyncio 
+import json 
+import os
+from typing import AsyncIterator
+
+from agent_shell.models.agent import AgentResponse, StreamEvent
+
+class ClaudeCodeAdapter():
+    def __init__(self):
+        self._active_processes = []
+
+    async def execute(
+            self,
+            cwd: str,
+            prompt: str,
+            allowed_tools: list[str] | None = None,
+            model: str | None = None,
+            effort: str | None = None,
+            include_thinking: bool = False,
+    ) -> AgentResponse:
+        chunks: list[StreamEvent] = []
+        async for event in self.stream(
+            cwd=cwd,
+            prompt=prompt,
+            allowed_tools=allowed_tools,
+            model=model,
+            effort=effort,
+            include_thinking=include_thinking,
+        ):
+            chunks.append(event)
+
+        text = "\n".join(e.content for e in chunks if e.type == "text")
+        cost = next((e.cost for e in reversed(chunks) if e.type == "result"), 0.0)
+        return AgentResponse(response=text, cost=cost)
+
+    async def stream(
+            self, 
+            cwd: str, 
+            prompt: str, 
+            allowed_tools: list[str] | None = None, 
+            model: str | None = None,
+            effort: str | None = None,
+            include_thinking: bool = False,
+    ) -> AsyncIterator[StreamEvent]:
+        cmd = [
+            "claude", "-p", prompt,
+           "--output-format", "stream-json",
+            "--verbose"
+        ]
+
+        if allowed_tools:
+            cmd.extend(["--allowed-tools", ",".join(allowed_tools)])
+
+        if model:
+            cmd.extend(["--model", model])
+        
+        if effort: 
+            cmd.extend(["--effort", effort])
+
+        process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=os.path.abspath(cwd),
+                preexec_fn=os.setsid,
+        )
+
+        self._active_processes.append(process)
+
+        buffer = ""
+        while True:
+            chunk = await process.stdout.read(65536)
+            if not chunk:
+                if buffer.strip():
+                    try:
+                        for event in self._parse_event(
+                            event=json.loads(buffer),
+                            include_thinking=include_thinking
+                            ):
+                                yield event
+                    except json.JSONDecodeError:
+                        pass
+                break
+
+            buffer += chunk.decode("utf-8")
+            while "\n" in buffer:
+                line, buffer = buffer.split("\n", 1)
+                if line.strip():
+                    try:
+                        for event in self._parse_event(
+                            event=json.loads(line),
+                            include_thinking=include_thinking):
+                            yield event
+                    except json.JSONDecodeError:
+                        pass
+
+        await process.wait()
+        if process in self._active_processes:
+            self._active_processes.remove(process)
+
+        stderr = await process.stderr.read()
+        if stderr and process.returncode != 0:
+            yield StreamEvent(type="error", content=stderr.decode("utf-8")[-500:])
+
+    def _parse_event(self, event: dict, include_thinking: bool) -> list[StreamEvent]:
+        t = event.get("type", "")
+        events = []
+
+        if t == "assistant":
+            for item in event.get("message", {}).get("content", []):
+                if item.get("type") == "text":
+                    events.append(StreamEvent(type="text", content=item["text"]))
+                elif item.get("type") == "tool_use":
+                    events.append(StreamEvent(type="tool_use", content=item.get("name", "")))
+                elif item.get("type") == "thinking" and include_thinking:
+                    events.append(StreamEvent(type="thinking", content=item.get("thinking", "")))
+
+        elif t == "result":
+            cost = event.get("total_cost_usd", 0) or 0
+            duration = (event.get("duration_ms", 0) or 0) / 1000
+            is_error = event.get("is_error", False)
+            status = "error" if is_error else "ok"
+            events.append(StreamEvent(type="result", content=status, cost=cost, duration=duration))
+
+        return events 
+
+    async def cancel(self) -> None:
+          for process in self._active_processes:
+              try:
+                  os.killpg(os.getpgid(process.pid), 9)
+              except ProcessLookupError:
+                  pass
+          self._active_processes.clear()
+
+                
+
+
+
+

agent_shell_py-0.1.0/src/agent_shell/models/agent.py

@@ -0,0 +1,22 @@
+from enum import StrEnum
+from dataclasses import dataclass
+
+class AgentType(StrEnum):
+    CLAUDE_CODE = "claude_code"
+    OPENCODE = "opencode"
+    GEMINI_CLI = "gemini_cli"
+    COPILOT_CLI = "copilot_cli"
+    CODEX = "codex"
+
+@dataclass
+class AgentResponse:
+    response: str 
+    cost: float 
+
+@dataclass 
+class StreamEvent:
+    type: str
+    content: str 
+    cost: float = 0.0
+    duration: float = 0.0
+

agent_shell_py-0.1.0/src/agent_shell/shell.py

@@ -0,0 +1,77 @@
+from pathlib import Path 
+from typing import AsyncIterator
+
+from agent_shell.models.agent import AgentType, AgentResponse, StreamEvent
+from agent_shell.adapters.agent_adapter_protocol import AgentAdapter
+from agent_shell.adapters.claude_code_adapter import ClaudeCodeAdapter
+
+
+class AgentShell():
+    def __init__(self, agent_type: AgentType):
+        self._adapter = self._resolve_adapter(agent_type=agent_type)
+
+    def _resolve_adapter(self, agent_type: AgentType) -> AgentAdapter:
+        adapters = {
+                AgentType.CLAUDE_CODE: ClaudeCodeAdapter
+        }
+        
+        adapter_cls = adapters.get(agent_type)
+
+        if not adapter_cls:
+            raise ValueError(f"Unsupported agent: {agent_type}")
+
+        return adapter_cls()
+
+    async def execute(
+            self,
+            cwd: str, 
+            prompt: str,
+            allowed_tools: list[str] | None = None,
+            model: str | None = None,
+            effort: str | None = None,
+            include_thinking: bool = False,
+    ) -> AgentResponse:
+
+        if not Path(cwd).is_dir():
+            raise ValueError(f"Directory does not exist: {cwd}") 
+
+        try: 
+            return await self._adapter.execute(
+                    cwd=cwd,
+                    prompt=prompt,
+                    allowed_tools=allowed_tools,
+                    model=model,
+                    effort=effort,
+                    include_thinking=include_thinking,
+            )
+        except KeyboardInterrupt:
+            await self._adapter.cancel()
+            raise
+
+    async def stream(
+            self,
+            cwd: str, 
+            prompt: str,
+            allowed_tools: list[str] | None = None,
+            model: str | None = None,
+            effort: str | None = None,
+            include_thinking: bool = False,
+    ) -> AsyncIterator[StreamEvent]:
+
+        if not Path(cwd).is_dir():
+            raise ValueError(f"Directory does not exist: {cwd}") 
+        
+        try:
+            async for chunk in self._adapter.stream(
+                    cwd=cwd,
+                    prompt=prompt,
+                    allowed_tools=allowed_tools,
+                    model=model,
+                    effort=effort,
+                    include_thinking=include_thinking,
+            ):
+                yield chunk
+        except KeyboardInterrupt:
+            await self._adapter.cancel()
+            raise
+

agent_shell_py-0.1.0/src/agent_shell_py.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: agent-shell-py
+Version: 0.1.0
+Summary: A lightweight abstraction for executing CLI coding agents headlessly
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Agent Shell
+Agent Shell is a light weight abstraction for executing a cli coding agent headlessly
+and returning the output that can be used programatically as a unified contract
+
+## Examples
+
+### Execute
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Can you tell me about this project?",
+    allowed_tools=["Read", "Glob", "Grep"],
+    model="sonnet",
+)
+
+print(response.response)
+print(f"Cost: ${response.cost:.4f}")
+```
+
+### Stream
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+async for event in shell.stream(
+    cwd="/path/to/project",
+    prompt="Refactor the auth module",
+    allowed_tools=["Read", "Edit", "Bash"],
+    model="sonnet",
+    effort="high",
+    include_thinking=True,
+):
+    print(f"[{event.type}] {event.content}")
+```
+
+## Supported CLI Agents:
+
+- [x] Claude Code
+- [ ] OpenCode
+- [ ] Gemini CLI
+- [ ] Copilot CLI
+- [ ] Codex
+
+
+
+

agent_shell_py-0.1.0/src/agent_shell_py.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/agent_shell/__init__.py
+src/agent_shell/shell.py
+src/agent_shell/adapters/__init__.py
+src/agent_shell/adapters/agent_adapter_protocol.py
+src/agent_shell/adapters/claude_code_adapter.py
+src/agent_shell/models/__init__.py
+src/agent_shell/models/agent.py
+src/agent_shell_py.egg-info/PKG-INFO
+src/agent_shell_py.egg-info/SOURCES.txt
+src/agent_shell_py.egg-info/dependency_links.txt
+src/agent_shell_py.egg-info/top_level.txt

agent_shell_py-0.1.0/src/agent_shell_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_shell_py-0.1.0/src/agent_shell_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_shell