agent-shell-py 0.3.2__tar.gz → 0.5.0__tar.gz

{agent_shell_py-0.3.2 → agent_shell_py-0.5.0}/.github/workflows/build.yml

@@ -4,6 +4,13 @@ on:
   push:
     tags: ["v*"]
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -12,6 +19,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
@@ -20,10 +28,13 @@ jobs:
         run: uv python install 3.12
 
       - name: Install dependencies
-        run: uv sync --group dev && uv pip install -e .
+        run: uv sync --locked --group dev
+
+      - name: Check architecture boundaries
+        run: uv run --no-sync lint-imports --no-cache
 
       - name: Run unit and integration tests
-        run: uv run pytest tests/unit tests/integration -v
+        run: uv run --no-sync pytest tests/unit tests/integration -v
 
       - name: Build package
         run: uv build

{agent_shell_py-0.3.2 → agent_shell_py-0.5.0}/.github/workflows/ci.yml

@@ -6,15 +6,25 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.12"]
 
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
@@ -23,7 +33,10 @@ jobs:
         run: uv python install ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --group dev && uv pip install -e .
+        run: uv sync --locked --group dev
+
+      - name: Check architecture boundaries
+        run: uv run --no-sync lint-imports --no-cache
 
       - name: Run unit and integration tests
-        run: uv run pytest tests/unit tests/integration -v
+        run: uv run --no-sync pytest tests/unit tests/integration -v

{agent_shell_py-0.3.2 → agent_shell_py-0.5.0}/.gitignore

@@ -9,3 +9,12 @@ src/agent_shell/_version.py
 
 # Virtual environments
 .venv
+
+# Local Pi workspace data
+/.pi/
+
+# Local credentials
+/.env
+
+# Local SonarQube configuration and scanner output
+/.sonarqube/

agent_shell_py-0.5.0/AGENTS.md

