agent-shell-py 0.2.1__tar.gz → 0.2.3__tar.gz

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-shell-py
-Version: 0.2.1
+Version: 0.2.3
 Summary: A lightweight abstraction for executing CLI coding agents headlessly
 License-Expression: MIT
 License-File: LICENSE

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/docs/development/agent_parameter_comparison.md

@@ -1,7 +1,7 @@
 # Agent CLI Parameter Comparison
 
 Comparison of headless/non-interactive configuration across supported CLI coding agents.
-Last updated: 2026-08-02
+Last updated: 2026-08-05
 
 > The summary matrix below has no Pi or Cursor column (it predates both adapters); see the
 > per-agent detail sections, the model-discovery section, and the `disallowed_tools` table.
@@ -20,9 +20,9 @@ Last updated: 2026-08-02
 | **Allowed tools** | `--allowed-tools` | No direct flag | `--allow-tool`, `--available-tools` | `tools` in config |
 | **Disallowed tools** | `--disallowed-tools` | `web_search` config only | `--deny-tool` | `OPENCODE_PERMISSION` env / `permission` config |
 | **Stream output** | `--output-format stream-json` | `--json` (NDJSON) | `--output-format=json` (JSONL) | `--format json` |
-| **Working dir** | cwd + `--add-dir` | `--cd` / `-C` | cwd (no flag) | cwd (no flag) |
+| **Working dir** | cwd + `--add-dir` | `--cd` / `-C` | cwd / `-C` | cwd |
 | **System prompt** | `--system-prompt` / `--append-system-prompt` | No flag (files only) | No flag (files only) | `instructions` in config |
-| **Budget** | `--max-budget-usd` | No direct flag | No direct flag | No direct flag |
+| **Budget** | `--max-budget-usd` | No direct flag | `--max-ai-credits` | No direct flag |
 | **Auto-approve** | `--dangerously-skip-permissions` | `--yolo` | `--yolo` / `--allow-all` | Auto in `run` mode |
 | **Session resume** | `--resume` | `exec resume <id>` | `--resume` | `-s <id>` |
 
@@ -123,23 +123,32 @@ real discovery commands.
 
 ## Copilot CLI (GitHub)
 
-- **Headless mode**: `-p` / `--prompt` for one-shot, `--acp --stdio` for programmatic JSON-RPC
-- **Model**: `--model` (default `claude-sonnet-4.5`)
-- **Effort**: `--effort low|medium|high` or `--reasoning-effort low|medium|high`
-- **Allowed tools**: `--allow-tool`, `--deny-tool`, `--available-tools`, `--excluded-tools`, `--allow-all-tools`
-- **Auto-approve**: `--allow-all` / `--yolo`, `--autopilot`
+- **Headless mode**: `-p` / `--prompt` for one-shot; `--acp` for Agent Client Protocol
+- **Model**: `--model <model>`; use `auto` to let Copilot choose
+- **Effort**: `--effort` / `--reasoning-effort` with choices
+  `none|minimal|low|medium|high|xhigh|max`. AgentShell accepts effort values
+  case-insensitively, validates them against these choices, and passes the normalized lowercase
+  value to Copilot via `--effort`.
+- **Allowed tools**: `--allow-tool`, `--deny-tool`, `--available-tools`,
+  `--excluded-tools`, `--allow-all-tools`
+- **Auto-approve**: `--allow-all-tools`; `--allow-all` / `--yolo` also grant path and URL
+  permissions
+- **Agent mode**: `--mode interactive|plan|autopilot`; `--autopilot` is the shortcut
 - **Output format**: `--output-format=json` (JSONL)
 - **Silent mode**: `--silent` suppresses stats, prints only response
-- **Working directory**: Uses cwd (no flag), ACP mode uses `newSession` parameter
-- **System prompt**: No CLI flag, uses `.github/copilot-instructions.md` and `AGENTS.md` files
-- **Budget**: No per-run flag, auto-compacts at 95% token limit
+- **Working directory**: CLI supports `-C <directory>`; AgentShell sets subprocess `cwd`
+- **System prompt**: No CLI flag; uses `.github/copilot-instructions.md` and `AGENTS.md` files
+- **AI credit budget**: `--max-ai-credits <credits>` limits credits for the session
+- **Token budget**: No per-run flag; auto-compacts at 95% of the token limit
 - **Path permissions**: `--allow-all-paths`, `--disallow-temp-dir`
 - **URL permissions**: `--allow-all-urls`, `--allow-url`, `--deny-url`
