Pseudo filesystem support (#85)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: samuelcolvin

.claude/settings.json

@@ -27,7 +27,6 @@
       "Bash(git mv:*)",
       "Bash(git log:*)",
       "Bash(git grep:*)",
-      "Bash(git commit:*)",
       "Bash(gh pr view:*)",
       "Bash(gh api:*)",
       "Bash(gh run view:*)",
@@ -43,7 +42,8 @@
       "WebFetch(domain:docs.anthropic.com)",
       "WebFetch(domain:github.com)",
       "WebFetch(domain:15r10nk.github.io)",
-      "WebFetch(domain:docs.rs)"
+      "WebFetch(domain:docs.rs)",
+      "WebFetch(domain:pyo3.rs)"
     ],
     "deny": [],
     "ask": []

CLAUDE.md

@@ -14,6 +14,29 @@ Project goals:
 - **Snapshotting and iteration**: Plan is to allow code to be iteratively executed and snapshotted at each function call
 - Targets the latest stable version of Python, currently Python 3.14
 
+## Important Security Notice
+
+It's ABSOLUTELY CRITICAL that there's no way for code run in a Monty sandbox to access the host filesystem, or environment or to in any way "escape the sandbox".
+
+**Monty will be used to run untrusted, potentially malicious code.**
+
+Make sure there's no risk of this, either in the implementation, or in the public API that makes it more like that a developer using the pydantic_monty package might make such a mistake.
+
+Possible security risks to consider:
+* filesystem access
+* path traversal to access files the users did not intend to expose to the monty sandbox
+* memory errors - use of unsafe memory operations
+* excessive memory usage - evading monty's resource limits
+* infinite loops - evading monty's resource limits
+* network access - sockets, HTTP requests
+* subprocess/shell execution - os.system, subprocess, etc.
+* import system abuse - importing modules with side effects or accessing `__import__`
+* external function/callback misuse - callbacks run in host environment
+* deserialization attacks - loading untrusted serialized Monty/snapshot data
+* regex/string DoS - catastrophic backtracking or operations bypassing limits
+* information leakage via timing or error messages
+* Python/Javascript/Rust APIs that accidentally allow developers to expose their host to monty code
+
 ## Bytecode VM Architecture
 
 Monty is implemented as a bytecode VM, same as CPython.
@@ -118,13 +141,17 @@ explain what it does and why and any considerations or potential foot-guns of us
 
 The only exception is trait implementation methods where a docstring is not necessary if the method is self-explanatory.
 
+It's important that docstrings cover the motivation and primary usage patterns of code, not just the simple "what it does".
+
+Similarly, you should add comments to code, especially if the code is complex or esoteric.
+
 Only add examples to docstrings of public functions and structs, examples should be <=8 lines, if the example is more, remove it.
 
 If you add example code to docstrings, it must be run in tests. NEVER add examples that are ignored.
 
-Similarly, you should add lots of comments to code.
+If you encounter a comment or docstring that's out of date - you MUST update it to be correct.
 
-If you see a comment or docstring that's out of date - you MUST update it to be correct.
+Similarly, if you encounter code that has no docstrings or comments, or they are minimal, you should add more detail.
 
 NOTE: COMMENTS AND DOCSTRINGS ARE EXTREMELY IMPORTANT TO THE LONG TERM HEALTH OF THE PROJECT.
 
@@ -329,6 +356,9 @@ Use `@pytest.mark.parametrize` whenever testing multiple similar cases.
 
 Use `snapshot` from `inline-snapshot` for all test asserts.
 
