vibecore 0.2.0__py3-none-any.whl

vibecore/tools/shell/tools.py

@@ -0,0 +1,156 @@
+"""Shell and system tools for Vibecore agents."""
+
+from agents import RunContextWrapper, function_tool
+
+from vibecore.context import VibecoreContext
+
+from .executor import bash_executor, glob_files, grep_files, list_directory
+
+
+@function_tool
+async def bash(
+    ctx: RunContextWrapper[VibecoreContext],
+    command: str,
+    timeout: int | None = None,
+    description: str | None = None,
+) -> str:
+    """Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling
+    and security measures.
+
+    Before executing the command, please follow these steps:
+
+    1. Directory Verification:
+       - If the command will create new directories or files, first use the LS tool to verify the parent directory
+         exists and is the correct location
+       - For example, before running "mkdir foo/bar", first use LS to check that "foo" exists and is the intended
+         parent directory
+
+    2. Command Execution:
+       - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
+       - Examples of proper quoting:
+         - cd "/Users/name/My Documents" (correct)
+         - cd /Users/name/My Documents (incorrect - will fail)
+         - python "/path/with spaces/script.py" (correct)
+         - python /path/with spaces/script.py (incorrect - will fail)
+       - After ensuring proper quoting, execute the command.
+       - Capture the output of the command.
+
+    Usage notes:
+      - The command argument is required.
+      - You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands
+        will timeout after 120000ms (2 minutes).
+      - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.
+      - If the output exceeds 30000 characters, output will be truncated before being returned to you.
+      - VERY IMPORTANT: You MUST avoid using search commands like `find` and `grep`. Instead use Grep, Glob, or Task
+        to search. You MUST avoid read tools like `cat`, `head`, `tail`, and `ls`, and use Read and LS to read files.
+      - If you _still_ need to run `grep`, STOP. ALWAYS USE ripgrep at `rg` first, which all users have pre-installed.
+      - When issuing multiple commands, use the ';' or '&&' operator to separate them. DO NOT use newlines (newlines
+        are ok in quoted strings).
+      - Try to maintain your current working directory throughout the session by using absolute paths and avoiding
+        usage of `cd`. You may use `cd` if the User explicitly requests it.
+
+    Args:
+        ctx: The run context wrapper
+        command: The command to execute
+        timeout: Optional timeout in milliseconds (max 600000)
+        description: Clear, concise description of what this command does in 5-10 words
+
+    Returns:
+        The command output or error message
+    """
+    output, exit_code = await bash_executor(command, timeout)
+    if exit_code != 0:
+        return f"{output}\nExit code: {exit_code}"
+    return output
+
+
+@function_tool
+async def glob(
+    ctx: RunContextWrapper[VibecoreContext],
+    pattern: str,
+    path: str | None = None,
+) -> str:
+    """Fast file pattern matching tool that works with any codebase size.
+
+    - Supports glob patterns like "**/*.js" or "src/**/*.ts"
+    - Returns matching file paths sorted by modification time
+    - Use this tool when you need to find files by name patterns
+    - When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the
+      Agent tool instead
+    - You have the capability to call multiple tools in a single response. It is always better to speculatively
+      perform multiple searches as a batch that are potentially useful.
+
+    Args:
+        ctx: The run context wrapper
+        pattern: The glob pattern to match files against
+        path: The directory to search in. If not specified, the current working directory will be used.
+              IMPORTANT: Omit this field to use the default directory. DO NOT enter "undefined" or "null" -
+              simply omit it for the default behavior. Must be a valid directory path if provided.
+
+    Returns:
+        List of matching file paths, one per line
+    """
+    files = await glob_files(pattern, path)
+    if files and files[0].startswith("Error:"):
+        return files[0]
+    return "\n".join(files) if files else "No files found matching pattern"
+
+
+@function_tool
+async def grep(
+    ctx: RunContextWrapper[VibecoreContext],
+    pattern: str,
+    path: str | None = None,
+    include: str | None = None,
+) -> str:
+    """Fast content search tool that works with any codebase size.
+
+    - Searches file contents using regular expressions
+    - Supports full regex syntax (eg. "log.*Error", "function\\s+\\w+", etc.)
+    - Filter files by pattern with the include parameter (eg. "*.js", "*.{ts,tsx}")
+    - Returns file paths with at least one match sorted by modification time
+    - Use this tool when you need to find files containing specific patterns
+    - If you need to identify/count the number of matches within files, use the Bash tool with `rg` (ripgrep)
+      directly. Do NOT use `grep`.
+    - When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the
+      Agent tool instead
+
+    Args:
+        ctx: The run context wrapper
+        pattern: The regular expression pattern to search for in file contents
+        path: The directory to search in. Defaults to the current working directory.
+        include: File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")
+
+    Returns:
+        List of file paths containing matches, one per line
+    """
+    files = await grep_files(pattern, path, include)
+    if files and files[0].startswith("Error:"):
+        return files[0]
+    return "\n".join(files) if files else "No files found containing pattern"
+
+
+@function_tool
+async def ls(
+    ctx: RunContextWrapper[VibecoreContext],
+    path: str,
+    ignore: list[str] | None = None,
+) -> str:
+    """Lists files and directories in a given path.
+
+    The path parameter must be an absolute path, not a relative path. You can optionally provide an array of glob
+    patterns to ignore with the ignore parameter. You should generally prefer the Glob and Grep tools, if you know
+    which directories to search.
+
+    Args:
+        ctx: The run context wrapper
+        path: The absolute path to the directory to list (must be absolute, not relative)
+        ignore: List of glob patterns to ignore
+
+    Returns:
+        List of entries in the directory, one per line
+    """
+    entries = await list_directory(path, ignore)
+    if entries and entries[0].startswith("Error:"):
+        return entries[0]
+    return "\n".join(entries) if entries else "Empty directory"