-- **Session**: `--resume`, `--continue`, plus `--session-id=<uuid>` to start a NEW session under
-  a chosen id. The adapter resumes with `--resume <id>`. The resumed run reports the SAME
-  `sessionId`, and an unknown id is rejected ("No session, task, or name matched"), so id
-  identity is real evidence the CLI continued that session (measured 2026-07-26)
-- **ACP mode**: `--acp --stdio` or `--acp --port 3000` for JSON-RPC integration
+- **Session**: `--resume`, `--continue`, and `--session-id <id>`. The latter resumes an existing
+  session or task, or assigns a UUID to a new session. AgentShell resumes with `--resume <id>`.
+  The resumed run reports the SAME `sessionId`, and an unknown id is rejected
+  ("No session, task, or name matched"), so id identity is real evidence the CLI continued that
+  session (measured 2026-07-26).
+- **ACP mode**: `--acp` uses stdio by default. Copilot CLI 1.0.78 also accepts hidden
+  `--stdio` and `--port <port>` transport options; they are not shown by `copilot --help`.
 
 ## OpenCode
 

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/src/agent_shell/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.1'
-__version_tuple__ = version_tuple = (0, 2, 1)
+__version__ = version = '0.2.3'
+__version_tuple__ = version_tuple = (0, 2, 3)
 
 __commit_id__ = commit_id = None

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/src/agent_shell/adapters/claude_code_adapter.py

@@ -7,9 +7,18 @@ import warnings
 from pathlib import Path
 from typing import AsyncIterator
 
-from agent_shell.models.agent import AgentResponse, StreamEvent, MCPServerSpec, MCPServerType, HealthCheckResult
-from agent_shell.process_cleanup import (register_process_group, kill_process_group,
-                                         release_process)
+from agent_shell.models.agent import (
+    AgentResponse,
+    HealthCheckResult,
+    MCPServerSpec,
+    MCPServerType,
+    StreamEvent,
+)
+from agent_shell.process_cleanup import (
+    create_grouped_process,
+    kill_process_group,
+    release_process,
+)
 from agent_shell.adapters.health import run_health_probe
 from agent_shell.adapters.model_discovery import decode_model_output, run_model_command
 from agent_shell.adapters.response import collect_response
@@ -105,18 +114,12 @@ class ClaudeCodeAdapter():
         logger.debug("Command: %s", cmd)
         logger.info("Process started (cwd=%s)", os.path.abspath(cwd))
 
-        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,
+        process = await create_grouped_process(
+            cmd,
+            cwd=os.path.abspath(cwd),
         )
 
         self._active_processes.append(process)
-        # setsid makes the child a session leader, so pgid == pid
-        register_process_group(process.pid)
 
         # Drain stderr concurrently with stdout. Reading it only after the stdout loop can
         # deadlock: a child that fills its stderr pipe buffer (~64KB) mid-run blocks on that
@@ -227,7 +230,7 @@ class ClaudeCodeAdapter():
 
     async def cancel(self) -> None:
         for process in self._active_processes:
