minitap-mobile-use 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

minitap/mobile_use/sdk/types/task.py

@@ -5,7 +5,8 @@ Task-related type definitions for the Mobile-use SDK.
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any, Generic, Optional, Type, TypeVar, overload
+from typing import Any, TypeVar, overload
+
 from pydantic import BaseModel, Field
 
 from minitap.mobile_use.config import LLMConfig, get_default_llm_config
@@ -36,8 +37,8 @@ class AgentProfile(BaseModel):
         self,
         *,
         name: str,
-        llm_config: Optional[LLMConfig] = None,
-        from_file: Optional[str] = None,
+        llm_config: LLMConfig | None = None,
+        from_file: str | None = None,
         **kwargs,
     ):
         kwargs["name"] = name
@@ -64,7 +65,7 @@ class TaskStatus(str, Enum):
 
 
 T = TypeVar("T", bound=BaseModel)
-TOutput = TypeVar("TOutput", bound=Optional[BaseModel])
+TOutput = TypeVar("TOutput", bound=BaseModel | None)
 
 
 class TaskRequestCommon(BaseModel):
@@ -75,11 +76,11 @@ class TaskRequestCommon(BaseModel):
     max_steps: int = RECURSION_LIMIT
     record_trace: bool = False
     trace_path: Path = Path("mobile-use-traces")
-    llm_output_path: Optional[Path] = None
-    thoughts_output_path: Optional[Path] = None
+    llm_output_path: Path | None = None
+    thoughts_output_path: Path | None = None
 
 
-class TaskRequest(TaskRequestCommon, Generic[TOutput]):
+class TaskRequest[TOutput](TaskRequestCommon):
     """
     Defines the format of a mobile automation task request.
 
@@ -98,10 +99,10 @@ class TaskRequest(TaskRequestCommon, Generic[TOutput]):
     """
 
     goal: str
-    profile: Optional[str] = None
-    task_name: Optional[str] = None
-    output_description: Optional[str] = None
-    output_format: Optional[type[TOutput]] = None
+    profile: str | None = None
+    task_name: str | None = None
+    output_description: str | None = None
+    output_format: type[TOutput] | None = None
 
 
 class TaskResult(BaseModel):
@@ -116,11 +117,11 @@ class TaskResult(BaseModel):
     """
 
     content: Any = None
-    error: Optional[str] = None
+    error: str | None = None
     execution_time_seconds: float
     steps_taken: int
 
-    def get_as_model(self, model_class: Type[T]) -> T:
+    def get_as_model(self, model_class: type[T]) -> T:
         """
         Parse the content into a Pydantic model instance.
 
@@ -158,14 +159,14 @@ class Task(BaseModel):
     status: TaskStatus
     request: TaskRequest
     created_at: datetime
-    ended_at: Optional[datetime] = None
-    result: Optional[TaskResult] = None
+    ended_at: datetime | None = None
+    result: TaskResult | None = None
 
     def finalize(
         self,
-        content: Optional[Any] = None,
-        state: Optional[dict] = None,
-        error: Optional[str] = None,
+        content: Any | None = None,
+        state: dict | None = None,
+        error: str | None = None,
         cancelled: bool = False,
     ):
         self.status = TaskStatus.COMPLETED if error is None else TaskStatus.FAILED

minitap/mobile_use/sdk/utils.py

@@ -16,7 +16,7 @@ def load_llm_config_override(path: Path) -> LLMConfig:
     override_config_dict = {}
     if os.path.exists(path):
         logger.info(f"Loading custom LLM config from {path.resolve()}...")
-        with open(path, "r") as f:
+        with open(path) as f:
             override_config_dict = load_jsonc(f)
     else:
         logger.warning("Custom LLM config not found - using the default config")

minitap/mobile_use/servers/config.py

@@ -1,4 +1,3 @@
-from typing import Optional
 from dotenv import load_dotenv
 from minitap.mobile_use.servers.device_hardware_bridge import DEVICE_HARDWARE_BRIDGE_PORT
 from minitap.mobile_use.utils.logger import get_logger
@@ -11,7 +10,7 @@ logger = get_logger(__name__)
 class ServerSettings(BaseSettings):
     DEVICE_HARDWARE_BRIDGE_BASE_URL: str = f"http://localhost:{DEVICE_HARDWARE_BRIDGE_PORT}"
     DEVICE_SCREEN_API_PORT: int = 9998
