agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/audit/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""Audit subpackage — delta engine, commitment, and GC."""

hypervisor/audit/commitment.py

@@ -0,0 +1,76 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Hash Commitment — stub implementation.
+
+Public Preview: stores commitments in-memory only.
+No blockchain anchoring.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+
+@dataclass
+class CommitmentRecord:
+    """Record of a Summary Hash commitment."""
+
+    session_id: str
+    hash_chain_root: str
+    participant_dids: list[str]
+    delta_count: int
+    committed_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    blockchain_tx_id: str | None = None
+    committed_to: str = "local"
+
+
+class CommitmentEngine:
+    """
+    Simple in-memory commitment store.
+
+    Public Preview: stores commitments locally, no external anchoring.
+    """
+
+    def __init__(self) -> None:
+        self._commitments: dict[str, CommitmentRecord] = {}
+        self._batch_queue: list[CommitmentRecord] = []
+
+    def commit(
+        self,
+        session_id: str,
+        hash_chain_root: str,
+        participant_dids: list[str],
+        delta_count: int,
+    ) -> CommitmentRecord:
+        """Commit a session's Summary Hash."""
+        record = CommitmentRecord(
+            session_id=session_id,
+            hash_chain_root=hash_chain_root,
+            participant_dids=participant_dids,
+            delta_count=delta_count,
+        )
+        self._commitments[session_id] = record
+        return record
+
+    def verify(self, session_id: str, expected_root: str) -> bool:
+        """Verify a session's audit log root."""
+        record = self._commitments.get(session_id)
+        if not record:
+            return False
+        return record.hash_chain_root == expected_root
+
+    def queue_for_batch(self, record: CommitmentRecord) -> None:
+        """Queue a commitment (Public Preview: no-op)."""
+        self._batch_queue.append(record)
+
+    def flush_batch(self) -> list[CommitmentRecord]:
+        """Flush the batch queue."""
+        batch = list(self._batch_queue)
+        self._batch_queue.clear()
+        return batch
+
+    def get_commitment(self, session_id: str) -> CommitmentRecord | None:
+        return self._commitments.get(session_id)

hypervisor/audit/delta.py

@@ -0,0 +1,135 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Delta Audit Engine — tamper-evident append-only audit log.
+
+Records VFS state changes as a SHA-256 hash chain where each entry
+links to its predecessor, providing cryptographic tamper evidence.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Optional
+
+
+@dataclass
+class VFSChange:
+    """A single change within a delta."""
+
+    path: str
+    operation: str
+    content_hash: str | None = None
+    previous_hash: str | None = None
+    agent_did: str | None = None
+
+
+@dataclass
+class SemanticDelta:
+    """A delta capturing VFS state changes at a single turn."""
+
+    delta_id: str
+    turn_id: int
+    session_id: str
+    agent_did: str
+    timestamp: datetime
+    changes: list[VFSChange]
+    parent_hash: str | None
+    delta_hash: str = ""
+
+    def _build_hash_input(self) -> str:
+        changes_data = [
+            {
+                "path": c.path,
+                "operation": c.operation,
+                "content_hash": c.content_hash,
+                "previous_hash": c.previous_hash,
+                "agent_did": c.agent_did,
+            }
+            for c in self.changes
+        ]
+        return json.dumps(
+            {
+                "delta_id": self.delta_id,
+                "turn_id": self.turn_id,
+                "session_id": self.session_id,
+                "agent_did": self.agent_did,
+                "timestamp": self.timestamp.isoformat(),
+                "parent_hash": self.parent_hash or "",
+                "changes": changes_data,
+            },
+            sort_keys=True,
+        )
+
+    def compute_hash(self) -> str:
+        """Compute SHA-256 hash covering all fields including changes and parent linkage."""
+        self.delta_hash = hashlib.sha256(self._build_hash_input().encode()).hexdigest()
+        return self.delta_hash
+
+    def verify_hash(self) -> bool:
+        """Recompute hash and compare to stored value without mutation."""
+        expected = hashlib.sha256(self._build_hash_input().encode()).hexdigest()
+        return expected == self.delta_hash
+
+
+class DeltaEngine:
+    """Tamper-evident append-only audit log with SHA-256 hash chain verification."""
+
+    def __init__(self, session_id: str) -> None:
+        self.session_id = session_id
+        self._deltas: list[SemanticDelta] = []
+        self._turn_counter = 0
+
+    def capture(
+        self,
+        agent_did: str,
+        changes: list[VFSChange],
+        delta_id: str | None = None,
+    ) -> SemanticDelta:
+        """Capture a delta for a turn, chaining to previous entry."""
+        self._turn_counter += 1
+        parent_hash = self._deltas[-1].delta_hash if self._deltas else None
+        delta = SemanticDelta(
+            delta_id=delta_id or f"delta:{self._turn_counter}",
+            turn_id=self._turn_counter,
+            session_id=self.session_id,
+            agent_did=agent_did,
+            timestamp=datetime.now(UTC),
+            changes=changes,
+            parent_hash=parent_hash,
+        )
+        delta.compute_hash()
+        self._deltas.append(delta)
+        return delta
+
+    def compute_hash_chain_root(self) -> str | None:
+        """Return hash of last delta in the chain."""
+        if not self._deltas:
+            return None
+        return self._deltas[-1].delta_hash
+
+    def verify_chain(self) -> tuple[bool, Optional[str]]:
+        """Verify full chain integrity: hash correctness and parent linkage."""
+        if not self._deltas:
+            return True, None
+
+        previous_hash = None
+        for i, delta in enumerate(self._deltas):
+            if not delta.verify_hash():
+                return False, f"Entry {i} hash mismatch"
+            if delta.parent_hash != previous_hash:
+                return False, f"Entry {i} chain broken"
+            previous_hash = delta.delta_hash
+
+        return True, None
+
+    @property
+    def deltas(self) -> list[SemanticDelta]:
+        return list(self._deltas)
+
+    @property
+    def turn_count(self) -> int:
+        return self._turn_counter