@@ -0,0 +1,115 @@
+# Agent Shell
+
+A lightweight, async Python package that executes CLI coding agents headlessly and returns output
+through a unified interface. Each agent's CLI differences are hidden behind a common adapter
+protocol, so consuming code never changes regardless of which agent is running underneath.
+
+## Architecture
+
+Before any planning, discussion of solution or code change work begins, you must read the
+[architecture class diagram](docs/architecture/class_diagram.md). It documents the interfaces,
+execution hosts, isolation policies, interactive sessions, and API behaviour.
+
+Keep agent-specific CLI flags, raw output parsing, configuration formats, and workarounds in
+that agent's adapter or agent-specific helpers. Shared code must use protocols and normalised
+models, not agent-name branches, concrete-adapter checks, private adapter state, or copied
+agent-specific logic. Host-specific terminal/process details belong in execution hosts.
+Concrete agent-adapter imports are permitted only in `shell.py` for construction/selection;
+shared helpers under `adapters/` are not exempt. Import Linter contracts in `pyproject.toml`
+enforce the [dependency boundaries](docs/architecture/dependency_boundaries.md), including
+indirect imports. New inner code uses `ports/`, not implementation-bearing compatibility
+facades. New top-level modules and adapter helpers must be classified in the contracts.
+Review must still catch copied agent-specific logic and dynamic imports.
+If a shared contract cannot express a feature, discuss the boundary change before adding a
+workaround or weakening the test.
+
+## Supported Agents
+
+- [x] Claude Code
+- [x] OpenCode
+- [x] Copilot CLI
+- [x] Codex
+- [x] Pi
+- [x] Cursor
+- [x] Grok
+
+## MCP Server Configuration
+
+`AgentShell` exposes a unified API for registering MCP servers across all supported agents:
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType, MCPServerSpec, MCPServerType
+
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+await shell.add_mcp_server(MCPServerSpec(
+    name="forgetful",
+    type=MCPServerType.STDIO,
+    command="uvx",
+    args=["forgetful-ai"],
+    env={"FORGETFUL_API_KEY": "..."},
+))
+```
+
+All adapters write to user-scope configuration:
+
+| Agent | Mechanism | Location |
+|-------|-----------|----------|
+| Claude Code | `claude mcp add --scope user` subprocess | `~/.claude.json` (managed by CLI) |
+| OpenCode | direct JSON file write | `~/.config/opencode/opencode.json` |
+| Copilot CLI | direct JSON file write | `~/.copilot/mcp-config.json` |
+| Codex | `codex mcp add` subprocess | Codex config |
+| Cursor | direct JSON file write | `~/.cursor/mcp.json` |
+| Grok | `grok mcp add --scope user` subprocess | `~/.grok/config.toml` (managed by CLI) |
+
+Adds are idempotent (update existing entries with the same name). Cursor preserves native fields
+that `MCPServerSpec` cannot represent when an update keeps the same transport, and writes its file
+atomically with user-only permissions. Removes warn rather than raise when the named server is not
+found. Claude Code listing reads the user-scope `mcpServers`
+entries from `~/.claude.json` directly, avoiding the health checks and human-readable output of
+`claude mcp list`. Cursor manages user-scope MCP entries directly in `~/.cursor/mcp.json` because
+its `mcp` subcommands have no add/remove commands. Grok listing reads user-scope `mcp_servers`
+entries from `~/.grok/config.toml` directly for the same reason. Pi's MCP add/remove/list methods
+raise `NotImplementedError`.
+
+## Package Management
+
+See [package management](docs/development/package_management.md) for the API, Pi behaviour,
+scope, and validation details.
+
+## Test Philosophy
+
+Tests validate real functionality, not code coverage metrics. Three tiers, each with a distinct
+purpose:
+
+| Tier | Scope | Runs in CI | Real CLI calls |
+|------|-------|-----------|----------------|
+| **Unit** | Isolated parsing, adapter resolution, input validation | Yes | No |
+| **Integration** | Shell -> adapter -> parser, with mocked agent subprocess | Yes | No |
+| **E2E** | Real CLI calls; usually real API costs | No (local only) | Yes |
+
+The model-discovery E2E test is the exception: it calls all seven real CLIs but only reads
+metadata, so it sends no inference request and incurs no model-token cost.
+
+Integration tests mirror the E2E tests but substitute mocked subprocesses emitting captured CLI
+output fixtures. This lets CI validate the full class interaction chain without credentials or API
+spend. E2E tests remain local smoke tests for the real agents.
+
+All tests follow the **AAA pattern** (Arrange, Act, Assert).
+
+```bash
+# Architecture contracts (development dependency only)
+uv run --locked lint-imports --no-cache
+
+# CI suite (unit + integration, including deliberate boundary violations in temp copies)
+uv run --locked pytest tests/unit tests/integration -v
+
+# Full suite including E2E (requires agent CLI + credentials)
+uv run pytest -v
+```
+
+## CI/CD
+
+- **CI**: Runs architecture contracts and unit + integration tests on every push and PR
+- **Build**: Triggers on `v*` tags, runs contracts/tests then builds release artifacts

agent_shell_py-0.5.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: agent-shell-py
+Version: 0.5.0
+Summary: A lightweight abstraction for executing CLI coding agents headlessly
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+![AgentShell — run CLI coding agents from Python](docs/assets/agentshell-banner.png?v=rounded)
+
+<h1 align="center">Agent Shell</h1>
+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
+
+## Features
+
+- **One unified contract** — the same `execute`, `stream`, `health_check`, and
+  `list_models` API across every agent; swap the backend without changing consuming code.
+- **Seven CLI agents** — Claude Code, OpenCode, Copilot CLI, Codex, Pi, Cursor, and Grok
+  behind a common adapter protocol.
+- **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
+  or async-iterate normalized `StreamEvent`s with optional thinking/reasoning.
+- **Composable execution policy** — preserve native execution by default, or opt into Linux PID
+  namespace isolation without changing an agent adapter.
+- **Session resumption** — continue any conversation by passing back its `session_id`.
+- **Normalized cost & tokens** — consistent `cost` and `output_tokens` (reasoning included)
+  regardless of how each CLI reports them.
+- **Model discovery** — retrieve the exact account/workspace-aware model strings accepted by
+  each CLI, without inference calls, SDK dependencies, or static catalogs.
+- **Health checks** — confirm an agent + model combination actually works before you rely on
+  it, read from the event stream rather than unreliable exit codes.
+- **Portable tool control** — one canonical allow/deny vocabulary
+  (`bash, edit, read, web_search, web_fetch`) translated to each CLI's own tool names.
+- **Unified MCP management** — register, remove, and list MCP servers across agents through a
+  single API.
+- **Package management** — install/register, list, and remove harness packages through a shared
+  API, with Pi as the first supported agent.
+- **Async & dependency-free** — pure `asyncio`, zero runtime dependencies, Python 3.12+.
+
+## Installation
+
+```bash
+uv add agent-shell-py
+```
+
+or with pip:
+
+```bash
+pip install agent-shell-py
+```
+
+## Agent skills
+
+The repository includes reusable skills that teach coding agents how to use AgentShell:
+
+- `invoking-cli-agents` — invoke, stream, resume, and restrict CLI agents.
+- `delegating-code-review` — delegate an independent code review through AgentShell.
+
+Install them interactively with the Vercel Skills CLI:
+
+```bash
+npx skills add ScottRBK/agent-shell
+```
+
+Or install both skills globally for every coding agent supported by AgentShell:
+
+```bash
+npx skills add ScottRBK/agent-shell --global \
+  --skill '*' \
+  --agent claude-code opencode github-copilot codex pi cursor grok \
+  --yes
+```
+
+Install only the core AgentShell skill with:
+
+```bash
+npx skills add ScottRBK/agent-shell --skill invoking-cli-agents
+```
+
+The skills provide agent instructions. Install `agent-shell-py` and the chosen coding-agent CLIs
+separately.
+
+## 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}")
+print(f"Output tokens: {response.output_tokens}")  # billed output, reasoning included
+print(f"Session: {response.session_id}")
+
+# Resume the conversation using the session_id
+follow_up = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Now refactor the auth module based on your findings",
+    allowed_tools=["Read", "Edit", "Bash"],
+    model="sonnet",
+    session_id=response.session_id,
+)
+```
+
+> `output_tokens` is a cost measure: the billed output-token count, which **includes reasoning
+> tokens** (they are billed at the output rate). It is reported consistently across all adapters.
+
+See [more examples](docs/examples.md) for isolation and execution hosts, failure handling,
+streaming, model discovery, health checks, tool restrictions, MCP servers, packages, and logging.

