sandfs 0.1.0__tar.gz

sandfs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 George Lydakis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sandfs-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: sandfs
+Version: 0.1.0
+Summary: Composable virtual filesystem sandbox with a UNIX-like command surface for agents
+Project-URL: Homepage, https://example.com/sandfs
+Project-URL: Repository, https://example.com/sandfs.git
+Author: sandfs contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,in-memory,sandbox,virtual filesystem
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sandfs
+
+`sandfs` is an experimental Python package that implements an entirely virtual filesystem (VFS) that can be embedded inside AI agent tooling. Each sandbox keeps its own private directory tree, supports dynamic nodes that are hydrated on demand, and exposes a small UNIX-like command surface (`cd`, `ls`, `cat`, `grep`, `rg`, etc.) so agents can reuse familiar workflows.
+
+> **Status**: design prototype. APIs are subject to change.
+
+## Why?
+
+Agent builders frequently need a scratch filesystem for planning, iterating on generated code, and testing hypotheses. Shipping a simple `exec` tool that proxies every bash command to the host disk is unsafe. `sandfs` keeps those operations inside a controlled, in-memory sandbox while still feeling like a mini Linux environment.
+
+## Features
+
+- In-memory directories and files that never touch the host disk unless exported.
+- Dynamic nodes backed by callables (e.g., query a DB, fetch from an API, or generate text on the fly).
+- Pure-Python shell/executor that understands a handful of GNU-style commands and can be extended with your own.
+- Optional Python execution helper that evaluates snippets against the sandbox state only.
+- Bridge to real GNU utilities via `host -p <path> <command>` which materializes the subtree and runs the host binary against it.
+- Node policies (read-only, append-only, visibility labels) plus shell views so different agents see only the nodes they are allowed to.
+- Write hooks and optimistic versions so hosts can flush files to external stores with conflict detection.
+- Storage adapters and snapshots so you can mount external state and roll forward/back within a turn.
+- Serialization helpers to snapshot or hydrate sandboxes (planned).
+
+## Installation
+
+```bash
+pip install git+https://github.com/lydakis/sandfs.git
+# Once a PyPI release is available: pip install sandfs
+```
+
+## Quickstart
+
+```python
+from sandfs import VirtualFileSystem, SandboxShell
+
+vfs = VirtualFileSystem()
+vfs.write_file("/notes/todo.txt", "- build VFS\n- add rg support\n")
+
+shell = SandboxShell(vfs)
+print(shell.exec("ls /notes").stdout)
+print(shell.exec("rg 'VFS' /notes").stdout)
+```
+
+### Agent shell usage
+
+```python
+from sandfs import ProvidedNode, SandboxShell, VirtualFileSystem
+
+vfs = VirtualFileSystem()
+vfs.write_file("/workspace/app.py", "print('hello')\n")
+
+def logs_provider(ctx):
+    return {"latest.log": ProvidedNode.file(content="generated on demand")}
+
+vfs.mount_directory("/workspace/logs", logs_provider)
+
+shell = SandboxShell(vfs)
+shell.exec("cd /workspace")
+print(shell.exec("ls").stdout)
+print(shell.exec("tree").stdout)
+```
+
+### Running host GNU tools
+
+`SandboxShell` exposes `host` to materialize a subtree onto the host disk and invoke any installed command:
+
+```
+host -p /workspace grep -n TODO app.py
+```
+
+The example above exports `/workspace` into a temporary directory, runs the system `grep` inside it, then discards the files.
+
+### Policies & views
+
+```python
+vfs.set_policy(
+    "/blue/identity/persona.md",
+    NodePolicy(writable=False, classification="private", principals={"alice", "bob"}),
+)
+shell = SandboxShell(vfs, view=VisibilityView(classifications={"public"}, principals={"alice"}))
+```
+
+### Agent shell mode
+
+```python
+shell = SandboxShell(
+    vfs,
+    allowed_commands={"ls", "cat", "rg"},
+    max_output_bytes=8_192,
+)
+```
+
+Commands outside `allowed_commands` now return an error immediately, and outputs larger than `max_output_bytes` are rejected so partner-facing agents cannot dump oversized payloads.
+
+### Storage adapters
+
+```python
+from sandfs import MemoryStorageAdapter, VirtualFileSystem
+
+adapter = MemoryStorageAdapter(initial={"a.txt": "seed"})
+vfs = VirtualFileSystem()
+vfs.mount_storage("/data", adapter)
+
+print(vfs.read_file("/data/a.txt"))
+vfs.write_file("/data/a.txt", "update")
+vfs.sync_storage("/data")  # refresh from adapter if it changed externally
+```
+
+`mount_storage` keeps the virtual tree synchronized with the adapter, while `sync_storage` refreshes the VFS from the latest adapter contents.
+
+### Snapshots
+
+```python
+snap = vfs.snapshot()
+# run risky operations ...
+vfs.restore(snap)
+```
+
+Snapshots capture the entire tree (including storage-backed nodes) so you can checkpoint before an agent action and roll back on failure.
+
+## Repository layout
+
+```
+.
+├── docs/               # design/vision notes
+├── sandfs/             # library sources
+└── tests/              # runtime smoke tests
+```
+
+## Local development
+
+```
+python -m venv .venv
+source .venv/bin/activate
+uv pip install -e .[dev]
+uv run pytest
+```
+
+### Persistence hooks
+
+Register a write hook to flush files into your own store and use optimistic versions to avoid clobbering concurrent updates:
+
+```python
+from sandfs import VirtualFileSystem
+from sandfs.hooks import WriteEvent
+
+vfs = VirtualFileSystem()
+
+def flush(event: WriteEvent) -> None:
+    save_to_db(event.path, event.content, event.version)
+
+vfs.register_write_hook("/blue/work", flush)
+vfs.write_file("/blue/work/note.md", "draft")
+vfs.write_file("/blue/work/note.md", "final", expected_version=1)
+```
+
+### Integration hooks
+
+```python
+from sandfs.integrations import InboxRecorder
+
+recorder = InboxRecorder()
+recorder.attach(vfs, "/blue/inbox")
+```
+
+`PathEvent` (used under the hood) carries the path, event type (`create`, `update`, `delete`), and latest content so you can fan writes into staging queues or audit logs.
+
+## License
+
+MIT
+
+## Further reading
+
+- [Using sandfs with Blue](docs/blue.md)
+- [Publishing sandfs](docs/publishing.md)

