agent-shell-py 0.3.1__tar.gz → 0.4.0__tar.gz

{agent_shell_py-0.3.1 → agent_shell_py-0.4.0}/AGENTS.md

@@ -17,6 +17,9 @@ classDiagram
         +add_mcp_server(spec) None
         +remove_mcp_server(name) None
         +list_mcp_servers() list~MCPServerSpec~
+        +add_package(spec, timeout) None
+        +list_packages() list~PackageSpec~
+        +remove_package(source, timeout) None
     }
 
     class AgentAdapter {
@@ -29,6 +32,9 @@ classDiagram
         +add_mcp_server(spec) None
         +remove_mcp_server(name) None
         +list_mcp_servers() list~MCPServerSpec~
+        +add_package(spec, timeout) None
+        +list_packages() list~PackageSpec~
+        +remove_package(source, timeout) None
     }
 
     class ClaudeCodeAdapter {
@@ -105,6 +111,21 @@ classDiagram
         +launch(command, cwd, env, stdin, isolation_policy) NativeRunHandle
     }
 
+    class HerdrExecutionHost {
+        <<experimental>>
+        +launch(command, cwd, env, stdin, isolation_policy) RunHandle
+    }
+
+    class TmuxExecutionHost {
+        <<experimental>>
+        +launch(command, cwd, env, stdin, isolation_policy) RunHandle
+    }
+
+    class TerminalWindowExecutionHost {
+        <<experimental>>
+        +launch(command, cwd, env, stdin, isolation_policy) RunHandle
+    }
+
     class IsolationPolicy {
         <<Protocol>>
         +prepare(command, env) PreparedLaunch
@@ -140,6 +161,9 @@ classDiagram
     AgentShell --> ExecutionHost : selects
     AgentShell --> IsolationPolicy : selects
     NativeExecutionHost ..|> ExecutionHost : satisfies
+    HerdrExecutionHost ..|> ExecutionHost : satisfies
+    TmuxExecutionHost ..|> ExecutionHost : satisfies
+    TerminalWindowExecutionHost ..|> ExecutionHost : satisfies
     NativeExecutionHost --> NativeRunHandle : creates
     NativeRunHandle ..|> RunHandle : satisfies
     NoIsolation ..|> IsolationPolicy : satisfies
@@ -157,15 +181,25 @@ classDiagram
 
 The adapter pattern uses Python's `Protocol` (structural typing) rather than ABC, so adapters satisfy the contract implicitly without inheritance. Each adapter translates agent-specific CLI flags and NDJSON output into the shared `StreamEvent`/`AgentResponse` models, while the selected `ExecutionHost` owns process creation and returns a per-run `RunHandle`.
 
+`HerdrExecutionHost`, `TmuxExecutionHost`, and `TerminalWindowExecutionHost` are experimental,
+opt-in APIs. Their constructors, placement options, supported platforms, and lifecycle behaviour
+may change in a later minor release. `NativeExecutionHost` remains the backwards-compatible
+default, and an unavailable experimental host never silently falls back to it.
+
 Execution location and protection are separate axes. Existing callers default to
 `NativeExecutionHost()` plus `NoIsolation()` when `AGENTSHELL_ISOLATION_POLICY` is unset. The
 environment accepts `none` or `linux-pid-namespace` as a process-wide construction default;
 explicit `isolation_policy=` takes precedence, and invalid or empty values raise `ValueError`.
 `LinuxPidNamespaceIsolation` is a direct signal boundary: a tiny init/reaper is PID 1 and the CLI
-is PID 2 or later, so child-namespace processes cannot see or signal AgentShell's ancestors. It
-requires Linux, `unshare`, and enabled unprivileged user/PID namespaces; an unavailable request
-raises `IsolationUnavailableError` and never falls back. This is not a general sandbox and does
-not restrict filesystem, credentials, network, tools, or resources. The host/policy applies to
+is PID 2 or later, so child-namespace processes cannot directly signal AgentShell's ancestors.
+The default `mount_proc=True` also hides those ancestors through a private `/proc` mount.
+Explicit `mount_proc=False` retains the PID boundary and descendant cleanup while inheriting the
+outer `/proc` view, exposing process metadata and potentially confusing tools that use its PIDs.
+It does not create a private mount namespace. The environment value `linux-pid-namespace` remains
+strict; each policy probes its own requested mode. It requires Linux, `unshare`, and enabled
+unprivileged user/PID namespaces; an unavailable request raises `IsolationUnavailableError` and
+never falls back. This is not a general sandbox and does not restrict filesystem, credentials,
+network, tools, or resources. The host/policy applies to
 `execute()`, `stream()`, and `health_check()`; model discovery and MCP configuration remain local.
 
 `output_tokens` is a cost measure — the billed output-token count, which **includes reasoning tokens** (billed at the output rate). Each adapter normalises this so the value is consistent across agents (e.g. OpenCode reports reasoning in a sibling field, so its adapter adds it back).
@@ -236,8 +270,12 @@ entries from `~/.claude.json` directly, avoiding the health checks and human-rea
 `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`. Pi manages capability via `pi install` extensions, which needs
-investigation before wiring up.
+raise `NotImplementedError`.
+
+## Package Management
+
+See [package management](docs/development/package_management.md) for the API, Pi behaviour,
+scope, and validation details.
 
 ## Test Philosophy
 

agent_shell_py-0.4.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: agent-shell-py
+Version: 0.4.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.4.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.