vibecore 0.2.0__py3-none-any.whl → 0.3.0b1__py3-none-any.whl

vibecore/agents/default.py

@@ -1,8 +1,7 @@
 from typing import TYPE_CHECKING
 
-from agents import Agent, ModelSettings
+from agents import Agent
 from agents.extensions.handoff_prompt import prompt_with_handoff_instructions
-from openai.types import Reasoning
 
 from vibecore.context import VibecoreContext
 from vibecore.settings import settings
@@ -11,6 +10,8 @@ from vibecore.tools.python.tools import execute_python
 from vibecore.tools.shell.tools import bash, glob, grep, ls
 from vibecore.tools.task.tools import task
 from vibecore.tools.todo.tools import todo_read, todo_write
+from vibecore.tools.webfetch.tools import webfetch
+from vibecore.tools.websearch.tools import websearch
 
 from .prompts import COMMON_PROMPT
 
@@ -50,26 +51,20 @@ def create_default_agent(mcp_servers: list["MCPServer"] | None = None) -> Agent[
         grep,
         ls,
         task,
+        websearch,
+        webfetch,
     ]
     instructions = INSTRUCTIONS
 
     instructions = prompt_with_handoff_instructions(instructions)
 
-    # Configure reasoning based on settings
-    reasoning_config = Reasoning(summary="auto")
-    if settings.reasoning_effort is not None:
-        reasoning_config = Reasoning(effort=settings.reasoning_effort, summary="auto")
-
     return Agent[VibecoreContext](
         name="Vibecore Agent",
         handoff_description="A versatile general-purpose assistant",
         instructions=instructions,
         tools=tools,
         model=settings.model,
-        model_settings=ModelSettings(
-            include_usage=True,  # Ensure token usage is tracked in streaming mode
-            reasoning=reasoning_config,
-        ),
+        model_settings=settings.default_model_settings,
         handoffs=[],
         mcp_servers=mcp_servers or [],
     )

vibecore/agents/{task_agent.py → task.py}

@@ -1,8 +1,7 @@
 """Task-specific agent configuration for executing delegated tasks."""
 
-from agents import Agent, ModelSettings
+from agents import Agent
 from agents.extensions.handoff_prompt import prompt_with_handoff_instructions
-from openai.types import Reasoning
 
 from vibecore.context import VibecoreContext
 from vibecore.settings import settings
@@ -58,9 +57,6 @@ def create_task_agent(prompt: str) -> Agent[VibecoreContext]:
         instructions=instructions,
         tools=tools,
         model=settings.model,
-        model_settings=ModelSettings(
-            include_usage=True,  # Ensure token usage is tracked in streaming mode
-            reasoning=Reasoning(summary="auto"),
-        ),
+        model_settings=settings.default_model_settings,
         handoffs=[],
     )

vibecore/flow.py

@@ -0,0 +1,105 @@
+import asyncio
+import threading
+from collections.abc import Callable, Coroutine
+from typing import Protocol
+
+from agents import Agent
+from textual.pilot import Pilot
+
+from vibecore.context import VibecoreContext
+from vibecore.main import AppIsExiting, VibecoreApp
+from vibecore.widgets.core import MyTextArea
+from vibecore.widgets.messages import SystemMessage
+
+
+class UserInputFunc(Protocol):
+    """Protocol for user input function with optional prompt parameter."""
+
+    async def __call__(self, prompt: str = "") -> str:
+        """Get user input with optional prompt message.
+
+        Args:
+            prompt: Optional prompt to display before getting input.
+
+        Returns:
+            The user's input string.
+        """
+        ...
+
+
+async def flow(
+    agent: Agent,
+    logic: Callable[[VibecoreApp, VibecoreContext, UserInputFunc], Coroutine],
+    headless: bool = False,
+    shutdown: bool = False,
+    disable_user_input: bool = True,
+):
+    ctx = VibecoreContext()
+    app = VibecoreApp(ctx, agent, show_welcome=False)
+
+    app_ready_event = asyncio.Event()
+
+    def on_app_ready() -> None:
+        """Called when app is ready to process events."""
+        app_ready_event.set()
+
+    async def run_app(app: VibecoreApp) -> None:
+        """Run the apps message loop.
+
+        Args:
+            app: App to run.
+        """
+
+        with app._context():
+            try:
+                app._loop = asyncio.get_running_loop()
+                app._thread_id = threading.get_ident()
+                await app._process_messages(
+                    ready_callback=on_app_ready,
+                    headless=headless,
+                )
+            finally:
+                app_ready_event.set()
+
+    async def user_input(prompt: str = "") -> str:
+        if prompt:
+            await app.add_message(SystemMessage(prompt))
+        app.query_one(MyTextArea).disabled = False
+        app.query_one(MyTextArea).focus()
+        user_input = await app.wait_for_user_input()
+        if disable_user_input:
+            app.query_one(MyTextArea).disabled = True
+        return user_input
+
+    async def run_logic(app: VibecoreApp, ctx: VibecoreContext, user_input: UserInputFunc) -> None:
+        try:
+            await logic(app, ctx, user_input)
+        except AppIsExiting:
+            return
+
+    app_task = asyncio.create_task(run_app(app), name=f"with_app({app})")
+    await app_ready_event.wait()
+    pilot = Pilot(app)
+    logic_task: asyncio.Task | None = None
+
+    await pilot._wait_for_screen()
+    if disable_user_input:
+        app.query_one(MyTextArea).disabled = True
+    logic_task = asyncio.create_task(run_logic(app, ctx, user_input), name="logic_task")
+    done, pending = await asyncio.wait([logic_task, app_task], return_when=asyncio.FIRST_COMPLETED)
+
+    # If app has exited and logic is still running, cancel logic
+    if app_task in done and logic_task in pending:
+        logic_task.cancel()
+    # If logic is finished and app is still running
+    elif logic_task in done and app_task in pending:
+        if shutdown:
+            if not headless:
+                await pilot._wait_for_screen()
+                await asyncio.sleep(1.0)
+            app.exit()
+        else:
+            # Enable text input so users can interact freely
+            app.query_one(MyTextArea).disabled = False
+            # Wait until app is exited
+            await app_task