+NEVER do the lazy `assert '...' in ...` instead always do `assert value == snapshot()`,
+then run the test and inline-snapshot will fill in the missing value in the `snapshot()` call.
+
 Use `pytest.raises` for expected exceptions, like this
 
 ```py

crates/monty-cli/src/main.rs

@@ -101,6 +101,11 @@ fn main() -> ExitCode {
                     eprintln!("{elapsed:?}, async futures not supported in CLI: {pending:?}");
                     return ExitCode::FAILURE;
                 }
+                RunProgress::OsCall { function, args, .. } => {
+                    let elapsed = start.elapsed();
+                    eprintln!("{elapsed:?}, OS calls not supported in CLI: {function:?}({args:?})");
+                    return ExitCode::FAILURE;
+                }
             }
         }
     } else {

crates/monty-js/src/convert.rs

@@ -80,6 +80,8 @@ pub fn monty_to_js<'e>(obj: &MontyObject, env: &'e Env) -> Result<JsMontyObject<
         MontyObject::Bytes(bytes) => create_js_buffer(bytes, env)?,
         MontyObject::List(items) => create_js_array(items, env)?.into_unknown(env)?,
         MontyObject::Tuple(items) => create_js_tuple(items, env)?,
+        // NamedTuple is converted to a tuple (loses named access in JS)
+        MontyObject::NamedTuple { values, .. } => create_js_tuple(values, env)?,
         MontyObject::Dict(pairs) => create_js_map(pairs, env)?,
         MontyObject::Set(items) | MontyObject::FrozenSet(items) => create_js_set(items, env)?,
         MontyObject::Exception { exc_type, arg } => create_js_exception(*exc_type, arg.as_deref(), env)?,
@@ -93,6 +95,7 @@ pub fn monty_to_js<'e>(obj: &MontyObject, env: &'e Env) -> Result<JsMontyObject<
             methods,
             frozen,
         } => create_js_dataclass(name, *type_id, field_names, attrs, methods, *frozen, env)?,
+        MontyObject::Path(p) => env.create_string(p)?.into_unknown(env)?,
         MontyObject::Repr(s) | MontyObject::Cycle(_, s) => env.create_string(s)?.into_unknown(env)?,
     };
     Ok(JsMontyObject(unknown))

crates/monty-js/src/monty_cls.rs

@@ -270,6 +270,11 @@ impl Monty {
                                 "Async futures are not supported in synchronous run(). Use start() for async execution.",
                             ));
                         }
+                        RunProgress::OsCall { function, .. } => {
+                            return Err(Error::from_reason(format!(
+                                "OS calls are not supported: {function:?}",
+                            )));
+                        }
                     }
                 }
             }};
@@ -720,6 +725,9 @@ where
         RunProgress::ResolveFutures(_) => {
             panic!("Async futures (ResolveFutures) are not yet supported in the JS bindings")
         }
+        RunProgress::OsCall { function, .. } => {
+            panic!("OS calls are not yet supported in the JS bindings: {function:?}")
+        }
     }
 }
 

crates/monty-python/python/pydantic_monty/__init__.py

@@ -18,8 +18,15 @@
     MontyTypingError,
     __version__,
 )
+from .os_access import AbstractFile, AbstractOS, CallbackFile, MemoryFile, OSAccess, OsFunction, StatResult
 
 __all__ = (
+    # this file
+    'run_monty_async',
+    'ExternalResult',
+    'ResourceLimits',
+    # _monty
+    '__version__',
     'Monty',
     'MontyComplete',
     'MontySnapshot',
@@ -29,10 +36,14 @@
     'MontyRuntimeError',
     'MontyTypingError',
     'Frame',
-    '__version__',
-    'run_monty_async',
-    'ResourceLimits',
-    'ExternalResult',
+    # os_access
+    'StatResult',
+    'OsFunction',
+    'AbstractOS',
+    'AbstractFile',
+    'MemoryFile',
+    'CallbackFile',
+    'OSAccess',
 )
 T = TypeVar('T')
 

crates/monty-python/python/pydantic_monty/_monty.pyi

@@ -4,8 +4,10 @@ from typing import Any, Callable, Literal, final, overload
 from typing_extensions import Self
 
 from . import ExternalResult, ResourceLimits
+from .os_access import OsFunction
 
 __all__ = [
+    '__version__',
     'Monty',
     'MontyComplete',
     'MontySnapshot',
@@ -15,7 +17,6 @@ __all__ = [
     'MontyRuntimeError',
     'MontyTypingError',
     'Frame',
-    '__version__',
 ]
 __version__: str
 
@@ -83,17 +84,22 @@ class Monty:
         limits: ResourceLimits | None = None,
         external_functions: dict[str, Callable[..., Any]] | None = None,
         print_callback: Callable[[Literal['stdout'], str], None] | None = None,
+        os: Callable[[OsFunction, tuple[Any, ...]], Any] | None = None,
     ) -> Any:
         """
         Execute the code and return the result.
 
-        The GIL is released allowing parallel execution if `print_callback` is `None`.
+        The GIL is released allowing parallel execution.
 
         Arguments:
             inputs: Dict of input variable values (must match names from __init__)
             limits: Optional resource limits configuration
             external_functions: Dict of external function callbacks (must match names from __init__)
             print_callback: Optional callback for print output
+            os: Optional callback for OS calls.
+                Called with (function_name, args) where function_name is like 'Path.exists'
+                and args is a tuple of arguments. Must return the appropriate value for the
+                OS function (e.g., bool for exists(), stat_result for stat()).
 
         Returns:
             The result of the last expression in the code
@@ -114,7 +120,7 @@ class Monty:
 
         This allows you to iteratively run code and parse/resume whenever an external function is called.
 
-        The GIL is released allowing parallel execution if `print_callback` is `None`.
+        The GIL is released allowing parallel execution.
 
         Arguments:
             inputs: Dict of input variable values (must match names from __init__)
@@ -196,8 +202,15 @@ class MontySnapshot:
         """The name of the script being executed."""
 
     @property
-    def function_name(self) -> str:
-        """The name of the external function being called."""
+    def is_os_function(self) -> bool:
+        """Whether this snapshot is for an OS function call (e.g., Path.stat)."""
+
+    @property
+    def function_name(self) -> str | OsFunction:
+        """The name of the function being called (external function or OS function like 'Path.stat').
+
+        Will be a `OsFunction` if `is_os_function` is `True`.
+        """
 
     @property
     def args(self) -> tuple[Any, ...]:
@@ -217,7 +230,7 @@ class MontySnapshot:
 
         `resume` may only be called once on each MontySnapshot instance.
 
-        The GIL is released allowing parallel execution if `print_callback` is `None`.
+        The GIL is released allowing parallel execution.
 
         Arguments:
             return_value: The value to return from the external function call.
@@ -325,7 +338,7 @@ class MontyFutureSnapshot:
 
         `resume` may only be called once on each MontyFutureSnapshot instance.
 
-        The GIL is released allowing parallel execution if `print_callback` is `None`.
+        The GIL is released allowing parallel execution.
 
         Arguments:
             results: Dict mapping call_id to result dict. Each result dict must have