alita-sdk 0.3.465__py3-none-any.whl → 0.3.486__py3-none-any.whl

alita_sdk/cli/tools/planning.py

@@ -6,6 +6,10 @@ Sessions are persisted to $ALITA_DIR/sessions/<session_id>/
 - plan.json: Execution plan with steps
 - memory.db: SQLite database for conversation memory
 - session.json: Session metadata (agent, model, etc.)
+
+This module re-exports the runtime PlanningToolkit for unified usage across
+CLI, indexer_worker, and SDK agents. The runtime toolkit supports both
+PostgreSQL (production) and filesystem (local) storage backends.
 """
 
 import os
@@ -21,9 +25,13 @@ import logging
 logger = logging.getLogger(__name__)
 
 
+# ============================================================================
+# Session Management Functions
+# ============================================================================
+
 def get_sessions_dir() -> Path:
-    """Get the sessions directory path."""
-    alita_dir = os.environ.get('ALITA_DIR', os.path.expanduser('~/.alita'))
+    """Get the sessions directory path (relative to $ALITA_DIR or .alita)."""
+    alita_dir = os.environ.get('ALITA_DIR', '.alita')
     return Path(alita_dir) / 'sessions'
 
 
@@ -102,6 +110,88 @@ def load_session_metadata(session_id: str) -> Optional[Dict[str, Any]]:
     return None
 
 
+def update_session_metadata(session_id: str, updates: Dict[str, Any]) -> None:
+    """
+    Update session metadata by merging new fields into existing metadata.
+    
+    This preserves existing fields while updating/adding new ones.
+    
+    Args:
+        session_id: The session ID
+        updates: Dictionary with fields to update/add
+    """
+    existing = load_session_metadata(session_id) or {}
+    existing.update(updates)
+    save_session_metadata(session_id, existing)
+    logger.debug(f"Updated session metadata with: {list(updates.keys())}")
+
+
+def get_alita_dir() -> Path:
+    """Get the ALITA_DIR path (relative to $ALITA_DIR or .alita)."""
+    return Path(os.environ.get('ALITA_DIR', '.alita'))
+
+
+def to_portable_path(path: str) -> str:
+    """
+    Convert an absolute path to a portable path for session storage.
+    
+    If the path is under $ALITA_DIR, store as relative path (e.g., 'agents/my-agent.yaml').
+    Otherwise, store the absolute path.
+    
+    Args:
+        path: Absolute file path
+        
+    Returns:
+        Portable path string (relative to ALITA_DIR if applicable, else absolute)
+    """
+    if not path:
+        return path
+    
+    try:
+        path_obj = Path(path).resolve()
+        alita_dir = get_alita_dir().resolve()
+        
+        # Check if path is under ALITA_DIR
+        if str(path_obj).startswith(str(alita_dir)):
+            relative = path_obj.relative_to(alita_dir)
+            return str(relative)
+    except (ValueError, OSError):
+        pass
+    
+    return str(path)
+
+
+def from_portable_path(portable_path: str) -> str:
+    """
+    Convert a portable path back to an absolute path.
+    
+    If the path is relative, resolve it against $ALITA_DIR.
+    Otherwise, return as-is.
+    
+    Args:
+        portable_path: Portable path string from session storage
+        
+    Returns:
+        Absolute file path
+    """
+    if not portable_path:
+        return portable_path
+    
+    path_obj = Path(portable_path)
+    
+    # If already absolute, return as-is
+    if path_obj.is_absolute():
+        return str(path_obj)
+    
+    # Resolve relative path against ALITA_DIR
+    alita_dir = get_alita_dir()
+    return str(alita_dir / portable_path)
+
+
+# ============================================================================
+# PlanState - For CLI UI compatibility and session listing
+# ============================================================================
+
 class PlanStep(BaseModel):
     """A single step in a plan."""
     description: str = Field(description="Step description")
@@ -109,7 +199,12 @@ class PlanStep(BaseModel):
 
 
 class PlanState(BaseModel):
-    """Current plan state."""
+    """
+    Current plan state for CLI display.
+    
+    This is used for CLI UI rendering and backwards compatibility.
+    The actual plan storage is handled by the runtime PlanningWrapper.
+    """
     title: str = Field(default="", description="Plan title")
     steps: List[PlanStep] = Field(default_factory=list, description="List of steps")
     session_id: str = Field(default="", description="Session ID for persistence")
@@ -148,23 +243,6 @@ class PlanState(BaseModel):
             session_id=data.get("session_id", "")
         )
     
-    def save(self) -> Optional[Path]:
-        """Save plan state to session file."""
-        if not self.session_id:
-            return None
-        
-        try:
-            session_dir = get_sessions_dir() / self.session_id
-            session_dir.mkdir(parents=True, exist_ok=True)
-            
-            plan_file = session_dir / "plan.json"
-            plan_file.write_text(json.dumps(self.to_dict(), indent=2))
-            logger.debug(f"Saved plan to {plan_file}")
-            return plan_file
-        except Exception as e:
-            logger.warning(f"Failed to save plan: {e}")
-            return None
-    
     @classmethod
     def load(cls, session_id: str) -> Optional["PlanState"]:
         """Load plan state from session file."""
@@ -248,121 +326,9 @@ def list_sessions() -> List[Dict[str, Any]]:
     return sessions
 
 
-class UpdatePlanInput(BaseModel):
-    """Input for updating the plan."""
-    title: str = Field(description="Title for the plan (e.g., 'Test Investigation Plan')")
-    steps: List[str] = Field(description="List of step descriptions in order")
-
-
-class CompleteStepInput(BaseModel):
-    """Input for marking a step as complete."""
-    step_number: int = Field(description="Step number to mark as complete (1-indexed)")
-
-
-class UpdatePlanTool(BaseTool):
-    """Create or update the execution plan."""
-    
-    name: str = "update_plan"
-    description: str = """Create or replace the current execution plan.
-    
-Use this when:
-- Starting a multi-step task that needs tracking
-- The sequence of activities matters
-- Breaking down a complex task into phases
-
-The plan will be displayed to the user and you can mark steps complete as you progress.
-Plans are automatically saved and can be resumed in future sessions.
-
-Example:
-    update_plan(
-        title="API Test Investigation",
-        steps=[
-            "Reproduce the failing test locally",
-            "Capture error logs and stack trace",
-            "Identify root cause",
-            "Apply fix to test or code",
-            "Re-run test suite to verify"
-        ]
-    )"""
-    args_schema: type[BaseModel] = UpdatePlanInput
-    
-    # Reference to shared plan state (set by executor)
-    plan_state: Optional[PlanState] = None
-    _plan_callback: Optional[Callable] = None
-    
-    def __init__(self, plan_state: Optional[PlanState] = None, plan_callback: Optional[Callable] = None, **kwargs):
-        super().__init__(**kwargs)
-        self.plan_state = plan_state or PlanState()
-        self._plan_callback = plan_callback
-    
-    def _run(self, title: str, steps: List[str]) -> str:
-        """Update the plan with new steps."""
-        self.plan_state.title = title
-        self.plan_state.steps = [PlanStep(description=s) for s in steps]
-        
-        # Auto-save to session
-        saved_path = self.plan_state.save()
-        
-        # Notify callback if set (for UI rendering)
-        if self._plan_callback:
-            self._plan_callback(self.plan_state)
-        
-        result = f"Plan updated:\n\n{self.plan_state.render()}"
-        if saved_path:
-            result += f"\n\n[dim]Session: {self.plan_state.session_id}[/dim]"
-        return result
-
-
-class CompleteStepTool(BaseTool):
-    """Mark a plan step as complete."""
-    
-    name: str = "complete_step"
-    description: str = """Mark a step in the current plan as completed.
-    
-Use this after finishing a step to update the plan progress.
-Step numbers are 1-indexed (first step is 1, not 0).
-Progress is automatically saved.
-
-Example:
-    complete_step(step_number=1)  # Mark first step as done"""
-    args_schema: type[BaseModel] = CompleteStepInput
-    
-    # Reference to shared plan state (set by executor)
-    plan_state: Optional[PlanState] = None
-    _plan_callback: Optional[Callable] = None
-    
-    def __init__(self, plan_state: Optional[PlanState] = None, plan_callback: Optional[Callable] = None, **kwargs):
-        super().__init__(**kwargs)
-        self.plan_state = plan_state or PlanState()
-        self._plan_callback = plan_callback
-    
-    def _run(self, step_number: int) -> str:
-        """Mark a step as complete."""
-        if not self.plan_state.steps:
-            return "No plan exists. Use update_plan first to create a plan."
-        
-        if step_number < 1 or step_number > len(self.plan_state.steps):
-            return f"Invalid step number. Plan has {len(self.plan_state.steps)} steps (1-{len(self.plan_state.steps)})."
-        
-        step = self.plan_state.steps[step_number - 1]
-        if step.completed:
-            return f"Step {step_number} was already completed."
-        
-        step.completed = True
-        
-        # Auto-save to session
-        self.plan_state.save()
-        
-        # Notify callback if set (for UI rendering)
-        if self._plan_callback:
-            self._plan_callback(self.plan_state)
-        
-        # Count progress
-        completed = sum(1 for s in self.plan_state.steps if s.completed)
-        total = len(self.plan_state.steps)
-        
-        return f"✓ Step {step_number} completed ({completed}/{total} done)\n\n{self.plan_state.render()}"
-
+# ============================================================================
+# Planning Tools - Using Runtime PlanningToolkit
+# ============================================================================
 
 def get_planning_tools(
     plan_state: Optional[PlanState] = None,
@@ -370,34 +336,54 @@ def get_planning_tools(
     session_id: Optional[str] = None
 ) -> tuple[List[BaseTool], PlanState]:
     """
-    Get planning tools with shared state.
+    Get planning tools using the runtime PlanningToolkit.
+    
+    Uses the runtime PlanningToolkit which supports both PostgreSQL
+    and filesystem storage. For CLI, it uses filesystem storage with
+    session_id as the thread identifier.
     
     Args:
-        plan_state: Optional existing plan state to use
-        plan_callback: Optional callback function called when plan changes
-        session_id: Optional session ID for persistence. If provided and plan exists,
-                   will load from disk. If None, generates a new session ID.
+        plan_state: Optional existing plan state (for backwards compatibility)
+        plan_callback: Optional callback function called when plan changes (for CLI UI)
+        session_id: Optional session ID for persistence. If None, generates a new one.
         
     Returns:
         Tuple of (list of tools, plan state object)
     """
-    # Try to load existing session or create new one
-    if session_id:
-        loaded = PlanState.load(session_id)
-        if loaded:
-            state = loaded
-            logger.info(f"Resumed session {session_id} with plan: {state.title}")
-        else:
-            state = plan_state or PlanState()
-            state.session_id = session_id
-    else:
-        state = plan_state or PlanState()
-        if not state.session_id:
-            state.session_id = generate_session_id()
+    from alita_sdk.runtime.toolkits.planning import PlanningToolkit
+    from alita_sdk.runtime.tools.planning.wrapper import PlanState as RuntimePlanState
+    
+    # Generate session_id if not provided
+    if not session_id:
+        session_id = generate_session_id()
+    
+    # Create adapter callback that converts between PlanState types
+    def adapter_callback(runtime_plan: RuntimePlanState):
+        if plan_callback:
+            # Convert runtime PlanState to CLI PlanState for UI
+            cli_plan = PlanState(
+                title=runtime_plan.title,
+                steps=[PlanStep(description=s.description, completed=s.completed) for s in runtime_plan.steps],
+                session_id=session_id
+            )
+            plan_callback(cli_plan)
+    
+    # Create toolkit with filesystem storage (no pgvector_configuration)
+    # Use session_id as conversation_id so tools don't need it passed explicitly
+    toolkit = PlanningToolkit.get_toolkit(
+        toolkit_name=None,  # No prefix - tools are called directly
+        selected_tools=['update_plan', 'complete_step', 'get_plan_status', 'delete_plan'],
+        pgvector_configuration=None,  # Uses filesystem storage
+        storage_dir=str(get_sessions_dir() / session_id),  # Use session-specific directory
+        plan_callback=adapter_callback if plan_callback else None,
+        conversation_id=session_id  # Use session_id as conversation_id
+    )
+    
+    tools = toolkit.get_tools()
     
-    tools = [
-        UpdatePlanTool(plan_state=state, plan_callback=plan_callback),
-        CompleteStepTool(plan_state=state, plan_callback=plan_callback),
-    ]
+    # Create local state for return (for backward compatibility)
+    loaded = PlanState.load(session_id)
+    state = loaded if loaded else (plan_state or PlanState())
+    state.session_id = session_id
     
     return tools, state

alita_sdk/cli/tools/terminal.py

@@ -66,6 +66,10 @@ class TerminalRunCommandInput(BaseModel):
     """Input for running a terminal command."""
     command: str = Field(description="Shell command to execute")
     timeout: int = Field(default=300, description="Timeout in seconds (default: 300)")
+    directory: Optional[str] = Field(
+        default=None, 
+        description="Working directory to execute the command in. Must be from the allowed directories list. If not specified, uses the default workspace directory."
+    )
 
 
 class TerminalRunCommandTool(BaseTool):
@@ -75,7 +79,7 @@ class TerminalRunCommandTool(BaseTool):
     description: str = """Execute a shell command in the workspace directory.
     
 Use this to run tests, build commands, git operations, package managers, etc.
-Commands are executed in the mounted workspace directory.
+Commands are executed in the mounted workspace directory or a specified allowed directory.
 
 Examples:
 - Run tests: `npm test`, `pytest`, `go test ./...`
@@ -83,17 +87,28 @@ Examples:
 - Git: `git status`, `git diff`, `git log --oneline -10`
 - Package managers: `npm install`, `pip install -r requirements.txt`
 
-The command runs with the workspace as the current working directory.
-Returns stdout, stderr, and exit code."""
+The command runs with the workspace (or specified directory) as the current working directory.
+Returns stdout, stderr, and exit code.
+
+Use the 'directory' parameter to run commands in a specific allowed directory when working with multi-folder workspaces."""
     args_schema: type[BaseModel] = TerminalRunCommandInput
     
     work_dir: str = ""
+    allowed_directories: List[str] = []
     blocked_patterns: List[str] = []
     
-    def __init__(self, work_dir: str, blocked_patterns: Optional[List[str]] = None, **kwargs):
+    def __init__(self, work_dir: str, blocked_patterns: Optional[List[str]] = None, 
+                 allowed_directories: Optional[List[str]] = None, **kwargs):
         super().__init__(**kwargs)
         self.work_dir = str(Path(work_dir).resolve())
         self.blocked_patterns = blocked_patterns or DEFAULT_BLOCKED_PATTERNS
+        # Build allowed directories list: always include work_dir, plus any additional allowed dirs
+        self.allowed_directories = [self.work_dir]
+        if allowed_directories:
+            for d in allowed_directories:
+                resolved = str(Path(d).resolve())
+                if resolved not in self.allowed_directories:
+                    self.allowed_directories.append(resolved)
     
     def _is_command_blocked(self, command: str) -> tuple[bool, str]:
         """Check if command matches any blocked patterns."""
@@ -103,52 +118,110 @@ Returns stdout, stderr, and exit code."""
                 return True, pattern
         return False, ""
     
-    def _validate_paths_in_command(self, command: str) -> tuple[bool, str]:
+    def _validate_directory(self, directory: Optional[str]) -> tuple[bool, str, str]:
+        """
+        Validate that the requested directory is in the allowed list.
+        
+        Args:
+            directory: Requested directory path or None
+            
+        Returns:
+            Tuple of (is_valid, error_message, resolved_directory)
         """
-        Validate that any paths referenced in the command don't escape work_dir.
+        if directory is None:
+            return True, "", self.work_dir
+        
+        # Resolve the requested directory
+        try:
+            resolved = str(Path(directory).resolve())
+        except Exception as e:
+            return False, f"Invalid directory path: {e}", ""
+        
+        # Check if directory exists
+        if not Path(resolved).is_dir():
+            return False, f"Directory does not exist: {directory}", ""
+        
+        # Check if it's in the allowed list or is a subdirectory of an allowed directory
+        for allowed in self.allowed_directories:
+            if resolved == allowed or resolved.startswith(allowed + os.sep):
+                return True, "", resolved
+        
+        allowed_list = "\n  - ".join(self.allowed_directories)
+        return False, f"Directory not in allowed list: {directory}\n\nAllowed directories:\n  - {allowed_list}", ""
+    
+    def _validate_paths_in_command(self, command: str, target_dir: str) -> tuple[bool, str]:
+        """
+        Validate that any paths referenced in the command don't escape allowed directories.
         This is a best-effort check for obvious path traversal.
+        
+        Args:
+            command: The command to validate
+            target_dir: The target directory where command will be executed
         """
         # Check for obvious path traversal patterns
         if "../../../" in command or "/.." in command:
             return False, "Path traversal detected"
         
-        # Check for absolute paths outside work_dir
-        parts = shlex.split(command)
+        # Check for absolute paths outside allowed directories
+        try:
+            parts = shlex.split(command)
+        except ValueError:
+            # If we can't parse the command, skip path validation
+            parts = []
+            
         for part in parts:
-            if part.startswith("/") and not part.startswith(self.work_dir):
+            if part.startswith("/"):
                 # Allow common system paths that are safe to reference
                 safe_prefixes = ["/dev/null", "/tmp", "/usr/bin", "/usr/local/bin", "/bin"]
-                if not any(part.startswith(p) for p in safe_prefixes):
-                    return False, f"Absolute path outside workspace: {part}"
+                if any(part.startswith(p) for p in safe_prefixes):
+                    continue
+                # Check if it's within any allowed directory
+                is_allowed = False
+                for allowed in self.allowed_directories:
+                    if part.startswith(allowed) or part == allowed:
+                        is_allowed = True
+                        break
+                if not is_allowed:
+                    return False, f"Absolute path outside allowed directories: {part}"
         
         return True, ""
     
-    def _run(self, command: str, timeout: int = 300) -> str:
+    def _run(self, command: str, timeout: int = 300, directory: Optional[str] = None) -> str:
         """Execute the command and return results."""
+        # Validate the requested directory
+        dir_valid, dir_error, target_dir = self._validate_directory(directory)
+        if not dir_valid:
+            return f"❌ Directory validation failed: {dir_error}"
+        
         # Check if command is blocked
         is_blocked, pattern = self._is_command_blocked(command)
         if is_blocked:
             return f"❌ Command blocked for security reasons.\nMatched pattern: {pattern}\n\nThis command pattern is not allowed. Please use a safer alternative."
         
         # Validate paths in command
-        path_valid, path_error = self._validate_paths_in_command(command)
+        path_valid, path_error = self._validate_paths_in_command(command, target_dir)
         if not path_valid:
-            return f"❌ Command rejected: {path_error}\n\nCommands must operate within the workspace directory: {self.work_dir}"
+            allowed_list = ", ".join(self.allowed_directories)
+            return f"❌ Command rejected: {path_error}\n\nCommands must operate within allowed directories: {allowed_list}"
         
         try:
-            # Execute command in work_dir
+            # Execute command in target_dir
             result = subprocess.run(
                 command,
                 shell=True,
-                cwd=self.work_dir,
+                cwd=target_dir,
                 capture_output=True,
                 text=True,
                 timeout=timeout,
-                env={**os.environ, "PWD": self.work_dir}
+                env={**os.environ, "PWD": target_dir}
             )
             
             output_parts = []
             
+            # Show which directory the command was executed in if not default
+            if target_dir != self.work_dir:
+                output_parts.append(f"[Executed in: {target_dir}]")
+            
             if result.stdout:
                 output_parts.append(f"stdout:\n{result.stdout}")
             
@@ -157,12 +230,58 @@ Returns stdout, stderr, and exit code."""
             
             output_parts.append(f"exit_code: {result.returncode}")
             
+            # Add hint when search-like commands return empty results
+            if result.returncode == 0 and not result.stdout.strip():
+                if self._is_search_command(command):
+                    hint = self._generate_empty_search_hint(command, target_dir)
+                    output_parts.append(hint)
+            
             return "\n\n".join(output_parts)
             
         except subprocess.TimeoutExpired:
             return f"❌ Command timed out after {timeout} seconds.\n\nConsider:\n- Breaking into smaller operations\n- Using --timeout flag for longer operations\n- Running in background if appropriate"
         except Exception as e:
             return f"❌ Error executing command: {str(e)}"
+    
+    def _is_search_command(self, command: str) -> bool:
+        """Check if the command is a search/find operation."""
+        search_patterns = [
+            r'\bfind\b',
+            r'\bgrep\b',
+            r'\brg\b',  # ripgrep
+            r'\bag\b',  # silver searcher
+            r'\back\b',
+            r'\bfzf\b',
+            r'\blocate\b',
+            r'\bfd\b',  # fd-find
+            r'\bxargs\s+grep',
+        ]
+        command_lower = command.lower()
+        return any(re.search(pattern, command_lower) for pattern in search_patterns)
+    
+    def _generate_empty_search_hint(self, command: str, target_dir: str) -> str:
+        """Generate a helpful hint when a search command returns no results."""
+        hints = ["💡 **No results found.** Consider:"]
+        
+        # Check if searching in the right directory
+        if len(self.allowed_directories) > 1:
+            other_dirs = [d for d in self.allowed_directories if d != target_dir]
+            hints.append(f"  - **Wrong directory?** You searched in `{target_dir}`")
+            hints.append(f"    Other allowed directories: {', '.join(f'`{d}`' for d in other_dirs)}")
+        else:
+            hints.append(f"  - **Verify directory:** Currently searching in `{target_dir}`")
+        
+        # Suggest adjusting search criteria
+        hints.append("  - **Adjust search pattern:** Try broader terms, different casing, or partial matches")
+        hints.append("  - **Check file extensions:** Ensure you're searching the right file types")
+        
+        # Specific suggestions based on command patterns
+        if 'grep' in command.lower():
+            hints.append("  - **Grep tips:** Use `-i` for case-insensitive, `-r` for recursive, or try regex patterns")
+        if 'find' in command.lower() and '-name' in command:
+            hints.append("  - **Find tips:** Use wildcards like `*.py` or `-iname` for case-insensitive matching")
+        
+        return "\n".join(hints)
 
 
 def load_blocked_patterns(config_path: Optional[str] = None) -> List[str]:
@@ -195,14 +314,18 @@ def load_blocked_patterns(config_path: Optional[str] = None) -> List[str]:
 
 def get_terminal_tools(
     work_dir: str,
-    blocked_patterns_path: Optional[str] = None
+    blocked_patterns_path: Optional[str] = None,
+    allowed_directories: Optional[List[str]] = None
 ) -> List[BaseTool]:
     """
     Get terminal execution tools for the given working directory.
     
     Args:
-        work_dir: The workspace directory (must be absolute path)
+        work_dir: The default workspace directory (must be absolute path)
         blocked_patterns_path: Optional path to custom blocked_commands.txt
+        allowed_directories: Optional list of additional directories where commands can be executed.
+                           The work_dir is always included in the allowed list.
+                           This enables multi-folder workspace support.
         
     Returns:
         List of terminal tools
@@ -214,10 +337,21 @@ def get_terminal_tools(
     
     blocked_patterns = load_blocked_patterns(blocked_patterns_path)
     
+    # Validate and resolve allowed directories
+    validated_allowed_dirs = []
+    if allowed_directories:
+        for d in allowed_directories:
+            resolved = str(Path(d).resolve())
+            if Path(resolved).is_dir():
+                validated_allowed_dirs.append(resolved)
+            else:
+                logger.warning(f"Allowed directory does not exist, skipping: {d}")
+    
     return [
         TerminalRunCommandTool(
             work_dir=work_dir,
-            blocked_patterns=blocked_patterns
+            blocked_patterns=blocked_patterns,
+            allowed_directories=validated_allowed_dirs
         )
     ]