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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-shell-py
-Version: 0.2.1
+Version: 0.2.2
 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.2}/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.2'
+__version_tuple__ = version_tuple = (0, 2, 2)
 
 __commit_id__ = commit_id = None

{agent_shell_py-0.2.1 → agent_shell_py-0.2.2}/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.2}/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.2}/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
@@ -195,17 +201,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 +349,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 +366,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 +402,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 +481,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.2}/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.2/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.2}/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.2}/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(

agent_shell_py-0.2.2/src/agent_shell/process_cleanup.py

@@ -0,0 +1,158 @@
+"""Process-group ownership and cleanup through dedicated guardian processes.
+
+Every CLI runs in a process group containing a tiny guardian. AgentShell owns the guardian through
+an anonymous pipe, which is an exact kernel object rather than a reusable numeric PID. Cleanup sends
+one byte through that pipe; the guardian then signals its own group.
+
+A normal stream sends RELEASE so a CLI's intentional leftover processes may continue. Cancellation,
+abandonment, model-discovery cleanup, and atexit send KILL. If AgentShell disappears before cleanup,
+the pipe closes and the guardian treats EOF as KILL.
+
+The parent never calls ``killpg``. If the guardian has already died, writing its pipe fails safely
+and cleanup accepts a possible leak rather than risking a signal to a recycled process-group ID.
+"""
+import asyncio
+import atexit
+import contextlib
+import logging
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+logger = logging.getLogger("agent_shell.process_cleanup")
+
+_KILL_GROUP = b"K"
+_RELEASE_GROUP = b"R"
+
+_GROUP_GUARDIAN = """
+import os
+import signal
+
+command = os.read(0, 1)
+if command == b"R":
+    raise SystemExit(0)
+os.kill(0, signal.SIGKILL)
+"""
+
+
+@dataclass(slots=True)
+class _GroupGuardian:
+    process: subprocess.Popen
+    control_fd: int
+
+    @property
+    def pid(self) -> int:
+        return self.process.pid
+
+
+# Process objects have stable identity even after their numeric PIDs are reaped and reused.
+_guardians: dict[asyncio.subprocess.Process, _GroupGuardian] = {}
+
+
+def _send_guardian_command(guardian: _GroupGuardian, command: bytes) -> None:
+    try:
+        os.write(guardian.control_fd, command)
+    except OSError as error:
+        logger.warning("Could not contact process-group guardian: %s", error)
+    finally:
+        with contextlib.suppress(OSError):
+            os.close(guardian.control_fd)
+
+    # subprocess.Popen, rather than asyncio, owns this direct child. Waiting here reaps that
+    # exact child; the PID is never used to choose a process or group to signal.
+    with contextlib.suppress(OSError, ChildProcessError):
+        guardian.process.wait()
+
+
+def _start_guardian() -> _GroupGuardian:
+    read_fd, write_fd = os.pipe()
+    argv = [sys.executable, "-I", "-S", "-c", _GROUP_GUARDIAN]
+
+    try:
+        process = subprocess.Popen(
+            argv,
+            stdin=read_fd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            close_fds=True,
+            process_group=0,
+        )
+    except BaseException:
+        os.close(write_fd)
+        raise
+    finally:
+        os.close(read_fd)
+
+    return _GroupGuardian(process=process, control_fd=write_fd)
+
+
+async def create_grouped_process(
+    command: list[str],
+    cwd: str,
+    *,
+    env: dict[str, str] | None = None,
+    stdin: int = asyncio.subprocess.DEVNULL,
+) -> asyncio.subprocess.Process:
+    """Start a command in a process group owned by an exact guardian pipe."""
+    guardian = _start_guardian()
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *command,
+            stdin=stdin,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+            env=env,
+            process_group=guardian.pid,
+        )
+    except BaseException:
+        _send_guardian_command(guardian, _KILL_GROUP)
+        raise
+
+    _guardians[process] = guardian
+    return process
+
+
+def release_process_group(process: asyncio.subprocess.Process) -> None:
+    """Stop the guardian without signalling leftovers from a completed CLI."""
+    guardian = _guardians.pop(process, None)
+    if guardian is not None:
+        _send_guardian_command(guardian, _RELEASE_GROUP)
+
+
+def kill_process_group(process: asyncio.subprocess.Process) -> None:
+    """Ask the process's exact guardian to SIGKILL its own group."""
+    guardian = _guardians.pop(process, None)
+    if guardian is not None:
+        _send_guardian_command(guardian, _KILL_GROUP)
+
+
+def release_process(
+    process: asyncio.subprocess.Process,
+    active_processes: list,
+    stderr_task,
+    *,
+    child_exited: bool,
+) -> None:
+    """Release the resources owned by one adapter stream on every exit path."""
+    if not stderr_task.done():
+        stderr_task.cancel()
+
+    if process in active_processes:
+        active_processes.remove(process)
+
+    if child_exited or process.returncode is not None:
+        release_process_group(process)
+    else:
+        kill_process_group(process)
+
+
+def cleanup_process_groups() -> None:
+    """Ask every still-registered guardian to kill its group during interpreter exit."""
+    for process in list(_guardians):
+        kill_process_group(process)
+
+
+atexit.register(cleanup_process_groups)

agent_shell_py-0.2.2/tests/conftest.py

@@ -0,0 +1,20 @@
+"""Fixtures shared by the whole suite."""
+import pytest
+
+from agent_shell import process_cleanup
+
+
+@pytest.fixture(autouse=True)
+def isolate_process_group_registry():
+    """Give every test an isolated guardian registry and close anything it leaks."""
+    saved = dict(process_cleanup._guardians)
+    process_cleanup._guardians.clear()
+    try:
+        yield
+    finally:
+        # This runs on assertion failures too. Leaving a guardian's pipe open would leave its
+        # process blocked and could hide the test failure behind process cleanup at interpreter
+        # exit.
+        for process in list(process_cleanup._guardians):
+            process_cleanup.kill_process_group(process)
+        process_cleanup._guardians.update(saved)