sandfs-0.1.0/README.md

@@ -0,0 +1,174 @@
+# sandfs
+
+`sandfs` is an experimental Python package that implements an entirely virtual filesystem (VFS) that can be embedded inside AI agent tooling. Each sandbox keeps its own private directory tree, supports dynamic nodes that are hydrated on demand, and exposes a small UNIX-like command surface (`cd`, `ls`, `cat`, `grep`, `rg`, etc.) so agents can reuse familiar workflows.
+
+> **Status**: design prototype. APIs are subject to change.
+
+## Why?
+
+Agent builders frequently need a scratch filesystem for planning, iterating on generated code, and testing hypotheses. Shipping a simple `exec` tool that proxies every bash command to the host disk is unsafe. `sandfs` keeps those operations inside a controlled, in-memory sandbox while still feeling like a mini Linux environment.
+
+## Features
+
+- In-memory directories and files that never touch the host disk unless exported.
+- Dynamic nodes backed by callables (e.g., query a DB, fetch from an API, or generate text on the fly).
+- Pure-Python shell/executor that understands a handful of GNU-style commands and can be extended with your own.
+- Optional Python execution helper that evaluates snippets against the sandbox state only.
+- Bridge to real GNU utilities via `host -p <path> <command>` which materializes the subtree and runs the host binary against it.
+- Node policies (read-only, append-only, visibility labels) plus shell views so different agents see only the nodes they are allowed to.
+- Write hooks and optimistic versions so hosts can flush files to external stores with conflict detection.
+- Storage adapters and snapshots so you can mount external state and roll forward/back within a turn.
+- Serialization helpers to snapshot or hydrate sandboxes (planned).
+
+## Installation
+
+```bash
+pip install git+https://github.com/lydakis/sandfs.git
+# Once a PyPI release is available: pip install sandfs
+```
+
+## Quickstart
+
+```python
+from sandfs import VirtualFileSystem, SandboxShell
+
+vfs = VirtualFileSystem()
+vfs.write_file("/notes/todo.txt", "- build VFS\n- add rg support\n")
+
+shell = SandboxShell(vfs)
+print(shell.exec("ls /notes").stdout)
+print(shell.exec("rg 'VFS' /notes").stdout)
+```
+
+### Agent shell usage
+
+```python
+from sandfs import ProvidedNode, SandboxShell, VirtualFileSystem
+
+vfs = VirtualFileSystem()
+vfs.write_file("/workspace/app.py", "print('hello')\n")
+
+def logs_provider(ctx):
+    return {"latest.log": ProvidedNode.file(content="generated on demand")}
+
+vfs.mount_directory("/workspace/logs", logs_provider)
+
+shell = SandboxShell(vfs)
+shell.exec("cd /workspace")
+print(shell.exec("ls").stdout)
+print(shell.exec("tree").stdout)
+```
+
+### Running host GNU tools
+
+`SandboxShell` exposes `host` to materialize a subtree onto the host disk and invoke any installed command:
+
+```
+host -p /workspace grep -n TODO app.py
+```
+
+The example above exports `/workspace` into a temporary directory, runs the system `grep` inside it, then discards the files.
+
+### Policies & views
+
+```python
+vfs.set_policy(
+    "/blue/identity/persona.md",
+    NodePolicy(writable=False, classification="private", principals={"alice", "bob"}),
+)
+shell = SandboxShell(vfs, view=VisibilityView(classifications={"public"}, principals={"alice"}))
+```
+
+### Agent shell mode
+
+```python
+shell = SandboxShell(
+    vfs,
+    allowed_commands={"ls", "cat", "rg"},
+    max_output_bytes=8_192,
+)
+```
+
+Commands outside `allowed_commands` now return an error immediately, and outputs larger than `max_output_bytes` are rejected so partner-facing agents cannot dump oversized payloads.
+
+### Storage adapters
+
+```python
+from sandfs import MemoryStorageAdapter, VirtualFileSystem
+
+adapter = MemoryStorageAdapter(initial={"a.txt": "seed"})
+vfs = VirtualFileSystem()
+vfs.mount_storage("/data", adapter)
+
+print(vfs.read_file("/data/a.txt"))
+vfs.write_file("/data/a.txt", "update")
+vfs.sync_storage("/data")  # refresh from adapter if it changed externally
+```
+
+`mount_storage` keeps the virtual tree synchronized with the adapter, while `sync_storage` refreshes the VFS from the latest adapter contents.
+
+### Snapshots
+
+```python
+snap = vfs.snapshot()
+# run risky operations ...
+vfs.restore(snap)
+```
+
+Snapshots capture the entire tree (including storage-backed nodes) so you can checkpoint before an agent action and roll back on failure.
+
+## Repository layout
+
+```
+.
+├── docs/               # design/vision notes
+├── sandfs/             # library sources
+└── tests/              # runtime smoke tests
+```
+
+## Local development
+
+```
+python -m venv .venv
+source .venv/bin/activate
+uv pip install -e .[dev]
+uv run pytest
+```
+
+### Persistence hooks
+
+Register a write hook to flush files into your own store and use optimistic versions to avoid clobbering concurrent updates:
+
+```python
+from sandfs import VirtualFileSystem
+from sandfs.hooks import WriteEvent
+
+vfs = VirtualFileSystem()
+
+def flush(event: WriteEvent) -> None:
+    save_to_db(event.path, event.content, event.version)
+
+vfs.register_write_hook("/blue/work", flush)
+vfs.write_file("/blue/work/note.md", "draft")
+vfs.write_file("/blue/work/note.md", "final", expected_version=1)
+```
+
+### Integration hooks
+
+```python
+from sandfs.integrations import InboxRecorder
+
+recorder = InboxRecorder()
+recorder.attach(vfs, "/blue/inbox")
+```
+
+`PathEvent` (used under the hood) carries the path, event type (`create`, `update`, `delete`), and latest content so you can fan writes into staging queues or audit logs.
+
+## License
+
+MIT
+
+## Further reading
+
+- [Using sandfs with Blue](docs/blue.md)
+- [Publishing sandfs](docs/publishing.md)

