kweaver-dolphin 0.1.0__py3-none-any.whl

dolphin/core/coroutine/context_snapshot_store.py

@@ -0,0 +1,268 @@
+import os
+import json
+import threading
+import time
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+from dolphin.core.logging.logger import get_logger
+from .context_snapshot import ContextSnapshot
+
+logger = get_logger()
+
+
+class ContextSnapshotStore(ABC):
+    """Abstract interface for context snapshot storage"""
+
+    @abstractmethod
+    def save_snapshot(self, snapshot: ContextSnapshot) -> str:
+        """Save snapshot, return snapshot ID"""
+        pass
+
+    @abstractmethod
+    def load_snapshot(self, snapshot_id: str) -> Optional[ContextSnapshot]:
+        """Load snapshot"""
+        pass
+
+    @abstractmethod
+    def delete_snapshot(self, snapshot_id: str) -> bool:
+        """Delete snapshot"""
+        pass
+
+    @abstractmethod
+    def list_snapshots(self, frame_id: Optional[str] = None) -> List[str]:
+        """List snapshots"""
+        pass
+
+    @abstractmethod
+    def save_pending_snapshot(self, snapshot: ContextSnapshot) -> str:
+        """Save pending snapshot (for transactional)"""
+        pass
+
+    @abstractmethod
+    def finalize_snapshot(self, snapshot_id: str) -> bool:
+        """Confirm Snapshot (Atomic Rename)"""
+        pass
+
+
+class FileContextSnapshotStore(ContextSnapshotStore):
+    """Filesystem-based context snapshot storage"""
+
+    def __init__(self, base_path: str = "./data/snapshots"):
+        self.base_path = base_path
+        self._lock = threading.RLock()
+        self._ensure_directory()
+
+    def _ensure_directory(self):
+        """Ensure the storage directory exists"""
+        os.makedirs(self.base_path, exist_ok=True)
+
+    def _get_snapshot_path(self, snapshot_id: str) -> str:
+        """Get snapshot file path"""
+        return os.path.join(self.base_path, f"{snapshot_id}.json")
+
+    def _get_pending_path(self, snapshot_id: str) -> str:
+        """Get pending snapshot file path"""
+        return os.path.join(self.base_path, f"{snapshot_id}.pending.json")
+
+    def save_snapshot(self, snapshot: ContextSnapshot) -> str:
+        """Save snapshot"""
+        with self._lock:
+            file_path = self._get_snapshot_path(snapshot.snapshot_id)
+            try:
+                with open(file_path, "w", encoding="utf-8") as f:
+                    json.dump(snapshot.encode(), f, ensure_ascii=False, indent=2)
+                return snapshot.snapshot_id
+            except Exception as e:
+                raise RuntimeError(
+                    f"Failed to save snapshot {snapshot.snapshot_id}: {e}"
+                )
+
+    def load_snapshot(self, snapshot_id: str) -> Optional[ContextSnapshot]:
+        """Load snapshot"""
+        with self._lock:
+            file_path = self._get_snapshot_path(snapshot_id)
+            if not os.path.exists(file_path):
+                return None
+
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                return ContextSnapshot.decode(data)
+            except Exception as e:
+                raise RuntimeError(f"Failed to load snapshot {snapshot_id}: {e}")
+
+    def delete_snapshot(self, snapshot_id: str) -> bool:
+        """Delete snapshot"""
+        with self._lock:
+            file_path = self._get_snapshot_path(snapshot_id)
+            if os.path.exists(file_path):
+                try:
+                    os.remove(file_path)
+                    return True
+                except Exception:
+                    return False
+            return False
+
+    def list_snapshots(self, frame_id: Optional[str] = None) -> List[str]:
+        """List snapshots"""
+        with self._lock:
+            snapshots = []
+            if not os.path.exists(self.base_path):
+                return snapshots
+
+            for filename in os.listdir(self.base_path):
+                if filename.endswith(".json") and not filename.endswith(
+                    ".pending.json"
+                ):
+                    snapshot_id = filename[:-5]  # Remove .json suffix
+
+                    # If frame_id is specified, filter it.
+                    if frame_id:
+                        try:
+                            snapshot = self.load_snapshot(snapshot_id)
+                            if snapshot and snapshot.frame_id == frame_id:
+                                snapshots.append(snapshot_id)
+                        except Exception:
+                            continue
+                    else:
+                        snapshots.append(snapshot_id)
+
+            return sorted(snapshots)
+
+    def save_pending_snapshot(self, snapshot: ContextSnapshot) -> str:
+        """Pending snapshot"""
+        with self._lock:
+            pending_path = self._get_pending_path(snapshot.snapshot_id)
+            try:
+                with open(pending_path, "w", encoding="utf-8") as f:
+                    json.dump(snapshot.encode(), f, ensure_ascii=False, indent=2)
+                return snapshot.snapshot_id
+            except Exception as e:
+                raise RuntimeError(
+                    f"Failed to save pending snapshot {snapshot.snapshot_id}: {e}"
+                )
+
+    def finalize_snapshot(self, snapshot_id: str) -> bool:
+        """Confirm Snapshot (Atomic Rename)"""
+        with self._lock:
+            pending_path = self._get_pending_path(snapshot_id)
+            final_path = self._get_snapshot_path(snapshot_id)
+
+            if not os.path.exists(pending_path):
+                return False
+
+            try:
+                os.rename(pending_path, final_path)
+                return True
+            except Exception:
+                return False
+
+    def cleanup_pending_snapshots(self, max_age_seconds: int = 3600) -> int:
+        """Clean up expired pending snapshots"""
+        with self._lock:
+            cleaned = 0
+            current_time = time.time()
+
+            if not os.path.exists(self.base_path):
+                return cleaned
+
+            for filename in os.listdir(self.base_path):
+                if filename.endswith(".pending.json"):
+                    file_path = os.path.join(self.base_path, filename)
+                    try:
+                        file_mtime = os.path.getmtime(file_path)
+                        if current_time - file_mtime > max_age_seconds:
+                            os.remove(file_path)
+                            cleaned += 1
+                    except Exception:
+                        continue
+
+            return cleaned
+
+    def get_snapshot_stats(self) -> Dict:
+        """Get snapshot storage statistics"""
+        with self._lock:
+            stats = {
+                "total_snapshots": 0,
+                "pending_snapshots": 0,
+                "total_size_bytes": 0,
+            }
+
+            if not os.path.exists(self.base_path):
+                return stats
+
+            for filename in os.listdir(self.base_path):
+                file_path = os.path.join(self.base_path, filename)
+                try:
+                    file_size = os.path.getsize(file_path)
+                    stats["total_size_bytes"] += file_size
+
+                    if filename.endswith(".pending.json"):
+                        stats["pending_snapshots"] += 1
+                    elif filename.endswith(".json"):
+                        stats["total_snapshots"] += 1
+                except Exception:
+                    continue
+
+            return stats
+
+
+class MemoryContextSnapshotStore(ContextSnapshotStore):
+    """In-memory context snapshot storage (for testing)"""
+
+    def __init__(self):
+        self._snapshots: Dict[str, ContextSnapshot] = {}
+        self._pending: Dict[str, ContextSnapshot] = {}
+        self._lock = threading.RLock()
+
+    def save_snapshot(self, snapshot: ContextSnapshot) -> str:
+        """Save snapshot"""
+        with self._lock:
+            self._snapshots[snapshot.snapshot_id] = snapshot
+            return snapshot.snapshot_id
+
+    def load_snapshot(self, snapshot_id: str) -> Optional[ContextSnapshot]:
+        """Load snapshot"""
+        with self._lock:
+            return self._snapshots.get(snapshot_id)
+
+    def delete_snapshot(self, snapshot_id: str) -> bool:
+        """Delete snapshot"""
+        with self._lock:
+            if snapshot_id in self._snapshots:
+                del self._snapshots[snapshot_id]
+                return True
+            return False
+
+    def list_snapshots(self, frame_id: Optional[str] = None) -> List[str]:
+        """List snapshots"""
+        with self._lock:
+            if frame_id:
+                return [
+                    sid
+                    for sid, snapshot in self._snapshots.items()
+                    if snapshot.frame_id == frame_id
+                ]
+            return list(self._snapshots.keys())
+
+    def save_pending_snapshot(self, snapshot: ContextSnapshot) -> str:
+        """Pending snapshot"""
+        with self._lock:
+            self._pending[snapshot.snapshot_id] = snapshot
+            return snapshot.snapshot_id
+
+    def finalize_snapshot(self, snapshot_id: str) -> bool:
+        """Confirm Snapshot"""
+        with self._lock:
+            if snapshot_id in self._pending:
+                snapshot = self._pending.pop(snapshot_id)
+                self._snapshots[snapshot_id] = snapshot
+                return True
+            return False
+
+    def clear(self):
+        """Clear all snapshots"""
+        with self._lock:
+            self._snapshots.clear()
+            self._pending.clear()

