Add DheeFS virtual context shell

Author: Ashish-dwi99

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4
@@ -21,8 +21,13 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
       - name: Install dependencies
-        run: pip install -e ".[dev]"
+        run: |
+          pip install -e ./dhee-accel
+          pip install -e ".[dev]"
 
       - name: Run tests
         run: pytest tests/ -v

.gitignore

@@ -164,7 +164,8 @@ runs/
 data/
 
 # Internal scripts & docs
-scripts/
+scripts/*
+!scripts/verify_full_suite.sh
 deep-research-report.md
 launch-article.md
 pitch-deck.md

README.md

@@ -28,6 +28,7 @@
 <p align="center">
   <a href="#what-is-dhee">What is Dhee</a> ·
   <a href="#shared-agent-learning">Shared Agent Learning</a> ·
+  <a href="#dheefs">DheeFS</a> ·
   <a href="#quick-start">Quick Start</a> ·
   <a href="#repo-shared-context">Repo-Shared Context</a> ·
   <a href="#benchmarks">Benchmarks</a> ·
@@ -99,6 +100,41 @@ This is the product contract: **with Dhee, a learning proven in one agent can be
 
 ---
 
+## <span id="dheefs">DheeFS — one local learning space every agent already understands</span>
+
+Agents already understand files and shell verbs. DheeFS exposes Dhee's memory, router, handoff, artifacts, shared tasks, and learning exchange as one virtual context space:
+
+```bash
+dhee shell "ls /learnings"
+dhee shell "cat /handoff/latest.md"
+dhee shell "grep parser /learnings/promoted"
+dhee shell "cat /router/ptr/R-abc123"
+```
+
+The first version is a virtual shell, not FUSE. It intentionally supports a small approved command set: `ls`, `cat`, `grep`, `why`, `promote`, `reject`, `broadcast`, `provision`, and `snapshot`. The same surface is available through MCP as `dhee_shell(command)` and through Python:
+
+```python
+from dhee import ContextWorkspace
+
+result = ContextWorkspace(repo=".").execute("provision 'fix parser bug'")
+print(result.stdout)
+```
+
+External systems such as Slack, Gmail, and Notion are future **context sources** under `/sources`, not generic remote action backends. They can sync and search evidence into Dhee artifacts, learnings, and handoffs without making the core install depend on SaaS SDKs.
+
+```text
+/learnings   candidates, promoted, rejected, archived
+/handoff     latest repo/session continuity
+/router/ptr  raw pointer lookup when explicitly requested
+/artifacts   host-parsed files and chunks
+/repo        .dhee/context decisions and conventions
+/agents      Hermes, Claude Code, Codex views
+/shared      inbox, broadcasts, shared task results
+/sources     optional future Slack/Gmail/Notion context mounts
+```
+
+---
+
 ## Quick Start
 
 **One command. No venv. No config. No pasting into `settings.json`.**
@@ -404,6 +440,13 @@ source .venv-dhee/bin/activate
 pytest
 ```
 
+For the same full-suite path CI expects, including the local Rust acceleration
+extension and async test plugin:
+
+```bash
+./scripts/verify_full_suite.sh
+```
+
 ---
 
 <p align="center">

dhee-accel/Cargo.lock

@@ -10,5 +10,5 @@ name = "dhee_accel"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { version = "0.22", features = ["extension-module"] }
+pyo3 = { version = "0.28.3", features = ["extension-module"] }
 rayon = "1.10"

dhee-accel/Cargo.toml

@@ -25,6 +25,7 @@
 from dhee.memory.main import FullMemory
 from dhee.simple import Dhee, Engram
 from dhee.plugin import DheePlugin
+from dhee.fs import ContextWorkspace
 from dhee.core.category import CategoryProcessor, Category, CategoryType, CategoryMatch
 from dhee.core.echo import EchoProcessor, EchoDepth, EchoResult
 from dhee.configs.base import MemoryConfig, FadeMemConfig, EchoMemConfig, CategoryMemConfig, ScopeConfig
@@ -44,6 +45,8 @@
     "Dhee",
     # Universal plugin
     "DheePlugin",
+    # DheeFS
+    "ContextWorkspace",
     # CategoryMem
     "CategoryProcessor",
     "Category",

dhee/__init__.py

@@ -84,6 +84,38 @@ def cmd_setup(args: argparse.Namespace) -> None:
     run_setup()
 
 
+def cmd_shell(args: argparse.Namespace) -> None:
+    """Run a DheeFS virtual shell command."""
+    from dhee.fs import ContextWorkspace
+
+    command = " ".join(getattr(args, "shell_command", []) or []).strip()
+    if not command:
+        print("Error: shell command is required", file=sys.stderr)
+        sys.exit(2)
+
+    repo = getattr(args, "repo", None)
+    if repo is None:
+        repo = os.getcwd()
+    workspace = ContextWorkspace(
+        repo=repo,
+        user_id=getattr(args, "user_id", "default"),
+        agent_id=getattr(args, "agent_id", None) or "cli",
+        db=_get_db(),
+        workspace_id=getattr(args, "workspace_id", None) or os.path.abspath(os.path.expanduser(repo)),
+    )
+    result = workspace.execute(command)
+    if getattr(args, "json", False):
+        _json_out(result.to_dict())
+    else:
+        stream = sys.stderr if result.exit_code else sys.stdout
+        if result.stdout:
+            print(result.stdout, file=stream)
+        elif result.stderr:
+            print(result.stderr, file=sys.stderr)
+    if result.exit_code:
+        sys.exit(result.exit_code)
+
+
 # ---------------------------------------------------------------------------
 # repo-link commands — personal vs repo context
 # ---------------------------------------------------------------------------
@@ -2073,6 +2105,18 @@ def build_parser() -> argparse.ArgumentParser:
     # setup
     sub.add_parser("setup", help="Interactive setup wizard")
 
+    # shell — DheeFS virtual learning/context space
+    p_shell = sub.add_parser(
+        "shell",
+        help="Run a DheeFS virtual shell command, e.g. `dhee shell \"ls /learnings\"`",
+    )
+    p_shell.add_argument("shell_command", nargs=argparse.REMAINDER, help="Command to run in DheeFS")
+    p_shell.add_argument("--repo", help="Repository/workspace root (default: cwd)")
+    p_shell.add_argument("--workspace-id", help="Explicit workspace id override")
+    p_shell.add_argument("--user-id", default="default", help="User ID")
+    p_shell.add_argument("--agent-id", default="cli", help="Agent ID for mutating commands")
+    p_shell.add_argument("--json", action="store_true", help="JSON output")
+
     # remember / add (aliases)
     p_remember = sub.add_parser("remember", help="Store a fact or preference")
     p_remember.add_argument("text", help="Memory content")
@@ -2625,6 +2669,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 COMMAND_MAP = {
     "setup": cmd_setup,
+    "shell": cmd_shell,
     "remember": cmd_add,   # alias
     "add": cmd_add,
     "recall": cmd_search,  # alias

dhee/cli.py

@@ -0,0 +1,13 @@
+"""DheeFS virtual learning/context shell."""
+
+from dhee.fs.types import DheeFSEntry, DheeFSError, DheeFSResult, DheeMount
+from dhee.fs.workspace import CommandRegistry, ContextWorkspace
+
+__all__ = [
+    "CommandRegistry",
+    "ContextWorkspace",
+    "DheeFSEntry",
+    "DheeFSError",
+    "DheeFSResult",
+    "DheeMount",
+]