droidrun 0.5.0.dev7__tar.gz → 0.5.1.dev2__tar.gz

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: droidrun
-Version: 0.5.0.dev7
+Version: 0.5.1.dev2
 Summary: A framework for controlling Android devices through LLM agents
 Project-URL: Homepage, https://github.com/droidrun/droidrun
 Project-URL: Bug Tracker, https://github.com/droidrun/droidrun/issues
@@ -71,6 +71,8 @@ Description-Content-Type: text/markdown
   <img src="./static/droidrun.png"  width="full">
 </picture>
 
+<h3 align="center"><em>DroidRun is not affiliated with, endorsed by, or sponsored by Google LLC or the Android Open Source Project. Android™ is a trademark of Google LLC.</em></h3>
+
 <div align="center">
 
 [![Docs](https://img.shields.io/badge/Docs-📕-0D9373?style=for-the-badge)](https://docs.droidrun.ai)
@@ -107,6 +109,10 @@ Description-Content-Type: text/markdown
 
 DroidRun is a powerful framework for controlling Android and iOS devices through LLM agents. It allows you to automate device interactions using natural language commands. [Checkout our benchmark results](https://droidrun.ai/benchmark)
 
+## ⚖️ Disclaimer
+
+Droidrun is an independent, open-source project and is not affiliated with, endorsed by, or sponsored by Google LLC or the Android Open Source Project. "Android" is a trademark of Google LLC. All other trademarks and brand names mentioned are the property of their respective owners. DroidRun is a third-party tool that interacts with the Android platform but is not part of the Android ecosystem.
+
 ## Why Droidrun?
 
 - 🤖 Control Android and iOS devices with natural language commands

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/README.md

@@ -4,6 +4,8 @@
   <img src="./static/droidrun.png"  width="full">
 </picture>
 
+<h3 align="center"><em>DroidRun is not affiliated with, endorsed by, or sponsored by Google LLC or the Android Open Source Project. Android™ is a trademark of Google LLC.</em></h3>
+
 <div align="center">
 
 [![Docs](https://img.shields.io/badge/Docs-📕-0D9373?style=for-the-badge)](https://docs.droidrun.ai)
@@ -40,6 +42,10 @@
 
 DroidRun is a powerful framework for controlling Android and iOS devices through LLM agents. It allows you to automate device interactions using natural language commands. [Checkout our benchmark results](https://droidrun.ai/benchmark)
 
+## ⚖️ Disclaimer
+
+Droidrun is an independent, open-source project and is not affiliated with, endorsed by, or sponsored by Google LLC or the Android Open Source Project. "Android" is a trademark of Google LLC. All other trademarks and brand names mentioned are the property of their respective owners. DroidRun is a third-party tool that interacts with the Android platform but is not part of the Android ecosystem.
+
 ## Why Droidrun?
 
 - 🤖 Control Android and iOS devices with natural language commands

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v4/sdk/configuration.mdx

@@ -189,7 +189,6 @@ TelemetryConfig(
 from droidrun import ToolsConfig
 
 ToolsConfig(
-    allow_drag=True,          # Enable drag tool
     disabled_tools=[],        # List of tools to disable (e.g., ["long_press", "wait"])
 )
 ```

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/concepts/events-and-workflows.mdx

@@ -75,7 +75,7 @@ class ManagerPlanEvent(Event):
     plan: str
     current_subgoal: str
     thought: str
-    manager_answer: str = ""
+    answer: str = ""
     success: bool | None = None
 
 class ExecutorInputEvent(Event):
@@ -115,8 +115,8 @@ Internal to ManagerAgent, streamed to frontend/logging.
 class ManagerContextEvent(Event): pass
 
 class ManagerResponseEvent(Event):
-    output_planning: str
-    usage: Optional[UsageResult]
+    response: str
+    usage: Optional[UsageResult] = None
 
 class ManagerPlanDetailsEvent(Event):
     plan: str
@@ -145,7 +145,7 @@ class ExecutorActionEvent(Event):
     action_json: str
     thought: str
     description: str
-    full_response: str
+    full_response: str = ""
 
 class ExecutorActionResultEvent(Event):
     action: Dict
@@ -190,10 +190,10 @@ class ScripterInputEvent(Event):
     pass
 
 class ScripterThinkingEvent(Event):
-    thoughts: str
-    code: Optional[str]
-    full_response: str
-    usage: Optional[UsageResult]
+    thought: str
+    code: Optional[str] = None
+    full_response: str = ""
+    usage: Optional[UsageResult] = None
 
 class ScripterExecutionEvent(Event):
     code: str
@@ -204,64 +204,25 @@ class ScripterExecutionResultEvent(Event):
 class ScripterEndEvent(Event):
     message: str
     success: bool
-    code_executions: int
+    code_executions: int = 0
 ```
   </Accordion>
 
-  <Accordion title="Action Recording Events">
-Emitted when actions are performed, used for macro recording and trajectory tracking.
-
+  <Accordion title="Common, Visual & Telemetry Events">
 ```python
-class MacroEvent(Event):  # Base class
-    action_type: str
-    description: str
-
-class TapActionEvent(MacroEvent):
-    x: int
-    y: int
-    element_index: int = None
-    element_text: str = ""
-    element_bounds: str = ""
-
-class SwipeActionEvent(MacroEvent):
-    start_x: int
-    start_y: int
-    end_x: int
-    end_y: int
-    duration_ms: int
-
-class DragActionEvent(MacroEvent):
-    start_x: int
-    start_y: int
-    end_x: int
-    end_y: int
-    duration_ms: int
-
-class InputTextActionEvent(MacroEvent):
-    text: str
-
-class KeyPressActionEvent(MacroEvent):
-    keycode: int
-    key_name: str = ""
-
-class StartAppEvent(MacroEvent):
-    package: str
-    activity: str = None
-
-class WaitEvent(MacroEvent):
-    duration: float
-```
-  </Accordion>
-
-  <Accordion title="Visual & Telemetry Events">
-```python
-# Visual events
+# Common events (droidrun/agent/common/events.py)
 class ScreenshotEvent(Event):
     screenshot: bytes
 
 class RecordUIStateEvent(Event):
     ui_state: list[Dict[str, Any]]
 
+class ToolExecutionEvent(Event):
+    tool_name: str
+    tool_args: Dict[str, Any]
+    success: bool
+    summary: str
+
 # Telemetry events (when enabled)
 class DroidAgentInitEvent(TelemetryEvent):
     goal: str
@@ -392,13 +353,13 @@ async def monitor_execution(goal: str):
 - Coordination: `ManagerInputEvent`, `ManagerPlanEvent`, `ExecutorInputEvent`, `ExecutorResultEvent`
 - Internal Manager: `ManagerContextEvent`, `ManagerResponseEvent`, `ManagerPlanDetailsEvent`
 - Internal Executor: `ExecutorContextEvent`, `ExecutorResponseEvent`, `ExecutorActionEvent`, `ExecutorActionResultEvent`
-- Actions: All action recording events (`TapActionEvent`, `SwipeActionEvent`, etc.)
+- Tool execution: `ToolExecutionEvent` (after every tool dispatch)
 - Visual: `ScreenshotEvent`, `RecordUIStateEvent` (when enabled)
 
 **Direct Mode** (`reasoning=False`) emits:
 - Coordination: `FastAgentExecuteEvent`, `FastAgentResultEvent`
 - Internal FastAgent: `FastAgentInputEvent`, `FastAgentResponseEvent`, `FastAgentToolCallEvent`, `FastAgentOutputEvent`, `FastAgentEndEvent`
-- Actions: All action recording events
+- Tool execution: `ToolExecutionEvent` (after every tool dispatch)
 - Visual: `ScreenshotEvent`, `RecordUIStateEvent` (when enabled)
 
 **ScripterAgent** (when triggered by `<script>` tags) emits:
@@ -419,9 +380,9 @@ async def monitor_execution(goal: str):
 - Located in agent-specific event files
 - Examples: `ManagerPlanDetailsEvent`, `ExecutorActionEvent`, `FastAgentResponseEvent`
 
-**Action Recording Events** - Emitted when actions are performed (for macros/trajectories)
+**Common Events** - Emitted during execution (for screenshots, UI state recording, and tool tracking)
 - Located in `droidrun/agent/common/events.py`
-- Examples: `TapActionEvent`, `SwipeActionEvent`, `InputTextActionEvent`
+- Examples: `ScreenshotEvent`, `RecordUIStateEvent`, `ToolExecutionEvent`
 
 **Telemetry Events** - Captured for analytics (when enabled)
 - Located in `droidrun/telemetry/events.py`

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/concepts/prompts.mdx

@@ -63,9 +63,13 @@ Each agent has access to different variables in its templates:
 
 - `instruction` - User's goal
 - `device_state` - Current UI tree
+- `plan` - Current plan from Manager
 - `subgoal` - Current subgoal from Manager
+- `progress_status` - Cumulative progress summary
 - `atomic_actions` - Available actions (includes custom tools)
 - `action_history` - Recent actions with outcomes
+- `available_secrets` - Available credential IDs
+- `variables` - Custom variables passed to DroidAgent
 
 ### FastAgent
 
@@ -82,8 +86,8 @@ Each agent has access to different variables in its templates:
 ### Scripter
 
 - `task` - Task description from Manager
-- `available_secrets` - Credential IDs
-- `variables` - Custom variables
+- `max_steps` - Maximum execution steps allowed
+- `available_libraries` - Descriptions of available Python libraries
 
 ## Example: Custom Manager Prompt
 

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/concepts/scripter-agent.mdx

@@ -134,21 +134,24 @@ Found 23 contacts from New York and saved them to /tmp/filtered_contacts.json
 ```yaml
 agent:
   scripter:
+    enabled: true
     max_steps: 10
-    safe_execution:
-      enabled: true
-      allowed_modules:
-        - requests    # API calls, webhooks
-        - json        # JSON parsing
-        - csv         # CSV file operations
-        - pathlib     # File path handling
-      blocked_modules:
-        - subprocess  # Process spawning
-        - os          # System operations
-        - sys         # System modifications
-```
-
-**Safe execution** restricts dangerous operations by default. Only modules in `allowed_modules` can be imported.
+    safe_execution: true   # Enable sandboxed execution
+
+# Top-level safe execution config (shared by all code-executing agents)
+safe_execution:
+  allowed_modules:
+    - requests    # API calls, webhooks
+    - json        # JSON parsing
+    - csv         # CSV file operations
+    - pathlib     # File path handling
+  blocked_modules:
+    - subprocess  # Process spawning
+    - os          # System operations
+    - sys         # System modifications
+```
+
+**Safe execution** restricts dangerous operations when enabled. The `agent.scripter.safe_execution` flag enables sandboxing, and the top-level `safe_execution` config controls which modules and builtins are accessible.
 
 ## Key Points
 

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/concepts/shared-state.mdx

@@ -34,16 +34,25 @@ class DroidAgentState(BaseModel):
     summary_history: List[str] = []            # Action summaries
 
     # Memory
-    memory: str = ""                           # Agent persistent memory
+    manager_memory: str = ""                   # Manager's planning notes (append-only)
+    fast_memory: List[str] = []                # FastAgent remember() items (max 10)
 
     # Planning (Manager)
     plan: str = ""                             # Current plan
     current_subgoal: str = ""                  # Current subgoal
-    manager_answer: str = ""                   # Answer-type responses
+    answer: str = ""                           # Final answer (manager completion or complete() tool)
+
+    # Completion (set by complete() tool)
+    finished: bool = False                     # Whether task is done
+    success: Optional[bool] = None             # Whether task succeeded
 
     # Error handling
     error_flag_plan: bool = False              # Signal error to Manager
     error_descriptions: List[str] = []         # Error messages
+    err_to_manager_thresh: int = 2             # Consecutive errors before escalation
+
+    # Message history (for stateful agents)
+    message_history: List[ChatMessage] = []    # Preserves ThinkingBlock, ImageBlock, etc.
 
     # Script execution (Scripter)
     scripter_history: List[Dict] = []          # Scripter results

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/features/credentials.mdx

@@ -105,10 +105,12 @@ When credentials are provided, the `type_secret` action is **automatically avail
 
 ### FastAgent Mode
 ```xml
-<type_secret>
-  <secret_id>MY_PASSWORD</secret_id>
-  <index>5</index>
-</type_secret>
+<function_calls>
+<invoke name="type_secret">
+<parameter name="secret_id">MY_PASSWORD</parameter>
+<parameter name="index">5</parameter>
+</invoke>
+</function_calls>
 ```
 
 The agent never sees the actual value - only the secret ID.

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/features/custom-tools.mdx

@@ -152,8 +152,8 @@ async def check_action_history(action_name: str, *, ctx, **kwargs) -> str:
     if shared_state.step_number > 10:
         return "Warning: Task taking too many steps"
 
-    # Access memory
-    if "skip_validation" in shared_state.memory:
+    # Access fast memory
+    if any("skip_validation" in m for m in shared_state.fast_memory):
         return "Validation skipped per memory"
 
     return f"Action '{action_name}' not yet performed"
@@ -173,7 +173,8 @@ custom_tools = {
 - `step_number` - Current execution step
 - `action_history` - List of executed actions
 - `action_outcomes` - Success/failure per action
-- `memory` - Agent memory dict
+- `manager_memory` - Manager planning notes (append-only string)
+- `fast_memory` - FastAgent remember() items (list of strings, max 10)
 - `custom_variables` - User-provided variables
 - `visited_packages` - Apps visited
 - `current_package_name` - Current app package

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/features/structured-output.mdx

@@ -117,7 +117,7 @@ if result.structured_output:
 
 ### Custom Extraction LLM
 
-By default, extraction uses the `fast_agent` LLM. Specify a dedicated `structured_output` profile:
+By default, extraction uses the `structured_output` LLM profile. If not configured, it falls back to the `fast_agent` LLM. You can specify a dedicated `structured_output` profile:
 
 **config.yaml:**
 ```yaml
@@ -257,7 +257,7 @@ async def finalize(self, ctx: Context, ev: FinalizeEvent) -> ResultEvent:
             pydantic_model=self.output_model,
             answer_text=ev.reason,
         )
-        extraction_result = await (await structured_agent.run())
+        extraction_result = await structured_agent.run()
         if extraction_result["success"]:
             result.structured_output = extraction_result["structured_output"]
 

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/features/tracing.mdx

@@ -91,7 +91,7 @@ For more on using Phoenix, see the [Arize Phoenix documentation](https://docs.ar
 Set environment variables to customize Phoenix:
 
 ```sh
-# Custom Phoenix server URL (default: http://127.0.0.1:6006)
+# Custom Phoenix server URL (default: http://0.0.0.0:6006)
 export phoenix_url=http://localhost:6006
 
 # Project name for organizing traces

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/guides/cli.mdx

@@ -21,7 +21,7 @@ droidrun run "Turn on Do Not Disturb"
 ```
 
 <Note>
-**Auto-configuration**: If `config.yaml` doesn't exist, Droidrun creates it from `config_example.yaml` automatically.
+**Auto-configuration**: If no config exists, Droidrun creates a default `config.yaml` at `~/.config/droidrun/config.yaml` automatically.
 
 **Command shorthand**: `droidrun "task"` is equivalent to `droidrun run "task"`
 </Note>
@@ -57,7 +57,7 @@ droidrun "<command>" [OPTIONS]
 | `--tcp` | Use TCP instead of content provider | `false` |
 | `--debug` | Verbose logging | `false` |
 | `--save-trajectory` | Save execution (`none`, `step`, `action`) | `none` |
-| `--config`, `-c` | Custom config path | `config.yaml` |
+| `--config`, `-c` | Custom config path | `~/.config/droidrun/config.yaml` |
 
 ### Examples
 
@@ -174,7 +174,7 @@ droidrun setup --path /path/to/portal.apk
 ```
 
 **What it does:**
-1. Downloads latest Portal APK
+1. Downloads compatible Portal APK for your SDK version
 2. Installs with all permissions
 3. Auto-enables accessibility service
 4. Opens settings if manual enable needed
@@ -324,7 +324,7 @@ trajectories/2025-10-16_14-30-45/
 ### Override Priority
 
 1. **CLI flags** (highest)
-2. **Config file** (`config.yaml`)
+2. **Config file** (`~/.config/droidrun/config.yaml`)
 3. **Defaults** (lowest)
 
 ### Common Patterns
@@ -387,7 +387,7 @@ droidrun setup
 
 # Enable accessibility manually
 adb shell settings put secure enabled_accessibility_services \
-  com.droidrun.portal/.DroidrunAccessibilityService
+  com.droidrun.portal/com.droidrun.portal.service.DroidrunAccessibilityService
 ```
   </Accordion>
 
@@ -444,7 +444,7 @@ droidrun ping --tcp
 | `OPENAI_API_KEY` | OpenAI API key | None |
 | `ANTHROPIC_API_KEY` | Anthropic API key | None |
 | `DEEPSEEK_API_KEY` | DeepSeek API key | None |
-| `DROIDRUN_CONFIG` | Config file path | `config.yaml` |
+| `DROIDRUN_CONFIG` | Config file path | `~/.config/droidrun/config.yaml` |
 
 **Setting variables:**
 

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/guides/device-setup.mdx

@@ -35,7 +35,7 @@ Droidrun controls devices through a specialized Portal app that bridges your com
 
   <Step title="Install Portal App">
     ```bash
-    # Automatic setup (downloads latest Portal APK)
+    # Automatic setup (downloads compatible Portal APK)
     droidrun setup
 
     # Or specify device
@@ -43,7 +43,7 @@ Droidrun controls devices through a specialized Portal app that bridges your com
     ```
 
     This will:
-    - Download the latest Portal APK
+    - Download the compatible Portal APK for your SDK version
     - Install with all permissions granted
     - Enable accessibility service automatically
   </Step>
@@ -223,7 +223,7 @@ The Portal only communicates locally via ADB. No data is sent to external server
     ```python
     import asyncio
     from droidrun import DeviceConfig, DroidrunConfig, DroidAgent
-    from adbutils import adb
+    from async_adbutils import adb
 
     async def control_device(serial: str, command: str):
         device_config = DeviceConfig(serial=serial)
@@ -232,7 +232,7 @@ The Portal only communicates locally via ADB. No data is sent to external server
         return await agent.run()
 
     async def main():
-        devices = adb.list()
+        devices = await adb.list()
 
         tasks = [
             control_device(devices[0].serial, "Open settings"),
@@ -279,7 +279,7 @@ The Portal only communicates locally via ADB. No data is sent to external server
     1. Auto-enable:
        ```bash
        adb shell settings put secure enabled_accessibility_services \
-         com.droidrun.portal/com.droidrun.portal.DroidrunAccessibilityService
+         com.droidrun.portal/com.droidrun.portal.service.DroidrunAccessibilityService
        adb shell settings put secure accessibility_enabled 1
        ```
     2. Manual: Settings > Accessibility > Droidrun Portal > Toggle ON
@@ -298,7 +298,7 @@ The Portal only communicates locally via ADB. No data is sent to external server
        ```bash
        # Verify
        adb shell settings get secure default_input_method
-       # Should show: com.droidrun.portal/.DroidrunKeyboardIME
+       # Should show: com.droidrun.portal/.input.DroidrunKeyboardIME
        ```
     2. Manual switch: Long press space bar → Select "Droidrun Keyboard"
     3. Focus the element first (tap it), then input text
@@ -349,9 +349,14 @@ iOS support is currently **experimental**. Functionality is limited compared to
   </Step>
 
   <Step title="Test Connection">
+    Run a simple task to verify connectivity:
     ```bash
-    droidrun ping --ios
+    droidrun run "take a screenshot" --ios
     ```
+
+    <Note>
+    The `droidrun ping` command is Android-only (uses ADB). For iOS, run a simple task with `--ios` to verify the connection.
+    </Note>
   </Step>
 </Steps>
 
@@ -411,8 +416,8 @@ Current iOS support has these limitations:
 | Feature | Status | Notes |
 |---------|--------|-------|
 | `get_date()` | ❌ | Not available on iOS |
-| `back()` | ❌ | Raises `NotImplementedError` |
-| `drag()` | ❌ | Not implemented, returns False |
+| `back()` | ❌ | No iOS equivalent, silently ignored |
+| `drag()` | ❌ | Not supported, auto-disabled |
 | `get_apps()` | ⚠️ | Use `list_packages()` instead |
 | `input_text()` | ⚠️ | No `index` or `clear` parameters |
 | `tap()`, `swipe()` | ✅ | Fully supported |

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/guides/overview.mdx

@@ -11,7 +11,7 @@ Welcome to the Droidrun Guides! This section provides step-by-step instructions
 ### Getting Started
 
 **[CLI Reference](./cli)** - Complete command-line interface guide
-- All CLI commands (`run`, `setup`, `devices`, `connect`, `ping`, `macro`)
+- All CLI commands (`run`, `setup`, `devices`, `connect`, `disconnect`, `ping`, `macro`, `doctor`, `tui`)
 - Configuration overrides and flags
 - Environment variables and API keys
 - Common workflows and troubleshooting

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/quickstart.mdx

@@ -18,7 +18,7 @@ This guide will help you get Droidrun installed and running quickly, controlling
 
 Before installing Droidrun, ensure you have:
 
-1. **Python 3.11+** installed on your system (Python 3.14 is not currently supported)
+1. **Python 3.11-3.13** installed on your system
 2. [Android Debug Bridge (adb)](https://developer.android.com/studio/releases/platform-tools) installed and configured
 3. **Android device** with:
    - [Developer options enabled](https://developer.android.com/studio/debug/dev-options)
@@ -78,9 +78,7 @@ droidrun ping
 
 If successful, you'll see:
 ```
-✓ Portal is running
-✓ Accessibility service enabled
-✓ Device ready
+Portal is installed and accessible. You're good to go!
 ```
 
 ### Configure Your LLM

{droidrun-0.5.0.dev7 → droidrun-0.5.1.dev2}/docs/v5/sdk/base-tools.mdx

@@ -36,11 +36,11 @@ The tools architecture follows a multi-layer pattern:
 2. **Driver Implementations**: Platform-specific drivers
    - `AndroidDriver` (`tools/driver/android.py`): Android devices via ADB + Portal app
    - `IOSDriver` (`tools/driver/ios.py`): iOS devices via HTTP REST API to Portal app
-   - `StealthDriver` (`tools/driver/stealth.py`): Stealth mode driver
+   - `StealthDriver` (`tools/driver/stealth.py`): Wraps another driver, adds human-like timing jitter
    - `RecordingDriver` (`tools/driver/recording.py`): Wraps another driver with trajectory recording
    - `CloudDriver` (`tools/driver/cloud.py`): Cloud-hosted device driver
 3. **StateProvider** (`tools/ui/provider.py`): Fetches raw data from a driver, applies filters/formatters, produces `UIState`
-4. **UIState** (`tools/ui/state.py`): Parsed UI elements with element resolution (`get_element()`, `get_element_coords()`, `get_element_info()`)
+4. **UIState** (`tools/ui/state.py`): Parsed UI elements with element resolution (`get_element()`, `get_element_coords()`, `get_element_info()`, `get_clear_point()`, `convert_point()`)
 5. **ToolRegistry** (`agent/tool_registry.py`): Central registry of all agent-callable tools
 6. **ActionContext** (`agent/action_context.py`): Dependency bag passed as `ctx` kwarg to action functions
 7. **ActionResult** (`agent/action_result.py`): Structured return type (`success: bool`, `summary: str`)
@@ -103,7 +103,7 @@ class StateProvider:
     async def get_state(self) -> UIState: ...
 ```
 
-Base class for state providers. Subclass to support different platforms.
+Base class for state providers. Subclass to support different platforms. Declares a `supported` set for capability checking (e.g. `{"element_index", "convert_point"}`).
 
 ### AndroidStateProvider
 
@@ -111,7 +111,7 @@ Base class for state providers. Subclass to support different platforms.
 class AndroidStateProvider(StateProvider)
 ```
 
-Fetches state from an Android device via `driver.get_ui_tree()`. Includes retry logic (3 attempts). Applies tree filters and formatters to produce a `UIState` snapshot.
+Fetches state from an Android device via `driver.get_ui_tree()`. Includes retry logic (3 attempts). Applies tree filters and formatters to produce a `UIState` snapshot. Constructor accepts `stealth: bool` to select `StealthUIState` (randomized tap coordinates within element bounds) vs regular `UIState`.
 
 ---
 
@@ -130,6 +130,8 @@ Holds parsed UI elements for a single device state snapshot.
 - `get_element(index: int) -> Dict | None` - Recursively find an element by its index
 - `get_element_coords(index: int) -> Tuple[int, int]` - Return the centre (x, y) of an element. Raises `ValueError` when element is missing or has no bounds.
 - `get_element_info(index: int) -> Dict` - Return element metadata (text, className, type, child_texts)
+- `get_clear_point(index: int) -> Tuple[int, int]` - Find a tap point that avoids overlapping elements (falls back to centre)
+- `convert_point(x: int, y: int) -> Tuple[int, int]` - Convert point to absolute pixels if normalized mode is active
 
 **Key Attributes:**
 
@@ -138,6 +140,7 @@ Holds parsed UI elements for a single device state snapshot.
 - `focused_text` - Text of the currently focused element
 - `phone_state` - Dict with current activity, keyboard visibility, etc.
 - `screen_width` / `screen_height` - Device screen dimensions
+- `use_normalized` - Whether normalized coordinate mode is active
 
 ---
 
@@ -193,19 +196,17 @@ async def click(index: int, *, ctx: ActionContext) -> ActionResult:
 **Available actions:**
 - `click(index)` - Click UI element by index
 - `click_at(x, y)` - Click at screen coordinates
-- `click_area(area)` - Click a named screen area
+- `click_area(x1, y1, x2, y2)` - Click center of area defined by coordinates
 - `long_press(index)` - Long press UI element by index
 - `long_press_at(x, y)` - Long press at screen coordinates
-- `type(text, index)` - Input text into element
-- `type_secret(secret_id)` - Input a credential secret
-- `swipe(coordinate, coordinate2)` - Swipe gesture
+- `type(text, index, clear=False)` - Input text into element (set `clear=True` to clear field first)
+- `type_secret(secret_id, index)` - Input a credential secret into element by index
+- `swipe(coordinate, coordinate2, duration=1.0)` - Swipe gesture between two coordinate lists
 - `system_button(button)` - Press system buttons (back, home, enter)
-- `open_app(text)` - Open app by name
-- `wait(seconds)` - Wait for a duration
+- `open_app(text)` - Open app by name or description
+- `wait(duration=1.0)` - Wait for a duration in seconds
 - `remember(information)` - Store info in agent memory
-- `complete(success, reason)` - Mark task as finished
-- `get_state()` - Get accessibility tree + phone state
-- `take_screenshot()` - Capture device screen
+- `complete(success, message)` - Mark task as finished
 
 ---
 
@@ -221,9 +222,15 @@ Central registry of all agent-callable tools.
 
 **Methods:**
 
-- `register(name, fn, params, description)` - Register a single tool
-- `register_from_dict(tools_dict)` - Register tools from `{"name": {"parameters": {...}, "description": "...", "function": callable}}` format
-- `disable(tool_names)` - Remove tools by name
+- `register(name, fn, params, description, deps=None)` - Register a single tool with optional capability dependencies
+- `register_from_dict(tools_dict)` - Register tools from `{"name": {"parameters": {...}, "description": "...", "function": callable, "deps": set}}` format
+- `disable(tool_names)` - Remove tools by name (silently ignores unknown names)
+- `disable_unsupported(capabilities)` - Remove tools whose `deps` are not satisfied by the given capabilities set
+- `execute(name, args, ctx, workflow_ctx=None)` - Dispatch action by name, returns `ActionResult`
+- `get_tool_descriptions_xml(exclude=None)` - Build XML `<functions>` block for FastAgent
+- `get_tool_descriptions_text(exclude=None)` - Build text descriptions for executor prompts
+- `get_param_types(exclude=None)` - Build flat `{param_name: type_string}` map for XML coercion
+- `get_signatures(exclude=None)` - Return `{name: {parameters, description}}` dict for prompt building
 
 ---