shell-session-manager 1.0.1__tar.gz → 2.1.0__tar.gz

shell_session_manager-1.0.1/README.md → shell_session_manager-2.1.0/PKG-INFO

@@ -1,3 +1,21 @@
+Metadata-Version: 2.4
+Name: shell-session-manager
+Version: 2.1.0
+Summary: Async subprocess session manager with incremental stdin/stdout/stderr support
+Author-Email: =?utf-8?b?WWFubGkg55uQ57KS?= <yanli@mail.one>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: anyio>=4.12.1
+Requires-Dist: fastapi>=0.116.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: sqlmodel>=0.0.24
+Requires-Dist: typer>=0.16.1
+Requires-Dist: uvicorn>=0.35.0
+Description-Content-Type: text/markdown
+
 # shell-session-manager
 
 `shell-session-manager` provides async subprocess sessions that can be resumed
@@ -49,3 +67,16 @@ async def main() -> None:
 
 anyio.run(main)
 ```
+
+## shellctl server
+
+Run the HTTP API locally with:
+
+```bash
+pdm run shellctl serve --listen 127.0.0.1:8765
+```
+
+Pass `--auth-token your-token` when you want bearer auth enforced. `shellctl
+serve` also reads `SHELLCTL_AUTH_TOKEN`, so you can export the token instead of
+passing the flag. Leave the flag/env var unset or empty to start without
+requiring an Authorization header.

shell_session_manager-1.0.1/PKG-INFO → shell_session_manager-2.1.0/README.md

@@ -1,14 +1,3 @@
-Metadata-Version: 2.4
-Name: shell-session-manager
-Version: 1.0.1
-Summary: Async subprocess session manager with incremental stdin/stdout/stderr support
-Author-Email: =?utf-8?b?WWFubGkg55uQ57KS?= <yanli@mail.one>
-License-Expression: Apache-2.0
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: anyio>=4.12.1
-Description-Content-Type: text/markdown
-
 # shell-session-manager
 
 `shell-session-manager` provides async subprocess sessions that can be resumed
@@ -60,3 +49,16 @@ async def main() -> None:
 
 anyio.run(main)
 ```
+
+## shellctl server
+
+Run the HTTP API locally with:
+
+```bash
+pdm run shellctl serve --listen 127.0.0.1:8765
+```
+
+Pass `--auth-token your-token` when you want bearer auth enforced. `shellctl
+serve` also reads `SHELLCTL_AUTH_TOKEN`, so you can export the token instead of
+passing the flag. Leave the flag/env var unset or empty to start without
+requiring an Authorization header.

{shell_session_manager-1.0.1 → shell_session_manager-2.1.0}/pyproject.toml

@@ -6,13 +6,20 @@ build-backend = "pdm.backend"
 
 [project]
 name = "shell-session-manager"
-version = "1.0.1"
+version = "2.1.0"
 description = "Async subprocess session manager with incremental stdin/stdout/stderr support"
 authors = [
     { name = "Yanli 盐粒", email = "yanli@mail.one" },
 ]
 dependencies = [
+    "aiosqlite>=0.21.0",
     "anyio>=4.12.1",
+    "fastapi>=0.116.1",
+    "httpx>=0.28.1",
+    "pydantic>=2.12.5",
+    "sqlmodel>=0.0.24",
+    "typer>=0.16.1",
+    "uvicorn>=0.35.0",
 ]
 requires-python = ">=3.12"
 readme = "README.md"
@@ -21,6 +28,9 @@ license-files = [
     "LICENSE",
 ]
 