vibecore/tools/task/__init__.py

@@ -0,0 +1,5 @@
+"""Task tool for spawning sub-agents to execute specific tasks."""
+
+from .tools import task
+
+__all__ = ["task"]

vibecore/tools/task/executor.py

@@ -0,0 +1,51 @@
+"""Task execution logic for spawning sub-agents."""
+
+import traceback
+
+from agents import (
+    Runner,
+)
+from textual import log
+
+from vibecore.agents.task_agent import create_task_agent
+from vibecore.context import VibecoreContext
+from vibecore.settings import settings
+
+
+async def execute_task(
+    context: VibecoreContext,
+    description: str,
+    prompt: str,
+    tool_name: str,
+    tool_call_id: str,
+) -> str:
+    """Execute a task using a sub-agent with streaming support.
+
+    Args:
+        context: The vibecore context to pass to the task agent
+        description: Short task description (for logging/display)
+        prompt: Full task instructions
+        tool_name: Name of the tool being invoked (e.g., "task")
+        tool_call_id: Unique identifier for this tool call
+
+    Returns:
+        Task execution results as a string with formatted sub-agent activity
+    """
+    try:
+        # Create the task agent
+        task_agent = create_task_agent(prompt)
+
+        # Run the task agent with streaming
+        result = Runner.run_streamed(task_agent, prompt, context=context, max_turns=settings.max_turns)
+
+        # Check if app is available for streaming
+        if context.app:
+            # Stream events to app handler
+            async for event in result.stream_events():
+                await context.app.handle_task_tool_event(tool_name, tool_call_id, event)
+
+        return result.final_output
+
+    except Exception as e:
+        log.error(f"Task execution error: {type(e).__name__}: {e!s}\n%s", traceback.format_exc())
+        return f"Task '{description}' failed with error: {e!s}"

vibecore/tools/task/tools.py