-    ADB_HOST: Optional[str] = None
+    ADB_HOST: str | None = None
 
     model_config = {"env_file": ".env", "extra": "ignore"}
 

minitap/mobile_use/servers/device_hardware_bridge.py

@@ -4,7 +4,6 @@ import subprocess
 import threading
 import time
 from enum import Enum
-from typing import Optional
 
 import requests
 from minitap.mobile_use.context import DevicePlatform
@@ -24,7 +23,7 @@ class BridgeStatus(Enum):
 
 
 class DeviceHardwareBridge:
-    def __init__(self, device_id: str, platform: DevicePlatform, adb_host: Optional[str] = None):
+    def __init__(self, device_id: str, platform: DevicePlatform, adb_host: str | None = None):
         self.process = None
         self.status = BridgeStatus.STOPPED
         self.thread = None
@@ -32,7 +31,7 @@ class DeviceHardwareBridge:
         self.lock = threading.Lock()
         self.device_id: str = device_id
         self.platform: DevicePlatform = platform
-        self.adb_host: Optional[str] = adb_host
+        self.adb_host: str | None = adb_host
 
     def _run_maestro_studio(self):
         try:
@@ -207,6 +206,6 @@ class DeviceHardwareBridge:
         with self.lock:
             return {"status": self.status.value, "output": self.output[-10:]}
 
-    def get_device_id(self) -> Optional[str]:
+    def get_device_id(self) -> str | None:
         with self.lock:
             return self.device_id

minitap/mobile_use/servers/start_servers.py

@@ -4,7 +4,7 @@ import signal
 import sys
 import time
 from enum import Enum
-from typing import Annotated, Optional
+from typing import Annotated
 
 import requests
 import typer
@@ -22,7 +22,7 @@ bridge_instance = None
 shutdown_requested = False
 
 
-def check_device_screen_api_health(base_url: Optional[str] = None, max_retries=30, delay=1):
+def check_device_screen_api_health(base_url: str | None = None, max_retries=30, delay=1):
     base_url = base_url or f"http://localhost:{server_settings.DEVICE_SCREEN_API_PORT}"
     health_url = f"{base_url}/health"
 
@@ -49,7 +49,7 @@ def check_device_screen_api_health(base_url: Optional[str] = None, max_retries=3
     return False
 
 
-def _start_device_screen_api_process() -> Optional[multiprocessing.Process]:
+def _start_device_screen_api_process() -> multiprocessing.Process | None:
     try:
         process = multiprocessing.Process(target=start_device_screen_api, daemon=True)
         process.start()
@@ -61,7 +61,7 @@ def _start_device_screen_api_process() -> Optional[multiprocessing.Process]:
 
 def start_device_hardware_bridge(
     device_id: str, platform: DevicePlatform
-) -> Optional[DeviceHardwareBridge]:
+) -> DeviceHardwareBridge | None:
     logger.info("Starting Device Hardware Bridge...")
 
     try:

minitap/mobile_use/servers/stop_servers.py

@@ -1,9 +1,9 @@
 import sys
 import time
-from typing import List
 
 import psutil
 import requests
+
 from minitap.mobile_use.servers.config import server_settings
 from minitap.mobile_use.servers.device_hardware_bridge import DEVICE_HARDWARE_BRIDGE_PORT
 from minitap.mobile_use.utils.logger import get_server_logger
@@ -11,7 +11,7 @@ from minitap.mobile_use.utils.logger import get_server_logger
 logger = get_server_logger()
 
 
-def find_processes_by_name(name: str) -> List[psutil.Process]:
+def find_processes_by_name(name: str) -> list[psutil.Process]:
     """Find all processes with the given name."""
     processes = []
     for proc in psutil.process_iter(["pid", "name", "cmdline"]):
@@ -25,7 +25,7 @@ def find_processes_by_name(name: str) -> List[psutil.Process]:
     return processes
 
 
-def find_processes_by_port(port: int) -> List[psutil.Process]:
+def find_processes_by_port(port: int) -> list[psutil.Process]:
     processes = []
     for proc in psutil.process_iter(["pid", "name"]):
         try:
@@ -44,27 +44,23 @@ def stop_process_gracefully(process: psutil.Process, timeout: int = 5) -> bool:
             logger.success(f"Process {process.pid} ({process.name()}) already terminated")
             return True
 
-        logger.info(f"Stopping process {process.pid} ({process.name()})")
+        logger.debug(f"Stopping process {process.pid} ({process.name()})")
 
         process.terminate()
 
         try:
             process.wait(timeout=timeout)