dolphin/core/coroutine/execution_frame.py

@@ -0,0 +1,145 @@
+import time
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional, List, Dict
+
+
+class FrameStatus(Enum):
+    RUNNING = "running"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    WAITING_FOR_INTERVENTION = "waiting_for_intervention"
+    TERMINATED = "terminated"
+
+
+class WaitReason(Enum):
+    """Reason for WAITING status (entropy-reduction: reuse WAITING with discriminator).
+
+    This enum distinguishes different waiting scenarios without adding new frame statuses.
+    """
+    TOOL_REQUEST = "tool_request"      # Tool requests user input (ToolInterrupt)
+    USER_INTERRUPT = "user_interrupt"  # User actively interrupted (UserInterrupt)
+
+
+@dataclass
+class ExecutionFrame:
+    """Execution frame - saves execution state and control flow information"""
+
+    frame_id: str
+    parent_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    block_pointer: int = 0
+    block_stack: List[Dict] = None
+    status: FrameStatus = FrameStatus.RUNNING
+    context_snapshot_id: str = ""
+    children: List[str] = None
+    created_at: float = None
+    updated_at: float = None
+    original_content: str = ""  # Added: Save original dolphin script content
+    error: Optional[Dict] = None  # Added: Error Messages
+    wait_reason: Optional[WaitReason] = None  # Reason when in WAITING status
+
+    def __post_init__(self):
+        if self.block_stack is None:
+            self.block_stack = []
+        if self.children is None:
+            self.children = []
+        if self.created_at is None:
+            self.created_at = time.time()
+        if self.updated_at is None:
+            self.updated_at = time.time()
+
+    @classmethod
+    def create_root_frame(cls, agent_id: Optional[str] = None) -> "ExecutionFrame":
+        """Create root execution frame"""
+        return cls(
+            frame_id=str(uuid.uuid4()),
+            parent_id=None,
+            agent_id=agent_id,
+            block_pointer=0,
+            block_stack=[],
+            status=FrameStatus.RUNNING,
+            children=[],
+        )
+
+    @classmethod
+    def create_child_frame(
+        cls, parent_frame: "ExecutionFrame", agent_id: Optional[str] = None
+    ) -> "ExecutionFrame":
+        """Create sub-execution frame"""
+        return cls(
+            frame_id=str(uuid.uuid4()),
+            parent_id=parent_frame.frame_id,
+            agent_id=agent_id,
+            block_pointer=0,
+            block_stack=[],
+            status=FrameStatus.RUNNING,
+            children=[],
+        )
+
+    def update_timestamp(self):
+        """Update timestamp"""
+        self.updated_at = time.time()
+
+    def is_completed(self) -> bool:
+        """Check if completed"""
+        return self.status == FrameStatus.COMPLETED
+
+    def is_failed(self) -> bool:
+        """Check if failed"""
+        return self.status == FrameStatus.FAILED
+
+    def is_paused(self) -> bool:
+        """Check if paused"""
+        return self.status == FrameStatus.PAUSED
+
+    def is_running(self) -> bool:
+        """Check if running"""
+        return self.status == FrameStatus.RUNNING
+
+    def is_waiting_for_intervention(self) -> bool:
+        """Check if waiting for user intervention"""
+        return self.status == FrameStatus.WAITING_FOR_INTERVENTION
+
+    def is_terminated(self) -> bool:
+        """Check if already terminated"""
+        return self.status == FrameStatus.TERMINATED
+
+    def is_waiting_for_user_input(self) -> bool:
+        """Check if waiting for user input (due to UserInterrupt)"""
+        return (
+            self.status == FrameStatus.WAITING_FOR_INTERVENTION
+            and self.wait_reason == WaitReason.USER_INTERRUPT
+        )
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary format"""
+        return {
+            "frame_id": self.frame_id,
+            "parent_id": self.parent_id,
+            "agent_id": self.agent_id,
+            "block_pointer": self.block_pointer,
+            "block_stack": self.block_stack,
+            "status": self.status.value,
+            "context_snapshot_id": self.context_snapshot_id,
+            "children": self.children,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "original_content": self.original_content,
+            "error": self.error,
+            "wait_reason": self.wait_reason.value if self.wait_reason else None,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "ExecutionFrame":
+        """Create execution frame from dictionary"""
+        data = data.copy()
+        data["status"] = FrameStatus(data["status"])
+        # Handle wait_reason if present
+        if data.get("wait_reason"):
+            data["wait_reason"] = WaitReason(data["wait_reason"])
+        else:
+            data["wait_reason"] = None
+        return cls(**data)

dolphin/core/coroutine/execution_state_registry.py

@@ -0,0 +1,161 @@
+import time
+import threading
+from typing import Dict, List, Optional, Tuple
+from .execution_frame import ExecutionFrame, FrameStatus
+
+
+class ExecutionStateRegistry:
+    """Execution Status Registry - Manage the lifecycle of all execution frames"""
+
+    def __init__(self):
+        self._frames: Dict[str, ExecutionFrame] = {}
+        self._lock = threading.RLock()  # Using Reentrant Lock
+
+    def register_frame(self, frame: ExecutionFrame) -> bool:
+        """Register Execution Frame"""
+        with self._lock:
+            if frame.frame_id in self._frames:
+                return False
+            self._frames[frame.frame_id] = frame
+            return True
+
+    def get_frame(self, frame_id: str) -> Optional[ExecutionFrame]:
+        """Get execution frame"""
+        with self._lock:
+            return self._frames.get(frame_id)
+
+    def update_frame(self, frame: ExecutionFrame) -> bool:
+        """Update execution frame"""
+        with self._lock:
+            if frame.frame_id not in self._frames:
+                return False
+            frame.update_timestamp()
+            self._frames[frame.frame_id] = frame
+            return True
+
+    def compare_and_swap(
+        self, frame_id: str, expected_version: int, updates: Dict
+    ) -> Tuple[bool, Optional[ExecutionFrame]]:
+        """Optimistic Concurrency Control - Compare and Swap"""
+        with self._lock:
+            frame = self._frames.get(frame_id)
+            if not frame:
+                return False, None
+
+            # Simplified version control - using update timestamp as version
+            current_version = int(frame.updated_at)
+            if current_version != expected_version:
+                return False, frame
+
+            # Application Update
+            for key, value in updates.items():
+                if hasattr(frame, key):
+                    setattr(frame, key, value)
+
+            frame.update_timestamp()
+            self._frames[frame_id] = frame
+            return True, frame
+
+    def remove_frame(self, frame_id: str) -> bool:
+        """Remove execution frame"""
+        with self._lock:
+            if frame_id in self._frames:
+                del self._frames[frame_id]
+                return True
+            return False
+
+    def get_child_frames(self, parent_id: str) -> List[ExecutionFrame]:
+        """Get the list of child execution frames"""
+        with self._lock:
+            children = []
+            for frame in self._frames.values():
+                if frame.parent_id == parent_id:
+                    children.append(frame)
+            return children
+
+    def get_frame_tree(self, root_id: str) -> Dict:
+        """Get the frame tree with the specified frame as root"""
+        with self._lock:
+            root_frame = self._frames.get(root_id)
+            if not root_frame:
+                return {}
+
+            def build_tree(frame_id: str) -> Dict:
+                frame = self._frames.get(frame_id)
+                if not frame:
+                    return {}
+
+                tree = {"frame": frame, "children": []}
+
+                for child_id in frame.children:
+                    child_tree = build_tree(child_id)
+                    if child_tree:
+                        tree["children"].append(child_tree)
+
+                return tree
+
+            return build_tree(root_id)
+
+    def list_frames_by_status(self, status: FrameStatus) -> List[ExecutionFrame]:
+        """List execution frames by status"""
+        with self._lock:
+            return [frame for frame in self._frames.values() if frame.status == status]
+
+    def list_all_frames(self) -> List[ExecutionFrame]:
+        """List all executed frames"""
+        with self._lock:
+            return list(self._frames.values())
+
+    def get_frame_count(self) -> int:
+        """Get the number of execution frames"""
+        with self._lock:
+            return len(self._frames)
+
+    def get_stats(self) -> Dict:
+        """Get registry statistics"""
+        with self._lock:
+            stats = {
+                "total_frames": len(self._frames),
+                "running": 0,
+                "paused": 0,
+                "completed": 0,
+                "failed": 0,
+                "waiting_for_intervention": 0,
+            }
+
+            for frame in self._frames.values():
+                if frame.status == FrameStatus.RUNNING:
+                    stats["running"] += 1
+                elif frame.status == FrameStatus.PAUSED:
+                    stats["paused"] += 1
+                elif frame.status == FrameStatus.COMPLETED:
+                    stats["completed"] += 1
+                elif frame.status == FrameStatus.FAILED:
+                    stats["failed"] += 1
+                elif frame.status == FrameStatus.WAITING_FOR_INTERVENTION:
+                    stats["waiting_for_intervention"] += 1
+
+            return stats
+
+    def cleanup_completed_frames(self, max_age_seconds: int = 3600) -> int:
+        """Clean up completed old execution frames"""
+        with self._lock:
+            current_time = time.time()
+            to_remove = []
+
+            for frame_id, frame in self._frames.items():
+                if (
+                    frame.status in [FrameStatus.COMPLETED, FrameStatus.FAILED]
+                    and current_time - frame.updated_at > max_age_seconds
+                ):
+                    to_remove.append(frame_id)
+
+            for frame_id in to_remove:
+                del self._frames[frame_id]
+
+            return len(to_remove)
+
+    def clear(self):
+        """Clear all execution frames"""
+        with self._lock:
+            self._frames.clear()

dolphin/core/coroutine/resume_handle.py

@@ -0,0 +1,101 @@
+import uuid
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Literal
+
+
+@dataclass
+class ResumeHandle:
+    """Resume handle - used to restore paused execution.
+
+    Supports two interrupt types:
+    - "tool_interrupt": Tool requested user input, resume from breakpoint
+    - "user_interrupt": User actively interrupted, restart block with new context
+
+    Attributes:
+        frame_id: ID of the execution frame
+        snapshot_id: ID of the context snapshot
+        resume_token: Unique token for this resume operation
+        interrupt_type: Type of interrupt ("tool_interrupt" or "user_interrupt")
+        current_block: Block pointer at interrupt time (for user_interrupt)
+        restart_block: Whether to restart the block (True for user_interrupt)
+    """
+
+    frame_id: str
+    snapshot_id: str
+    resume_token: str
+    interrupt_type: Literal["tool_interrupt", "user_interrupt"] = "tool_interrupt"
+    current_block: Optional[int] = None
+    restart_block: bool = False
+
+    @classmethod
+    def create_handle(cls, frame_id: str, snapshot_id: str) -> "ResumeHandle":
+        """Create recovery handle (for tool interrupt - backward compatible)"""
+        return cls(
+            frame_id=frame_id,
+            snapshot_id=snapshot_id,
+            resume_token=str(uuid.uuid4()),
+            interrupt_type="tool_interrupt",
+            restart_block=False,
+        )
+
+    @classmethod
+    def create_user_interrupt_handle(
+        cls,
+        frame_id: str,
+        snapshot_id: str,
+        current_block: Optional[int] = None,
+    ) -> "ResumeHandle":
+        """Create resume handle for user interrupt.
+
+        Args:
+            frame_id: ID of the execution frame
+            snapshot_id: ID of the context snapshot
+            current_block: Block pointer at interrupt time
+
+        Returns:
+            ResumeHandle configured for user interrupt (restart_block=True)
+        """
+        return cls(
+            frame_id=frame_id,
+            snapshot_id=snapshot_id,
+            resume_token=str(uuid.uuid4()),
+            interrupt_type="user_interrupt",
+            current_block=current_block,
+            restart_block=True,
+        )
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary format"""
+        return {
+            "frame_id": self.frame_id,
+            "snapshot_id": self.snapshot_id,
+            "resume_token": self.resume_token,
+            "interrupt_type": self.interrupt_type,
+            "current_block": self.current_block,
+            "restart_block": self.restart_block,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "ResumeHandle":
+        """Create a restore handle from a dictionary"""
+        # Handle backward compatibility for old data without new fields
+        return cls(
+            frame_id=data["frame_id"],
+            snapshot_id=data["snapshot_id"],
+            resume_token=data["resume_token"],
+            interrupt_type=data.get("interrupt_type", "tool_interrupt"),
+            current_block=data.get("current_block"),
+            restart_block=data.get("restart_block", False),
+        )
+
+    def is_valid(self) -> bool:
+        """Check if the handle is valid"""
+        return bool(self.frame_id and self.snapshot_id and self.resume_token)
+
+    def is_user_interrupt(self) -> bool:
+        """Check if this handle is for a user interrupt"""
+        return self.interrupt_type == "user_interrupt"
+
+    def is_tool_interrupt(self) -> bool:
+        """Check if this handle is for a tool interrupt"""
+        return self.interrupt_type == "tool_interrupt"