vsh-python 0.3.1__cp313-cp313-win_amd64.whl

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,28 @@
+# Third-party notices
+
+VSH links and adapts the public typed execution/protocol seams of Monty 0.0.21,
+including the `monty`, `monty-types`, `monty-proto`, and `monty-alloc` crates.
+Monty is maintained by Pydantic and distributed under the MIT License:
+https://github.com/pydantic/monty/tree/v0.0.21
+
+The MIT License (MIT)
+
+Copyright (c) 2017 to present Pydantic Services Inc. and individual contributors.
+
+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.

vsh/__init__.py

@@ -0,0 +1,39 @@
+from __future__ import annotations as _annotations
+
+from ._native import (
+    ExecutionBudget,
+    Receipt,
+    ReceiptDetail,
+    RecoveryReport,
+    RunMode,
+    RunRequest,
+    Runtime,
+    VshExecutionError,
+    VshInternalError,
+    VshRecoveryError,
+    VshRuntimeError,
+    VshStaleError,
+    VshStateError,
+    engine_kind,
+    normalize_path,
+)
+from ._version import __version__
+
+__all__ = (
+    "__version__",
+    "engine_kind",
+    "ExecutionBudget",
+    "normalize_path",
+    "Receipt",
+    "ReceiptDetail",
+    "RecoveryReport",
+    "RunMode",
+    "RunRequest",
+    "Runtime",
+    "VshExecutionError",
+    "VshInternalError",
+    "VshRecoveryError",
+    "VshRuntimeError",
+    "VshStaleError",
+    "VshStateError",
+)

vsh/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations as _annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

vsh/_native.pyi