-            logger.success(f"Process {process.pid} terminated gracefully")
             return True
         except psutil.TimeoutExpired:
             logger.warning(f"Process {process.pid} didn't terminate gracefully, force killing...")
             try:
                 process.kill()
                 process.wait(timeout=2)
-                logger.success(f"Process {process.pid} force killed")
                 return True
             except psutil.NoSuchProcess:
-                logger.success(f"Process {process.pid} already terminated during force kill")
                 return True
 
     except psutil.NoSuchProcess:
-        logger.success(f"Process {process.pid} no longer exists (already terminated)")
         return True
     except (psutil.AccessDenied, psutil.ZombieProcess) as e:
         logger.warning(f"Cannot stop process {process.pid}: {e}")
@@ -84,7 +80,7 @@ def check_service_health(port: int, service_name: str) -> bool:
             return False
 
         if response.status_code == 200:
-            logger.warning(f"{service_name} is still responding on port {port}")
+            logger.debug(f"{service_name} is still responding on port {port}")
             return True
     except requests.exceptions.RequestException:
         pass
@@ -167,19 +163,15 @@ def stop_device_hardware_bridge() -> bool:
 
 
 def stop_servers(
-    device_screen_api: bool = False, device_hardware_bridge: bool = False
+    should_stop_screen_api: bool = False, should_stop_hw_bridge: bool = False
 ) -> tuple[bool, bool]:
-    """Stop all servers and return (api_success, bridge_success).
-
-    Args:
-        device_screen_api: If True, stop the Device Screen API
-        device_hardware_bridge: If True, stop the Device Hardware Bridge
+    """Stop the servers and return whether they stopped successfully (api_success, bridge_success).
 
     Returns:
         Tuple of (api_stopped, bridge_stopped) booleans
     """
-    api_success = stop_device_screen_api() if device_screen_api else True
-    bridge_success = stop_device_hardware_bridge() if device_hardware_bridge else True
+    api_success = stop_device_screen_api() if should_stop_screen_api else True
+    bridge_success = stop_device_hardware_bridge() if should_stop_hw_bridge else True
 
     if api_success and bridge_success:
         logger.success("All servers stopped successfully")
@@ -195,7 +187,9 @@ def stop_servers(
 
 def main():
     """Main function to stop all servers."""
-    api_success, bridge_success = stop_servers(device_screen_api=True, device_hardware_bridge=True)
+    api_success, bridge_success = stop_servers(
+        should_stop_screen_api=True, should_stop_hw_bridge=True
+    )
     if api_success and bridge_success:
         return 0
     elif api_success or bridge_success:

minitap/mobile_use/services/llm.py

@@ -1,6 +1,7 @@
 import logging
-from typing import Awaitable, Callable, Literal, TypeVar
-from typing_extensions import overload
+from typing import Literal, TypeVar
+from collections.abc import Awaitable, Callable
+from typing import overload
 
 from langchain_google_genai import ChatGoogleGenerativeAI
 from langchain_openai import ChatOpenAI
@@ -39,6 +40,7 @@ def get_openai_llm(
     client = ChatOpenAI(
         model=model_name,
         api_key=settings.OPENAI_API_KEY,
+        base_url=settings.OPENAI_BASE_URL,
         temperature=temperature,
     )
     return client

minitap/mobile_use/tools/index.py

@@ -1,17 +1,17 @@
 from langchain_core.tools import BaseTool
+
 from minitap.mobile_use.context import MobileUseContext
 from minitap.mobile_use.tools.mobile.back import back_wrapper
+from minitap.mobile_use.tools.mobile.clear_text import clear_text_wrapper
 from minitap.mobile_use.tools.mobile.copy_text_from import copy_text_from_wrapper
-from minitap.mobile_use.tools.mobile.erase_text import erase_text_wrapper
+from minitap.mobile_use.tools.mobile.erase_one_char import erase_one_char_wrapper
+from minitap.mobile_use.tools.mobile.find_packages import find_packages_wrapper
 from minitap.mobile_use.tools.mobile.input_text import input_text_wrapper
 from minitap.mobile_use.tools.mobile.launch_app import launch_app_wrapper
-from minitap.mobile_use.tools.mobile.list_packages import list_packages_wrapper
 from minitap.mobile_use.tools.mobile.long_press_on import long_press_on_wrapper
 from minitap.mobile_use.tools.mobile.open_link import open_link_wrapper
 from minitap.mobile_use.tools.mobile.paste_text import paste_text_wrapper
 from minitap.mobile_use.tools.mobile.press_key import press_key_wrapper
-
-# from minitap.mobile_use.tools.mobile.run_flow import run_flow_wrapper
 from minitap.mobile_use.tools.mobile.stop_app import stop_app_wrapper
 from minitap.mobile_use.tools.mobile.swipe import swipe_wrapper
 from minitap.mobile_use.tools.mobile.take_screenshot import take_screenshot_wrapper
@@ -28,14 +28,14 @@ EXECUTOR_WRAPPERS_TOOLS = [
     long_press_on_wrapper,
     swipe_wrapper,
     take_screenshot_wrapper,
-    # run_flow_wrapper, # To decomment when subflow is implemented
     copy_text_from_wrapper,
     input_text_wrapper,
-    list_packages_wrapper,
+    erase_one_char_wrapper,
+    find_packages_wrapper,
     launch_app_wrapper,
     stop_app_wrapper,
     paste_text_wrapper,
-    erase_text_wrapper,
+    clear_text_wrapper,
     press_key_wrapper,
     wait_for_animation_to_end_wrapper,
 ]
@@ -46,6 +46,10 @@ def get_tools_from_wrappers(ctx: MobileUseContext, wrappers: list[ToolWrapper])
     return [wrapper.tool_fn_getter(ctx) for wrapper in wrappers]
 
 
+def format_tools_list(ctx: MobileUseContext, wrappers: list[ToolWrapper]) -> str:
+    return "\n".join([tool.name for tool in get_tools_from_wrappers(ctx, wrappers)])
+
+
 def get_tool_wrapper_from_name(name: str) -> ToolWrapper | None:
     """Get the tool wrapper from the name."""
     for wrapper in EXECUTOR_WRAPPERS_TOOLS:

minitap/mobile_use/tools/mobile/back.py

@@ -1,12 +1,11 @@
-from typing import Optional
-
 from langchain_core.messages import ToolMessage
 from langchain_core.tools import tool
 from langchain_core.tools.base import InjectedToolCallId
 from langgraph.types import Command
+from minitap.mobile_use.constants import EXECUTOR_MESSAGES_KEY
 from minitap.mobile_use.controllers.mobile_command_controller import back as back_controller
-from minitap.mobile_use.tools.tool_wrapper import ExecutorMetadata, ToolWrapper
-from typing_extensions import Annotated
+from minitap.mobile_use.tools.tool_wrapper import ToolWrapper
+from typing import Annotated
 from minitap.mobile_use.context import MobileUseContext
 from minitap.mobile_use.graph.state import State
 from langgraph.prebuilt import InjectedState
@@ -18,7 +17,6 @@ def get_back_tool(ctx: MobileUseContext):
         tool_call_id: Annotated[str, InjectedToolCallId],
         state: Annotated[State, InjectedState],
         agent_thought: str,
-        executor_metadata: Optional[ExecutorMetadata],
     ):
         """Navigates to the previous screen. (Only works on Android for the moment)"""
         output = back_controller(ctx=ctx)
@@ -27,18 +25,16 @@ def get_back_tool(ctx: MobileUseContext):
             tool_call_id=tool_call_id,
             content=back_wrapper.on_failure_fn() if has_failed else back_wrapper.on_success_fn(),
             additional_kwargs={"error": output} if has_failed else {},
+            status="error" if has_failed else "success",
         )
         return Command(
-            update=back_wrapper.handle_executor_state_fields(
+            update=state.sanitize_update(
                 ctx=ctx,
-                state=state,
-                executor_metadata=executor_metadata,
-                tool_message=tool_message,
-                is_failure=has_failed,
-                updates={
+                update={
                     "agents_thoughts": [agent_thought],
-                    "messages": [tool_message],
+                    EXECUTOR_MESSAGES_KEY: [tool_message],
                 },
+                agent="executor",
             ),
         )
 

minitap/mobile_use/tools/mobile/clear_text.py

@@ -0,0 +1,277 @@
+from typing import Annotated
+
+from langchain_core.messages import ToolMessage
+from langchain_core.tools import tool
+from langchain_core.tools.base import InjectedToolCallId
+from langgraph.prebuilt import InjectedState
+from langgraph.types import Command
+from pydantic import BaseModel
+
+from minitap.mobile_use.constants import EXECUTOR_MESSAGES_KEY
+from minitap.mobile_use.context import MobileUseContext
+from minitap.mobile_use.controllers.mobile_command_controller import (
+    erase_text as erase_text_controller,
+)
+from minitap.mobile_use.controllers.mobile_command_controller import (
+    get_screen_data,
+)
+from minitap.mobile_use.graph.state import State
+from minitap.mobile_use.tools.tool_wrapper import ToolWrapper
+from minitap.mobile_use.tools.utils import (
+    focus_element_if_needed,
+    move_cursor_to_end_if_bounds,
+)
+from minitap.mobile_use.utils.logger import get_logger
+from minitap.mobile_use.utils.ui_hierarchy import (
+    find_element_by_resource_id,
+    get_element_text,
+    text_input_is_empty,
+)
+
+logger = get_logger(__name__)
+
+MAX_CLEAR_TRIES = 5
+DEFAULT_CHARS_TO_ERASE = 50
+
+
+class ClearTextResult(BaseModel):
+    success: bool
+    error_message: str | None
+    chars_erased: int
+    final_text: str | None
+
+
+class TextClearer:
+    def __init__(self, ctx: MobileUseContext, state: State):
+        self.ctx = ctx
+        self.state = state
+
+    def _refresh_ui_hierarchy(self) -> None:
+        screen_data = get_screen_data(screen_api_client=self.ctx.screen_api_client)
+        self.state.latest_ui_hierarchy = screen_data.elements
+
+    def _get_element_info(self, resource_id: str) -> tuple[object | None, str | None, str | None]:
+        if not self.state.latest_ui_hierarchy:
+            self._refresh_ui_hierarchy()
+
+        if not self.state.latest_ui_hierarchy:
+            return None, None, None
+
+        element = find_element_by_resource_id(
+            ui_hierarchy=self.state.latest_ui_hierarchy, resource_id=resource_id
+        )
+
+        if not element:
+            return None, None, None
+
+        current_text = get_element_text(element)
+        hint_text = get_element_text(element, hint_text=True)
+
+        return element, current_text, hint_text
+
+    def _format_text_with_hint_info(self, text: str | None, hint_text: str | None) -> str | None:
+        if text is None:
+            return None
+
+        is_hint_text = hint_text is not None and hint_text != "" and hint_text == text
+
+        if is_hint_text:
+            return f"{text} (which is the hint text, the input is very likely empty)"
+
+        return text
+
+    def _should_clear_text(self, current_text: str | None, hint_text: str | None) -> bool:
+        return current_text is not None and current_text != "" and current_text != hint_text
+
+    def _prepare_element_for_clearing(self, resource_id: str) -> bool:
+        if not focus_element_if_needed(ctx=self.ctx, resource_id=resource_id):
+            return False
+
+        move_cursor_to_end_if_bounds(ctx=self.ctx, state=self.state, resource_id=resource_id)
+        return True
+
+    def _erase_text_attempt(self, text_length: int) -> str | None:
+        chars_to_erase = text_length + 1
+        logger.info(f"Erasing {chars_to_erase} characters from the input")
+
+        error = erase_text_controller(ctx=self.ctx, nb_chars=chars_to_erase)
+        if error:
+            logger.error(f"Failed to erase text: {error}")
+            return str(error)
+
+        return None
+
+    def _clear_with_retries(
+        self, resource_id: str, initial_text: str, hint_text: str | None
+    ) -> tuple[bool, str | None, int]:
+        current_text = initial_text
+        erased_chars = 0
+
+        for attempt in range(1, MAX_CLEAR_TRIES + 1):
+            logger.info(f"Clear attempt {attempt}/{MAX_CLEAR_TRIES}")
+
+            chars_to_erase = len(current_text) if current_text else DEFAULT_CHARS_TO_ERASE
+            error = self._erase_text_attempt(text_length=chars_to_erase)
+
+            if error:
+                return False, current_text, 0
+            erased_chars += chars_to_erase
+
+            self._refresh_ui_hierarchy()
+            elt = find_element_by_resource_id(
+                ui_hierarchy=self.state.latest_ui_hierarchy or [],
+                resource_id=resource_id,
+            )
+            if elt:
+                current_text = get_element_text(elt)
+                logger.info(f"Current text: {current_text}")
+                if text_input_is_empty(text=current_text, hint_text=hint_text):
+                    break
+
+            move_cursor_to_end_if_bounds(
+                ctx=self.ctx, state=self.state, resource_id=resource_id, elt=elt
+            )
+
+        return True, current_text, erased_chars
+
+    def _create_result(
+        self,
+        success: bool,
+        error_message: str | None,
+        chars_erased: int,
+        final_text: str | None,
+        hint_text: str | None,
+    ) -> ClearTextResult:
+        formatted_final_text = self._format_text_with_hint_info(final_text, hint_text)
+
+        return ClearTextResult(
+            success=success,
+            error_message=error_message,
+            chars_erased=chars_erased,
+            final_text=formatted_final_text,
+        )
+
+    def _handle_no_clearing_needed(
+        self, current_text: str | None, hint_text: str | None
+    ) -> ClearTextResult:
+        return self._create_result(
+            success=True,
+            error_message=None,
+            chars_erased=-1,
+            final_text=current_text,
+            hint_text=hint_text,
+        )
+
+    def _handle_element_not_found(self, resource_id: str, hint_text: str | None) -> ClearTextResult:
+        error = erase_text_controller(ctx=self.ctx)
+        self._refresh_ui_hierarchy()
+
+        _, final_text, _ = self._get_element_info(resource_id)
+
+        return self._create_result(
+            success=error is None,
+            error_message=str(error) if error is not None else None,
+            chars_erased=0,  # Unknown since we don't have initial text
+            final_text=final_text,
+            hint_text=hint_text,
+        )
+
+    def clear_text_by_resource_id(self, resource_id: str) -> ClearTextResult:
+        element, current_text, hint_text = self._get_element_info(resource_id)
+
+        if not element:
+            return self._handle_element_not_found(resource_id, hint_text)
+
+        if not self._should_clear_text(current_text, hint_text):
+            return self._handle_no_clearing_needed(current_text, hint_text)
+
+        if not self._prepare_element_for_clearing(resource_id):
+            return self._create_result(
+                success=False,
+                error_message="Failed to focus element",
+                chars_erased=0,
+                final_text=current_text,
+                hint_text=hint_text,
+            )
+
+        success, final_text, chars_erased = self._clear_with_retries(
+            resource_id=resource_id,
+            initial_text=current_text or "",
+            hint_text=hint_text,
+        )
+
+        error_message = None if success else "Failed to clear text after retries"
+
+        return self._create_result(
+            success=success,
+            error_message=error_message,
+            chars_erased=chars_erased,
+            final_text=final_text,
+            hint_text=hint_text,
+        )
+
+
+def get_clear_text_tool(ctx: MobileUseContext):
+    @tool
+    def clear_text(
+        tool_call_id: Annotated[str, InjectedToolCallId],
+        state: Annotated[State, InjectedState],
+        agent_thought: str,
+        text_input_resource_id: str,
+    ):
+        """
+        Clears all the text from the text field, by focusing it if needed.
+        """
+        clearer = TextClearer(ctx, state)
+        result = clearer.clear_text_by_resource_id(text_input_resource_id)
+
+        content = (
+            clear_text_wrapper.on_failure_fn(result.error_message)
+            if not result.success
+            else clear_text_wrapper.on_success_fn(
+                nb_char_erased=result.chars_erased, new_text_value=result.final_text
+            )
+        )
+
+        tool_message = ToolMessage(
+            tool_call_id=tool_call_id,
+            content=content,
+            additional_kwargs={"error": result.error_message} if not result.success else {},
+            status="error" if not result.success else "success",
+        )
+
+        return Command(
+            update=state.sanitize_update(
+                ctx=ctx,
+                update={
+                    "agents_thoughts": [agent_thought],
+                    EXECUTOR_MESSAGES_KEY: [tool_message],
+                },
+                agent="executor",
+            ),
+        )
+
+    return clear_text
+
+
+def _format_success_message(nb_char_erased: int, new_text_value: str | None) -> str:
+    if nb_char_erased == -1:
+        msg = "No text clearing was needed (the input was already empty)."
+    else:
+        msg = f"Text erased successfully. {nb_char_erased} characters were erased."
+
+    if new_text_value is not None:
+        msg += f" New text in the input is '{new_text_value}'."
+
+    return msg
+
+
+def _format_failure_message(output: str | None) -> str:
+    return "Failed to erase text. " + (str(output) if output else "")
+
+
+clear_text_wrapper = ToolWrapper(
+    tool_fn_getter=get_clear_text_tool,
+    on_success_fn=_format_success_message,
+    on_failure_fn=_format_failure_message,
+)