-            kill_process_group(process.pid)
+            kill_process_group(process)
         self._active_processes.clear()
 
     async def health_check(

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/src/agent_shell/adapters/codex_adapter.py

@@ -6,9 +6,18 @@ import os
 import warnings
 from typing import AsyncIterator
 
-from agent_shell.models.agent import AgentResponse, StreamEvent, MCPServerSpec, MCPServerType, HealthCheckResult
-from agent_shell.process_cleanup import (register_process_group, kill_process_group,
-                                         release_process)
+from agent_shell.models.agent import (
+    AgentResponse,
+    HealthCheckResult,
+    MCPServerSpec,
+    MCPServerType,
+    StreamEvent,
+)
+from agent_shell.process_cleanup import (
+    create_grouped_process,
+    kill_process_group,
+    release_process,
+)
 from agent_shell.adapters.health import run_health_probe
 from agent_shell.adapters.model_discovery import decode_model_output, run_model_command
 from agent_shell.adapters.response import collect_response
@@ -117,17 +126,12 @@ class CodexAdapter:
         logger.debug("Command: %s", cmd)
         logger.info("Process started (cwd=%s)", os.path.abspath(cwd))
 
-        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,
+        process = await create_grouped_process(
+            cmd,
+            cwd=os.path.abspath(cwd),
         )
 
         self._active_processes.append(process)
-        register_process_group(process.pid)
 
         # Drain stderr concurrently with stdout. Reading it only after the stdout loop can
         # deadlock: a child that fills its stderr pipe buffer (~64KB) mid-run blocks on that
@@ -279,7 +283,7 @@ class CodexAdapter:
 
     async def cancel(self) -> None:
         for process in self._active_processes:
-            kill_process_group(process.pid)
+            kill_process_group(process)
         self._active_processes.clear()
 
     async def health_check(

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/src/agent_shell/adapters/copilot_cli_adapter.py

@@ -7,10 +7,16 @@ import warnings
 from pathlib import Path
 from typing import AsyncIterator
 
-from agent_shell.models.agent import AgentResponse, StreamEvent, MCPServerSpec, MCPServerType, HealthCheckResult
+from agent_shell.models.agent import (
+    AgentResponse,
+    HealthCheckResult,
+    MCPServerSpec,
+    MCPServerType,
+    StreamEvent,
+)
 from agent_shell.process_cleanup import (
+    create_grouped_process,
     kill_process_group,
-    register_process_group,
     release_process,
 )
 from agent_shell.adapters.health import run_health_probe
@@ -38,6 +44,21 @@ _DISALLOWED_TOOL_MAP = {
     "edit": ["write"],
 }
 
+_COPILOT_EFFORTS = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
+
+
+def _normalize_effort(effort: str | None) -> str | None:
+    if effort is None:
+        return None
+
+    normalized = effort.lower() if isinstance(effort, str) else None
+    if normalized not in _COPILOT_EFFORTS:
+        choices = ", ".join(_COPILOT_EFFORTS)
+        raise ValueError(
+            f"Unsupported Copilot effort {effort!r}; accepted choices: {choices}"
+        )
+    return normalized
+
 
 def _json_rpc_frame(message: dict) -> bytes:
     payload = json.dumps(message, separators=(",", ":")).encode("utf-8")
@@ -154,6 +175,7 @@ class CopilotCLIAdapter:
             session_id: str | None = None,
             disallowed_tools: list[str] | None = None,
     ) -> AsyncIterator[StreamEvent]:
+        effort = _normalize_effort(effort)
         cmd = [
             "copilot", "-p", prompt,
             "--output-format", "json",
@@ -195,17 +217,12 @@ class CopilotCLIAdapter:
         logger.debug("Command: %s", cmd)
         logger.info("Process started (cwd=%s)", os.path.abspath(cwd))
 
-        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,
+        process = await create_grouped_process(
+            cmd,
+            cwd=os.path.abspath(cwd),
         )
 
         self._active_processes.append(process)
-        register_process_group(process.pid)
 
         # Drain stderr concurrently with stdout. Reading it only after the stdout loop can
         # deadlock: a child that fills its stderr pipe buffer (~64KB) mid-run blocks on that
@@ -348,7 +365,7 @@ class CopilotCLIAdapter:
 
     async def cancel(self) -> None:
         for process in self._active_processes:
-            kill_process_group(process.pid)
+            kill_process_group(process)
         self._active_processes.clear()
 
     async def health_check(
@@ -365,7 +382,7 @@ class CopilotCLIAdapter:
             timeout: float = 30.0,
     ) -> list[str]:
         cmd = ["copilot", "--headless", "--no-auto-update", "--stdio"]
-        process, group_leader = await start_model_process(
+        process = await start_model_process(
             cmd,
             cwd,
             stdin=asyncio.subprocess.PIPE,
@@ -401,7 +418,7 @@ class CopilotCLIAdapter:
             ) from error
         finally:
             try:
-                await stop_model_processes(process, group_leader)
+                await stop_model_processes(process)
             finally:
                 if not stderr_task.done():
                     stderr_task.cancel()
@@ -480,8 +497,10 @@ class CopilotCLIAdapter:
 
         for name, entry in servers.items():
             if not isinstance(entry, dict):
+                actual_type = type(entry).__name__
                 warnings.warn(
-                    f"Skipping malformed MCP entry '{name}': expected object, got {type(entry).__name__}",
+                    f"Skipping malformed MCP entry '{name}': "
+                    f"expected object, got {actual_type}",
                     UserWarning,
                     stacklevel=2,
                 )

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/src/agent_shell/adapters/cursor_adapter.py

@@ -6,9 +6,17 @@ import os
 import warnings
 from typing import AsyncIterator
 
-from agent_shell.models.agent import AgentResponse, StreamEvent, MCPServerSpec, HealthCheckResult
-from agent_shell.process_cleanup import (register_process_group, kill_process_group,
-                                         release_process)
+from agent_shell.models.agent import (
+    AgentResponse,
+    HealthCheckResult,
+    MCPServerSpec,
+    StreamEvent,
+)
+from agent_shell.process_cleanup import (
+    create_grouped_process,
+    kill_process_group,
+    release_process,
+)
 from agent_shell.adapters.health import run_health_probe
 from agent_shell.adapters.model_discovery import decode_model_output, run_model_command
 from agent_shell.adapters.response import collect_response
@@ -105,18 +113,12 @@ class CursorAdapter:
         logger.debug("Command: %s", cmd)
         logger.info("Process started (cwd=%s)", os.path.abspath(cwd))
 
-        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,
+        process = await create_grouped_process(
+            cmd,
+            cwd=os.path.abspath(cwd),
         )
 
         self._active_processes.append(process)
-        # setsid makes the child a session leader, so pgid == pid
-        register_process_group(process.pid)
 
         # Drain stderr concurrently with stdout. Reading it only after the stdout loop can
         # deadlock: a child that fills its stderr pipe buffer (~64KB) mid-run blocks on that
@@ -281,7 +283,7 @@ class CursorAdapter:
 
     async def cancel(self) -> None:
         for process in self._active_processes:
-            kill_process_group(process.pid)
+            kill_process_group(process)
         self._active_processes.clear()
 
     async def health_check(

agent_shell_py-0.2.3/src/agent_shell/adapters/model_discovery.py

@@ -0,0 +1,81 @@
+import asyncio
+import os
+
+from agent_shell.process_cleanup import create_grouped_process, kill_process_group
+
+
+def decode_model_output(output: bytes, source: str) -> str:
+    """Decode model metadata without leaking a low-level codec error."""
+    try:
+        return output.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise RuntimeError(f"{source} returned invalid UTF-8 output") from error
+
+
+async def _reap_process(process: asyncio.subprocess.Process) -> None:
+    try:
+        await asyncio.wait_for(process.wait(), timeout=2.0)
+    except (TimeoutError, ProcessLookupError):
+        pass
+
+
+async def stop_model_processes(process: asyncio.subprocess.Process) -> None:
+    """Ask the exact guardian to kill the discovery group, then reap the CLI."""
+    kill_process_group(process)
+    await _reap_process(process)
+
+
+async def start_model_process(
+    command: list[str],
+    cwd: str,
+    *,
+    env: dict[str, str] | None = None,
+    stdin: int = asyncio.subprocess.DEVNULL,
+) -> asyncio.subprocess.Process:
+    """Start a discovery CLI in a group owned by an exact guardian handle."""
+    return await create_grouped_process(
+        command,
+        cwd=os.path.abspath(cwd),
+        env=env,
+        stdin=stdin,
+    )
+
+
+async def run_model_command(
+    command: list[str],
+    cwd: str,
+    timeout: float,
+    *,
+    env: dict[str, str] | None = None,
+    input_data: bytes | None = None,
+) -> tuple[int, bytes, bytes]:
+    """Run a short-lived model-discovery command and clean up its whole group."""
+    process = await start_model_process(
+        command,
+        cwd,
+        env=env,
+        stdin=(
+            asyncio.subprocess.PIPE
+            if input_data is not None
+            else asyncio.subprocess.DEVNULL
+        ),
+    )
+
+    try:
+        stdout, stderr = await asyncio.wait_for(
+            process.communicate(input_data),
+            timeout=timeout,
+        )
+    except TimeoutError as error:
+        await stop_model_processes(process)
+        rendered = " ".join(command)
+        raise RuntimeError(
+            f"`{rendered}` timed out after {timeout:g} seconds"
+        ) from error
+    except BaseException:
+        await stop_model_processes(process)
+        raise
+
+    returncode = process.returncode
+    await stop_model_processes(process)
+    return returncode, stdout, stderr

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/src/agent_shell/adapters/opencode_adapter.py

@@ -7,9 +7,18 @@ import warnings
 from pathlib import Path
 from typing import AsyncIterator
 
-from agent_shell.models.agent import AgentResponse, StreamEvent, MCPServerSpec, MCPServerType, HealthCheckResult
-from agent_shell.process_cleanup import (register_process_group, kill_process_group,
-                                         release_process)
+from agent_shell.models.agent import (
+    AgentResponse,
+    HealthCheckResult,
+    MCPServerSpec,
+    MCPServerType,
+    StreamEvent,
+)
+from agent_shell.process_cleanup import (
+    create_grouped_process,
+    kill_process_group,
+    release_process,
+)
 from agent_shell.adapters.health import run_health_probe
 from agent_shell.adapters.model_discovery import decode_model_output, run_model_command
 from agent_shell.adapters.response import collect_response
@@ -103,19 +112,13 @@ class OpenCodeAdapter():
         logger.debug("Command: %s", cmd)
         logger.info("Process started (cwd=%s)", os.path.abspath(cwd))
 
-        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,
-                env=env,
+        process = await create_grouped_process(
+            cmd,
+            cwd=os.path.abspath(cwd),
+            env=env,
         )
 
         self._active_processes.append(process)
-        # setsid makes the child a session leader, so pgid == pid
-        register_process_group(process.pid)
 
         # Drain stderr concurrently with stdout. Reading it only after the stdout loop can
         # deadlock: a child that fills its stderr pipe buffer (~64KB) mid-run blocks on that
@@ -344,7 +347,7 @@ class OpenCodeAdapter():
 
     async def cancel(self) -> None:
         for process in self._active_processes:
-            kill_process_group(process.pid)
+            kill_process_group(process)
         self._active_processes.clear()
 
     async def health_check(
@@ -432,8 +435,10 @@ class OpenCodeAdapter():
 
         for name, entry in servers.items():
             if not isinstance(entry, dict):
+                actual_type = type(entry).__name__
                 warnings.warn(
-                    f"Skipping malformed MCP entry '{name}': expected object, got {type(entry).__name__}",
+                    f"Skipping malformed MCP entry '{name}': "
+                    f"expected object, got {actual_type}",
                     UserWarning,
                     stacklevel=2,
                 )

{agent_shell_py-0.2.1 → agent_shell_py-0.2.3}/src/agent_shell/adapters/pi_adapter.py

@@ -7,9 +7,17 @@ import re
 import warnings
 from typing import AsyncIterator
 
-from agent_shell.models.agent import AgentResponse, StreamEvent, MCPServerSpec, HealthCheckResult
-from agent_shell.process_cleanup import (register_process_group, kill_process_group,
-                                         release_process)
+from agent_shell.models.agent import (
+    AgentResponse,
+    HealthCheckResult,
+    MCPServerSpec,
+    StreamEvent,
+)
+from agent_shell.process_cleanup import (
+    create_grouped_process,
+    kill_process_group,
+    release_process,
+)
 from agent_shell.adapters.health import run_health_probe
 from agent_shell.adapters.model_discovery import decode_model_output, run_model_command
 from agent_shell.adapters.response import collect_response
@@ -115,18 +123,12 @@ class PiAdapter:
         logger.debug("Command: %s", cmd)
         logger.info("Process started (cwd=%s)", os.path.abspath(cwd))
 
-        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,
+        process = await create_grouped_process(
+            cmd,
+            cwd=os.path.abspath(cwd),
         )
 
         self._active_processes.append(process)
-        # setsid makes the child a session leader, so pgid == pid
-        register_process_group(process.pid)
 
         # Drain stderr concurrently with stdout. Reading it only after the stdout loop can
         # deadlock: a child that fills its stderr pipe buffer (~64KB) mid-run blocks on that
@@ -307,7 +309,7 @@ class PiAdapter:
 
     async def cancel(self) -> None:
         for process in self._active_processes:
-            kill_process_group(process.pid)
+            kill_process_group(process)
         self._active_processes.clear()
 
     async def health_check(