hypervisor/audit/gc.py

@@ -0,0 +1,99 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Ephemeral Session Data Garbage Collection — stub implementation.
+
+Public Preview: GC is a no-op. Data is retained in-memory for
+session lifetime only.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass
+class GCResult:
+    """Result of a garbage collection run."""
+
+    session_id: str
+    retained_deltas: int
+    retained_hash: bool
+    purged_vfs_files: int
+    purged_caches: int
+    storage_before_bytes: int
+    storage_after_bytes: int
+    gc_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    @property
+    def storage_saved_bytes(self) -> int:
+        return self.storage_before_bytes - self.storage_after_bytes
+
+    @property
+    def savings_pct(self) -> float:
+        if self.storage_before_bytes == 0:
+            return 0.0
+        return (self.storage_saved_bytes / self.storage_before_bytes) * 100
+
+
+@dataclass
+class RetentionPolicy:
+    """Configuration for what to retain after GC."""
+
+    delta_retention_days: int = 180
+    hash_retention: str = "permanent"
+    liability_snapshot: bool = True
+
+
+class EphemeralGC:
+    """
+    GC stub (Public Preview: logs collection requests, no actual purge).
+    """
+
+    def __init__(self, policy: RetentionPolicy | None = None) -> None:
+        self.policy = policy or RetentionPolicy()
+        self._gc_history: list[GCResult] = []
+        self._purged_sessions: set[str] = set()
+
+    def collect(
+        self,
+        session_id: str,
+        vfs: Any = None,
+        delta_engine: Any = None,
+        vfs_file_count: int = 0,
+        cache_count: int = 0,
+        delta_count: int = 0,
+        estimated_vfs_bytes: int = 0,
+        estimated_cache_bytes: int = 0,
+        estimated_delta_bytes: int = 0,
+    ) -> GCResult:
+        """Log a GC request (Public Preview: no actual purge)."""
+        result = GCResult(
+            session_id=session_id,
+            retained_deltas=delta_count,
+            retained_hash=True,
+            purged_vfs_files=0,
+            purged_caches=0,
+            storage_before_bytes=estimated_vfs_bytes + estimated_cache_bytes + estimated_delta_bytes,
+            storage_after_bytes=estimated_vfs_bytes + estimated_cache_bytes + estimated_delta_bytes,
+        )
+        self._gc_history.append(result)
+        self._purged_sessions.add(session_id)
+        return result
+
+    def is_purged(self, session_id: str) -> bool:
+        return session_id in self._purged_sessions
+
+    def should_expire_deltas(self, delta_timestamp: datetime) -> bool:
+        return False
+
+    @property
+    def history(self) -> list[GCResult]:
+        return list(self._gc_history)
+
+    @property
+    def purged_session_count(self) -> int:
+        return len(self._purged_sessions)