@@ -0,0 +1,51 @@
+"""Task tool for spawning sub-agents to execute specific tasks."""
+
+from agents import function_tool
+from agents.tool_context import ToolContext
+
+from vibecore.context import VibecoreContext
+
+from .executor import execute_task
+
+
+@function_tool
+async def task(
+    ctx: ToolContext[VibecoreContext],
+    description: str,
+    prompt: str,
+) -> str:
+    """Launch a new agent to execute a specific task with access to all tools except the Task tool itself.
+
+    The task agent has access to: bash, glob, grep, ls, read, edit, multi_edit, write, execute_python,
+    todo_read, and todo_write. Use this tool when you need to delegate complex, multi-step operations
+    or searches to a sub-agent.
+
+    When to use the Task tool:
+    - When searching for a keyword like "config" or "logger" across many files
+    - For questions like "which file does X?" where you're not sure of the location
+    - When you need to perform complex multi-step operations autonomously
+    - When the task requires extensive file exploration or analysis
+
+    When NOT to use the Task tool:
+    - If you want to read a specific file path (use Read instead)
+    - If searching for a specific class definition like "class Foo" (use Grep instead)
+    - If searching within a specific file or set of 2-3 files (use Read instead)
+    - For simple, single-step operations (use the appropriate tool directly)
+
+    Usage notes:
+    1. Launch multiple tasks concurrently when possible by using multiple tool calls
+    2. The task agent returns a single final message - you should summarize results for the user
+    3. Each task invocation is stateless - provide complete instructions in the prompt
+    4. Clearly specify whether the agent should write code or just research/analyze
+    5. The agent is not aware of the user's original request - be explicit in instructions
+
+    Args:
+        ctx: The run context wrapper
+        description: A short task description (3-5 words)
+        prompt: Full task instructions for the agent - be highly detailed and specify
+                exactly what information should be returned
+
+    Returns:
+        The task execution results as a string
+    """
+    return await execute_task(ctx.context, description, prompt, ctx.tool_name, ctx.tool_call_id)

vibecore/tools/todo/__init__.py

@@ -0,0 +1 @@
+"""Todo management tools."""

vibecore/tools/todo/manager.py

@@ -0,0 +1,31 @@
+"""Todo list manager."""
+
+from typing import Any
+
+from .models import TodoItem, TodoPriority, TodoStatus
+
+
+class TodoManager:
+    """Manages a session-scoped todo list."""
+
+    def __init__(self):
+        self.todos: list[TodoItem] = []
+
+    def read(self) -> list[dict[str, Any]]:
+        """Read all todos."""
+        return [
+            {"id": todo.id, "content": todo.content, "status": todo.status.value, "priority": todo.priority.value}
+            for todo in self.todos
+        ]
+
+    def write(self, todos: list[dict[str, Any]]) -> None:
+        """Replace the entire todo list."""
+        self.todos = [
+            TodoItem(
+                id=todo["id"],
+                content=todo["content"],
+                status=TodoStatus(todo["status"]),
+                priority=TodoPriority(todo["priority"]),
+            )
+            for todo in todos
+        ]

vibecore/tools/todo/models.py

