agentshim 0.4.0__tar.gz → 0.5.1__tar.gz

agentshim-0.5.1/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --locked --dev
+      - run: bash scripts/format_code.sh --check
+      - run: bash scripts/check_errors.sh
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --locked --dev
+      - run: bash scripts/type_check.sh
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked --dev
+      - run: uv run pytest

agentshim-0.5.1/.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - run: uv sync --locked --group docs
+      - run: uv run mkdocs build --strict --site-dir site
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v5
+      - id: deployment
+        uses: actions/deploy-pages@v4

{agentshim-0.4.0 → agentshim-0.5.1}/.gitignore

@@ -4,3 +4,4 @@ __pycache__/
 .ruff_cache/
 dist/
 build/
+site/

{agentshim-0.4.0 → agentshim-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentshim
-Version: 0.4.0
+Version: 0.5.1
 Summary: Provider-agnostic coding-agent CLI shims
 Requires-Python: >=3.10
 Requires-Dist: litellm>=1.0.0
@@ -22,6 +22,7 @@ prompting, session resumption, event parsing, or MCP configuration.
 - a shared CLI agent abstraction with a provider registry
 - adapters for Claude Code, Codex, Gemini, and Opencode
 - stateful chat sessions that automatically resume provider-native threads
+- injectable command executors for custom process launching or sandboxing
 - MCP server config models for providers that support MCP
 - sandbox settings helpers for Claude Code
 - a lightweight LiteLLM client and subagent helper
@@ -152,7 +153,90 @@ agent = CodingAgent(provider="claude")
 reply = agent.generate("Return only the answer.", silent=True)
 ```
 
-### 3. Instantiate a Specific Provider Directly
+### 3. Run Commands Through a Custom Executor
+
+Provider classes accept an optional `executor=`. The executor controls binary
+lookup, CLI validation, and streaming process execution while `agentshim` keeps
+owning provider command construction, stdout/stderr parsing, session state, and
+event emission.
+
+This is useful when a caller needs to run the CLI somewhere other than the
+current host process, for example through an existing container, remote shell,
+or custom sandbox.
+
+```python
+from agentshim import (
+    CodexCodingAgent,
+    CommandHandle,
+    CommandRequest,
+    CommandResult,
+    CommandStreamSink,
+)
+
+
+class MyCommandHandle:
+    def terminate(self) -> None:
+        ...
+
+    def kill(self) -> None:
+        ...
+
+
+class MyExecutor:
+    def find_binary(self, binary_name: str, env: dict[str, str]) -> str:
+        # This value becomes request.argv[0]. Container or remote executors can
+        # return the binary name if lookup happens in the target runtime.
+        return binary_name
+
+    def check_binary(self, binary_path: str, env: dict[str, str], *, timeout: int) -> None:
+        # Raise RuntimeError if the target CLI is unavailable. No-op is fine
+        # when validation is not cheap or is handled by the runtime.
+        return None
+
+    def run(self, request: CommandRequest, sink: CommandStreamSink) -> CommandResult:
+        handle = MyCommandHandle()
+        sink.started(handle)
+
+        stdout = ""
+        stderr = ""
+
+        # Run request.argv in your target runtime, with request.stdin,
+        # request.cwd, request.env, and request.timeout. Stream each complete
+        # line as it arrives, preserving trailing newlines when present.
+        line = "streamed output\n"
+        stdout += line
+        sink.stdout(line)
+
+        return CommandResult(returncode=0, stdout=stdout, stderr=stderr)
+
+
+agent = CodexCodingAgent(executor=MyExecutor())
+```
+
+The default `HostCommandExecutor` preserves the normal local `subprocess`
+behavior. `CodingAgent(provider=..., executor=...)` forwards the same executor
+to the selected provider.
+
+Executor contract:
+
+- `CommandRequest.argv` is the complete provider CLI command. `argv[0]` is the
+  value returned by `find_binary`.
+- `CommandRequest.stdin` is the prompt text to write to the command's standard
+  input, then stdin should be closed.
+- `CommandRequest.cwd`, `env`, and `timeout` should be honored by the executor.
+- Call `sink.started(handle)` once after the command starts. The handle only
+  needs `terminate()` and `kill()`.
+- Call `sink.stdout(line)` and `sink.stderr(line)` as output is produced. Lines
+  should include trailing newlines when the underlying stream provided them.
+- Return `CommandResult(returncode, stdout, stderr)` after the command exits.
+  The returned text should match what was streamed through the sink.
+
+If you were using the pre-0.5 executor preview, replace
+`run_streaming(cmd, ..., on_stdout, on_stderr, on_process_started)` with
+`run(request, sink)`. The parser/event APIs remain internal; custom executors
+only provide a stable command runtime.
+
+### 4. Instantiate a Specific Provider Directly
 
 If you already know which backend you want, construct the provider class
 yourself.
@@ -174,7 +258,7 @@ The bundled provider classes are:
 - `GeminiCodingAgent`
 - `OpencodeCodingAgent`
 
-### 4. Configure MCP Servers
+### 5. Configure MCP Servers
 
 Claude Code and Codex can be configured with MCP servers by passing
 `HttpMcpServer` and `StdioMcpServer` objects at construction time.
@@ -251,13 +335,16 @@ Notes:
 - Registration is import-driven. Your provider is available only after the module defining it has been imported in the current Python process.
 - `list_providers()` returns canonical provider names only. Aliases resolve via `get_provider_class(...)` and `CodingAgent(provider=...)`.
 - `register_provider(...)` rejects invalid names, abstract classes, and accidental name collisions unless you pass `overwrite=True`.
-- If you want `CodingAgent(...)` to instantiate your provider, its constructor should accept the shared kwargs `model`, `event_handler`, `event_handlers`, `mcp_servers`, and `sandbox` as needed.
+- If you want `CodingAgent(...)` to instantiate your provider, its constructor should accept the shared kwargs `model`, `event_handler`, `event_handlers`, `mcp_servers`, `sandbox`, and `executor` as needed.
 - If your provider needs extra constructor arguments beyond the shared portable set, pass them via `backend_kwargs={...}` when constructing `CodingAgent(...)`.
 
 ## Development
 
 ```bash
 uv sync --dev
+bash scripts/format_code.sh --check
+bash scripts/check_errors.sh
+bash scripts/type_check.sh
 uv run pytest
 ```
 

{agentshim-0.4.0 → agentshim-0.5.1}/README.md

@@ -11,6 +11,7 @@ prompting, session resumption, event parsing, or MCP configuration.
 - a shared CLI agent abstraction with a provider registry
 - adapters for Claude Code, Codex, Gemini, and Opencode
 - stateful chat sessions that automatically resume provider-native threads
+- injectable command executors for custom process launching or sandboxing
 - MCP server config models for providers that support MCP
 - sandbox settings helpers for Claude Code
 - a lightweight LiteLLM client and subagent helper
@@ -141,7 +142,90 @@ agent = CodingAgent(provider="claude")
 reply = agent.generate("Return only the answer.", silent=True)
 ```
 
-### 3. Instantiate a Specific Provider Directly
+### 3. Run Commands Through a Custom Executor
+
+Provider classes accept an optional `executor=`. The executor controls binary
+lookup, CLI validation, and streaming process execution while `agentshim` keeps
+owning provider command construction, stdout/stderr parsing, session state, and
+event emission.
+
+This is useful when a caller needs to run the CLI somewhere other than the
+current host process, for example through an existing container, remote shell,
+or custom sandbox.
+
+```python
+from agentshim import (
+    CodexCodingAgent,
+    CommandHandle,
+    CommandRequest,
+    CommandResult,
+    CommandStreamSink,
+)
+
+
+class MyCommandHandle:
+    def terminate(self) -> None:
+        ...
+
+    def kill(self) -> None:
+        ...
+
+
+class MyExecutor:
+    def find_binary(self, binary_name: str, env: dict[str, str]) -> str:
+        # This value becomes request.argv[0]. Container or remote executors can
+        # return the binary name if lookup happens in the target runtime.
+        return binary_name
+
+    def check_binary(self, binary_path: str, env: dict[str, str], *, timeout: int) -> None:
+        # Raise RuntimeError if the target CLI is unavailable. No-op is fine
+        # when validation is not cheap or is handled by the runtime.
+        return None
+
+    def run(self, request: CommandRequest, sink: CommandStreamSink) -> CommandResult:
+        handle = MyCommandHandle()
+        sink.started(handle)
+
+        stdout = ""
+        stderr = ""
+
+        # Run request.argv in your target runtime, with request.stdin,
+        # request.cwd, request.env, and request.timeout. Stream each complete
+        # line as it arrives, preserving trailing newlines when present.
+        line = "streamed output\n"
+        stdout += line
+        sink.stdout(line)
+
+        return CommandResult(returncode=0, stdout=stdout, stderr=stderr)
+
+
+agent = CodexCodingAgent(executor=MyExecutor())
+```
+
+The default `HostCommandExecutor` preserves the normal local `subprocess`
+behavior. `CodingAgent(provider=..., executor=...)` forwards the same executor
+to the selected provider.
+
+Executor contract:
+
+- `CommandRequest.argv` is the complete provider CLI command. `argv[0]` is the
+  value returned by `find_binary`.
+- `CommandRequest.stdin` is the prompt text to write to the command's standard
+  input, then stdin should be closed.
+- `CommandRequest.cwd`, `env`, and `timeout` should be honored by the executor.
+- Call `sink.started(handle)` once after the command starts. The handle only
+  needs `terminate()` and `kill()`.
+- Call `sink.stdout(line)` and `sink.stderr(line)` as output is produced. Lines
+  should include trailing newlines when the underlying stream provided them.
+- Return `CommandResult(returncode, stdout, stderr)` after the command exits.
+  The returned text should match what was streamed through the sink.
+
+If you were using the pre-0.5 executor preview, replace
+`run_streaming(cmd, ..., on_stdout, on_stderr, on_process_started)` with
+`run(request, sink)`. The parser/event APIs remain internal; custom executors
+only provide a stable command runtime.
+
+### 4. Instantiate a Specific Provider Directly
 
 If you already know which backend you want, construct the provider class
 yourself.
@@ -163,7 +247,7 @@ The bundled provider classes are:
 - `GeminiCodingAgent`
 - `OpencodeCodingAgent`
 
-### 4. Configure MCP Servers
+### 5. Configure MCP Servers
 
 Claude Code and Codex can be configured with MCP servers by passing
 `HttpMcpServer` and `StdioMcpServer` objects at construction time.
@@ -240,13 +324,16 @@ Notes:
 - Registration is import-driven. Your provider is available only after the module defining it has been imported in the current Python process.
 - `list_providers()` returns canonical provider names only. Aliases resolve via `get_provider_class(...)` and `CodingAgent(provider=...)`.
 - `register_provider(...)` rejects invalid names, abstract classes, and accidental name collisions unless you pass `overwrite=True`.
-- If you want `CodingAgent(...)` to instantiate your provider, its constructor should accept the shared kwargs `model`, `event_handler`, `event_handlers`, `mcp_servers`, and `sandbox` as needed.
+- If you want `CodingAgent(...)` to instantiate your provider, its constructor should accept the shared kwargs `model`, `event_handler`, `event_handlers`, `mcp_servers`, `sandbox`, and `executor` as needed.
 - If your provider needs extra constructor arguments beyond the shared portable set, pass them via `backend_kwargs={...}` when constructing `CodingAgent(...)`.
 
 ## Development
 
 ```bash
 uv sync --dev
+bash scripts/format_code.sh --check
+bash scripts/check_errors.sh
+bash scripts/type_check.sh
 uv run pytest
 ```
 

{agentshim-0.4.0 → agentshim-0.5.1}/agentshim/__init__.py

@@ -1,8 +1,17 @@
 from .base import BaseAgentSession, BaseCodingAgent, CodingAgent, get_provider_class, list_providers, register_provider
 from .claude import ClaudeCodeCodingAgent
-from .copilot import CopilotCodingAgent
 from .codex import CodexCodingAgent
+from .copilot import CopilotCodingAgent
 from .events import CompositeEventHandler, ConsoleEventHandler, NullEventHandler
+from .executor import (
+    CallbackCommandStreamSink,
+    CommandExecutor,
+    CommandHandle,
+    CommandRequest,
+    CommandResult,
+    CommandStreamSink,
+    HostCommandExecutor,
+)
 from .gemini import GeminiCodingAgent
 from .mcp_config import HttpMcpServer, McpServerConfig, StdioMcpServer
 from .opencode import OpencodeCodingAgent
@@ -18,6 +27,13 @@ __all__ = [
     "CompositeEventHandler",
     "ConsoleEventHandler",
     "NullEventHandler",
+    "CallbackCommandStreamSink",
+    "CommandExecutor",
+    "CommandHandle",
+    "CommandRequest",
+    "CommandResult",
+    "CommandStreamSink",
+    "HostCommandExecutor",
     "CopilotCodingAgent",
     "CodexCodingAgent",
     "GeminiCodingAgent",

{agentshim-0.4.0 → agentshim-0.5.1}/agentshim/base.py

@@ -3,12 +3,15 @@ from __future__ import annotations
 import inspect
 import re
 from abc import ABC, abstractmethod
-from collections.abc import Callable, Sequence
-from typing import Any, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar, cast
 
-from agentshim.events import AgentEventHandler
-from agentshim.mcp_config import McpServerConfig
-from agentshim.sandbox import SandboxConfig
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from agentshim.events import AgentEventHandler
+    from agentshim.executor import CommandExecutor, CommandHandle
+    from agentshim.mcp_config import McpServerConfig
+    from agentshim.sandbox import SandboxConfig
 
 _T = TypeVar("_T")
 _READABLE_NAME_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
@@ -83,7 +86,7 @@ class BaseAgentSession(ABC):
         cwd: str | None = None,
         timeout: int | None = None,
         silent: bool | None = None,
-        on_process_started: Callable[[Any], None] | None = None,
+        on_process_started: Callable[[CommandHandle], None] | None = None,
     ) -> str:
         """Send ``prompt`` within an existing chat session."""
 
@@ -104,7 +107,7 @@ class ProviderRegistry:
         self._providers: dict[str, ProviderClass] = {}
         self._canonical_names: dict[str, str] = {}
 
-    def _normalize_name(self, name: str) -> str:
+    def _normalize_name(self, name: object) -> str:
         if not isinstance(name, str):
             raise TypeError(f"provider name must be a string, got {type(name).__name__}")
         normalized = name.strip().lower()
@@ -121,6 +124,9 @@ class ProviderRegistry:
         )
         return canonical, normalized_aliases
 
