shellsim 0.1.0__tar.gz → 0.1.3__tar.gz

{shellsim-0.1.0 → shellsim-0.1.3}/Cargo.lock

@@ -330,7 +330,7 @@ dependencies = [
 
 [[package]]
 name = "shellsim"
-version = "0.1.0"
+version = "0.1.3"
 dependencies = [
  "base64",
  "crc32fast",

{shellsim-0.1.0 → shellsim-0.1.3}/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "shellsim"
-version = "0.1.0"
+version = "0.1.3"
 edition = "2021"
-description = "Deterministic, resource-constrained BusyBox-like environment for evaluating agents"
+description = "In-process BusyBox-like environment for RL rollouts and agent tests"
 license = "Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/rjpower/shellsim"
@@ -58,4 +58,5 @@ python = []
 opt-level = 1
 
 [profile.release]
-opt-level = 2
+opt-level = "s"
+lto = false

shellsim-0.1.3/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: shellsim
+Version: 0.1.3
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+License-File: LICENSE
+Summary: In-process BusyBox-like environment for RL rollouts and agent tests
+Keywords: agents,containers,reinforcement-learning,sandbox,simulation,testing
+Author: The shellsim authors
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/rjpower/shellsim
+Project-URL: Issues, https://github.com/rjpower/shellsim/issues
+Project-URL: Repository, https://github.com/rjpower/shellsim
+
+# shellsim
+
+Shellsim is a BusyBox for containers: one small, deterministic process that provides a useful
+Unix-shaped environment without starting a VM, container runtime, or host subprocess. It is built
+for experimentation and testing with reinforcement-learning rollouts and agentic environments,
+where fast startup, reproducibility, isolation, and explicit resource limits matter more than
+cycle-accurate emulation.
+
+Shell programs, common command-line tools, logical processes, and Python run in-process against an
+in-memory filesystem. Simulated code cannot access the host filesystem, processes, network,
+environment, or clock. A trusted harness may copy a selected project into the virtual filesystem
+before execution; changes never write back to the host.
+
+## Compatibility
+
+Shellsim aims for broad compatibility inside clear boundaries. A supported facility should handle
+almost all ordinary uses, even when obscure flags or legacy behavior remain out of scope. A module
+or command with no coherent useful subset is omitted instead of being exposed as a misleading
+stub. Unsupported syntax, options, executable formats, and capabilities fail visibly and are
+included in structured results.
+
+The current environment includes:
+
+- a Bash-like shell with pipelines, redirections, functions, common expansions, control flow,
+  background jobs, signals, and job control;
+- common filesystem, text, archive, Git, Make, process, and system commands;
+- deterministic virtual time, network fixtures, `/proc`, `/dev`, processes, descriptors, and
+  bounded pipes;
+- a mostly complete Python language runtime with a deliberately selected standard-library and
+  third-party module surface.
+
+Python is source-compatible where supported, not ABI-compatible with CPython. Native extensions,
+package installation, compilers, and arbitrary machine code are outside the simulation boundary.
+See [Python in shellsim](docs/python.md) for the current contract.
+
+## Install and run
+
+Install the Python package and console command:
+
+```sh
+python -m pip install shellsim
+shellsim -c 'printf "b\na\n" | sort'
+shellsim --root ./project -c 'python3.14 test.py'
+```
+
+`--root` copies the selected host tree into a disposable `/work` snapshot. With no `-c` and a
+terminal attached, `shellsim` starts a persistent interactive session.
+
+To build the Rust binaries from source:
+
+```sh
+cargo build --release
+./target/release/shellsim -c 'echo hello'
+./target/release/shellsim eval --cpu 100k --memory 8m -c 'make test'
+./target/release/shellsim-python ./project/main.py -- arg1
+```
+
+Limits accept `k`, `m`, and `g` binary suffixes. `eval` emits a structured result containing the
+exit status, stdout and stderr, resource use, command trace, and unsupported behavior.
+
+The Python API exposes fresh and persistent environments:
+
+```python
+import shellsim
+
+environment = shellsim.Environment(cpu=100_000)
+environment.write_file("/work/main.py", "print(6 * 7)\n")
+result = environment.run("python3.14 /work/main.py")
+assert result.returncode == 0
+assert result.stdout == b"42\n"
+```
+
+## Agent harness
+
+`shellsim serve --root ./project` runs a persistent newline-delimited JSON session. It supports
+bounded execution, streaming actions, VFS operations, checkpoints, workspace diffs, process and
+resource inspection, and deterministic session forks. `shellsim mcp` exposes the same environment
+as a stdio MCP server. `shellsim replay scenario.ndjson` reruns checked action transcripts.
+
+```sh
+printf '%s\n' \
+  '{"id":1,"op":"execute","source":"printf hello > result"}' \
+  '{"id":2,"op":"workspace_diff"}' \
+  | shellsim serve --root ./project
+```
+
+## Resource model
+
+CPU is deterministic fuel, memory is modeled working set, disk is current virtual-filesystem
+usage, and output bounds materialized stdout and stderr. The defaults are 10,000,000 CPU units,
+64 MiB memory, 64 MiB disk, and 4 MiB output. Costs are stable and intentionally approximate.
+Exhaustion is observable and never falls back to an ambient host implementation.
+
+For internals and contribution workflow, see [implementation](docs/implementation.md),
+[Python](docs/python.md), and [CONTRIBUTING.md](CONTRIBUTING.md).
+

shellsim-0.1.3/README.md

@@ -0,0 +1,95 @@
+# shellsim
+
+Shellsim is a BusyBox for containers: one small, deterministic process that provides a useful
+Unix-shaped environment without starting a VM, container runtime, or host subprocess. It is built
+for experimentation and testing with reinforcement-learning rollouts and agentic environments,
+where fast startup, reproducibility, isolation, and explicit resource limits matter more than
+cycle-accurate emulation.
+
+Shell programs, common command-line tools, logical processes, and Python run in-process against an
+in-memory filesystem. Simulated code cannot access the host filesystem, processes, network,
+environment, or clock. A trusted harness may copy a selected project into the virtual filesystem
+before execution; changes never write back to the host.
+
+## Compatibility
+
+Shellsim aims for broad compatibility inside clear boundaries. A supported facility should handle
+almost all ordinary uses, even when obscure flags or legacy behavior remain out of scope. A module
+or command with no coherent useful subset is omitted instead of being exposed as a misleading
+stub. Unsupported syntax, options, executable formats, and capabilities fail visibly and are
+included in structured results.
+
+The current environment includes:
+
+- a Bash-like shell with pipelines, redirections, functions, common expansions, control flow,
+  background jobs, signals, and job control;
+- common filesystem, text, archive, Git, Make, process, and system commands;
+- deterministic virtual time, network fixtures, `/proc`, `/dev`, processes, descriptors, and
+  bounded pipes;
+- a mostly complete Python language runtime with a deliberately selected standard-library and
+  third-party module surface.
+
+Python is source-compatible where supported, not ABI-compatible with CPython. Native extensions,
+package installation, compilers, and arbitrary machine code are outside the simulation boundary.
+See [Python in shellsim](docs/python.md) for the current contract.
+
+## Install and run
+
+Install the Python package and console command:
+
+```sh
+python -m pip install shellsim
+shellsim -c 'printf "b\na\n" | sort'
+shellsim --root ./project -c 'python3.14 test.py'
+```
+
+`--root` copies the selected host tree into a disposable `/work` snapshot. With no `-c` and a
+terminal attached, `shellsim` starts a persistent interactive session.
+
+To build the Rust binaries from source:
+
+```sh
+cargo build --release
+./target/release/shellsim -c 'echo hello'
+./target/release/shellsim eval --cpu 100k --memory 8m -c 'make test'
+./target/release/shellsim-python ./project/main.py -- arg1
+```
+
+Limits accept `k`, `m`, and `g` binary suffixes. `eval` emits a structured result containing the
+exit status, stdout and stderr, resource use, command trace, and unsupported behavior.
+
+The Python API exposes fresh and persistent environments:
+
+```python
+import shellsim
+
+environment = shellsim.Environment(cpu=100_000)
+environment.write_file("/work/main.py", "print(6 * 7)\n")
+result = environment.run("python3.14 /work/main.py")
+assert result.returncode == 0
+assert result.stdout == b"42\n"
+```
+
+## Agent harness
+
+`shellsim serve --root ./project` runs a persistent newline-delimited JSON session. It supports
+bounded execution, streaming actions, VFS operations, checkpoints, workspace diffs, process and
+resource inspection, and deterministic session forks. `shellsim mcp` exposes the same environment
+as a stdio MCP server. `shellsim replay scenario.ndjson` reruns checked action transcripts.
+
+```sh
+printf '%s\n' \
+  '{"id":1,"op":"execute","source":"printf hello > result"}' \
+  '{"id":2,"op":"workspace_diff"}' \
+  | shellsim serve --root ./project
+```
+
+## Resource model
+
+CPU is deterministic fuel, memory is modeled working set, disk is current virtual-filesystem
+usage, and output bounds materialized stdout and stderr. The defaults are 10,000,000 CPU units,
+64 MiB memory, 64 MiB disk, and 4 MiB output. Costs are stable and intentionally approximate.
+Exhaustion is observable and never falls back to an ambient host implementation.
+
+For internals and contribution workflow, see [implementation](docs/implementation.md),
+[Python](docs/python.md), and [CONTRIBUTING.md](CONTRIBUTING.md).

{shellsim-0.1.0 → shellsim-0.1.3}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "maturin"
 [project]
 name = "shellsim"
 dynamic = ["version"]
-description = "Deterministic, resource-constrained shell and Python execution for tests"
+description = "In-process BusyBox-like environment for RL rollouts and agent tests"
 readme = "README.md"
 requires-python = ">=3.9"
 license = { file = "LICENSE" }
@@ -22,13 +22,16 @@ classifiers = [
     "Topic :: Software Development :: Testing",
     "Typing :: Typed",
 ]
-keywords = ["sandbox", "shell", "simulation", "testing"]
+keywords = ["agents", "containers", "reinforcement-learning", "sandbox", "simulation", "testing"]
 
 [project.urls]
 Homepage = "https://github.com/rjpower/shellsim"
 Issues = "https://github.com/rjpower/shellsim/issues"
 Repository = "https://github.com/rjpower/shellsim"
 
+[project.scripts]
+shellsim = "shellsim._cli:main"
+
 [dependency-groups]
 test = ["pytest>=8"]
 
@@ -42,3 +45,25 @@ strip = true
 
 [tool.pytest.ini_options]
 testpaths = ["python_tests"]
+
+[tool.marin-style]
+checks = ["ruff-check", "ruff-format"]
+include = [
+    "infra/*.py",
+    "infra/**/*.py",
+    "python/**/*.py",
+    "python_tests/*.py",
+    "python_tests/**/*.py",
+    "tools/*.py",
+    "tools/**/*.py",
+]
+main_branch = "main"
+ruff_version = "0.14.3"
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "C4"]
+ignore = ["E501"]

{shellsim-0.1.0 → shellsim-0.1.3}/python/native/Cargo.lock

@@ -406,7 +406,7 @@ dependencies = [
 
 [[package]]
 name = "shellsim"
-version = "0.1.0"
+version = "0.1.3"
 dependencies = [
  "base64",
  "crc32fast",
@@ -427,7 +427,7 @@ dependencies = [
 
 [[package]]
 name = "shellsim-python-bindings"
-version = "0.1.0"
+version = "0.1.3"
 dependencies = [
  "pyo3",
  "serde",

{shellsim-0.1.0 → shellsim-0.1.3}/python/native/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "shellsim-python-bindings"
-version = "0.1.0"
+version = "0.1.3"
 edition = "2021"
 description = "Python bindings for shellsim"
 license = "Apache-2.0"
@@ -18,3 +18,7 @@ pyo3 = { version = "0.28", features = ["abi3-py39", "extension-module"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 shellsim = { path = "../.." }
+
+[profile.release]
+opt-level = "s"
+lto = false

shellsim-0.1.3/python/shellsim/__main__.py

@@ -0,0 +1,5 @@
+"""Run the shellsim package as a module."""
+
+from ._cli import main
+
+raise SystemExit(main())

{shellsim-0.1.0 → shellsim-0.1.3}/python/shellsim/_api.py

@@ -2,14 +2,14 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
 import json
 import os
-from typing import Any, Mapping, Optional, Tuple, Union
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Optional, Tuple, Union
 
 from . import _native
 
-
 SimulationError = _native.SimulationError
 
 _MAX_U64 = (1 << 64) - 1
@@ -111,9 +111,7 @@ class RunResult:
         if self.returncode != 0:
             diagnostic = self.stderr_text.strip()
             suffix = f": {diagnostic}" if diagnostic else ""
-            raise SimulationError(
-                f"shellsim action exited with status {self.returncode}{suffix}"
-            )
+            raise SimulationError(f"shellsim action exited with status {self.returncode}{suffix}")
 
 
 class Environment:
@@ -138,11 +136,7 @@ class Environment:
         if limits is not None and not isinstance(limits, Limits):
             raise TypeError("limits must be a shellsim.Limits instance")
         resolved = limits or Limits(
-            **{
-                name: _validate_limit(name, value)
-                for name, value in overrides.items()
-                if value is not None
-            }
+            **{name: _validate_limit(name, value) for name, value in overrides.items() if value is not None}
         )
         self._native = _native.NativeEnvironment(
             resolved.cpu,
@@ -157,9 +151,7 @@ class Environment:
 
         return bool(self._native.terminated)
 
-    def run(
-        self, source: str, stdin: Union[bytes, bytearray, memoryview] = b""
-    ) -> RunResult:
+    def run(self, source: str, stdin: Union[bytes, bytearray, memoryview] = b"") -> RunResult:
         """Execute one complete shell action with an explicit input byte stream."""
 
         if not isinstance(source, str):
@@ -204,9 +196,7 @@ class Environment:
             raise TypeError("parents must be bool")
         self._native.mkdir(path, parents)
 
-    def mount(
-        self, host_root: Union[str, os.PathLike[str]], destination: str = "/work"
-    ) -> MountResult:
+    def mount(self, host_root: Union[str, os.PathLike[str]], destination: str = "/work") -> MountResult:
         """Copy an explicitly trusted host directory into the bounded VFS.
 
         The walk rejects symlinks and non-regular files, has a 10,000-file limit, and skips

shellsim-0.1.3/python/shellsim/_cli.py

@@ -0,0 +1,175 @@
+"""Command-line interface for the installed shellsim Python package."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from typing import Any, Optional
+
+from ._api import Environment, RunResult, SimulationError
+
+_MAX_U64 = (1 << 64) - 1
+
+
+def _quantity(value: str) -> int:
+    """Parse a non-negative count with an optional binary k, m, or g suffix."""
+
+    suffixes = {"k": 1024, "m": 1024**2, "g": 1024**3}
+    suffix = value[-1:].lower()
+    multiplier = suffixes.get(suffix, 1)
+    digits = value[:-1] if suffix in suffixes else value
+    try:
+        number = int(digits)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("expected a count, optionally suffixed with k, m, or g") from error
+    result = number * multiplier
+    if number < 0 or result > _MAX_U64:
+        raise argparse.ArgumentTypeError(f"expected a count between 0 and {_MAX_U64}")
+    return result
+
+
+def _parser() -> argparse.ArgumentParser:
+    """Build the command-line parser shared by the console and module entry points."""
+
+    parser = argparse.ArgumentParser(
+        prog="shellsim",
+        description="Run shell commands in a deterministic in-memory simulation.",
+    )
+    parser.add_argument("-c", "--command", metavar="SOURCE", help="execute one shell action")
+    parser.add_argument(
+        "--root",
+        metavar="DIR",
+        help="copy this trusted host directory into the simulated /work tree",
+    )
+    parser.add_argument("--cpu", type=_quantity, help="cumulative CPU fuel limit")
+    parser.add_argument("--memory", type=_quantity, help="modeled memory limit")
+    parser.add_argument("--disk", type=_quantity, help="simulated filesystem limit")
+    parser.add_argument("--output", type=_quantity, help="cumulative output limit")
+    return parser
+
+
+def _binary_stream(stream: Any) -> Any:
+    """Return a stream that accepts bytes, including under in-process test doubles."""
+
+    return getattr(stream, "buffer", stream)
+
+
+def _write_bytes(stream: Any, data: bytes) -> None:
+    """Write exact simulator bytes to a host console stream."""
+
+    binary = _binary_stream(stream)
+    try:
+        binary.write(data)
+    except TypeError:
+        binary.write(data.decode("utf-8", errors="replace"))
+    binary.flush()
+
+
+def _emit_result(result: RunResult, stdout: Any, stderr: Any) -> None:
+    """Forward one simulated action's byte-preserving output."""
+
+    _write_bytes(stdout, result.stdout)
+    _write_bytes(stderr, result.stderr)
+
+
+def _execute_action(
+    environment: Environment,
+    source: str,
+    stdin: bytes,
+    stdout: Any,
+    stderr: Any,
+) -> Optional[RunResult]:
+    """Execute and forward one action, reporting adapter failures without a traceback."""
+
+    try:
+        result = environment.run(source, stdin)
+    except SimulationError as error:
+        print(f"shellsim: {error}", file=stderr)
+        return None
+    _emit_result(result, stdout, stderr)
+    return result
+
+
+def _read_bytes(stream: Any) -> bytes:
+    """Read all remaining input without depending on a text-stream encoding."""
+
+    data = _binary_stream(stream).read()
+    return data.encode() if isinstance(data, str) else data
+
+
+def _prepare_environment(options: argparse.Namespace, stdout: Any, stderr: Any) -> tuple[Optional[Environment], int]:
+    """Create a simulated machine, import an optional host snapshot, and enter `/work`."""
+
+    environment = Environment(
+        cpu=options.cpu,
+        memory=options.memory,
+        disk=options.disk,
+        output=options.output,
+    )
+    try:
+        if options.root is not None:
+            environment.mount(options.root)
+        prepared = environment.run("cd /work")
+    except SimulationError as error:
+        print(f"shellsim: {error}", file=stderr)
+        return None, 2
+
+    if prepared.returncode != 0:
+        _emit_result(prepared, stdout, stderr)
+        return None, prepared.returncode
+    return environment, 0
+
+
+def _interactive(environment: Environment, stdin: Any, stdout: Any, stderr: Any) -> int:
+    """Run one action per input line while retaining simulated state."""
+
+    status = 0
+    while not environment.terminated:
+        stdout.write("shellsim$ ")
+        stdout.flush()
+        try:
+            line = stdin.readline()
+        except KeyboardInterrupt:
+            stdout.write("\n")
+            stdout.flush()
+            continue
+        if not line:
+            stdout.write("\n")
+            stdout.flush()
+            break
+        result = _execute_action(environment, line, b"", stdout, stderr)
+        if result is None:
+            return 1
+        status = result.returncode
+    return status
+
+
+def main(arguments: Optional[Sequence[str]] = None) -> int:
+    """Run the package CLI and return the simulated or usage exit status."""
+
+    options = _parser().parse_args(sys.argv[1:] if arguments is None else arguments)
+    environment, preparation_status = _prepare_environment(options, sys.stdout, sys.stderr)
+    if environment is None:
+        return preparation_status
+
+    if options.command is not None:
+        stdin = b"" if sys.stdin.isatty() else _read_bytes(sys.stdin)
+        result = _execute_action(environment, options.command, stdin, sys.stdout, sys.stderr)
+        if result is None:
+            return 1
+        return result.returncode
+
+    if sys.stdin.isatty():
+        return _interactive(environment, sys.stdin, sys.stdout, sys.stderr)
+
+    source_bytes = _read_bytes(sys.stdin)
+    try:
+        source = source_bytes.decode("utf-8")
+    except UnicodeDecodeError as error:
+        print(f"shellsim: stdin is not valid UTF-8 shell source: {error}", file=sys.stderr)
+        return 2
+    result = _execute_action(environment, source, b"", sys.stdout, sys.stderr)
+    if result is None:
+        return 1
+    return result.returncode