sandfs-0.1.0/docs/blue.md

@@ -0,0 +1,57 @@
+# Using sandfs with Blue
+
+This document shows how a Blue runtime can mount `/blue`, enforce view-specific policies, attach inbox/log recorders, and wrap each turn in snapshots.
+
+## Installation
+
+```bash
+pip install git+https://github.com/lydakis/sandfs.git
+# once published: pip install sandfs
+```
+
+## Bootstrap a sandbox per chat
+
+```python
+from sandfs import MemoryStorageAdapter, NodePolicy, SandboxShell, VirtualFileSystem, VisibilityView
+from sandfs.integrations import InboxRecorder
+
+# 1. create the sandbox
+vfs = VirtualFileSystem()
+
+# 2. mount identity + workspaces with policies
+vfs.mount_storage("/blue/identity", MemoryStorageAdapter(initial=identity_blob))
+vfs.set_policy(
+    "/blue/identity/persona.md",
+    NodePolicy(writable=False, classification="private", principals={chat.owner_id}),
+)
+
+# 3. attach inbox/log recorders
+inbox = InboxRecorder()
+inbox.attach(vfs, "/blue/inbox")
+
+# 4. configure the shell for the chat participants
+view = VisibilityView(
+    classifications={"public", "partner"},
+    principals=set(chat.participant_ids),
+)
+shell = SandboxShell(
+    vfs,
+    view=view,
+    allowed_commands={"ls", "cat", "rg", "python"},
+    max_output_bytes=8_000,
+)
+```
+
+## Per-turn workflow
+
+```python
+snapshot = vfs.snapshot()
+try:
+    result = shell.exec(agent_command)
+    process_inbox(inbox.events)  # fan into Blue staging queues
+finally:
+    vfs.restore(snapshot)
+    inbox.events.clear()
+```
+
+This keeps `/blue` isolated per turn while still letting the runtime flush writes into its storage layer.