+    def validate_names(self, canonical_name: str, aliases: tuple[str, ...]) -> None:
+        self._normalize_names(canonical_name, aliases)
+
     def _validate_provider_class(self, cls: type[Any]) -> ProviderClass:
         if not inspect.isclass(cls):
             raise TypeError(f"registered provider must be a class, got {type(cls).__name__}")
@@ -185,7 +191,7 @@ def register_provider(
     *extra_names: str,
     aliases: tuple[str, ...] = (),
     overwrite: bool = False,
-) -> Callable[[type[_T]], _T]:
+) -> Callable[[type[_T]], type[_T]]:
     """Decorator to register a coding agent provider.
 
     Registration is import-driven: the decorated class becomes available only
@@ -199,14 +205,17 @@ def register_provider(
     """
 
     all_aliases = (*extra_names, *aliases)
-    _PROVIDER_REGISTRY._normalize_names(canonical_name, all_aliases)
-
-    def decorator(cls: type[_T]) -> _T:
-        return _PROVIDER_REGISTRY.register(
-            cls,
-            canonical_name=canonical_name,
-            aliases=all_aliases,
-            overwrite=overwrite,
+    _PROVIDER_REGISTRY.validate_names(canonical_name, all_aliases)
+
+    def decorator(cls: type[_T]) -> type[_T]:
+        return cast(
+            "type[_T]",
+            _PROVIDER_REGISTRY.register(
+                cls,
+                canonical_name=canonical_name,
+                aliases=all_aliases,
+                overwrite=overwrite,
+            ),
         )
 
     return decorator
@@ -237,6 +246,7 @@ class CodingAgent(BaseCodingAgent):
         event_handlers: Sequence[AgentEventHandler] | None = None,
         mcp_servers: Sequence[McpServerConfig] | None = None,
         sandbox: bool | SandboxConfig | None = False,
+        executor: CommandExecutor | None = None,
         backend_kwargs: dict[str, Any] | None = None,
     ) -> None:
         requested_provider = _PROVIDER_REGISTRY.get_canonical_name(provider)