vibecore/main.py

@@ -30,7 +30,11 @@ from vibecore.widgets.core import AppFooter, MainScroll, MyTextArea
 from vibecore.widgets.info import Welcome
 from vibecore.widgets.messages import AgentMessage, BaseMessage, MessageStatus, SystemMessage, UserMessage
 
-AgentStatus = Literal["idle", "running"]
+AgentStatus = Literal["idle", "running", "waiting_user_input"]
+
+
+class AppIsExiting(Exception):
+    pass
 
 
 def detect_reasoning_effort(prompt: str) -> Literal["low", "medium", "high"] | None:
@@ -82,6 +86,7 @@ class VibecoreApp(App):
         agent: Agent,
         session_id: str | None = None,
         print_mode: bool = False,
+        show_welcome: bool = True,
     ) -> None:
         """Initialize the Vibecore app with context and agent.
 
@@ -90,6 +95,7 @@ class VibecoreApp(App):
             agent: The Agent instance to use
             session_id: Optional session ID to load existing session
             print_mode: Whether to run in print mode (useful for pipes)
+            show_welcome: Whether to show the welcome message (default: True)
         """
         self.context = context
         self.context.app = self  # Set the app reference in context
@@ -99,6 +105,7 @@ class VibecoreApp(App):
         self.current_worker: Worker[None] | None = None
         self._session_id_provided = session_id is not None  # Track if continuing session
         self.print_mode = print_mode
+        self.show_welcome = show_welcome
         self.message_queue: deque[str] = deque()  # Queue for user messages
 
         # Initialize session based on settings
@@ -124,7 +131,8 @@ class VibecoreApp(App):
         yield Header()
         yield AppFooter()
         with MainScroll(id="messages"):
-            yield Welcome()
+            if self.show_welcome:
+                yield Welcome()
 
     async def on_mount(self) -> None:
         """Called when the app is mounted."""