agent_shell_py-0.5.0/README.md

@@ -0,0 +1,111 @@
+![AgentShell — run CLI coding agents from Python](docs/assets/agentshell-banner.png?v=rounded)
+
+<h1 align="center">Agent Shell</h1>
+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
+
+## Features
+
+- **One unified contract** — the same `execute`, `stream`, `health_check`, and
+  `list_models` API across every agent; swap the backend without changing consuming code.
+- **Seven CLI agents** — Claude Code, OpenCode, Copilot CLI, Codex, Pi, Cursor, and Grok
+  behind a common adapter protocol.
+- **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
+  or async-iterate normalized `StreamEvent`s with optional thinking/reasoning.
+- **Composable execution policy** — preserve native execution by default, or opt into Linux PID
+  namespace isolation without changing an agent adapter.
+- **Session resumption** — continue any conversation by passing back its `session_id`.
+- **Normalized cost & tokens** — consistent `cost` and `output_tokens` (reasoning included)
+  regardless of how each CLI reports them.
+- **Model discovery** — retrieve the exact account/workspace-aware model strings accepted by
+  each CLI, without inference calls, SDK dependencies, or static catalogs.
+- **Health checks** — confirm an agent + model combination actually works before you rely on
+  it, read from the event stream rather than unreliable exit codes.
+- **Portable tool control** — one canonical allow/deny vocabulary
+  (`bash, edit, read, web_search, web_fetch`) translated to each CLI's own tool names.
+- **Unified MCP management** — register, remove, and list MCP servers across agents through a
+  single API.
+- **Package management** — install/register, list, and remove harness packages through a shared
+  API, with Pi as the first supported agent.
+- **Async & dependency-free** — pure `asyncio`, zero runtime dependencies, Python 3.12+.
+
+## Installation
+
+```bash
+uv add agent-shell-py
+```
+
+or with pip:
+
+```bash
+pip install agent-shell-py
+```
+
+## Agent skills
+
+The repository includes reusable skills that teach coding agents how to use AgentShell:
+
+- `invoking-cli-agents` — invoke, stream, resume, and restrict CLI agents.
+- `delegating-code-review` — delegate an independent code review through AgentShell.
+
+Install them interactively with the Vercel Skills CLI:
+
+```bash
+npx skills add ScottRBK/agent-shell
+```
+
+Or install both skills globally for every coding agent supported by AgentShell:
+
+```bash
+npx skills add ScottRBK/agent-shell --global \
+  --skill '*' \
+  --agent claude-code opencode github-copilot codex pi cursor grok \
+  --yes
+```
+
+Install only the core AgentShell skill with:
+
+```bash
+npx skills add ScottRBK/agent-shell --skill invoking-cli-agents
+```
+
+The skills provide agent instructions. Install `agent-shell-py` and the chosen coding-agent CLIs
+separately.
+
+## 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}")
+print(f"Output tokens: {response.output_tokens}")  # billed output, reasoning included
+print(f"Session: {response.session_id}")
+
+# Resume the conversation using the session_id
+follow_up = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Now refactor the auth module based on your findings",
+    allowed_tools=["Read", "Edit", "Bash"],
+    model="sonnet",
+    session_id=response.session_id,
+)
+```
+
+> `output_tokens` is a cost measure: the billed output-token count, which **includes reasoning
+> tokens** (they are billed at the output rate). It is reported consistently across all adapters.
+
+See [more examples](docs/examples.md) for isolation and execution hosts, failure handling,
+streaming, model discovery, health checks, tool restrictions, MCP servers, packages, and logging.