shell-session-manager 1.0.0__tar.gz → 2.0.0__tar.gz

{shell_session_manager-1.0.0 → shell_session_manager-2.0.0}/PKG-INFO

@@ -1,12 +1,19 @@
 Metadata-Version: 2.4
 Name: shell-session-manager
-Version: 1.0.0
+Version: 2.0.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.14.*
+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-1.0.0 → shell_session_manager-2.0.0}/pyproject.toml

@@ -6,21 +6,31 @@ build-backend = "pdm.backend"
 
 [project]
 name = "shell-session-manager"
-version = "1.0.0"
+version = "2.0.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.14.*"
+requires-python = ">=3.12"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = [
     "LICENSE",
 ]
 
+[project.scripts]
+shellctl = "shell_session_manager.shellctl.server:main"
+
 [dependency-groups]
 dev = [
     "pytest>=9.0.2",

{shell_session_manager-1.0.0 → shell_session_manager-2.0.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.0.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.0.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.0.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.0.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.0.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()

shell_session_manager-2.0.0/src/shell_session_manager/shellctl/server/api.py

@@ -0,0 +1,201 @@
+"""FastAPI wiring for shellctl server endpoints."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Annotated, cast
+
+from fastapi import Depends, FastAPI, Header, Query, Request
+from fastapi.responses import JSONResponse
+
+from shell_session_manager.shellctl.server.config import ShellctlConfig
+from shell_session_manager.shellctl.server.errors import ShellctlServerError
+from shell_session_manager.shellctl.server.service import ShellctlService
+from shell_session_manager.shellctl.shared import (
+    DEFAULT_HEALTH_STATUS,
+    DEFAULT_LIST_LIMIT,
+    DEFAULT_OUTPUT_LIMIT_BYTES,
+    DEFAULT_TERMINATE_GRACE_SECONDS,
+    MAX_LIST_LIMIT,
+    MAX_OUTPUT_LIMIT_BYTES,
+    DeleteJobResponse,
+    ErrorDetail,
+    ErrorResponse,
+    HealthResponse,
+    InputJobRequest,
+    JobResult,
+    JobStatusName,
+    JobStatusView,
+    ListJobsResponse,
+    RunJobRequest,
+    TerminateJobRequest,
+    WaitJobRequest,
+)
+
+
+def create_app(
+    config: ShellctlConfig | None = None,
+    *,
+    service: ShellctlService | None = None,
+) -> FastAPI:
+    """Create the FastAPI application used by `shellctl serve`."""
+
+    resolved_config = config or ShellctlConfig()
+    resolved_service = service or ShellctlService(resolved_config)
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        await resolved_service.initialize()
+        resolved_service.start_background_gc()
+        resolved_service.start_background_pipe_monitor()
+        try:
+            yield
+        finally:
+            await resolved_service.shutdown()
+
+    app = FastAPI(title="shellctl", version="0.1.0", lifespan=lifespan)
+    app.state.shellctl_service = resolved_service
+
+    @app.exception_handler(ShellctlServerError)
+    async def handle_shellctl_error(
+        _request: Request,
+        exc: ShellctlServerError,
+    ) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=ErrorResponse(
+                error=ErrorDetail(code=exc.code, message=exc.message)
+            ).model_dump(mode="json"),
+        )
+
+    @app.exception_handler(RuntimeError)
+    async def handle_runtime_error(
+        _request: Request, exc: RuntimeError
+    ) -> JSONResponse:
+        return JSONResponse(
+            status_code=500,
+            content=ErrorResponse(
+                error=ErrorDetail(
+                    code="internal_error",
+                    message=str(exc) or "internal server error",
+                )
+            ).model_dump(mode="json"),
+        )
+
+    def get_service() -> ShellctlService:
+        return cast(ShellctlService, app.state.shellctl_service)
+
+    def verify_auth(
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> None:
+        expected = f"Bearer {resolved_config.auth_token}"
+        if authorization != expected:
+            raise ShellctlServerError(
+                401, "unauthorized", "Missing or invalid bearer token"
+            )
+
+    @app.get("/healthz", response_model=HealthResponse)
+    async def healthz() -> HealthResponse:
+        return HealthResponse(status=DEFAULT_HEALTH_STATUS)
+
+    @app.post(
+        "/v1/jobs/run",
+        response_model=JobResult,
+        dependencies=[Depends(verify_auth)],
+    )
+    async def run_job(
+        payload: RunJobRequest,
+        svc: ShellctlService = Depends(get_service),
+    ) -> JobResult:
+        return await svc.run_job(payload)
+
+    @app.post(
+        "/v1/jobs/{job_id}/wait",
+        response_model=JobResult,
+        dependencies=[Depends(verify_auth)],
+    )
+    async def wait_job(
+        job_id: str,
+        payload: WaitJobRequest,
+        svc: ShellctlService = Depends(get_service),
+    ) -> JobResult:
+        return await svc.wait_job(job_id, payload)
+
+    @app.get(
+        "/v1/jobs/{job_id}/log/tail",
+        response_model=JobResult,
+        dependencies=[Depends(verify_auth)],
+    )
+    async def tail_job(
+        job_id: str,
+        output_limit: Annotated[
+            int, Query(ge=1, le=MAX_OUTPUT_LIMIT_BYTES)
+        ] = DEFAULT_OUTPUT_LIMIT_BYTES,
+        svc: ShellctlService = Depends(get_service),
+    ) -> JobResult:
+        return await svc.tail_job(job_id, output_limit=output_limit)
+
+    @app.get(
+        "/v1/jobs/{job_id}",
+        response_model=JobStatusView,
+        dependencies=[Depends(verify_auth)],
+    )
+    async def job_status(
+        job_id: str,
+        svc: ShellctlService = Depends(get_service),
+    ) -> JobStatusView:
+        return await svc.get_job_status(job_id)
+
+    @app.get(
+        "/v1/jobs",
+        response_model=ListJobsResponse,
+        dependencies=[Depends(verify_auth)],
+    )
+    async def list_jobs(
+        status: Annotated[JobStatusName | None, Query()] = None,
+        limit: Annotated[int, Query(ge=1, le=MAX_LIST_LIMIT)] = DEFAULT_LIST_LIMIT,
+        svc: ShellctlService = Depends(get_service),
+    ) -> ListJobsResponse:
+        return await svc.list_jobs(status=status, limit=limit)
+
+    @app.post(
+        "/v1/jobs/{job_id}/input",
+        response_model=JobResult,
+        dependencies=[Depends(verify_auth)],
+    )
+    async def input_job(
+        job_id: str,
+        payload: InputJobRequest,
+        svc: ShellctlService = Depends(get_service),
+    ) -> JobResult:
+        return await svc.send_input(job_id, payload)
+
+    @app.post(
+        "/v1/jobs/{job_id}/terminate",
+        response_model=JobStatusView,
+        dependencies=[Depends(verify_auth)],
+    )
+    async def terminate_job(
+        job_id: str,
+        payload: TerminateJobRequest,
+        svc: ShellctlService = Depends(get_service),
+    ) -> JobStatusView:
+        return await svc.terminate_job(job_id, payload)
+
+    @app.delete(
+        "/v1/jobs/{job_id}",
+        response_model=DeleteJobResponse,
+        dependencies=[Depends(verify_auth)],
+    )
+    async def delete_job(
+        job_id: str,
+        force: bool = False,
+        grace_seconds: float = DEFAULT_TERMINATE_GRACE_SECONDS,
+        svc: ShellctlService = Depends(get_service),
+    ) -> DeleteJobResponse:
+        return await svc.delete_job(job_id, force=force, grace_seconds=grace_seconds)
+
+    return app
+
+
+__all__ = ["create_app"]