hypervisor/cli/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""CLI for inspecting hypervisor session state."""

hypervisor/cli/formatters.py

@@ -0,0 +1,99 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Output formatters for CLI commands."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def format_output(data: Any, fmt: str) -> str:
+    """Format data as table, json, or yaml."""
+    if fmt == "json":
+        return json.dumps(data, indent=2, default=str)
+    if fmt == "yaml":
+        return _to_yaml(data)
+    # Default: table
+    if isinstance(data, list):
+        return _format_table(data)
+    if isinstance(data, dict):
+        return _format_dict(data)
+    return str(data)
+
+
+def _format_table(rows: list[dict[str, Any]]) -> str:
+    """Render a list of dicts as an aligned text table."""
+    if not rows:
+        return "No results."
+    keys = list(rows[0].keys())
+    widths = {k: max(len(k), *(len(str(r.get(k, ""))) for r in rows)) for k in keys}
+    header = "  ".join(k.upper().ljust(widths[k]) for k in keys)
+    sep = "  ".join("-" * widths[k] for k in keys)
+    lines = [header, sep]
+    for row in rows:
+        lines.append("  ".join(str(row.get(k, "")).ljust(widths[k]) for k in keys))
+    return "\n".join(lines)
+
+
+def _format_dict(d: dict[str, Any]) -> str:
+    """Render a dict as key-value pairs."""
+    if not d:
+        return "No data."
+    width = max(len(str(k)) for k in d)
+    lines = []
+    for k, v in d.items():
+        if isinstance(v, list):
+            lines.append(f"{str(k).ljust(width)}: ({len(v)} items)")
+            for item in v:
+                if isinstance(item, dict):
+                    parts = ", ".join(f"{ik}={iv}" for ik, iv in item.items())
+                    lines.append(f"  - {parts}")
+                else:
+                    lines.append(f"  - {item}")
+        else:
+            lines.append(f"{str(k).ljust(width)}: {v}")
+    return "\n".join(lines)
+
+
+def _to_yaml(data: Any, indent: int = 0) -> str:
+    """Minimal YAML serializer (no external dependency)."""
+    prefix = "  " * indent
+    if isinstance(data, dict):
+        if not data:
+            return f"{prefix}{{}}"
+        lines = []
+        for k, v in data.items():
+            if isinstance(v, (dict, list)):
+                lines.append(f"{prefix}{k}:")
+                lines.append(_to_yaml(v, indent + 1))
+            else:
+                lines.append(f"{prefix}{k}: {_yaml_scalar(v)}")
+        return "\n".join(lines)
+    if isinstance(data, list):
+        if not data:
+            return f"{prefix}[]"
+        lines = []
+        for item in data:
+            if isinstance(item, dict):
+                first = True
+                for k, v in item.items():
+                    tag = "- " if first else "  "
+                    first = False
+                    if isinstance(v, (dict, list)):
+                        lines.append(f"{prefix}{tag}{k}:")
+                        lines.append(_to_yaml(v, indent + 2))
+                    else:
+                        lines.append(f"{prefix}{tag}{k}: {_yaml_scalar(v)}")
+            else:
+                lines.append(f"{prefix}- {_yaml_scalar(item)}")
+        return "\n".join(lines)
+    return f"{prefix}{_yaml_scalar(data)}"
+
+
+def _yaml_scalar(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return str(v)

hypervisor/cli/session_commands.py

@@ -0,0 +1,200 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Session inspection CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from hypervisor.cli.formatters import format_output
+from hypervisor.core import Hypervisor, ManagedSession
+from hypervisor.security.kill_switch import KillReason, KillSwitch
+
+
+def _build_session_summary(managed: ManagedSession) -> dict[str, Any]:
+    """Build a summary dict for a single session."""
+    sso = managed.sso
+    return {
+        "session_id": sso.session_id,
+        "state": sso.state.value,
+        "participants": sso.participant_count,
+        "consistency": sso.consistency_mode.value,
+        "created_at": sso.created_at.isoformat(),
+    }
+
+
+def _build_session_detail(managed: ManagedSession) -> dict[str, Any]:
+    """Build a detailed inspection dict for a session."""
+    sso = managed.sso
+
+    participants = [
+        {
+            "agent_did": p.agent_did,
+            "ring": p.ring.value,
+            "eff_score": round(p.eff_score, 4),
+            "sigma_raw": round(p.sigma_raw, 4),
+            "is_active": p.is_active,
+        }
+        for p in sso.participants
+    ]
+
+    # Saga steps
+    saga_steps: list[dict[str, Any]] = []
+    for saga in managed.saga._sagas.values():
+        for step in saga.steps:
+            saga_steps.append({
+                "saga_id": saga.saga_id,
+                "step_id": step.step_id,
+                "action_id": step.action_id,
+                "agent_did": step.agent_did,
+                "state": step.state.value,
+                "error": step.error,
+            })
+
+    # Audit deltas
+    audit_entries = [
+        {
+            "delta_id": d.delta_id,
+            "turn_id": d.turn_id,
+            "agent_did": d.agent_did,
+            "timestamp": d.timestamp.isoformat(),
+            "changes": len(d.changes),
+        }
+        for d in managed.delta_engine.deltas
+    ]
+
+    # Resource usage
+    resource_usage = {
+        "vfs_files": sso.vfs.file_count,
+        "vfs_snapshots": sso.vfs.snapshot_count,
+        "audit_turns": managed.delta_engine.turn_count,
+    }
+
+    return {
+        "session_id": sso.session_id,
+        "state": sso.state.value,
+        "consistency_mode": sso.consistency_mode.value,
+        "created_at": sso.created_at.isoformat(),
+        "terminated_at": sso.terminated_at.isoformat() if sso.terminated_at else None,
+        "participants": participants,
+        "saga_steps": saga_steps,
+        "resource_usage": resource_usage,
+        "audit_log": audit_entries,
+    }
+
+
+def cmd_list(hv: Hypervisor, fmt: str) -> str:
+    """List all active sessions."""
+    sessions = hv.active_sessions
+    if not sessions:
+        return "No active sessions."
+    rows = [_build_session_summary(m) for m in sessions]
+    return format_output(rows, fmt)
+
+
+def cmd_inspect(hv: Hypervisor, session_id: str, fmt: str) -> str:
+    """Inspect a single session in detail."""
+    managed = hv.get_session(session_id)
+    if managed is None:
+        return f"Error: session '{session_id}' not found."
+    detail = _build_session_detail(managed)
+    return format_output(detail, fmt)
+
+
+def cmd_kill(
+    hv: Hypervisor,
+    session_id: str,
+    fmt: str,
+    kill_switch: KillSwitch | None = None,
+) -> str:
+    """Trigger kill switch on all agents in a session."""
+    managed = hv.get_session(session_id)
+    if managed is None:
+        return f"Error: session '{session_id}' not found."
+
+    ks = kill_switch or KillSwitch()
+    results = []
+    for p in managed.sso.participants:
+        result = ks.kill(
+            agent_did=p.agent_did,
+            session_id=session_id,
+            reason=KillReason.MANUAL,
+            details="Killed via CLI",
+        )
+        managed.sso.leave(p.agent_did)
+        results.append({
+            "kill_id": result.kill_id,
+            "agent_did": result.agent_did,
+            "reason": result.reason.value,
+            "timestamp": result.timestamp.isoformat(),
+        })
+
+    return format_output(results, fmt)
+
+
+def build_parser(
+    parent: argparse._SubParsersAction | None = None,
+) -> argparse.ArgumentParser:
+    """Build the 'session' sub-command parser."""
+    if parent is not None:
+        parser = parent.add_parser("session", help="Inspect session state")
+    else:
+        parser = argparse.ArgumentParser(prog="hypervisor session")
+
+    parser.add_argument(
+        "--format",
+        choices=["table", "json", "yaml"],
+        default="table",
+        dest="output_format",
+        help="Output format (default: table)",
+    )
+
+    sub = parser.add_subparsers(dest="session_command")
+
+    sub.add_parser("list", help="List all active sessions")
+
+    inspect_p = sub.add_parser("inspect", help="Show detailed session state")
+    inspect_p.add_argument("session_id", help="Session ID to inspect")
+
+    kill_p = sub.add_parser("kill", help="Trigger kill switch on a session")
+    kill_p.add_argument("session_id", help="Session ID to kill")
+
+    return parser
+
+
+def dispatch(
+    args: argparse.Namespace,
+    hv: Hypervisor,
+    kill_switch: KillSwitch | None = None,
+) -> str:
+    """Dispatch a parsed session command to the appropriate handler."""
+    fmt = getattr(args, "output_format", "table")
+    cmd = args.session_command
+
+    if cmd == "list":
+        return cmd_list(hv, fmt)
+    elif cmd == "inspect":
+        return cmd_inspect(hv, args.session_id, fmt)
+    elif cmd == "kill":
+        return cmd_kill(hv, args.session_id, fmt, kill_switch)
+    else:
+        return "Error: specify a sub-command (list, inspect, kill)."
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for the CLI."""
+    top = argparse.ArgumentParser(prog="hypervisor")
+    sub = top.add_subparsers(dest="command")
+    build_parser(sub)
+
+    args = top.parse_args(argv)
+    if args.command != "session" or not args.session_command:
+        top.print_help()
+        sys.exit(1)
+
+    # In standalone mode, create an empty hypervisor (useful for testing the parser).
+    hv = Hypervisor()
+    output = dispatch(args, hv)
+    print(output)