@@ -0,0 +1,204 @@
+"""Typed surface of the PyO3-backed VSH native module."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from os import PathLike
+from typing import overload
+
+__version__: str
+
+class VshRuntimeError(RuntimeError):
+    """Base exception for typed native VSH failures."""
+
+class VshExecutionError(VshRuntimeError):
+    """Monty compilation, execution, or hard-budget failure."""
+
+class VshStateError(VshRuntimeError):
+    """Transaction lifecycle, approval, reservation, or replay failure."""
+
+class VshStaleError(VshRuntimeError):
+    """Host dependencies changed after virtual execution."""
+
+class VshRecoveryError(VshRuntimeError):
+    """Durable recovery is required or could not prove ownership."""
+
+class VshInternalError(VshRuntimeError):
+    """A contained internal panic or invariant failure."""
+
+class RunMode(Enum):
+    PREVIEW: RunMode
+    AUTO: RunMode
+
+class ReceiptDetail(Enum):
+    COMPACT: ReceiptDetail
+    FULL: ReceiptDetail
+
+class ExecutionBudget:
+    def __init__(
+        self,
+        *,
+        max_program_bytes: int | None = ...,
+        max_duration_ms: int | None = ...,
+        max_recursion_depth: int | None = ...,
+        max_memory_bytes: int | None = ...,
+        max_os_calls: int | None = ...,
+        max_read_bytes: int | None = ...,
+        max_write_bytes: int | None = ...,
+        max_io_call_bytes: int | None = ...,
+        max_path_bytes: int | None = ...,
+        max_directory_entries: int | None = ...,
+        max_output_bytes: int | None = ...,
+        max_result_bytes: int | None = ...,
+        max_exception_bytes: int | None = ...,
+    ) -> None: ...
+    @property
+    def max_program_bytes(self) -> int: ...
+    @property
+    def max_duration_ms(self) -> int: ...
+    @property
+    def max_recursion_depth(self) -> int: ...
+    @property
+    def max_memory_bytes(self) -> int: ...
+    @property
+    def max_os_calls(self) -> int: ...
+    @property
+    def max_read_bytes(self) -> int: ...
+    @property
+    def max_write_bytes(self) -> int: ...
+    @property
+    def max_io_call_bytes(self) -> int: ...
+    @property
+    def max_path_bytes(self) -> int: ...
+    @property
+    def max_directory_entries(self) -> int: ...
+    @property
+    def max_output_bytes(self) -> int: ...
+    @property
+    def max_result_bytes(self) -> int: ...
+    @property
+    def max_exception_bytes(self) -> int: ...
+
+class RunRequest:
+    def __init__(
+        self,
+        code: str,
+        *,
+        intent: str | None = ...,
+        mode: RunMode | None = ...,
+        detail: ReceiptDetail | None = ...,
+        budget: ExecutionBudget | None = ...,
+    ) -> None: ...
+    @property
+    def code(self) -> str: ...
+    @property
+    def intent(self) -> str | None: ...
+    @property
+    def mode(self) -> RunMode: ...
+    @property
+    def detail(self) -> ReceiptDetail: ...
+    @property
+    def budget(self) -> ExecutionBudget: ...
+
+class Receipt:
+    @property
+    def transaction(self) -> str: ...
+    @property
+    def base_snapshot(self) -> str: ...
+    @property
+    def state(self) -> str: ...
+    @property
+    def decision(self) -> str: ...
+    @property
+    def diff(self) -> str: ...
+    @property
+    def changed_paths(self) -> int: ...
+    @property
+    def changes(self) -> list[tuple[str, str]]: ...
+    @property
+    def result(self) -> object: ...
+    @property
+    def result_repr(self) -> str: ...
+    @property
+    def stdout(self) -> str: ...
+    @property
+    def risk_flags(self) -> list[str]: ...
+    @property
+    def deny_reason(self) -> str | None: ...
+    @property
+    def os_calls(self) -> int: ...
+    @property
+    def read_bytes(self) -> int: ...
+    @property
+    def write_bytes(self) -> int: ...
+    @property
+    def directory_entries(self) -> int: ...
+    @property
+    def output_bytes(self) -> int: ...
+    @property
+    def denied_accesses(self) -> int: ...
+    @property
+    def result_bytes(self) -> int: ...
+    @property
+    def committed(self) -> bool: ...
+    @property
+    def commit_operations(self) -> int | None: ...
+    @property
+    def verified_paths(self) -> int | None: ...
+    @property
+    def cleanup_pending(self) -> bool: ...
+    def timings_ns(self) -> Mapping[str, int]: ...
+
+class RecoveryReport:
+    @property
+    def finalized_commits(self) -> int: ...
+    @property
+    def rolled_back(self) -> int: ...
+    @property
+    def cleaned(self) -> int: ...
+    @property
+    def orphaned(self) -> int: ...
+    @property
+    def conflicts(self) -> list[tuple[str, str | None, str]]: ...
+
+class Runtime:
+    @staticmethod
+    def open(
+        workspace: str | PathLike[str],
+        *,
+        data_directory: str | PathLike[str] | None = ...,
+        policy: str = ...,
+        worker_path: str | PathLike[str] | None = ...,
+    ) -> Runtime: ...
+    def run(self, request: RunRequest) -> Receipt: ...
+    @overload
+    def preview(self, request: RunRequest) -> Receipt: ...
+    @overload
+    def preview(
+        self,
+        request: str,
+        *,
+        intent: str | None = ...,
+        detail: ReceiptDetail | None = ...,
+        budget: ExecutionBudget | None = ...,
+    ) -> Receipt: ...
+    def discard_preview(self, transaction: str) -> bool: ...
+    def approve(
+        self,
+        transaction: str,
+        principal: str,
+        issued_at_unix_ms: int,
+        expires_at_unix_ms: int,
+    ) -> str: ...
+    def commit(self, transaction: str, now_unix_ms: int) -> Receipt: ...
+    def recover(self) -> RecoveryReport: ...
+
+def version() -> str:
+    """Return the native VSH semantic version."""
+
+def engine_kind() -> str:
+    """Return the native engine identity."""
+
+def normalize_path(path: str) -> str:
+    """Normalize a workspace-relative virtual path."""

vsh/_version.py

@@ -0,0 +1,5 @@
+from __future__ import annotations as _annotations
+
+from ._native import version as _native_version
+
+__version__ = _native_version()

vsh/cli.py

@@ -0,0 +1,56 @@
+"""Dependency-free CLI composition over the native PyO3 runtime."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="vsh", description="Run VSH's native Rust engine")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    run = commands.add_parser("run", help="run one Monty transaction")
+    source = run.add_mutually_exclusive_group(required=True)
+    source.add_argument("--code", help="Monty source text")
+    source.add_argument("--file", type=Path, help="read Monty source from a UTF-8 file")
+    source.add_argument("--transaction", help="promote an exact preview transaction")
+    run.add_argument("--workspace", type=Path, default=Path.cwd())
+    run.add_argument("--intent")
+    run.add_argument("--mode", choices=("preview", "auto"), default="preview")
+    run.add_argument("--policy", choices=("balanced", "strict", "paranoid"), default="balanced")
+    run.add_argument("--detail", choices=("compact", "full"), default="compact")
+
+    commands.add_parser("serve", help="serve the single-tool MCP surface over stdio")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the VSH CLI."""
+    arguments = _parser().parse_args(argv)
+    if arguments.command == "serve":
+        from .mcp.server import mcp
+
+        mcp.run()
+        return
+
+    from .mcp.native_tools import vsh_run
+
+    code = arguments.code
+    if arguments.file is not None:
+        code = arguments.file.read_text(encoding="utf-8")
+    payload = vsh_run(
+        code,
+        transaction=arguments.transaction,
+        workspace_root=str(arguments.workspace),
+        intent=arguments.intent,
+        mode=arguments.mode,
+        policy=arguments.policy,
+        detail=arguments.detail,
+    )
+    print(json.dumps(payload, ensure_ascii=False, separators=(",", ":")))

vsh/mcp/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations as _annotations
+
+from .native_tools import BudgetOverrides, vsh_run
+
+__all__ = ("BudgetOverrides", "vsh_run")

vsh/mcp/codemode_server.py

@@ -0,0 +1,125 @@
+from __future__ import annotations as _annotations
+
+import os
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from vsh import __version__
+
+from .prompts import register_codemode_prompts
+from .surface import register_vsh_agent_surface, register_vsh_surface
+
+CODEMODE_SERVER_NAME = "vsh-codemode"
+
+CODEMODE_INSTRUCTIONS = """\
+vsh CodeMode MCP server.
+
+The server exposes exactly one normal tool: `vsh_run`. Its `code` argument is one Monty
+Python program executed against an immutable workspace snapshot and copy-on-write Rust
+VirtualFs. Use pathlib-style filesystem operations under `/workspace`.
+
+`mode="preview"` guarantees no host mutation. `mode="auto"` asks the native policy to
+commit the exact canonical diff; denied and escalated transactions remain virtual. Put
+the complete multi-file operation in one program so it stays one transaction, one policy
+decision, and one Python-to-Rust boundary call. To promote an auto-approved preview, pass
+its returned `transaction` with no code and `mode="auto"`; VSH revalidates dependencies
+before commit. Never emulate a shell or use a second simulation path.
+"""
+
+_CUSTOM_SECTION_HEADER = "Project-specific instructions:"
+
+__all__ = (
+    "CODEMODE_INSTRUCTIONS",
+    "CODEMODE_SERVER_NAME",
+    "build_codemode_instructions",
+    "codemode_mcp",
+    "create_agent_codemode_server",
+    "create_codemode_server",
+    "load_custom_instructions",
+    "main",
+    "run_codemode_server",
+)
+
+
+def build_codemode_instructions(*, custom_instructions: str | None = None) -> str:
+    """Merge built-in CodeMode guidance with optional project-specific text."""
+    if custom_instructions is None:
+        return CODEMODE_INSTRUCTIONS
+
+    trimmed = custom_instructions.strip()
+    if not trimmed:
+        return CODEMODE_INSTRUCTIONS
+
+    return f"{CODEMODE_INSTRUCTIONS.rstrip()}\n\n---\n\n{_CUSTOM_SECTION_HEADER}\n{trimmed}\n"
+
+
+def load_custom_instructions(
+    *,
+    inline: str | None = None,
+    instructions_file: str | Path | None = None,
+) -> str | None:
+    """Resolve custom instructions from CLI args or environment variables."""
+    parts: list[str] = []
+
+    if instructions_file is not None:
+        parts.append(Path(instructions_file).read_text(encoding="utf-8").strip())
+    else:
+        env_file = os.environ.get("VSH_CODEMODE_INSTRUCTIONS_FILE")
+        if env_file:
+            parts.append(Path(env_file).read_text(encoding="utf-8").strip())
+
+    if inline is not None:
+        parts.append(inline.strip())
+    else:
+        env_inline = os.environ.get("VSH_CODEMODE_INSTRUCTIONS")
+        if env_inline:
+            parts.append(env_inline.strip())
+
+    merged = "\n\n".join(part for part in parts if part)
+    return merged or None
+
+
+def create_codemode_server(*, custom_instructions: str | None = None) -> FastMCP:
+    """Build the CodeMode-oriented FastMCP server."""
+    server = FastMCP(
+        CODEMODE_SERVER_NAME,
+        instructions=build_codemode_instructions(custom_instructions=custom_instructions),
+        version=__version__,
+    )
+    register_vsh_surface(server)
+    register_codemode_prompts(server)
+    return server
+
+
+def create_agent_codemode_server() -> FastMCP:
+    """Build a minimal CodeMode MCP server for pydantic-ai agent runs."""
+    server = FastMCP(
+        CODEMODE_SERVER_NAME,
+        instructions=None,
+        version=__version__,
+    )
+    register_vsh_agent_surface(server)
+    return server
+
+
+def run_codemode_server(
+    *,
+    inline: str | None = None,
+    instructions_file: str | Path | None = None,
+) -> None:
+    """Run the CodeMode MCP server, optionally with custom instructions."""
+    custom = load_custom_instructions(inline=inline, instructions_file=instructions_file)
+    if custom is None:
+        codemode_mcp.run()
+        return
+
+    create_codemode_server(custom_instructions=custom).run()
+
+
+codemode_mcp = create_codemode_server()
+
+
+def main() -> None:
+    """Run the vsh CodeMode MCP server over stdio."""
+    run_codemode_server()

vsh/mcp/native_tools.py

@@ -0,0 +1,157 @@
+"""One compact MCP tool over the PyO3-backed VSH runtime."""
+
+from __future__ import annotations
+
+import os
+import time
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal, TypedDict
+
+from vsh import ExecutionBudget, Receipt, ReceiptDetail, RunMode, RunRequest, Runtime
+
+RunModeName = Literal["preview", "auto"]
+PolicyName = Literal["balanced", "strict", "paranoid"]
+DetailName = Literal["compact", "full"]
+
+_MAX_INLINE_CHARS = 64 * 1024
+
+
+class BudgetOverrides(TypedDict, total=False):
+    """Optional native execution-budget overrides accepted by ``vsh_run``."""
+
+    max_program_bytes: int
+    max_duration_ms: int
+    max_recursion_depth: int
+    max_memory_bytes: int
+    max_os_calls: int
+    max_read_bytes: int
+    max_write_bytes: int
+    max_io_call_bytes: int
+    max_path_bytes: int
+    max_directory_entries: int
+    max_output_bytes: int
+    max_result_bytes: int
+    max_exception_bytes: int
+
+
+@lru_cache(maxsize=16)
+def _runtime_for(workspace: str, policy: PolicyName, worker_identity: str | None) -> Runtime:
+    # ``worker_identity`` intentionally participates in cache identity. Runtime.open resolves
+    # the trusted path itself, including wheel-local scripts, and the model cannot override it.
+    del worker_identity
+    return Runtime.open(workspace, policy=policy)
+
+
+def _bounded_text(value: str) -> tuple[str, bool]:
+    if len(value) <= _MAX_INLINE_CHARS:
+        return value, False
+    return f"{value[:_MAX_INLINE_CHARS]}…", True
+
+
+def _receipt_payload(receipt: Receipt) -> dict[str, object]:
+    result_repr, result_truncated = _bounded_text(receipt.result_repr)
+    stdout, stdout_truncated = _bounded_text(receipt.stdout)
+    return {
+        "transaction": receipt.transaction,
+        "base_snapshot": receipt.base_snapshot,
+        "state": receipt.state,
+        "decision": receipt.decision,
+        "diff": receipt.diff,
+        "changed_paths": receipt.changed_paths,
+        "changes": [{"path": path, "kind": kind} for path, kind in receipt.changes],
+        "result_repr": result_repr,
+        "result_truncated": result_truncated,
+        "stdout": stdout,
+        "stdout_truncated": stdout_truncated,
+        "risk_flags": list(receipt.risk_flags),
+        "deny_reason": receipt.deny_reason,
+        "execution": {
+            "os_calls": receipt.os_calls,
+            "read_bytes": receipt.read_bytes,
+            "write_bytes": receipt.write_bytes,
+            "directory_entries": receipt.directory_entries,
+            "output_bytes": receipt.output_bytes,
+            "denied_accesses": receipt.denied_accesses,
+            "result_bytes": receipt.result_bytes,
+        },
+        "commit": {
+            "committed": receipt.committed,
+            "operations": receipt.commit_operations,
+            "verified_paths": receipt.verified_paths,
+            "cleanup_pending": receipt.cleanup_pending,
+        },
+        "timings_ns": dict(receipt.timings_ns()),
+    }
+
+
+def vsh_run(
+    code: str | None = None,
+    *,
+    transaction: str | None = None,
+    workspace_root: str | None = None,
+    intent: str | None = None,
+    mode: RunModeName = "preview",
+    policy: PolicyName = "balanced",
+    detail: DetailName = "compact",
+    budget: BudgetOverrides | None = None,
+) -> dict[str, object]:
+    """Execute Monty code against one Rust VirtualFs transaction.
+
+    ``preview`` never changes host files. A later call may promote its exact artifact by passing
+    the returned ``transaction`` with ``mode="auto"`` and no code. Otherwise ``auto`` executes and
+    commits only a deterministic native auto-approval in one call. Denied or escalated
+    transactions remain non-mutating. The receipt is compact and JSON-safe, while all simulation,
+    policy, revalidation, and commit semantics stay inside the Rust core.
+    """
+    if mode not in {"preview", "auto"}:
+        raise ValueError(f"unknown run mode: {mode!r}")
+    if detail not in {"compact", "full"}:
+        raise ValueError(f"unknown receipt detail: {detail!r}")
+    if policy not in {"balanced", "strict", "paranoid"}:
+        raise ValueError(f"unknown policy profile: {policy!r}")
+
+    workspace = Path(workspace_root or os.getcwd()).resolve(strict=True)
+    if not workspace.is_dir():
+        raise NotADirectoryError(f"workspace root is not a directory: {workspace}")
+
+    runtime = _runtime_for(str(workspace), policy, os.environ.get("VSH_MONTY_WORKER"))
+    if transaction is not None:
+        if code is not None:
+            raise ValueError("pass either code or a preview transaction, not both")
+        if mode != "auto":
+            raise ValueError("a preview transaction can only be resumed with mode='auto'")
+        now_unix_ms = time.time_ns() // 1_000_000
+        return _receipt_payload(runtime.commit(transaction, now_unix_ms))
+    if code is None:
+        raise ValueError("code is required unless a preview transaction is supplied")
+
+    if budget is None:
+        native_budget = ExecutionBudget()
+    else:
+        native_budget = ExecutionBudget(
+            max_program_bytes=budget.get("max_program_bytes"),
+            max_duration_ms=budget.get("max_duration_ms"),
+            max_recursion_depth=budget.get("max_recursion_depth"),
+            max_memory_bytes=budget.get("max_memory_bytes"),
+            max_os_calls=budget.get("max_os_calls"),
+            max_read_bytes=budget.get("max_read_bytes"),
+            max_write_bytes=budget.get("max_write_bytes"),
+            max_io_call_bytes=budget.get("max_io_call_bytes"),
+            max_path_bytes=budget.get("max_path_bytes"),
+            max_directory_entries=budget.get("max_directory_entries"),
+            max_output_bytes=budget.get("max_output_bytes"),
+            max_result_bytes=budget.get("max_result_bytes"),
+            max_exception_bytes=budget.get("max_exception_bytes"),
+        )
+    request = RunRequest(
+        code,
+        intent=intent,
+        mode=RunMode.AUTO if mode == "auto" else RunMode.PREVIEW,
+        detail=ReceiptDetail.FULL if detail == "full" else ReceiptDetail.COMPACT,
+        budget=native_budget,
+    )
+    return _receipt_payload(runtime.run(request))
+
+
+__all__ = ("BudgetOverrides", "vsh_run")

vsh/mcp/prompts.py

@@ -0,0 +1,32 @@
+from __future__ import annotations as _annotations
+
+from fastmcp import FastMCP
+
+__all__ = ("register_codemode_prompts",)
+
+_RUN_PROMPT = """\
+Use the single `vsh_run` tool for workspace simulation and mutation.
+
+- Send one Monty Python program containing the complete filesystem transaction.
+- Use `mode="preview"` first when the user wants to inspect effects.
+- To apply an auto-approved preview, call `vsh_run` again with its `transaction`, no `code`, and
+  `mode="auto"`; dependency revalidation still occurs before mutation.
+- Otherwise use `mode="auto"` with code only when the user requested the change; Rust policy
+  still decides whether the exact virtual transaction may commit.
+- Read `state`, `decision`, `changes`, `result_repr`, and `stdout` from the receipt.
+- A `denied` or `pending_approval` receipt never means the host change was applied.
+- Do not emulate shell commands or call an alternate simulator.
+"""
+
+
+def register_codemode_prompts(mcp: FastMCP) -> None:
+    """Register guidance for the single native transaction tool."""
+
+    @mcp.prompt(
+        name="vsh_run_transaction",
+        title="Run one VSH transaction",
+        description="Compose one bounded Monty transaction over the native Rust engine.",
+        tags={"native", "transaction", "vsh"},
+    )
+    def run_transaction() -> str:
+        return _RUN_PROMPT

vsh/mcp/server.py

@@ -0,0 +1,8 @@
+from __future__ import annotations as _annotations
+
+from fastmcp import FastMCP
+
+from .surface import register_vsh_surface
+
+mcp = FastMCP("vsh")
+register_vsh_surface(mcp)