+[project.scripts]
+shellctl = "shell_session_manager.shellctl.server:main"
+
 [dependency-groups]
 dev = [
     "pytest>=9.0.2",

{shell_session_manager-1.0.1 → shell_session_manager-2.1.0}/src/shell_session_manager/__init__.py

@@ -4,6 +4,10 @@ The package exports the session primitives from `shell_session_manager.session`.
 Callers are responsible for constructing the command string; this package only
 owns process lifetime, incremental stdin writes, stdout/stderr draining, and
 session registry management.
+
+The higher-level HTTP/tmux shellctl implementation lives under
+`shell_session_manager.shellctl` so projects that only need in-process shell
+sessions do not need to import the networked manager.
 """
 
 from shell_session_manager.session import (

shell_session_manager-2.1.0/src/shell_session_manager/shellctl/__init__.py

@@ -0,0 +1,69 @@
+"""Public shellctl package exports.
+
+The client/server/shared entry points now live in package subfolders so each can
+contain smaller responsibility-focused files while preserving the original
+import paths through package `__init__` re-exports.
+"""
+
+from shell_session_manager.shellctl.client import ShellctlClient, ShellctlClientError
+from shell_session_manager.shellctl.shared import (
+    DEFAULT_AUTH_TOKEN_ENV,
+    DEFAULT_GC_FINISHED_JOB_RETENTION_SECONDS,
+    DEFAULT_GC_INTERVAL_SECONDS,
+    DEFAULT_IDLE_FLUSH_SECONDS,
+    DEFAULT_LIST_LIMIT,
+    DEFAULT_OUTPUT_LIMIT_BYTES,
+    DEFAULT_TERMINAL_COLS,
+    DEFAULT_TERMINAL_ROWS,
+    DEFAULT_TERMINATE_GRACE_SECONDS,
+    DEFAULT_TIMEOUT_SECONDS,
+    DeleteJobResponse,
+    HealthResponse,
+    InputJobRequest,
+    JobInfo,
+    JobResult,
+    JobStatusName,
+    JobStatusView,
+    ListJobsResponse,
+    PtySanitizer,
+    RunJobRequest,
+    TerminalSize,
+    TerminateJobRequest,
+    WaitJobRequest,
+    generate_job_id,
+    read_output_window,
+    sanitize_pty_output,
+    tail_output_window,
+)
+
+__all__ = [
+    "DEFAULT_AUTH_TOKEN_ENV",
+    "DEFAULT_GC_FINISHED_JOB_RETENTION_SECONDS",
+    "DEFAULT_GC_INTERVAL_SECONDS",
+    "DEFAULT_IDLE_FLUSH_SECONDS",
+    "DEFAULT_LIST_LIMIT",
+    "DEFAULT_OUTPUT_LIMIT_BYTES",
+    "DEFAULT_TERMINAL_COLS",
+    "DEFAULT_TERMINAL_ROWS",
+    "DEFAULT_TERMINATE_GRACE_SECONDS",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "DeleteJobResponse",
+    "HealthResponse",
+    "InputJobRequest",
+    "JobInfo",
+    "JobResult",
+    "JobStatusName",
+    "JobStatusView",
+    "ListJobsResponse",
+    "PtySanitizer",
+    "RunJobRequest",
+    "ShellctlClient",
+    "ShellctlClientError",
+    "TerminalSize",
+    "TerminateJobRequest",
+    "WaitJobRequest",
+    "generate_job_id",
+    "read_output_window",
+    "sanitize_pty_output",
+    "tail_output_window",
+]

shell_session_manager-2.1.0/src/shell_session_manager/shellctl/client/__init__.py

@@ -0,0 +1,12 @@
+"""Async HTTP client package for shellctl.
+
+`shell_session_manager.shellctl.client` remains importable as before, but it is
+ now a package so future client helpers can live beside the main SDK class.
+"""
+
+from shell_session_manager.shellctl.client.sdk import (
+    ShellctlClient,
+    ShellctlClientError,
+)
+
+__all__ = ["ShellctlClient", "ShellctlClientError"]

shell_session_manager-2.1.0/src/shell_session_manager/shellctl/client/sdk.py

@@ -0,0 +1,264 @@
+"""Async HTTP client for the shellctl server API.
+
+The SDK keeps transport-level knobs (`output_limit`, `idle_flush_seconds`, and
+ bearer token handling) on the client instance so individual method calls stay
+ close to the proposal's high-level workflow.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from shell_session_manager.shellctl.shared import (
+    DEFAULT_AUTH_TOKEN_ENV,
+    DEFAULT_IDLE_FLUSH_SECONDS,
+    DEFAULT_LIST_LIMIT,
+    DEFAULT_OUTPUT_LIMIT_BYTES,
+    DEFAULT_TERMINATE_GRACE_SECONDS,
+    DEFAULT_TIMEOUT_SECONDS,
+    DeleteJobResponse,
+    JobInfo,
+    JobResult,
+    JobStatusView,
+    ListJobsResponse,
+    RunJobRequest,
+    TerminalSize,
+)
+
+
+class ShellctlClientError(RuntimeError):
+    """Raised when the shellctl server returns an error response."""
+
+    def __init__(self, status_code: int, code: str, message: str) -> None:
+        super().__init__(f"{code} ({status_code}): {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+
+class ShellctlClient:
+    """Thin async SDK for the shellctl HTTP API.
+
+    The client owns a reusable `httpx.AsyncClient` unless one is injected via the
+    `client` argument. Callers can therefore either keep one instance for a full
+    workflow or treat it as an async context manager.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        output_limit: int = DEFAULT_OUTPUT_LIMIT_BYTES,
+        idle_flush_seconds: float = DEFAULT_IDLE_FLUSH_SECONDS,
+        token: str | None = None,
+        client: httpx.AsyncClient | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.output_limit = output_limit
+        self.idle_flush_seconds = idle_flush_seconds
+        self.token = (
+            token if token is not None else os.environ.get(DEFAULT_AUTH_TOKEN_ENV)
+        )
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(
+            base_url=self.base_url,
+            follow_redirects=True,
+            timeout=httpx.Timeout(
+                DEFAULT_TIMEOUT_SECONDS, connect=DEFAULT_TIMEOUT_SECONDS
+            ),
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> ShellctlClient:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client if this SDK instance owns it."""
+
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def healthz(self) -> dict[str, Any]:
+        """Call the public health endpoint without requiring auth."""
+
+        response = await self._client.get("/healthz")
+        return self._decode_response(response)
+
+    async def run(
+        self,
+        script: str,
+        *,
+        cwd: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        terminal: TerminalSize | None = None,
+    ) -> JobResult:
+        """Create a new job and wait for initial output or completion."""
+
+        payload = RunJobRequest(
+            script=script,
+            cwd=cwd,
+            terminal=terminal,
+            timeout=timeout,
+            output_limit=self.output_limit,
+            idle_flush_seconds=self.idle_flush_seconds,
+        )
+        response = await self._client.post(
+            "/v1/jobs/run",
+            json=payload.model_dump(mode="json", exclude_none=True),
+            headers=self._auth_headers(),
+        )
+        return JobResult.model_validate(self._decode_response(response))
+
+    async def wait(
+        self,
+        job_id: str,
+        *,
+        offset: int,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> JobResult:
+        """Wait for incremental output, completion, truncation, or timeout."""
+
+        response = await self._client.post(
+            f"/v1/jobs/{job_id}/wait",
+            json={
+                "offset": offset,
+                "timeout": timeout,
+                "output_limit": self.output_limit,
+                "idle_flush_seconds": self.idle_flush_seconds,
+            },
+            headers=self._auth_headers(),
+        )
+        return JobResult.model_validate(self._decode_response(response))
+
+    async def status(self, job_id: str) -> JobStatusView:
+        """Fetch the materialized status view for one job."""
+
+        response = await self._client.get(
+            f"/v1/jobs/{job_id}",
+            headers=self._auth_headers(),
+        )
+        return JobStatusView.model_validate(self._decode_response(response))
+
+    async def list_jobs(
+        self,
+        *,
+        status: str | None = None,
+        limit: int = DEFAULT_LIST_LIMIT,
+    ) -> list[JobInfo]:
+        """List recent jobs, optionally filtered by lifecycle status."""
+
+        params: dict[str, Any] = {"limit": limit}
+        if status is not None:
+            params["status"] = status
+        response = await self._client.get(
+            "/v1/jobs",
+            params=params,
+            headers=self._auth_headers(),
+        )
+        payload = ListJobsResponse.model_validate(self._decode_response(response))
+        return payload.jobs
+
+    async def input(
+        self,
+        job_id: str,
+        text: str,
+        *,
+        offset: int,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> JobResult:
+        """Send text input to a running job and then wait like `wait()`."""
+
+        response = await self._client.post(
+            f"/v1/jobs/{job_id}/input",
+            json={
+                "text": text,
+                "offset": offset,
+                "timeout": timeout,
+                "output_limit": self.output_limit,
+                "idle_flush_seconds": self.idle_flush_seconds,
+            },
+            headers=self._auth_headers(),
+        )
+        return JobResult.model_validate(self._decode_response(response))
+
+    async def tail(self, job_id: str) -> JobResult:
+        """Fetch an immediate UTF-8-safe tail snapshot for a job."""
+
+        response = await self._client.get(
+            f"/v1/jobs/{job_id}/log/tail",
+            params={"output_limit": self.output_limit},
+            headers=self._auth_headers(),
+        )
+        return JobResult.model_validate(self._decode_response(response))
+
+    async def terminate(
+        self,
+        job_id: str,
+        grace_seconds: float = DEFAULT_TERMINATE_GRACE_SECONDS,
+    ) -> JobStatusView:
+        """Terminate a job, returning the resulting materialized status view."""
+
+        response = await self._client.post(
+            f"/v1/jobs/{job_id}/terminate",
+            json={"grace_seconds": grace_seconds},
+            headers=self._auth_headers(),
+        )
+        return JobStatusView.model_validate(self._decode_response(response))
+
+    async def delete(
+        self,
+        job_id: str,
+        *,
+        force: bool = False,
+        grace_seconds: float | None = None,
+    ) -> DeleteJobResponse:
+        """Delete job artifacts, optionally terminating the job first."""
+
+        params: dict[str, Any] = {"force": str(force).lower()}
+        if grace_seconds is not None:
+            params["grace_seconds"] = grace_seconds
+        response = await self._client.delete(
+            f"/v1/jobs/{job_id}",
+            params=params,
+            headers=self._auth_headers(),
+        )
+        return DeleteJobResponse.model_validate(self._decode_response(response))
+
+    def _auth_headers(self) -> dict[str, str]:
+        if not self.token:
+            return {}
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def _decode_response(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError as exc:  # pragma: no cover - network/proxy corruption
+            raise ShellctlClientError(
+                response.status_code, "invalid_json", response.text
+            ) from exc
+
+        if response.is_error:
+            error = payload.get("error") if isinstance(payload, dict) else None
+            if isinstance(error, dict):
+                code = str(error.get("code", "request_failed"))
+                message = str(error.get("message", response.text))
+            else:
+                code = "request_failed"
+                message = response.text
+            raise ShellctlClientError(response.status_code, code, message)
+
+        if not isinstance(payload, dict):
+            raise ShellctlClientError(
+                response.status_code, "invalid_payload", response.text
+            )
+        return payload
+
+
+__all__ = ["ShellctlClient", "ShellctlClientError"]

shell_session_manager-2.1.0/src/shell_session_manager/shellctl/server/__init__.py

@@ -0,0 +1,33 @@
+"""shellctl server package.
+
+The original monolithic `shellctl.server` module is now organized as a package
+with smaller files for configuration, SQLite models, tmux control, lifecycle
+service logic, FastAPI wiring, and CLI commands. This `__init__` keeps the
+common public-ish imports stable without re-exporting unrelated internals.
+"""
+
+from shell_session_manager.shellctl.server.api import create_app
+from shell_session_manager.shellctl.server.cli import (
+    cli,
+    main,
+    runner_exit_command,
+    sanitize_pty_command,
+    serve_command,
+)
+from shell_session_manager.shellctl.server.config import ShellctlConfig
+from shell_session_manager.shellctl.server.db import JobRow
+from shell_session_manager.shellctl.server.errors import ShellctlServerError
+from shell_session_manager.shellctl.server.service import ShellctlService
+
+__all__ = [
+    "JobRow",
+    "ShellctlConfig",
+    "ShellctlServerError",
+    "ShellctlService",
+    "cli",
+    "create_app",
+    "main",
+    "runner_exit_command",
+    "sanitize_pty_command",
+    "serve_command",
+]

shell_session_manager-2.1.0/src/shell_session_manager/shellctl/server/__main__.py

@@ -0,0 +1,6 @@
+"""Support `python -m shell_session_manager.shellctl.server`."""
+
+from shell_session_manager.shellctl.server.cli import main
+
+if __name__ == "__main__":
+    main()