sandfs-0.1.0/docs/publishing.md

@@ -0,0 +1,32 @@
+# Publishing sandfs
+
+1. Ensure `pyproject.toml` has the correct `version` and changelog/README are up to date.
+2. Build the package:
+
+```bash
+uv build
+```
+
+This produces distributions under `dist/`.
+
+3. Publish to PyPI:
+
+```bash
+uv publish --username <pypi-user>
+```
+
+`uv publish` will prompt for credentials or can read `PYPI_TOKEN`. Remove `--dry-run`; uv currently publishes directly.
+
+If you prefer Twine:
+
+```bash
+python -m build
+python -m twine upload dist/*
+```
+
+4. Tag the release:
+
+```bash
+git tag -a v0.1.0 -m "sandfs v0.1.0"
+git push origin v0.1.0
+```

sandfs-0.1.0/docs/vision.md

@@ -0,0 +1,29 @@
+# sandfs Vision
+
+`sandfs` aims to provide an extensible, self-contained virtual filesystem (VFS) that can be embedded in agentic workflows. The VFS is designed to be backed by in-memory state, dynamically generated nodes, or live data sources that are exposed via provider callables. Agent developers can expose a single `exec` tool that proxies commands into the sandbox, enabling AIs to manipulate a private filesystem with familiar UNIX idioms.
+
+## Core Principles
+
+1. **Virtual-first** – The filesystem lives in memory and never touches the host disk unless explicitly exported.
+2. **Dynamic data** – Nodes can be backed by callables (or adapters around DB queries, APIs, etc.) that materialize file contents or directory listings on demand.
+3. **Command friendly** – The sandbox ships with a tiny command runner that understands a subset of GNU-style commands (`cd`, `ls`, `cat`, `grep`, `rg`, `tree`, etc.). New commands can be registered.
+4. **Execution context isolation** – Python or shell snippets can be executed against the VFS without escaping it. All side-effects remain local to the sandbox state object.
+5. **Composable layers** – Multiple providers can be mounted at different paths, enabling hybrid topologies (e.g., static project template + live DB dumps + scratch space).
+
+## Proposed Architecture
+
+- `sandfs.nodes` keeps lightweight dataclasses for directories, files, and symbolic links. Nodes expose a uniform `read()` / `write()` / `iterdir()` API and support lazy population.
+- `sandfs.providers` defines the provider protocol (callables receiving a `NodeContext` and returning bytes/str) plus adapters for common scenarios (e.g., `StaticText`, `CallableProvider`).
+- `sandfs.vfs.VirtualFileSystem` manages the tree, the current working directory, path resolution, mounting/unmounting providers, and basic file operations.
+- `sandfs.shell.SandboxShell` hosts a registry of command handlers, parses user commands via `shlex`, and executes them against the VFS, returning a `CommandResult` object.
+- `sandfs.pyexec.PythonExecutor` offers a helper to run Python code with a curated globals dict that includes the VFS helpers but forbids direct disk I/O by default.
+
+## Roadmap Snapshot
+
+1. Build the foundational VFS and directory/file nodes with provider support.
+2. Layer on top a shell/executor that mimics common filesystem commands.
+3. Add serialization/import/export helpers so sandboxes can be persisted or hydrated from templates.
+4. Expand command coverage (pipelines, redirection, e.g., `head`, `tail`, `sed`) and integrate with long-lived agent sessions.
+5. Offer host integration points, such as bridging selected directories to the real FS through adapters guarded by policies.
+
+This document captures the initial architectural intent and can be revised as the package evolves.

