shellsim 0.1.22__tar.gz → 0.1.25__tar.gz

{shellsim-0.1.22 → shellsim-0.1.25}/Cargo.lock

@@ -861,7 +861,7 @@ dependencies = [
 
 [[package]]
 name = "shellsim"
-version = "0.1.22"
+version = "0.1.25"
 dependencies = [
  "base64",
  "crc32fast",

{shellsim-0.1.22 → shellsim-0.1.25}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "shellsim"
-version = "0.1.22"
+version = "0.1.25"
 edition = "2021"
 description = "In-process BusyBox-like environment for RL rollouts and agent tests"
 license = "Apache-2.0"

{shellsim-0.1.22 → shellsim-0.1.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellsim
-Version: 0.1.22
+Version: 0.1.25
 Classifier: Development Status :: 3 - Alpha
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
@@ -10,6 +10,8 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
+Requires-Dist: shellsim-c-toolchain==0.1.25 ; extra == 'c'
+Provides-Extra: c
 License-File: LICENSE
 Summary: In-process BusyBox-like environment for RL rollouts and agent tests
 Keywords: agents,containers,reinforcement-learning,sandbox,simulation,testing
@@ -84,6 +86,10 @@ shellsim -c 'printf "b\na\n" | sort'
 shellsim --root ./project -c 'python3.14 test.py'
 ```
 
+Install `shellsim[c]` instead when a `.shl` package needs the separately distributed C-to-Wasm
+toolchain. The core wheel does not contain TinyCC or the WASI sysroot. See
+[the C toolchain contract](docs/shl-packages.md#optional-c-toolchain).
+
 `--root` copies the selected host tree into a disposable `/work` snapshot. With no `-c` and a
 terminal attached, `shellsim` starts a persistent interactive session.
 
@@ -206,6 +212,13 @@ as a stdio MCP server. `shellsim replay scenario.ndjson` reruns checked action t
 `shellsim corpus manifest.json` runs frozen shell and Python workloads under a versioned stock
 environment and emits a classified JSON report. See [compatibility testing](docs/compatibility-testing.md).
 
+`shellsim serve --host-tools` grants a virtual guest-to-host tool route at construction. The
+trusted runner receives typed calls in `poll_action` and completes them with `respond_tool_call`;
+ordinary sessions have no such route. See [`.shl` package design](docs/shl-packages.md).
+
+Python hosts can instead use `shellsim.Container(tools={"name": handler})` to register handlers
+at construction and call `container.run(...)` without a CLI subprocess or manual polling.
+
 ```sh
 printf '%s\n' \
   '{"id":1,"op":"execute","source":"printf hello > result"}' \

{shellsim-0.1.22 → shellsim-0.1.25}/README.md

@@ -61,6 +61,10 @@ shellsim -c 'printf "b\na\n" | sort'
 shellsim --root ./project -c 'python3.14 test.py'
 ```
 
+Install `shellsim[c]` instead when a `.shl` package needs the separately distributed C-to-Wasm
+toolchain. The core wheel does not contain TinyCC or the WASI sysroot. See
+[the C toolchain contract](docs/shl-packages.md#optional-c-toolchain).
+
 `--root` copies the selected host tree into a disposable `/work` snapshot. With no `-c` and a
 terminal attached, `shellsim` starts a persistent interactive session.
 
@@ -183,6 +187,13 @@ as a stdio MCP server. `shellsim replay scenario.ndjson` reruns checked action t
 `shellsim corpus manifest.json` runs frozen shell and Python workloads under a versioned stock
 environment and emits a classified JSON report. See [compatibility testing](docs/compatibility-testing.md).
 
+`shellsim serve --host-tools` grants a virtual guest-to-host tool route at construction. The
+trusted runner receives typed calls in `poll_action` and completes them with `respond_tool_call`;
+ordinary sessions have no such route. See [`.shl` package design](docs/shl-packages.md).
+
+Python hosts can instead use `shellsim.Container(tools={"name": handler})` to register handlers
+at construction and call `container.run(...)` without a CLI subprocess or manual polling.
+
 ```sh
 printf '%s\n' \
   '{"id":1,"op":"execute","source":"printf hello > result"}' \

{shellsim-0.1.22 → shellsim-0.1.25}/pyproject.toml

@@ -24,6 +24,9 @@ classifiers = [
 ]
 keywords = ["agents", "containers", "reinforcement-learning", "sandbox", "simulation", "testing"]
 
+[project.optional-dependencies]
+c = ["shellsim-c-toolchain==0.1.25"]
+
 [project.urls]
 Homepage = "https://github.com/rjpower/shellsim"
 Issues = "https://github.com/rjpower/shellsim/issues"
@@ -52,6 +55,7 @@ include = [
     "infra/*.py",
     "infra/**/*.py",
     "python/**/*.py",
+    "toolchain/**/*.py",
     "tests/python/test_*.py",
     "tests/python_package/**/*.py",
     "tests/tooling/**/*.py",

{shellsim-0.1.22 → shellsim-0.1.25}/python/native/Cargo.lock

@@ -925,7 +925,7 @@ dependencies = [
 
 [[package]]
 name = "shellsim"
-version = "0.1.22"
+version = "0.1.25"
 dependencies = [
  "base64",
  "crc32fast",
@@ -949,8 +949,9 @@ dependencies = [
 
 [[package]]
 name = "shellsim-python-bindings"
-version = "0.1.22"
+version = "0.1.25"
 dependencies = [
+ "base64",
  "pyo3",
  "serde",
  "serde_json",

{shellsim-0.1.22 → shellsim-0.1.25}/python/native/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "shellsim-python-bindings"
-version = "0.1.22"
+version = "0.1.25"
 edition = "2021"
 description = "Python bindings for shellsim"
 license = "Apache-2.0"
@@ -14,6 +14,7 @@ name = "shellsim_native"
 crate-type = ["cdylib"]
 
 [dependencies]
+base64 = "0.22"
 pyo3 = { version = "0.28", features = ["abi3-py39", "extension-module"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

{shellsim-0.1.22 → shellsim-0.1.25}/python/native/src/lib.rs

@@ -12,15 +12,21 @@ use std::path::Path;
 use std::sync::Mutex;
 use std::thread;
 
+use base64::engine::general_purpose::STANDARD;
+use base64::Engine;
 use pyo3::create_exception;
 use pyo3::exceptions::PyException;
 use pyo3::prelude::*;
 use pyo3::types::PyBytes;
 use serde::Serialize;
+use shellsim::display::KeyEvent;
+use shellsim::harness::{HarnessOperation, HarnessRequest, HarnessSession};
 use shellsim::net::NetworkRequest;
+use shellsim::realtime::ClockMode;
 use shellsim::{CommandTrust, InvocationEvent, Limits, RunOutcome};
 
 const ACTION_STACK_BYTES: usize = 8 * 1024 * 1024;
+type PythonFrame = (u64, u32, u32, Py<PyBytes>);
 
 create_exception!(
     shellsim._native,
@@ -67,6 +73,253 @@ struct NativeEnvironment {
     environment: Mutex<shellsim::Environment>,
 }
 
+/// In-process host control for a machine granted the virtual tool endpoint.
+#[pyclass(module = "shellsim._native")]
+struct NativeContainer {
+    session: Mutex<HarnessSession>,
+}
+
+#[pymethods]
+impl NativeContainer {
+    #[new]
+    fn new(cpu: u64, memory: u64, disk: u64, output: u64, real_time: bool) -> Self {
+        Self {
+            session: Mutex::new(HarnessSession::with_clock_and_host_tools(
+                Limits {
+                    cpu,
+                    memory,
+                    disk,
+                    output,
+                },
+                if real_time {
+                    ClockMode::RealTime
+                } else {
+                    ClockMode::Virtual
+                },
+            )),
+        }
+    }
+
+    fn write_file(&self, py: Python<'_>, path: String, data: Vec<u8>, mode: u32) -> PyResult<()> {
+        let path = container_vfs_path(&path).map_err(SimulationError::new_err)?;
+        if mode > 0o7777 {
+            return Err(SimulationError::new_err("invalid file mode"));
+        }
+        py.detach(|| {
+            let mut session = self
+                .session
+                .lock()
+                .map_err(|_| "shellsim container lock is poisoned".to_string())?;
+            on_worker(&mut session, move |session| {
+                session.environment.sync_vfs_time();
+                session
+                    .environment
+                    .vfs
+                    .put_file(&path, data, mode)
+                    .map_err(|error| error.to_string())
+            })
+        })
+        .map_err(SimulationError::new_err)
+    }
+
+    fn read_file(&self, py: Python<'_>, path: String) -> PyResult<Py<PyBytes>> {
+        let path = container_vfs_path(&path).map_err(SimulationError::new_err)?;
+        let bytes = py
+            .detach(|| {
+                let mut session = self
+                    .session
+                    .lock()
+                    .map_err(|_| "shellsim container lock is poisoned".to_string())?;
+                on_worker(&mut session, move |session| {
+                    session
+                        .environment
+                        .vfs
+                        .read("/", &path)
+                        .map_err(|error| error.to_string())
+                })
+            })
+            .map_err(SimulationError::new_err)?;
+        Ok(PyBytes::new(py, &bytes).unbind())
+    }
+
+    fn mkdir(&self, py: Python<'_>, path: String, mode: u32) -> PyResult<()> {
+        let path = container_vfs_path(&path).map_err(SimulationError::new_err)?;
+        if mode > 0o7777 {
+            return Err(SimulationError::new_err("invalid directory mode"));
+        }
+        py.detach(|| {
+            let mut session = self
+                .session
+                .lock()
+                .map_err(|_| "shellsim container lock is poisoned".to_string())?;
+            on_worker(&mut session, move |session| {
+                session.environment.sync_vfs_time();
+                session
+                    .environment
+                    .vfs
+                    .put_dir(&path, mode)
+                    .map_err(|error| error.to_string())
+            })
+        })
+        .map_err(SimulationError::new_err)
+    }
+
+    fn snapshot_workspace(&self, py: Python<'_>) -> PyResult<String> {
+        py.detach(|| {
+            let mut session = self
+                .session
+                .lock()
+                .map_err(|_| "shellsim container lock is poisoned".to_string())?;
+            on_worker(&mut session, |session| {
+                let entries = session.snapshot_workspace()?;
+                serde_json::to_string(&entries).map_err(|error| error.to_string())
+            })
+        })
+        .map_err(SimulationError::new_err)
+    }
+
+    fn start_execute(&self, py: Python<'_>, source: String, stdin: Vec<u8>) -> PyResult<String> {
+        self.apply(
+            py,
+            HarnessOperation::StartExecute {
+                source,
+                stdin_base64: STANDARD.encode(stdin),
+                stdin_closed: true,
+            },
+        )
+        .and_then(serialize_result)
+    }
+
+    fn poll_action(&self, py: Python<'_>, action_id: u64) -> PyResult<String> {
+        self.apply(
+            py,
+            HarnessOperation::PollAction {
+                action_id,
+                work_quanta: 100_000,
+                advance_time: true,
+            },
+        )
+        .and_then(serialize_result)
+    }
+
+    fn respond_tool_call(
+        &self,
+        py: Python<'_>,
+        request_id: u64,
+        result_json: Option<String>,
+        error: Option<String>,
+    ) -> PyResult<()> {
+        let result = result_json
+            .map(|json| serde_json::from_str(&json))
+            .transpose()
+            .map_err(|error| SimulationError::new_err(error.to_string()))?;
+        self.apply(
+            py,
+            HarnessOperation::RespondToolCall {
+                request_id,
+                result,
+                error,
+            },
+        )?;
+        Ok(())
+    }
+
+    fn read_action_output(&self, py: Python<'_>, action_id: u64) -> PyResult<String> {
+        self.apply(py, HarnessOperation::ReadActionOutput { action_id })
+            .and_then(serialize_result)
+    }
+
+    fn cancel_action(&self, py: Python<'_>, action_id: u64) -> PyResult<()> {
+        self.apply(py, HarnessOperation::CancelAction { action_id })?;
+        Ok(())
+    }
+
+    fn drop_action(&self, py: Python<'_>, action_id: u64) -> PyResult<()> {
+        self.apply(py, HarnessOperation::DropAction { action_id })?;
+        Ok(())
+    }
+
+    fn display_frame(&self, py: Python<'_>, action_id: u64) -> PyResult<Option<PythonFrame>> {
+        let frame = py
+            .detach(|| {
+                let mut session = self
+                    .session
+                    .lock()
+                    .map_err(|_| "shellsim container lock is poisoned".to_string())?;
+                on_worker(&mut session, |session| session.display_frame(action_id))
+            })
+            .map_err(SimulationError::new_err)?;
+        Ok(frame.map(|(generation, frame)| {
+            (
+                generation,
+                frame.width,
+                frame.height,
+                PyBytes::new(py, &frame.pixels).unbind(),
+            )
+        }))
+    }
+
+    fn inject_key(&self, py: Python<'_>, action_id: u64, code: u32, pressed: bool) -> PyResult<()> {
+        py.detach(|| {
+            let mut session = self
+                .session
+                .lock()
+                .map_err(|_| "shellsim container lock is poisoned".to_string())?;
+            on_worker(&mut session, |session| {
+                session.inject_action_key(action_id, KeyEvent { code, pressed })
+            })
+        })
+        .map_err(SimulationError::new_err)
+    }
+
+    fn clock_mode(&self) -> PyResult<&'static str> {
+        let session = self
+            .session
+            .lock()
+            .map_err(|_| SimulationError::new_err("shellsim container lock is poisoned"))?;
+        Ok(match session.environment.clock_mode() {
+            ClockMode::Virtual => "virtual",
+            ClockMode::RealTime => "real_time",
+        })
+    }
+}
+
+impl NativeContainer {
+    fn apply(&self, py: Python<'_>, operation: HarnessOperation) -> PyResult<serde_json::Value> {
+        py.detach(|| {
+            let mut session = self
+                .session
+                .lock()
+                .map_err(|_| "shellsim container lock is poisoned".to_string())?;
+            on_worker(&mut session, move |session| {
+                let response = session.handle(HarnessRequest {
+                    id: None,
+                    session_id: None,
+                    operation,
+                });
+                if !response.ok {
+                    return Err(response
+                        .error
+                        .unwrap_or_else(|| "container operation failed".into()));
+                }
+                serde_json::to_value(response.result).map_err(|error| error.to_string())
+            })
+        })
+        .map_err(SimulationError::new_err)
+    }
+}
+
+fn container_vfs_path(path: &str) -> Result<String, String> {
+    if path.contains('\0') {
+        return Err("container path contains NUL".to_string());
+    }
+    Ok(shellsim::vfs::resolve_against("/work", path))
+}
+
+fn serialize_result(result: serde_json::Value) -> PyResult<String> {
+    serde_json::to_string(&result).map_err(|error| SimulationError::new_err(error.to_string()))
+}
+
 #[pymethods]
 impl NativeEnvironment {
     #[new]
@@ -380,11 +633,16 @@ fn invocation_names(events: &[InvocationEvent], trust: CommandTrust) -> Vec<Stri
 }
 
 /// Run an environment operation with a predictable native stack and contain all Rust unwinds.
-fn on_worker<T, F>(environment: &mut shellsim::Environment, operation: F) -> Result<T, String>
+fn on_worker<State, T, F>(
+    guard: &mut std::sync::MutexGuard<'_, State>,
+    operation: F,
+) -> Result<T, String>
 where
+    State: Send,
     T: Send,
-    F: FnOnce(&mut shellsim::Environment) -> Result<T, String> + Send,
+    F: FnOnce(&mut State) -> Result<T, String> + Send,
 {
+    let environment = &mut **guard;
     thread::scope(|scope| {
         let worker = thread::Builder::new()
             .name("shellsim-python".to_string())
@@ -416,6 +674,7 @@ fn panic_suffix(payload: &(dyn Any + Send)) -> String {
 #[pymodule]
 fn _native(module: &Bound<'_, PyModule>) -> PyResult<()> {
     module.add_class::<NativeEnvironment>()?;
+    module.add_class::<NativeContainer>()?;
     module.add("SimulationError", module.py().get_type::<SimulationError>())?;
     Ok(())
 }

{shellsim-0.1.22 → shellsim-0.1.25}/python/shellsim/__init__.py

@@ -2,7 +2,11 @@
 
 from . import python as python
 from ._api import (
+    Action,
+    ActionPoll,
     CommandUsage,
+    Container,
+    DisplayFrame,
     Environment,
     HttpRequest,
     HttpResponse,
@@ -12,21 +16,32 @@ from ._api import (
     RunResult,
     ShellSession,
     SimulationError,
+    ToolError,
     Usage,
     run,
 )
+from .display_host import DisplayHost
+from .package import Package, PackageSpec
 
 __all__ = [
+    "Action",
+    "ActionPoll",
     "CommandUsage",
+    "Container",
+    "DisplayFrame",
+    "DisplayHost",
     "Environment",
     "HttpRequest",
     "HttpResponse",
     "Invocation",
     "Limits",
     "MountResult",
+    "Package",
+    "PackageSpec",
     "RunResult",
     "ShellSession",
     "SimulationError",
+    "ToolError",
     "Usage",
     "run",
     "python",