@@ -162,6 +170,8 @@ class VibecoreApp(App):
         Args:
             message: The message to add
         """
+        if not self.is_running:
+            raise AppIsExiting("App is not running")
         main_scroll = self.query_one("#messages", MainScroll)
         await main_scroll.mount(message)
 
@@ -225,6 +235,14 @@ class VibecoreApp(App):
         else:
             footer.hide_loading()
 
+    async def wait_for_user_input(self) -> str:
+        """Used in flow mode. See examples/basic_agent.py"""
+        self.agent_status = "waiting_user_input"
+        self.user_input_event = asyncio.Event()
+        await self.user_input_event.wait()
+        user_input = self.message_queue.pop()
+        return user_input
+
     async def on_my_text_area_user_message(self, event: MyTextArea.UserMessage) -> None:
         """Handle user messages from the text area."""
         if event.text:
@@ -248,8 +266,11 @@ class VibecoreApp(App):
             await self.add_message(user_message)
             user_message.scroll_visible()
 
-            # If agent is running, queue the message
+            if self.agent_status == "waiting_user_input":
+                self.message_queue.append(event.text)
+                self.user_input_event.set()
             if self.agent_status == "running":
+                # If agent is running, queue the message
                 self.message_queue.append(event.text)
                 log(f"Message queued: {event.text}")
                 footer = self.query_one(AppFooter)
@@ -268,7 +289,7 @@ class VibecoreApp(App):
                 if reasoning_effort is not None:
                     # Create a copy of the agent with updated model settings
                     current_settings = self.agent.model_settings or ModelSettings()
-                    new_reasoning = Reasoning(effort=reasoning_effort, summary="auto")
+                    new_reasoning = Reasoning(effort=reasoning_effort, summary=settings.reasoning_summary)
                     updated_settings = ModelSettings(
                         include_usage=current_settings.include_usage,
                         reasoning=new_reasoning,
@@ -496,8 +517,9 @@ class VibecoreApp(App):
         for welcome in main_scroll.query("Welcome"):
             welcome.remove()
 
-        # Add welcome widget back
-        await main_scroll.mount(Welcome())
+        # Add welcome widget back if show_welcome is True
+        if self.show_welcome:
+            await main_scroll.mount(Welcome())
 
         # Show system message to confirm the clear operation
         system_message = SystemMessage(f"✨ Session cleared! Started new session: {new_session_id}")

vibecore/settings.py

@@ -4,9 +4,10 @@ import os
 from pathlib import Path
 from typing import Literal
 
-from agents import Model, OpenAIChatCompletionsModel
+from agents import Model, ModelSettings, OpenAIChatCompletionsModel
 from agents.models.multi_provider import MultiProvider
-from pydantic import BaseModel, Field
+from openai.types import Reasoning
+from pydantic import BaseModel, Field, field_validator
 from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict, YamlConfigSettingsSource
 
 from vibecore.models import AnthropicModel
@@ -92,9 +93,10 @@ class Settings(BaseSettings):
     default_model: str = Field(
         # default="o3",
         # default="gpt-4.1",
+        default="gpt-5",
         # default="qwen3-30b-a3b-mlx@8bit",
         # default="mistralai/devstral-small-2507",
-        default="anthropic/claude-sonnet-4-20250514",
+        # default="anthropic/claude-sonnet-4-20250514",
         # default="anthropic/claude-3-5-haiku-20241022",
         # default="litellm/deepseek/deepseek-chat",
         description="Default model to use for agents (e.g., 'gpt-4.1', 'o3-mini', 'anthropic/claude-sonnet-4')",
@@ -109,6 +111,18 @@ class Settings(BaseSettings):
         default=None,
         description="Default reasoning effort level for agents (null, 'minimal', 'low', 'medium', 'high')",
     )
+    reasoning_summary: Literal["auto", "concise", "detailed"] | None = Field(
+        default="auto",
+        description="Reasoning summary mode ('auto', 'concise', 'detailed', or 'off')",
+    )
+
+    @field_validator("reasoning_summary", mode="before")
+    @classmethod
+    def validate_reasoning_summary(cls, v):
+        """Convert string 'null' to None for reasoning_summary field."""
+        if v == "off" or v == "":
+            return None
+        return v
 
     # Session configuration
     session: SessionSettings = Field(
@@ -138,6 +152,17 @@ class Settings(BaseSettings):
             return OpenAIChatCompletionsModel(self.default_model, openai_provider._get_client())
         return self.default_model
 
+    @property
+    def default_model_settings(self) -> ModelSettings:
+        """Get the default model settings."""
+        return ModelSettings(
+            include_usage=True,
+            reasoning=Reasoning(
+                summary=self.reasoning_summary,
+                effort=self.reasoning_effort,
+            ),
+        )
+
     @classmethod
     def settings_customise_sources(
         cls,

vibecore/tools/task/executor.py

@@ -7,7 +7,7 @@ from agents import (
 )
 from textual import log
 
-from vibecore.agents.task_agent import create_task_agent
+from vibecore.agents.task import create_task_agent
 from vibecore.context import VibecoreContext
 from vibecore.settings import settings
 

vibecore/tools/webfetch/__init__.py

@@ -0,0 +1,7 @@
+"""Webfetch tool for fetching and converting web content to Markdown."""
+
+from .executor import fetch_url
+from .models import WebFetchParams
+from .tools import webfetch
+
+__all__ = ["WebFetchParams", "fetch_url", "webfetch"]

vibecore/tools/webfetch/executor.py

@@ -0,0 +1,127 @@
+"""Webfetch execution logic for fetching and converting web content."""
+
+import json
+from urllib.parse import urlparse
+
+import html2text
+import httpx
+
+from .models import WebFetchParams
+
+
+async def fetch_url(params: WebFetchParams) -> str:
+    """Fetch a URL and convert its content to Markdown.
+
+    Args:
+        params: WebFetch parameters including URL and options
+
+    Returns:
+        Markdown-formatted content or error message
+    """
+    try:
+        # Validate URL
+        parsed = urlparse(params.url)
+        if not parsed.scheme:
+            return f"Error: Invalid URL - missing scheme (http:// or https://): {params.url}"
+        if not parsed.netloc:
+            return f"Error: Invalid URL - missing domain: {params.url}"
+        if parsed.scheme not in ["http", "https"]:
+            return f"Error: Unsupported URL scheme: {parsed.scheme}"
+
+        # Configure headers
+        headers = {
+            "User-Agent": params.user_agent
+            or "Mozilla/5.0 (compatible; Vibecore/1.0; +https://github.com/serialx/vibecore)",
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,"
+            "text/plain;q=0.8,application/json;q=0.7,*/*;q=0.5",
+            "Accept-Language": "en-US,en;q=0.9",
+            "Accept-Encoding": "gzip, deflate",
+        }
+
+        # Fetch the URL
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(params.timeout),
+            follow_redirects=params.follow_redirects,
+        ) as client:
+            response = await client.get(params.url, headers=headers)
+            response.raise_for_status()
+
+            # Get content type
+            content_type = response.headers.get("content-type", "").lower()
+
+            # Handle different content types
+            if "application/json" in content_type:
+                # Pretty-print JSON as Markdown code block
+                try:
+                    json_data = response.json()
+                    content = f"```json\n{json.dumps(json_data, indent=2)}\n```"
+                except json.JSONDecodeError:
+                    content = response.text[: params.max_length]
+
+            elif "text/html" in content_type or "application/xhtml" in content_type:
+                # Convert HTML to Markdown
+                html_content = response.text[: params.max_length]
+
+                # Configure html2text
+                h = html2text.HTML2Text()
+                h.ignore_links = False
+                h.ignore_images = False
+                h.ignore_emphasis = False
+                h.body_width = 0  # Don't wrap lines
+                h.skip_internal_links = False
+                h.inline_links = True
+                h.wrap_links = False
+                h.wrap_list_items = False
+                h.ul_item_mark = "-"
+                h.emphasis_mark = "*"
+                h.strong_mark = "**"
+
+                content = h.handle(html_content)
+
+                # Clean up excessive newlines
+                while "\n\n\n" in content:
+                    content = content.replace("\n\n\n", "\n\n")
+                content = content.strip()
+
+            elif "text/plain" in content_type or "text/" in content_type:
+                # Plain text - return as is
+                content = response.text[: params.max_length]
+
+            else:
+                # Unknown content type - try to handle as text
+                content = response.text[: params.max_length]
+                if not content:
+                    return f"Error: Unable to extract text content from {content_type}"
+
+            # Add metadata
+            metadata = [
+                f"# Content from {params.url}",
+                f"**Status Code:** {response.status_code}",
+                f"**Content Type:** {content_type.split(';')[0] if content_type else 'unknown'}",
+            ]
+
+            # Add redirect info if applicable
+            if response.history:
+                metadata.append(f"**Redirected:** {len(response.history)} time(s)")
+                metadata.append(f"**Final URL:** {response.url}")
+
+            metadata.append("")  # Empty line before content
+
+            # Check if content was truncated
+            if len(response.text) > params.max_length:
+                metadata.append(f"*Note: Content truncated to {params.max_length} characters*")
+                metadata.append("")
+
+            # Combine metadata and content
+            full_content = "\n".join(metadata) + "\n" + content
+
+            return full_content
+
+    except httpx.TimeoutException:
+        return f"Error: Request timed out after {params.timeout} seconds"
+    except httpx.HTTPStatusError as e:
+        return f"Error: HTTP {e.response.status_code} - {e.response.reason_phrase}"
+    except httpx.RequestError as e:
+        return f"Error: Failed to connect to {params.url}: {e!s}"
+    except Exception as e:
+        return f"Error: Unexpected error while fetching {params.url}: {e!s}"

vibecore/tools/webfetch/models.py

@@ -0,0 +1,22 @@
+"""Data models for the webfetch tool."""
+
+from pydantic import BaseModel, Field
+
+
+class WebFetchParams(BaseModel):
+    """Parameters for fetching web content."""
+
+    url: str = Field(description="The URL to fetch content from")
+    timeout: int = Field(default=30, description="Request timeout in seconds")
+    user_agent: str | None = Field(
+        default=None,
+        description="Optional custom User-Agent header",
+    )
+    follow_redirects: bool = Field(
+        default=True,
+        description="Whether to follow HTTP redirects",
+    )
+    max_length: int = Field(
+        default=1000000,  # ~1MB of text
+        description="Maximum content length to fetch in characters",
+    )

vibecore/tools/webfetch/tools.py

@@ -0,0 +1,46 @@
+"""Webfetch tool for Vibecore agents."""
+
+from agents import RunContextWrapper, function_tool
+
+from vibecore.context import VibecoreContext
+
+from .executor import fetch_url
+from .models import WebFetchParams
+
+
+@function_tool
+async def webfetch(
+    ctx: RunContextWrapper[VibecoreContext],
+    url: str,
+    timeout: int = 30,
+    follow_redirects: bool = True,
+) -> str:
+    """Fetch content from a URL and convert it to Markdown format.
+
+    This tool fetches web content and converts it to clean, readable Markdown.
+    It handles HTML pages, JSON APIs, and plain text content appropriately.
+
+    Args:
+        ctx: The run context wrapper
+        url: The URL to fetch content from (must include http:// or https://)
+        timeout: Request timeout in seconds (default: 30)
+        follow_redirects: Whether to follow HTTP redirects (default: True)
+
+    Returns:
+        Markdown-formatted content from the URL, including metadata about the
+        request (status code, content type, etc.) or an error message if the
+        fetch fails.
+
+    Examples:
+        - Fetch a webpage: url="https://example.com"
+        - Fetch JSON API: url="https://api.example.com/data"
+        - Fetch with timeout: url="https://slow-site.com", timeout=60
+        - Don't follow redirects: url="https://short.link/abc", follow_redirects=False
+    """
+    params = WebFetchParams(
+        url=url,
+        timeout=timeout,
+        follow_redirects=follow_redirects,
+    )
+
+    return await fetch_url(params)

vibecore/tools/websearch/__init__.py

@@ -0,0 +1,5 @@
+"""Websearch tool for Vibecore agents."""
+
+from .tools import websearch
+
+__all__ = ["websearch"]

vibecore/tools/websearch/base.py

@@ -0,0 +1,27 @@
+"""Base classes for websearch backends."""
+
+from abc import ABC, abstractmethod
+
+from .models import SearchParams
+
+
+class WebSearchBackend(ABC):
+    """Abstract base class for web search backends."""
+
+    @abstractmethod
+    async def search(self, params: SearchParams) -> str:
+        """Perform a web search.
+
+        Args:
+            params: Search parameters
+
+        Returns:
+            JSON string containing search results or error message
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the name of this backend."""
+        pass

vibecore/tools/websearch/ddgs/__init__.py

@@ -0,0 +1,5 @@
+"""DuckDuckGo search backend for websearch tool."""
+
+from .backend import DDGSBackend
+
+__all__ = ["DDGSBackend"]

vibecore/tools/websearch/ddgs/backend.py

@@ -0,0 +1,64 @@
+"""DuckDuckGo search backend implementation."""
+
+import json
+
+from ddgs import DDGS
+
+from ..base import WebSearchBackend
+from ..models import SearchParams, SearchResult
+
+
+class DDGSBackend(WebSearchBackend):
+    """DuckDuckGo search backend using ddgs library."""
+
+    @property
+    def name(self) -> str:
+        """Return the name of this backend."""
+        return "DuckDuckGo"
+
+    async def search(self, params: SearchParams) -> str:
+        """Perform a web search using ddgs.
+
+        Args:
+            params: Search parameters
+
+        Returns:
+            JSON string containing search results or error message
+        """
+        try:
+            # Create DDGS instance
+            ddgs = DDGS()
+
+            # Perform search (synchronous call)
+            # ddgs.text() expects 'query' as first positional argument
+            raw_results = ddgs.text(
+                query=params.query,
+                region=params.region,
+                safesearch=params.safesearch,
+                max_results=params.max_results,
+            )
+
+            # Convert to our model format
+            results = []
+            for r in raw_results:
+                result = SearchResult(
+                    title=r.get("title", ""),
+                    href=r.get("href", ""),
+                    body=r.get("body", ""),
+                )
+                results.append(result.model_dump())
+
+            if not results:
+                return json.dumps({"success": False, "message": "No search results found", "results": []})
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "message": f"Found {len(results)} result{'s' if len(results) != 1 else ''}",
+                    "query": params.query,
+                    "results": results,
+                }
+            )
+
+        except Exception as e:
+            return json.dumps({"success": False, "message": f"Search failed: {e!s}", "results": []})

vibecore/tools/websearch/executor.py

@@ -0,0 +1,43 @@
+"""Websearch execution logic with backend selection."""
+
+from .base import WebSearchBackend
+from .ddgs import DDGSBackend
+from .models import SearchParams
+
+# Default backend
+_default_backend: WebSearchBackend = DDGSBackend()
+
+
+def set_default_backend(backend: WebSearchBackend) -> None:
+    """Set the default search backend.
+
+    Args:
+        backend: The backend to use for searches
+    """
+    global _default_backend
+    _default_backend = backend
+
+
+def get_default_backend() -> WebSearchBackend:
+    """Get the current default search backend.
+
+    Returns:
+        The current default backend
+    """
+    return _default_backend
+
+
+async def perform_websearch(params: SearchParams, backend: WebSearchBackend | None = None) -> str:
+    """Perform a web search using the specified or default backend.
+
+    Args:
+        params: Search parameters
+        backend: Optional specific backend to use (defaults to default backend)
+
+    Returns:
+        JSON string containing search results or error message
+    """
+    if backend is None:
+        backend = _default_backend
+
+    return await backend.search(params)

vibecore/tools/websearch/models.py

@@ -0,0 +1,20 @@
+"""Models for websearch tool."""
+
+from pydantic import BaseModel, Field
+
+
+class SearchResult(BaseModel):
+    """A single search result."""
+
+    title: str = Field(description="Title of the search result")
+    href: str = Field(description="URL of the search result")
+    body: str = Field(description="Description/snippet of the result")
+
+
+class SearchParams(BaseModel):
+    """Parameters for web search."""
+
+    query: str = Field(description="Search query")
+    max_results: int = Field(default=5, description="Maximum number of results to return")
+    region: str | None = Field(default=None, description="Region code (e.g., 'us-en')")
+    safesearch: str = Field(default="moderate", description="SafeSearch setting: 'on', 'moderate', or 'off'")

vibecore/tools/websearch/tools.py

@@ -0,0 +1,49 @@
+"""Websearch tool for Vibecore agents."""
+
+from agents import RunContextWrapper, function_tool
+
+from vibecore.context import VibecoreContext
+
+from .executor import perform_websearch
+from .models import SearchParams
+
+
+@function_tool
+async def websearch(
+    ctx: RunContextWrapper[VibecoreContext],
+    query: str,
+    max_results: int = 5,
+    region: str | None = None,
+    safesearch: str = "moderate",
+) -> str:
+    """Search the web for information using DuckDuckGo.
+
+    This tool allows you to search the web for current information, news, and general knowledge.
+    It supports advanced search operators like quotes for exact phrases, minus for exclusions,
+    site: for specific domains, and filetype: for specific file types.
+
+    Args:
+        ctx: The run context wrapper
+        query: The search query (supports advanced operators like "exact phrase", -exclude, site:example.com)
+        max_results: Maximum number of results to return (default: 5)
+        region: Optional region code for localized results (e.g., 'us-en' for US English)
+        safesearch: SafeSearch filter level ('on', 'moderate', or 'off', default: 'moderate')
+
+    Returns:
+        JSON string containing search results with title, URL, and snippet for each result
+
+    Examples:
+        - Basic search: query="python programming"
+        - Exact phrase: query='"machine learning algorithms"'
+        - Exclude terms: query="python -javascript"
+        - Site-specific: query="AI site:github.com"
+        - File type: query="climate change filetype:pdf"
+    """
+    params = SearchParams(
+        query=query,
+        max_results=max_results,
+        region=region,
+        safesearch=safesearch,
+    )
+
+    return await perform_websearch(params)

vibecore/widgets/tool_message_factory.py

@@ -18,6 +18,8 @@ from vibecore.widgets.tool_messages import (
     TaskToolMessage,
     TodoWriteToolMessage,
     ToolMessage,
+    WebFetchToolMessage,
+    WebSearchToolMessage,
     WriteToolMessage,
 )
 
@@ -113,6 +115,20 @@ def create_tool_message(
         else:
             return WriteToolMessage(file_path=file_path, content=content, status=status)
 
+    elif tool_name == "websearch":
+        query = args_dict.get("query", "") if args_dict else ""
+        if output is not None:
+            return WebSearchToolMessage(query=query, output=output, status=status)
+        else:
+            return WebSearchToolMessage(query=query, status=status)
+
+    elif tool_name == "webfetch":
+        url = args_dict.get("url", "") if args_dict else ""
+        if output is not None:
+            return WebFetchToolMessage(url=url, output=output, status=status)
+        else:
+            return WebFetchToolMessage(url=url, status=status)
+
     # Default to generic ToolMessage for all other tools
     else:
         if output is not None:

vibecore/widgets/tool_messages.py

@@ -481,3 +481,120 @@ class MCPToolMessage(BaseToolMessage):
                         yield ExpandableMarkdown(
                             processed_output, language="", truncated_lines=5, classes="mcp-output-markdown"
                         )
+
+
+class WebSearchToolMessage(BaseToolMessage):
+    """A widget to display web search results."""
+
+    search_query: reactive[str] = reactive("")
+
+    def __init__(self, query: str, output: str = "", status: MessageStatus = MessageStatus.EXECUTING, **kwargs) -> None:
+        """
+        Construct a WebSearchToolMessage.
+
+        Args:
+            query: The search query.
+            output: The search results as JSON string (optional, can be set later).
+            status: The status of execution.
+            **kwargs: Additional keyword arguments for Widget.
+        """
+        super().__init__(status=status, **kwargs)
+        self.search_query = query
+        self.output = output
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the search message."""
+        # Header line
+        header = f"WebSearch({self.search_query})"
+        yield MessageHeader("⏺", header, status=self.status)
+
+        # Process and display search results
+        if self.output:
+            try:
+                result_data = json.loads(self.output)
+                if result_data.get("success") and result_data.get("results"):
+                    with Horizontal(classes="tool-output"):
+                        yield Static("└─", classes="tool-output-prefix")
+                        with Vertical(classes="tool-output-content"):
+                            # Format results as markdown
+                            markdown_results = []
+                            for i, result in enumerate(result_data["results"], 1):
+                                title = result.get("title", "No title")
+                                href = result.get("href", "")
+                                body = result.get("body", "")
+
+                                # Format each result
+                                result_md = f"**{i}. [{title}]({href})**"
+                                if body:
+                                    # Truncate body if too long
+                                    max_body_length = 200
+                                    if len(body) > max_body_length:
+                                        body = body[:max_body_length] + "..."
+                                    result_md += f"\n   {body}"
+                                if href:
+                                    result_md += f"\n   🔗 {href}"
+
+                                markdown_results.append(result_md)
+
+                            # Join all results with spacing
+                            all_results = "\n\n".join(markdown_results)
+
+                            # Add result count message
+                            count_msg = result_data.get("message", "")
+                            if count_msg:
+                                all_results = f"_{count_msg}_\n\n{all_results}"
+
+                            yield ExpandableMarkdown(
+                                all_results, language="", truncated_lines=10, classes="websearch-results"
+                            )
+                else:
+                    # No results or error
+                    with Horizontal(classes="tool-output"):
+                        yield Static("└─", classes="tool-output-prefix")
+                        with Vertical(classes="tool-output-content"):
+                            message = result_data.get("message", "No results found")
+                            yield Static(message, classes="websearch-no-results")
+            except (json.JSONDecodeError, KeyError, TypeError):
+                # Fallback to raw output if JSON parsing fails
+                yield from self._render_output(self.output, truncated_lines=5)
+
+
+class WebFetchToolMessage(BaseToolMessage):
+    """A widget to display fetched web content."""
+
+    fetch_url: reactive[str] = reactive("")
+
+    def __init__(self, url: str, output: str = "", status: MessageStatus = MessageStatus.EXECUTING, **kwargs) -> None:
+        """
+        Construct a WebFetchToolMessage.
+
+        Args:
+            url: The URL that was fetched.
+            output: The fetched content as Markdown (optional, can be set later).
+            status: The status of execution.
+            **kwargs: Additional keyword arguments for Widget.
+        """
+        super().__init__(status=status, **kwargs)
+        self.fetch_url = url
+        self.output = output
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the fetch message."""
+        # Header line
+        header = f"WebFetch({self.fetch_url})"
+        yield MessageHeader("⏺", header, status=self.status)
+
+        # Display fetched content
+        if self.output:
+            with Horizontal(classes="tool-output"):
+                yield Static("└─", classes="tool-output-prefix")
+                with Vertical(classes="tool-output-content"):
+                    # Check if it's an error message
+                    if self.output.startswith("Error:"):
+                        yield Static(self.output, classes="webfetch-error")
+                    else:
+                        # Display as expandable markdown content
+                        # Default to showing first 15 lines since web content can be long
+                        yield ExpandableMarkdown(
+                            self.output, language="", truncated_lines=15, classes="webfetch-content"
+                        )

vibecore/widgets/tool_messages.tcss

@@ -286,4 +286,52 @@ MCPToolMessage {
             width: 1fr;
         }
     }
+}
+
+WebSearchToolMessage {
+    Horizontal.tool-output {
+        height: auto;
+
+        &> .tool-output-prefix {
+            height: 1;
+            width: 5;
+            padding-left: 2;
+            padding-right: 1;
+        }
+
+        &> Vertical.tool-output-content {
+            height: auto;
+
+            &> .tool-output-content {
+                # color: $text-muted;
+            }
+
+            &> .tool-output-content-more {
+            }
+            }
+    }
+}
+
+WebFetchToolMessage {
+    Horizontal.tool-output {
+        height: auto;
+
+        &> .tool-output-prefix {
+            height: 1;
+            width: 5;
+            padding-left: 2;
+            padding-right: 1;
+        }
+
+        &> Vertical.tool-output-content {
+            height: auto;
+
+            &> .tool-output-content {
+                # color: $text-muted;
+            }
+
+            &> .tool-output-content-more {
+            }
+            }
+    }
 }

{vibecore-0.2.0.dist-info → vibecore-0.3.0b1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vibecore
-Version: 0.2.0
+Version: 0.3.0b1
 Summary: Build your own AI-powered automation tools in the terminal with this extensible agent framework
 Project-URL: Homepage, https://github.com/serialx/vibecore
 Project-URL: Repository, https://github.com/serialx/vibecore
@@ -27,6 +27,8 @@ Classifier: Topic :: Terminals
 Classifier: Topic :: Text Processing :: Linguistic
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: ddgs>=9.5.4
+Requires-Dist: html2text>=2024.2.26
 Requires-Dist: litellm>=1.72.4
 Requires-Dist: openai-agents[litellm]>=0.2.2
 Requires-Dist: pydantic-settings>=2.10.1
@@ -65,6 +67,7 @@ Built on [Textual](https://textual.textualize.io/) and the [OpenAI Agents SDK](h
 
 ### Key Features
 
+- **Flow Mode (Experimental)** - Build structured agent-based applications with programmatic conversation control
 - **AI-Powered Chat Interface** - Interact with state-of-the-art language models through an intuitive terminal interface
 - **Rich Tool Integration** - Built-in tools for file operations, shell commands, Python execution, and task management
 - **MCP Support** - Connect to external tools and services via Model Context Protocol servers
@@ -79,6 +82,26 @@ Built on [Textual](https://textual.textualize.io/) and the [OpenAI Agents SDK](h
 ### Prerequisites
 
 - Python 3.11 or higher
+- (Optional) [uv](https://docs.astral.sh/uv/) for quick testing and better package management
+
+### Quick Test (No Installation)
+
+Try vibecore instantly without installing it:
+
+```bash
+# Install uv if you don't have it (optional)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Configure your API key
+export ANTHROPIC_API_KEY="your-api-key-here"
+# or
+export OPENAI_API_KEY="your-api-key-here"
+
+# Run vibecore directly with uvx
+uvx vibecore
+```
+
+This will download and run vibecore in an isolated environment without affecting your system Python installation.
 
 ### Install from PyPI
 
@@ -136,6 +159,88 @@ Once vibecore is running, you can:
 - `/help` - Show help and keyboard shortcuts
 - `/clear` - Clear the current session and start a new one
 
+## Flow Mode (Experimental)
+
+Flow Mode is vibecore's **key differentiator** - it transforms the framework from a chat interface into a platform for building structured agent-based applications with programmatic conversation control.
+
+### What is Flow Mode?
+
+Flow Mode allows you to:
+- **Define custom conversation logic** that controls how agents process user input
+- **Build multi-step workflows** with defined sequences and decision points
+- **Orchestrate multiple agents** with handoffs and shared context
+- **Maintain conversation state** across interactions
+- **Create agent-based applications** rather than just chatbots
+
+### Example: Simple Flow
+
+```python
+import asyncio
+from agents import Agent, Runner
+from vibecore.flow import flow, UserInputFunc
+from vibecore.context import VibecoreContext
+
+# Define your agent with tools
+agent = Agent[VibecoreContext](
+    name="Assistant",
+    instructions="You are a helpful assistant",
+    tools=[...],  # Your tools here
+)
+
+# Define your conversation logic
+async def logic(app, ctx: VibecoreContext, user_input: UserInputFunc):
+    # Get user input programmatically
+    user_message = await user_input("What would you like to do?")
+    
+    # Process with agent
+    result = Runner.run_streamed(
+        agent,
+        input=user_message,
+        context=ctx,
+        session=app.session,
+    )
+    
+    # Handle the response
+    app.current_worker = app.handle_streamed_response(result)
+    await app.current_worker.wait()
+
+# Run the flow
+async def main():
+    await flow(agent, logic)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Example: Multi-Agent Customer Service
+
+Flow Mode shines when building complex multi-agent systems. See `examples/customer_service.py` for a complete implementation featuring:
+
+- **Triage Agent**: Routes requests to appropriate specialists
+- **FAQ Agent**: Handles frequently asked questions
+- **Booking Agent**: Manages seat reservations
+- **Agent Handoffs**: Seamless transitions between agents with context preservation
+- **Shared State**: Maintains customer information across the conversation
+
+### Key Components
+
+- **`flow()`**: Entry point that sets up the Vibecore app with your custom logic
+- **`logic()`**: Your async function that controls the conversation flow
+- **`UserInputFunc`**: Provides programmatic user input collection
+- **`VibecoreContext`**: Shared state across tools and agents
+- **Agent Handoffs**: Transfer control between specialized agents
+
+### Use Cases
+
+Flow Mode enables building:
+- **Customer service systems** with routing and escalation
+- **Guided workflows** for complex tasks
+- **Interactive tutorials** with step-by-step guidance
+- **Task automation** with human-in-the-loop controls
+- **Multi-stage data processing** pipelines
+
+The examples in the `examples/` directory are adapted from the official OpenAI Agents SDK with minimal modifications, demonstrating how easily you can build sophisticated agent applications with vibecore.
+
 ### Available Tools
 
 vibecore comes with powerful built-in tools:

{vibecore-0.2.0.dist-info → vibecore-0.3.0b1.dist-info}/RECORD

@@ -1,13 +1,14 @@
 vibecore/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 vibecore/cli.py,sha256=JspCzt8jlPur35yil7i6Whiw_u33DYeRldx4G-36ueo,4166
 vibecore/context.py,sha256=JUVkZpmKGUSlcchrHpxu-oSO8D21GDgHT1BXDzZDTeQ,844
-vibecore/main.py,sha256=dml8vUoEQrqBZIaH04i15xuBRo_LDZbPwQt8dnVZHZU,19274
+vibecore/flow.py,sha256=ZaKzMsz4YBvgelVzJOIHnTJzMWTmvkfvudwW_hllq6U,3384
+vibecore/main.py,sha256=MIn7Mpg_xO_20c6Mju8PgY-MmVCTER9cepHd5YFbtYs,20175
 vibecore/main.tcss,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 vibecore/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-vibecore/settings.py,sha256=_X2HLh6LbBiQOUKst5Z3sdzcaAxH3m7xNHXI-JXPrHs,5154
-vibecore/agents/default.py,sha256=HnJ33t9rxwco7jfbbZ9dzgyRcpqvGoYH-3KPdTRKX-c,2539
+vibecore/settings.py,sha256=u6kWIMdd5IoLE_SJYqPChR1du8bJ3ZhuCHQQvsUy_cY,6041
+vibecore/agents/default.py,sha256=wxeP3Hsq9MVBChyMF_sNkVHCtFFXgy5ghDIxy9eH_fQ,2287
 vibecore/agents/prompts.py,sha256=0oO9QzcytIbzgZcKJQjWD9fSRNQqBqqK5ku0fcYZZrA,324
-vibecore/agents/task_agent.py,sha256=WcqmSIml1TVZZSWg1xqODAnzpfvSkC-caZuV9ejjUi0,2073
+vibecore/agents/task.py,sha256=cdhZDzKDA8eHHNYPhogFIKBms3oVAMvYeiBB2GqYNuE,1898
 vibecore/handlers/__init__.py,sha256=pFogA2n3GeIi4lmlUEU5jFprNNOaA6AWRR8Wc9X-P4Y,148
 vibecore/handlers/stream_handler.py,sha256=N3fs7jO9QcjSClSyglrwJQ3ky08F70xS8j5m-aYNkyM,10336
 vibecore/mcp/__init__.py,sha256=sl2_8pWjPx4TotO0ZojunVA6Jn6yOhbTQNbQG9-C-Jc,199
@@ -37,12 +38,23 @@ vibecore/tools/shell/__init__.py,sha256=Ias6qmBMDK29q528VtUGtCQeYD4RU_Yx73SIAJrB
 vibecore/tools/shell/executor.py,sha256=yXUkbPqLc3anlsLUB_g4yEu1A_QpzfzwsoMAqx-gplA,6933
 vibecore/tools/shell/tools.py,sha256=hpftFrv4JWn7mbYLJwpCPLROTFyj-RiAOg1hyecV0bE,6829
 vibecore/tools/task/__init__.py,sha256=Fyw33zGiBArMnPuRMm7qwSYE6ZRPCZVbHK6eIUJDiJY,112
-vibecore/tools/task/executor.py,sha256=gPOAbPNf5Rwxke8pC9-dDfMp07gNptNcL6HsMC7en0U,1612
+vibecore/tools/task/executor.py,sha256=gRIdq0f2gjDKxnWH-b5Rbmk1H2garIs56EDYFVKfUiw,1606
 vibecore/tools/task/tools.py,sha256=m6MBOQC3Pz07TZgd3lVAHPGQu9M-Ted-YOxQvIPrGvo,2257
 vibecore/tools/todo/__init__.py,sha256=67o76OyzqYKBH461R9H2-rkNx7ZK6tRSydca3GjqKh8,29
 vibecore/tools/todo/manager.py,sha256=COcVMX8sm--dtqXo0L7914krJMEcK6P2Va4OJiVroBg,871
 vibecore/tools/todo/models.py,sha256=gSheOpIP8NJf44X1JNwvbJQNsyrkfzP3LxrP_9rXzYw,634
 vibecore/tools/todo/tools.py,sha256=kbWXOMu5_xiMdWelxtbh6qS3yBomkveyOFlBcaJKcSY,5121
+vibecore/tools/webfetch/__init__.py,sha256=fKfht3oiz-wMNgtukQjYIUcUC4y7g3GLKK7QXHl0Mcg,224
+vibecore/tools/webfetch/executor.py,sha256=DFjnHgAvDPuwP5h4fgXM2JH270TgF4Vux7ndmZLs9BI,4912
+vibecore/tools/webfetch/models.py,sha256=YvGR4i8Mi7gygCJe7-VPyrvbgacBUJ1PLHyCmOQPmuU,694
+vibecore/tools/webfetch/tools.py,sha256=PWt8hBPD02ua2d9ZnDVfqtNVzachtIPB9QPStbkYY2Y,1494
+vibecore/tools/websearch/__init__.py,sha256=xl3aPD-pOt0Ya4L8khMbOfqpcCpkWTy2-KVk2hUxnOU,97
+vibecore/tools/websearch/base.py,sha256=El9Mx6MFWM3CKGG8MPbPIKgRjdbNZtylFALsPCUTPFs,596
+vibecore/tools/websearch/executor.py,sha256=CLwFkPSDzllH7J1hNdjsp5L0SDLqoINlOSl-zoQKs2A,1114
+vibecore/tools/websearch/models.py,sha256=5cwDw9dWLZ6krP_khx1euwsHjSYLIE4_hNefkjzrkWE,749
+vibecore/tools/websearch/tools.py,sha256=leDf9nmvl8577TMrj7MTodYFx1vyXiIPDral0yzEYm8,1734
+vibecore/tools/websearch/ddgs/__init__.py,sha256=XwZ7As5mVqxXz69In96L3TDChPhpc8GnZR72LgdBvX4,113
+vibecore/tools/websearch/ddgs/backend.py,sha256=HHcckGFoPaFGYSl4k5UH6PURgF1sk8zYWSWVEYeAEtI,1959
 vibecore/utils/__init__.py,sha256=KIS8TkfaDZ1AclSstkYcG8DvJPNsJNOE4EL4zHJE2k4,112
 vibecore/utils/text.py,sha256=RLVFrVsD5L7xi68JTgSa0PeN9S32faqIiaF79dNCyTM,978
 vibecore/widgets/core.py,sha256=ZIdHBvfIaAXaBhA2X3EUkDlL2pN4l5j5Kc_E-VCsM3g,12068
@@ -53,11 +65,11 @@ vibecore/widgets/info.py,sha256=hXtsRUOE13oHbIm9FNe1GCUX_FCht28pgT9SQWeJ69I,1567
 vibecore/widgets/info.tcss,sha256=v30IqNt1two-ezIcm18ZEInKRKcRkAW-h-UH2r8QzSo,201
 vibecore/widgets/messages.py,sha256=az4fJtdk3ItSoFZBG_adRDUHdTLttIV8F23E8LOb-mg,8156
 vibecore/widgets/messages.tcss,sha256=WtBbjf5LgFkUhzhVlxJB7NMbagWladJawDizvDm7hBE,1271
-vibecore/widgets/tool_message_factory.py,sha256=8sSJOo_yXsKY46lDGExdbyB179kFUIEGyfAHWzc6ksY,4749
-vibecore/widgets/tool_messages.py,sha256=uF_QoqtdxPEN0VnoFlvPLdRJKGvIpklHe_NwhqVFStw,19167
-vibecore/widgets/tool_messages.tcss,sha256=K7aCmx_zCbYYwCs6IFfPfvK9pygRVf1PDd8gX0vVtc0,5999
-vibecore-0.2.0.dist-info/METADATA,sha256=uJl8-HZOKevE6JRuUy3RiE34LK8H02FEeciBzyFOMwU,14355
-vibecore-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-vibecore-0.2.0.dist-info/entry_points.txt,sha256=YldTakc3dNelboaWXtzCcnM5MXvU2_6pVOjc2xPjDTY,47
-vibecore-0.2.0.dist-info/licenses/LICENSE,sha256=KXxxifvrcreHrZ4aOYgP-vA8DRHHueW389KKOeEbtjc,1069
-vibecore-0.2.0.dist-info/RECORD,,
+vibecore/widgets/tool_message_factory.py,sha256=FMwavKMRNT8ik9RgcL37WuM19Ln-c5wuFmS0A2CkikM,5377
+vibecore/widgets/tool_messages.py,sha256=PKmPigeOlccowo0uLpgIPzsmmE-zkichzuXIS6hWsbQ,24501
+vibecore/widgets/tool_messages.tcss,sha256=mcFY58FE1AcfEvEiA_Yb7sMpIniTIC_IjDvv8M7vWOA,6924
+vibecore-0.3.0b1.dist-info/METADATA,sha256=PYHen54ZzyRC9-8d6NA9GNxiV24aexWU8kPaQiiuJCk,18066
+vibecore-0.3.0b1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+vibecore-0.3.0b1.dist-info/entry_points.txt,sha256=YldTakc3dNelboaWXtzCcnM5MXvU2_6pVOjc2xPjDTY,47
+vibecore-0.3.0b1.dist-info/licenses/LICENSE,sha256=KXxxifvrcreHrZ4aOYgP-vA8DRHHueW389KKOeEbtjc,1069
+vibecore-0.3.0b1.dist-info/RECORD,,