sandfs-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.20"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sandfs"
+version = "0.1.0"
+description = "Composable virtual filesystem sandbox with a UNIX-like command surface for agents"
+requires-python = ">=3.10"
+authors = [
+  { name = "sandfs contributors" }
+]
+readme = "README.md"
+license = { text = "MIT" }
+keywords = ["virtual filesystem", "agents", "sandbox", "in-memory"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: System :: Filesystems",
+  "Topic :: Software Development :: Libraries"
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+]
+
+[project.urls]
+Homepage = "https://example.com/sandfs"
+Repository = "https://example.com/sandfs.git"
+
+[tool.hatch.metadata]
+allow-direct-references = true

sandfs-0.1.0/sandfs/__init__.py

@@ -0,0 +1,30 @@
+"""sandfs package: virtual filesystem sandbox with a mini shell."""
+
+from .vfs import VirtualFileSystem
+from .shell import SandboxShell, CommandResult
+from .pyexec import PythonExecutor, PythonExecutionResult
+from .providers import ContentProvider, DirectoryProvider, NodeContext, ProvidedNode
+from .policies import NodePolicy, VisibilityView
+from .hooks import WriteEvent, WriteHook
+from .integrations import PathEvent, PathHook
+from .adapters import MemoryStorageAdapter, StorageAdapter
+
+__all__ = [
+    "VirtualFileSystem",
+    "SandboxShell",
+    "CommandResult",
+    "PythonExecutor",
+    "PythonExecutionResult",
+    "ContentProvider",
+    "DirectoryProvider",
+    "NodeContext",
+    "ProvidedNode",
+    "NodePolicy",
+    "VisibilityView",
+    "WriteEvent",
+    "WriteHook",
+    "PathEvent",
+    "PathHook",
+    "StorageAdapter",
+    "MemoryStorageAdapter",
+]

sandfs-0.1.0/sandfs/adapters.py

@@ -0,0 +1,58 @@
+"""Storage adapter interfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Mapping, Optional
+
+
+@dataclass
+class StorageEntry:
+    content: str
+    version: int = 0
+
+
+class StorageAdapter:
+    def read(self, path: str) -> StorageEntry:
+        raise NotImplementedError
+
+    def write(self, path: str, content: str, *, version: int) -> StorageEntry:
+        raise NotImplementedError
+
+    def list(self) -> Dict[str, StorageEntry]:
+        raise NotImplementedError
+
+    def delete(self, path: str) -> None:
+        raise NotImplementedError
+
+
+@dataclass
+class MemoryStorageAdapter(StorageAdapter):
+    initial: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self._entries: Dict[str, StorageEntry] = {
+            path: StorageEntry(content=text, version=0)
+            for path, text in self.initial.items()
+        }
+
+    def read(self, path: str) -> StorageEntry:
+        entry = self._entries.get(path)
+        if entry is None:
+            raise FileNotFoundError(path)
+        return StorageEntry(content=entry.content, version=entry.version)
+
+    def write(self, path: str, content: str, *, version: int) -> StorageEntry:
+        entry = self._entries.get(path)
+        if entry and entry.version != version:
+            raise ValueError("version mismatch")
+        next_version = version + 1
+        entry = StorageEntry(content=content, version=next_version)
+        self._entries[path] = entry
+        return StorageEntry(content=entry.content, version=entry.version)
+
+    def list(self) -> Dict[str, StorageEntry]:
+        return {path: StorageEntry(content=entry.content, version=entry.version) for path, entry in self._entries.items()}
+
+    def delete(self, path: str) -> None:
+        self._entries.pop(path, None)

sandfs-0.1.0/sandfs/exceptions.py

@@ -0,0 +1,32 @@
+"""Custom exceptions for sandfs."""
+
+from __future__ import annotations
+
+
+class SandboxError(RuntimeError):
+    """Base error for the sandbox."""
+
+
+class NodeNotFound(SandboxError):
+    """Raised when a node cannot be resolved."""
+
+
+class NodeExists(SandboxError):
+    """Raised when attempting to create a node that already exists."""
+
+
+class InvalidOperation(SandboxError):
+    """Raised when an operation cannot be completed."""
+
+
+class ProviderError(SandboxError):
+    """Raised when a provider callable fails."""
+
+
+__all__ = [
+    "SandboxError",
+    "NodeNotFound",
+    "NodeExists",
+    "InvalidOperation",
+    "ProviderError",
+]

sandfs-0.1.0/sandfs/hooks.py

@@ -0,0 +1,20 @@
+"""Hook dataclasses and type hints for persistence adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class WriteEvent:
+    path: str
+    content: str
+    version: int
+    append: bool
+
+
+WriteHook = Callable[[WriteEvent], None]
+
+
+__all__ = ["WriteEvent", "WriteHook"]