shell-session-manager 2.1.1__tar.gz → 2.2.0__tar.gz

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shell-session-manager
-Version: 2.1.1
+Version: 2.2.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

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "shell-session-manager"
-version = "2.1.1"
+version = "2.2.0"
 description = "Async subprocess session manager with incremental stdin/stdout/stderr support"
 authors = [
     { name = "Yanli 盐粒", email = "yanli@mail.one" },

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/src/shell_session_manager/shellctl/client/sdk.py

@@ -96,14 +96,20 @@ class ShellctlClient:
         script: str,
         *,
         cwd: str | None = None,
+        env: dict[str, str] | None = None,
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         terminal: TerminalSize | None = None,
     ) -> JobResult:
-        """Create a new job and wait for initial output or completion."""
+        """Create a new job and wait for initial output or completion.
+
+        `cwd` and `env` preset the script's working directory and environment
+        overlay on the server side.
+        """
 
         payload = RunJobRequest(
             script=script,
             cwd=cwd,
+            env=env,
             terminal=terminal,
             timeout=timeout,
             output_limit=self.output_limit,

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/src/shell_session_manager/shellctl/server/artifacts.py

@@ -3,8 +3,10 @@
 Normal job completion is coordinated through small marker files inside each
 `jobs/<job_id>/` directory so the tmux output-pipe finalizer can publish the
 SQLite `exited(exit_code, ended_at)` state only after PTY output is fully
-drained into `output.log`. A separate failure marker is used so an unsuccessful
-sanitizer run does not masquerade as a drained normal exit.
+drained into `output.log`. The same artifact directory also stores the request's
+environment overlay so the runner can merge arbitrary key/value pairs without
+shell-escaping them into the generated script. A separate failure marker is used
+so an unsuccessful sanitizer run does not masquerade as a drained normal exit.
 """
 
 from __future__ import annotations
@@ -13,6 +15,7 @@ from pathlib import Path
 
 RUNNER_EXIT_CODE_FILENAME = ".runner-exit-code"
 RUNNER_ENDED_AT_FILENAME = ".runner-ended-at"
+JOB_ENV_FILENAME = ".job-env.json"
 PIPE_DRAINED_FILENAME = ".pipe-drained"
 PIPE_FAILED_FILENAME = ".pipe-failed"
 
@@ -25,6 +28,10 @@ def runner_ended_at_path(job_dir: Path) -> Path:
     return job_dir / RUNNER_ENDED_AT_FILENAME
 
 
+def job_env_path(job_dir: Path) -> Path:
+    return job_dir / JOB_ENV_FILENAME
+
+
 def pipe_drained_path(job_dir: Path) -> Path:
     return job_dir / PIPE_DRAINED_FILENAME
 
@@ -34,10 +41,12 @@ def pipe_failed_path(job_dir: Path) -> Path:
 
 
 __all__ = [
+    "JOB_ENV_FILENAME",
     "PIPE_DRAINED_FILENAME",
     "PIPE_FAILED_FILENAME",
     "RUNNER_ENDED_AT_FILENAME",
     "RUNNER_EXIT_CODE_FILENAME",
+    "job_env_path",
     "pipe_drained_path",
     "pipe_failed_path",
     "runner_ended_at_path",

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/src/shell_session_manager/shellctl/server/service.py

@@ -9,6 +9,7 @@ This module owns the long-lived job lifecycle rules: artifact creation,
 from __future__ import annotations
 
 import asyncio
+import json
 import shlex
 import shutil
 import stat
@@ -24,8 +25,10 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_asyn
 from sqlmodel import SQLModel
 
 from shell_session_manager.shellctl.server.artifacts import (
+    JOB_ENV_FILENAME,
     RUNNER_ENDED_AT_FILENAME,
     RUNNER_EXIT_CODE_FILENAME,
+    job_env_path,
     pipe_drained_path,
     pipe_failed_path,
     runner_ended_at_path,
@@ -148,7 +151,8 @@ class ShellctlService:
         """Create a tmux-backed job and wait for its initial result window.
 
         Side effects:
-        - allocates `jobs/<job_id>/` and writes `script` / `output.log`
+        - allocates `jobs/<job_id>/` and writes `script`, `.job-env.json`, and
+          `output.log`
         - inserts a `jobs` row into SQLite, then conditionally transitions it
           through `created -> starting -> running`
         - creates a dedicated tmux session, installs `pipe-pane`, waits for the
@@ -168,6 +172,7 @@ class ShellctlService:
         """
 
         cwd = self._resolve_cwd(request.cwd)
+        env = self._resolve_env(request.env)
         terminal = request.terminal or TerminalSize(
             cols=self.config.default_terminal_cols,
             rows=self.config.default_terminal_rows,
@@ -183,6 +188,10 @@ class ShellctlService:
                 script_path = candidate_job_dir / "script"
                 output_path = candidate_job_dir / "output.log"
                 script_path.write_text(request.script, encoding="utf-8")
+                job_env_path(candidate_job_dir).write_text(
+                    json.dumps(env, ensure_ascii=False),
+                    encoding="utf-8",
+                )
                 output_path.touch()
                 row = JobRow(
                     job_id=candidate_job_id,
@@ -1000,6 +1009,17 @@ class ShellctlService:
             )
         return cwd
 
+    def _resolve_env(self, raw_env: dict[str, str] | None) -> dict[str, str]:
+        """Return a detached environment overlay for the generated runner.
+
+        `RunJobRequest` validates names/values before the service sees them.
+        The overlay augments the runner's inherited environment after shellctl
+        scrubs its own control variables, so explicit request values can be used
+        without replacing ambient entries like `PATH`.
+        """
+
+        return dict(raw_env or {})
+
     def _validate_offset(self, output_path: Path, offset: int) -> None:
         size = output_path.stat().st_size if output_path.exists() else 0
         if offset > size:
@@ -1022,7 +1042,59 @@ class ShellctlService:
         self.config.runner_path.chmod(mode | stat.S_IXUSR)
 
     def _runner_script_source(self) -> str:
+        """Build the bash runner installed into the shellctl runtime directory.
+
+        The wrapper still handles gate waiting and exit metadata in bash, but it
+        delegates launch setup to Python so per-job env overlays can be loaded
+        from JSON without shell-escaping arbitrary values into `export`
+        statements. The Python helper then `exec`s the target process instead of
+        waiting on it, which keeps `SIGINT` behavior identical to running the
+        script directly in the tmux pane. The bootstrap uses `python -c ...`
+        instead of a stdin-fed heredoc so the exec'd job still inherits the tmux
+        pane's PTY on fd 0 and can receive later `send_input()` data.
+        """
+
         auth_env = shlex.quote(DEFAULT_AUTH_TOKEN_ENV)
+        bootstrap_source = shlex.quote(
+            """
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+script_path = Path(sys.argv[1])
+cwd = sys.argv[2]
+env_path = Path(sys.argv[3])
+
+env = os.environ.copy()
+if env_path.exists():
+    env.update(json.loads(env_path.read_text(encoding="utf-8")))
+
+try:
+    os.chdir(cwd)
+except OSError:
+    raise SystemExit(111)
+
+with script_path.open("r", encoding="utf-8") as handle:
+    first_line = handle.readline()
+
+if first_line.startswith("#!"):
+    script_path.chmod(script_path.stat().st_mode | stat.S_IXUSR)
+    argv = [str(script_path)]
+else:
+    argv = ["sh", str(script_path)]
+
+try:
+    os.execvpe(argv[0], argv, env)
+except FileNotFoundError as exc:
+    print(f"{argv[0]}: {exc.strerror}", file=sys.stderr)
+    raise SystemExit(127) from exc
+except OSError as exc:
+    print(f"{argv[0]}: {exc.strerror}", file=sys.stderr)
+    raise SystemExit(126) from exc
+            """.strip()
+        )
         return f"""#!/usr/bin/env bash
 set -uo pipefail
 
@@ -1030,6 +1102,7 @@ JOB_DIR="$1"
 JOB_ID="$2"
 CWD="$3"
 SCRIPT_PATH="$JOB_DIR/script"
+ENV_PATH="$JOB_DIR/{JOB_ENV_FILENAME}"
 START_GATE="$JOB_DIR/start-gate"
 RUNNER_EXIT_CODE_PATH="$JOB_DIR/{RUNNER_EXIT_CODE_FILENAME}"
 RUNNER_ENDED_AT_PATH="$JOB_DIR/{RUNNER_ENDED_AT_FILENAME}"
@@ -1053,18 +1126,8 @@ unset SHELLCTL_TMUX_SOCKET
 unset SHELLCTL_RUNNER
 unset {auth_env}
 
-if cd "$CWD"; then
-  if IFS= read -r FIRST_LINE < "$SCRIPT_PATH" && [[ "$FIRST_LINE" == '#!'* ]]; then
-    chmod +x "$SCRIPT_PATH"
-    "$SCRIPT_PATH"
-    EXIT_CODE=$?
-  else
-    sh "$SCRIPT_PATH"
-    EXIT_CODE=$?
-  fi
-else
-  EXIT_CODE=111
-fi
+{shlex.quote(sys.executable)} -c {bootstrap_source} "$SCRIPT_PATH" "$CWD" "$ENV_PATH"
+EXIT_CODE=$?
 
 ENDED_AT="$({shlex.quote(sys.executable)} - <<'PY'
 from datetime import UTC, datetime

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/src/shell_session_manager/shellctl/shared/schemas.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from enum import StrEnum
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from shell_session_manager.shellctl.shared.constants import (
     DEFAULT_HEALTH_STATUS,
@@ -128,10 +128,16 @@ class ErrorResponse(ShellctlModel):
 
 
 class RunJobRequest(ShellctlModel):
-    """HTTP request body for `POST /v1/jobs/run`."""
+    """HTTP request body for `POST /v1/jobs/run`.
+
+    `env` augments the runner's inherited process environment instead of
+    replacing it, so callers can preset script-local variables without losing
+    ambient values such as `PATH`.
+    """
 
     script: str
     cwd: str | None = None
+    env: dict[str, str] | None = None
     terminal: TerminalSize | None = None
     timeout: float = Field(
         default=DEFAULT_TIMEOUT_SECONDS, gt=0, le=MAX_WAIT_TIMEOUT_SECONDS
@@ -141,6 +147,30 @@ class RunJobRequest(ShellctlModel):
     )
     idle_flush_seconds: float = Field(default=DEFAULT_IDLE_FLUSH_SECONDS, ge=0, le=30)
 
+    @field_validator("env")
+    @classmethod
+    def _validate_env(cls, env: dict[str, str] | None) -> dict[str, str] | None:
+        """Reject env entries that cannot be represented in `execve`.
+
+        shellctl applies `env` as a process environment overlay, so validation
+        follows the low-level `NAME=value` constraints instead of shell variable
+        naming rules: names must be non-empty and cannot contain `=` or NUL,
+        while values cannot contain NUL.
+        """
+
+        if env is None:
+            return None
+        for name, value in env.items():
+            if not name:
+                raise ValueError("env names must be non-empty")
+            if "=" in name:
+                raise ValueError(f"env name must not contain '=': {name!r}")
+            if "\x00" in name:
+                raise ValueError(f"env name must not contain NUL: {name!r}")
+            if "\x00" in value:
+                raise ValueError(f"env value must not contain NUL: {name!r}")
+        return env
+
 
 class WaitJobRequest(ShellctlModel):
     """HTTP request body for `POST /v1/jobs/{job_id}/wait`."""

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/tests/test_shellctl_client.py

@@ -39,7 +39,12 @@ async def test_shellctl_client_run_injects_headers_and_instance_defaults(
         idle_flush_seconds=0.25,
         transport=transport,
     ) as client:
-        await client.run("printf ready\\n", cwd="/tmp", timeout=12)
+        await client.run(
+            "printf ready\\n",
+            cwd="/tmp",
+            env={"HELLO": "world"},
+            timeout=12,
+        )
 
     assert captured["method"] == "POST"
     assert captured["path"] == "/v1/jobs/run"
@@ -47,6 +52,7 @@ async def test_shellctl_client_run_injects_headers_and_instance_defaults(
     assert captured["json"] == {
         "script": "printf ready\\n",
         "cwd": "/tmp",
+        "env": {"HELLO": "world"},
         "timeout": 12.0,
         "output_limit": 4096,
         "idle_flush_seconds": 0.25,

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/tests/test_shellctl_service.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import importlib
+import json
 import os
 import re
 import shutil
@@ -26,10 +27,12 @@ from shell_session_manager.shellctl.server import (
     create_app,
 )
 from shell_session_manager.shellctl.server.artifacts import (
+    JOB_ENV_FILENAME,
     PIPE_DRAINED_FILENAME,
     PIPE_FAILED_FILENAME,
     RUNNER_ENDED_AT_FILENAME,
     RUNNER_EXIT_CODE_FILENAME,
+    job_env_path,
 )
 from shell_session_manager.shellctl.server.tmux import TmuxController
 from shell_session_manager.shellctl.shared import (
@@ -352,6 +355,7 @@ async def test_run_job_happy_path_persists_running_row_and_artifacts(
         RunJobRequest(
             script="printf ready\n",
             cwd=str(tmp_path),
+            env={"HELLO": "world", "UNICODE": "盐粒"},
             terminal=TerminalSize(cols=100, rows=40),
             timeout=0.01,
             output_limit=8192,
@@ -372,6 +376,10 @@ async def test_run_job_happy_path_persists_running_row_and_artifacts(
     assert row.output_path == f"jobs/{result.job_id}/output.log"
     assert row.started_at is not None
     assert (job_dir / "script").exists()
+    assert json.loads(job_env_path(job_dir).read_text(encoding="utf-8")) == {
+        "HELLO": "world",
+        "UNICODE": "盐粒",
+    }
     assert (job_dir / "output.log").exists()
     assert (job_dir / "start-gate").exists()
     assert job_session_name(result.job_id) in fake_tmux.sessions
@@ -389,6 +397,205 @@ async def test_run_job_happy_path_persists_running_row_and_artifacts(
     await service.shutdown()
 
 
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_run_job_env_overlay_is_visible_without_replacing_inherited_env(
+    tmp_path: Path,
+) -> None:
+    service = await _create_real_service(tmp_path)
+
+    try:
+        result = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "python3 - <<'PY'\n"
+                    "import os\n"
+                    "print(os.environ['SHELLCTL_PRESET'])\n"
+                    "print('PATH' in os.environ)\n"
+                    "PY\n"
+                ),
+                cwd=str(tmp_path),
+                env={"SHELLCTL_PRESET": "from-client"},
+                terminal=TerminalSize(),
+                timeout=5,
+                output_limit=8192,
+                idle_flush_seconds=1,
+            )
+        )
+
+        assert result.done is True
+        assert result.status is JobStatusName.EXITED
+        assert result.exit_code == 0
+        assert result.output == "from-client\nTrue\n"
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_run_job_env_overlay_overrides_inherited_value(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("SHELLCTL_PRESET", "parent")
+    service = await _create_real_service(tmp_path)
+
+    try:
+        result = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "python3 - <<'PY'\n"
+                    "import os\n"
+                    "print(os.environ['SHELLCTL_PRESET'])\n"
+                    "PY\n"
+                ),
+                cwd=str(tmp_path),
+                env={"SHELLCTL_PRESET": "from-client"},
+                terminal=TerminalSize(),
+                timeout=5,
+                output_limit=8192,
+                idle_flush_seconds=1,
+            )
+        )
+
+        assert result.done is True
+        assert result.status is JobStatusName.EXITED
+        assert result.exit_code == 0
+        assert result.output == "from-client\n"
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_send_input_reaches_real_job_stdin_after_env_bootstrap(
+    tmp_path: Path,
+) -> None:
+    service = await _create_real_service(tmp_path)
+
+    try:
+        initial = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "printf 'ready\\n'\n"
+                    "IFS= read -r line\n"
+                    "printf 'got:%s\\n' \"$line\"\n"
+                ),
+                cwd=str(tmp_path),
+                terminal=TerminalSize(),
+                timeout=5,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            )
+        )
+
+        ready_window = initial
+        if ready_window.output == "":
+            ready_window = await service.wait_job(
+                initial.job_id,
+                WaitJobRequest(
+                    offset=initial.offset,
+                    timeout=1,
+                    output_limit=8192,
+                    idle_flush_seconds=0.01,
+                ),
+            )
+
+        result = await service.send_input(
+            initial.job_id,
+            InputJobRequest(
+                text="hello from stdin\n",
+                offset=ready_window.offset,
+                timeout=1,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            ),
+        )
+
+        output_after_input = result.output
+        final = result
+        if not final.done:
+            # `send_input()` shares wait semantics with `wait_job()`: it may
+            # return after the post-input output flushes but before tmux exit
+            # artifacts have materialized into a terminal DB status on slower CI.
+            final = await service.wait_job(
+                initial.job_id,
+                WaitJobRequest(
+                    offset=result.offset,
+                    timeout=5,
+                    output_limit=8192,
+                    idle_flush_seconds=0.01,
+                ),
+            )
+            output_after_input += final.output
+
+        assert ready_window.done is False
+        assert final.done is True
+        assert final.status is JobStatusName.EXITED
+        assert final.exit_code == 0
+        assert output_after_input.endswith("got:hello from stdin\n")
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_terminated_job_does_not_emit_python_wrapper_traceback(
+    tmp_path: Path,
+) -> None:
+    service = await _create_real_service(tmp_path)
+
+    try:
+        initial = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "trap 'exit 130' INT\n"
+                    "printf 'ready\\n'\n"
+                    "while :; do sleep 1; done\n"
+                ),
+                cwd=str(tmp_path),
+                terminal=TerminalSize(),
+                timeout=5,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            )
+        )
+
+        ready_window = initial
+        if ready_window.output == "":
+            ready_window = await service.wait_job(
+                initial.job_id,
+                WaitJobRequest(
+                    offset=initial.offset,
+                    timeout=1,
+                    output_limit=8192,
+                    idle_flush_seconds=0.01,
+                ),
+            )
+        assert ready_window.done is False
+
+        terminated = await service.terminate_job(
+            initial.job_id,
+            TerminateJobRequest(grace_seconds=0.2),
+        )
+        final = await service.wait_job(
+            initial.job_id,
+            WaitJobRequest(
+                offset=ready_window.offset,
+                timeout=1,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            ),
+        )
+
+        assert terminated.status is JobStatusName.TERMINATED
+        assert final.done is True
+        assert "KeyboardInterrupt" not in final.output
+        assert "Traceback (most recent call last)" not in final.output
+    finally:
+        await service.shutdown()
+
+
 @pytest.mark.anyio
 @pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
 async def test_run_job_returns_flushed_output_on_first_terminal_result(
@@ -1342,6 +1549,7 @@ def test_runner_script_records_completion_metadata_without_direct_runner_exit(
     )
     source = service._runner_script_source()
 
+    assert JOB_ENV_FILENAME in source
     assert RUNNER_EXIT_CODE_FILENAME in source
     assert RUNNER_ENDED_AT_FILENAME in source
     assert "write_atomic" in source

{shell_session_manager-2.1.1 → shell_session_manager-2.2.0}/tests/test_shellctl_shared.py

@@ -4,9 +4,13 @@ from datetime import UTC, datetime
 from io import BytesIO
 from pathlib import Path
 
+import pytest
+from pydantic import ValidationError
+
 from shell_session_manager.shellctl.shared import (
     JOB_ID_ALPHABET,
     PtySanitizer,
+    RunJobRequest,
     generate_job_id,
     read_output_window,
     sanitize_pty_output,
@@ -112,3 +116,19 @@ def test_sanitize_pty_stream_flushes_incrementally() -> None:
 
     assert stdout.getvalue() == b"ready\nnext\n"
     assert stdout.flush_count >= 2
+
+
+@pytest.mark.parametrize(
+    ("env", "message"),
+    [
+        ({"": "x"}, "non-empty"),
+        ({"A=B": "x"}, "must not contain '='"),
+        ({"A\x00B": "x"}, "must not contain NUL"),
+        ({"A": "x\x00y"}, "must not contain NUL"),
+    ],
+)
+def test_run_job_request_rejects_invalid_env_entries(
+    env: dict[str, str], message: str
+) -> None:
+    with pytest.raises(ValidationError, match=message):
+        RunJobRequest(script="printf ready\n", env=env)