@@ -254,6 +264,8 @@ class CodingAgent(BaseCodingAgent):
             portable_kwargs["mcp_servers"] = list(mcp_servers)
         if sandbox is not None and sandbox is not False:
             portable_kwargs["sandbox"] = sandbox
+        if executor is not None:
+            portable_kwargs["executor"] = executor
 
         advanced_kwargs = dict(backend_kwargs or {})
         overlapping_keys = sorted(portable_kwargs.keys() & advanced_kwargs.keys())
@@ -293,6 +305,17 @@ class CodingAgent(BaseCodingAgent):
     def event_handler(self, value: Any | None) -> None:
         self._backend.event_handler = value
 
+    @property
+    def last_usage(self) -> Any:
+        """Token/turn usage from the backend's most recent ``generate``.
+
+        ``generate`` writes usage onto the concrete backend, so the
+        portable wrapper must surface it here — otherwise callers holding a
+        ``CodingAgent`` (rather than the raw provider class) read a missing
+        attribute and lose all usage accounting.
+        """
+        return getattr(self._backend, "last_usage", None)
+
     def start_session(
         self,
         cwd: str | None = None,

{agentshim-0.4.0 → agentshim-0.5.1}/agentshim/claude/agent.py

@@ -1,12 +1,12 @@
 import json
-import subprocess
 import time
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Sequence
 from typing import Any
 
 from ..base import register_provider
 from ..cli_agent import CLICodingAgent, CLIGenerationSession
 from ..events import AgentEventHandler
+from ..executor import CommandExecutor, CommandHandle
 from ..mcp_config import HttpMcpServer, McpServerConfig
 from ..sandbox import SandboxConfig, build_claude_sandbox_settings, resolve_sandbox
 from ..usage import ProviderUsage, TokenUsage
@@ -130,8 +130,9 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
         model: str | None = None,
         event_handler: AgentEventHandler | None = None,
         event_handlers: Iterable[AgentEventHandler] | None = None,
-        mcp_servers: list[McpServerConfig] | None = None,
+        mcp_servers: Sequence[McpServerConfig] | None = None,
         sandbox: bool | SandboxConfig = False,
+        executor: CommandExecutor | None = None,
     ):
         """Initialize the Claude Code coding agent.
 
@@ -145,8 +146,9 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
                 ``--settings``. Only bash subprocess commands are
                 sandboxed; the Claude process itself is not wrapped.
                 Defaults to False (no sandbox).
+            executor: Optional command executor for binary lookup and process execution.
         """
-        super().__init__("claude", model, event_handler, event_handlers, mcp_servers)
+        super().__init__("claude", model, event_handler, event_handlers, mcp_servers, executor=executor)
         self.sandbox = resolve_sandbox(sandbox)
         if self.sandbox is not None:
             # Without this, Claude Code cd's into a per-invocation scratch dir
@@ -223,7 +225,7 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
         cwd: str | None = None,
         timeout: int = 300,
         silent: bool = False,
-        on_process_started: Callable[[subprocess.Popen[str]], None] | None = None,
+        on_process_started: Callable[[CommandHandle], None] | None = None,
     ) -> ClaudeGenerationSession:
         return ClaudeGenerationSession(
             binary_name=self.binary_name,
@@ -235,5 +237,6 @@ class ClaudeCodeCodingAgent(CLICodingAgent):
             timeout=timeout,
             silent=silent,
             event_handler=self.event_handler,
+            executor=self.executor,
             on_process_started=on_process_started,
         )