@@ -0,0 +1,36 @@
+"""Todo data models."""
+
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class TodoStatus(str, Enum):
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+
+
+class TodoPriority(str, Enum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class TodoItem:
+    content: str
+    status: TodoStatus
+    priority: TodoPriority
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+
+
+class TodoItemModel(BaseModel):
+    """Pydantic model for todo items."""
+
+    id: str
+    content: str
+    status: str
+    priority: str

vibecore/tools/todo/tools.py

@@ -0,0 +1,111 @@
+"""Todo management tools."""
+
+from typing import Any
+
+from agents import RunContextWrapper, function_tool
+
+from vibecore.context import VibecoreContext
+
+from .models import TodoItemModel
+
+
+@function_tool
+async def todo_read(ctx: RunContextWrapper[VibecoreContext]) -> list[dict[str, Any]]:
+    """Use this tool to read the current to-do list for the session. This tool should be used proactively and
+    frequently to ensure that you are aware of the status of the current task list. You should make use of this
+    tool as often as possible, especially in the following situations:
+    - At the beginning of conversations to see what's pending
+    - Before starting new tasks to prioritize work
+    - When the user asks about previous tasks or plans
+    - Whenever you're uncertain about what to do next
+    - After completing tasks to update your understanding of remaining work
+    - After every few messages to ensure you're on track
+
+    Usage:
+    - This tool takes in no parameters. So leave the input blank or empty. DO NOT include a dummy object,
+      placeholder string or a key like "input" or "empty". LEAVE IT BLANK.
+    - Returns a list of todo items with their status, priority, and content
+    - Use this information to track progress and plan next steps
+    - If no todos exist yet, an empty list will be returned
+
+        Args:
+            ctx: The run context wrapper containing the todo manager.
+
+        Returns:
+            A list of todo items with their status, priority, and content.
+    """
+    return ctx.context.todo_manager.read()
+
+
+@function_tool
+async def todo_write(ctx: RunContextWrapper[VibecoreContext], todos: list[TodoItemModel]) -> str:
+    """Use this tool to create and manage a structured task list for your current coding session. This helps you
+    track progress, organize complex tasks, and demonstrate thoroughness to the user. It also helps the user
+    understand the progress of the task and overall progress of their requests.
+
+    ## When to Use This Tool
+    Use this tool proactively in these scenarios:
+
+    1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+    2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+    3. User explicitly requests todo list - When the user directly asks you to use the todo list
+    4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+    5. After receiving new instructions - Immediately capture user requirements as todos
+    6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only
+       have one todo as in_progress at a time
+    7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+    ## When NOT to Use This Tool
+
+    Skip using this tool when:
+    1. There is only a single, straightforward task
+    2. The task is trivial and tracking it provides no organizational benefit
+    3. The task can be completed in less than 3 trivial steps
+    4. The task is purely conversational or informational
+
+    NOTE that you should not use this tool if there is only one trivial task to do. In this case you are
+    better off just doing the task directly.
+
+    ## Task States and Management
+
+    1. **Task States**: Use these states to track progress:
+       - pending: Task not yet started
+       - in_progress: Currently working on (limit to ONE task at a time)
+       - completed: Task finished successfully
+
+    2. **Task Management**:
+       - Update task status in real-time as you work
+       - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+       - Only have ONE task in_progress at any time
+       - Complete current tasks before starting new ones
+       - Remove tasks that are no longer relevant from the list entirely
+
+    3. **Task Completion Requirements**:
+       - ONLY mark a task as completed when you have FULLY accomplished it
+       - If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+       - When blocked, create a new task describing what needs to be resolved
+       - Never mark a task as completed if:
+         - Tests are failing
+         - Implementation is partial
+         - You encountered unresolved errors
+         - You couldn't find necessary files or dependencies
+
+    4. **Task Breakdown**:
+       - Create specific, actionable items
+       - Break complex tasks into smaller, manageable steps
+       - Use clear, descriptive task names
+
+    When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures
+    you complete all requirements successfully.
+
+        Args:
+            ctx: The run context wrapper containing the todo manager.
+            todos: The updated todo list.
+
+        Returns:
+            Success message.
+    """
+    # Convert Pydantic models to dicts for the implementation
+    todos_dict = [todo.model_dump() for todo in todos]
+    ctx.context.todo_manager.write(todos_dict)
+    return "Todo list updated successfully."

vibecore/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility modules for vibecore."""
+
+from vibecore.utils.text import TextExtractor
+
+__all__ = ["TextExtractor"]

vibecore/utils/text.py

@@ -0,0 +1,28 @@
+"""Text extraction utilities for vibecore."""
+
+from openai.types.responses.response_output_message import Content
+from openai.types.responses.response_output_refusal import ResponseOutputRefusal
+from openai.types.responses.response_output_text import ResponseOutputText
+
+
+class TextExtractor:
+    """Utility class for extracting text from various content formats."""
+
+    @staticmethod
+    def extract_from_content(content: list[Content]) -> str:
+        """Extract text from various content formats.
+
+        Args:
+            content: List of content items from OpenAI response
+
+        Returns:
+            Concatenated text from all text content items
+        """
+        text_parts = []
+        for item in content:
+            match item:
+                case ResponseOutputText(text=text):
+                    text_parts.append(text)
+                case ResponseOutputRefusal(refusal=text):
+                    text_parts.append(text)
+        return "".join(text_parts)