openhands-tools 1.43.0__tar.gz → 1.44.0__tar.gz

{openhands_tools-1.43.0 → openhands_tools-1.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-tools
-Version: 1.43.0
+Version: 1.44.0
 Summary: OpenHands Tools - Runtime tools for AI agents
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk

{openhands_tools-1.43.0 → openhands_tools-1.44.0}/openhands/tools/__init__.py

@@ -18,6 +18,7 @@ from ``openhands.tools.browser_use``.
 
 from importlib.metadata import PackageNotFoundError, version
 
+from openhands.tools.ask_oracle import AskOracleTool
 from openhands.tools.delegate import DelegationVisualizer
 from openhands.tools.file_editor import FileEditorTool
 from openhands.tools.preset.default import (
@@ -40,6 +41,7 @@ except PackageNotFoundError:
 
 __all__ = [
     "__version__",
+    "AskOracleTool",
     "DelegationVisualizer",
     "FileEditorTool",
     "TaskToolSet",

openhands_tools-1.44.0/openhands/tools/ask_oracle/__init__.py

@@ -0,0 +1,36 @@
+"""Ask-Oracle tool package.
+
+Provides a read-only ``ask_oracle`` tool: a one-shot, tool-less sub-agent that
+consults a stronger/more-capable LLM for a second opinion. The Oracle model is a
+saved LLM profile, resolved by convention under the name ``oracle`` (see
+``ORACLE_PROFILE_NAME``).
+
+Usage:
+    from openhands.tools.ask_oracle import AskOracleTool
+
+    agent = Agent(
+        llm=llm,
+        tools=[Tool(name=AskOracleTool.name)],
+    )
+
+The agent's active conversation LLM is never switched. The Oracle call sends only
+the Oracle system prompt plus the agent's question and optional context, without
+forwarding conversation history or tools.
+"""
+
+from openhands.tools.ask_oracle.definition import (
+    ORACLE_PROFILE_NAME,
+    AskOracleAction,
+    AskOracleObservation,
+    AskOracleTool,
+)
+from openhands.tools.ask_oracle.impl import AskOracleExecutor
+
+
+__all__ = [
+    "ORACLE_PROFILE_NAME",
+    "AskOracleAction",
+    "AskOracleObservation",
+    "AskOracleExecutor",
+    "AskOracleTool",
+]

openhands_tools-1.44.0/openhands/tools/ask_oracle/definition.py

@@ -0,0 +1,114 @@
+"""Action, observation, and tool definitions for the ask_oracle tool."""
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, Self
+
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.tool.registry import register_tool
+from openhands.sdk.tool.tool import (
+    Action,
+    Observation,
+    ToolAnnotations,
+    ToolDefinition,
+)
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.state import ConversationState
+
+
+# The Oracle model is a saved LLM profile resolved by convention under this
+# name. Save a profile named "oracle" (e.g. via LLMProfileStore.save("oracle",
+# llm)) and the tool will consult it. No agent setting or wiring is required.
+ORACLE_PROFILE_NAME: Final[str] = "oracle"
+
+
+class AskOracleAction(Action):
+    """Action for asking the Oracle for advice."""
+
+    question: str = Field(
+        description=(
+            "The specific question or dilemma to ask the Oracle about. Use this "
+            "when you are stuck, uncertain, or need a second opinion."
+        )
+    )
+    context: str | None = Field(
+        default=None,
+        description=(
+            "Optional extra context, such as approaches already tried, constraints, "
+            "or the recommendation you are considering."
+        ),
+    )
+
+    @property
+    def visualize(self) -> Text:
+        content = Text()
+        content.append("Ask Oracle: ", style="bold cyan")
+        content.append(self.question)
+        if self.context:
+            content.append("\nContext: ", style="bold")
+            content.append(self.context)
+        return content
+
+
+class AskOracleObservation(Observation):
+    """Observation returned by the Oracle consultation."""
+
+    @property
+    def visualize(self) -> Text:
+        content = Text()
+        if self.is_error:
+            content.append("Oracle consultation failed", style="bold red")
+        else:
+            content.append("Oracle recommendation", style="bold green")
+        if self.text:
+            content.append("\n")
+            content.append(self.text)
+        return content
+
+
+_DESCRIPTION = (
+    "Ask the Oracle for a second opinion. The Oracle is a smart model intended "
+    "to help with difficult reasoning.\n\n"
+    "Use this when you are stuck, uncertain, comparing approaches, or need a "
+    "higher-quality recommendation before proceeding.\n\n"
+    "Treat the Oracle's response as strong guidance and follow its recommendation "
+    "unless you have a clear reason not to."
+)
+
+
+class AskOracleTool(ToolDefinition[AskOracleAction, AskOracleObservation]):
+    """Tool for consulting the Oracle (a saved LLM profile named "oracle")."""
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: "ConversationState | None" = None,  # noqa: ARG003
+        **params,
+    ) -> Sequence[Self]:
+        if params:
+            raise ValueError("AskOracleTool does not accept parameters")
+
+        # Import here to keep module import light and avoid any import cycles.
+        from openhands.tools.ask_oracle.impl import AskOracleExecutor
+
+        return [
+            cls(
+                description=_DESCRIPTION,
+                action_type=AskOracleAction,
+                observation_type=AskOracleObservation,
+                executor=AskOracleExecutor(),
+                annotations=ToolAnnotations(
+                    readOnlyHint=True,
+                    destructiveHint=False,
+                    idempotentHint=False,
+                    openWorldHint=True,
+                ),
+            )
+        ]
+
+
+# Automatically register when this module is imported.
+register_tool(AskOracleTool.name, AskOracleTool)

openhands_tools-1.44.0/openhands/tools/ask_oracle/impl.py

@@ -0,0 +1,120 @@
+"""Executor for the ask_oracle tool."""
+
+from typing import TYPE_CHECKING
+
+from openhands.sdk.agent.utils import make_llm_completion
+from openhands.sdk.llm import Message, TextContent
+from openhands.sdk.tool.tool import ToolExecutor
+from openhands.tools.ask_oracle.definition import (
+    ORACLE_PROFILE_NAME,
+    AskOracleAction,
+    AskOracleObservation,
+)
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+
+
+ORACLE_USAGE_PREFIX = "oracle"
+
+
+_ORACLE_SYSTEM_PROMPT = """\
+You are the Oracle: a highly capable reviewer giving a second opinion to an \
+OpenHands agent.
+
+Answer the agent's question directly. Do not call tools. Do not perform work \
+directly. Give a concrete recommendation the agent can follow, including important \
+risks or caveats."""
+
+_ORACLE_USER_PROMPT_TEMPLATE = """\
+Question:
+{question}
+{context_section}"""
+
+
+class AskOracleExecutor(ToolExecutor[AskOracleAction, AskOracleObservation]):
+    """Consult the Oracle: a saved LLM profile named ``oracle``.
+
+    The Oracle is resolved by convention from the conversation's LLM profile
+    store under the name ``oracle`` (``ORACLE_PROFILE_NAME``). The call is
+    stateless: it sends only the Oracle system prompt plus the agent's question
+    and optional context, with no conversation history and no tools, and returns
+    the Oracle's text. The active conversation LLM is never switched.
+    """
+
+    def __call__(
+        self,
+        action: AskOracleAction,
+        conversation: "LocalConversation | None" = None,
+    ) -> AskOracleObservation:
+        if conversation is None:
+            return AskOracleObservation.from_text(
+                text="Cannot ask the Oracle without an active conversation.",
+                is_error=True,
+            )
+
+        try:
+            oracle_llm = conversation.get_or_create_profile_llm(
+                profile_name=ORACLE_PROFILE_NAME,
+                usage_id=f"{ORACLE_USAGE_PREFIX}:{ORACLE_PROFILE_NAME}",
+            )
+        except FileNotFoundError:
+            return AskOracleObservation.from_text(
+                text=(
+                    "The Oracle is not available because no profile named "
+                    f"'{ORACLE_PROFILE_NAME}' was found. Save one to enable it."
+                ),
+                is_error=True,
+            )
+        except ValueError as exc:
+            return AskOracleObservation.from_text(
+                text=f"The Oracle is not available: {exc}",
+                is_error=True,
+            )
+        except Exception as exc:
+            return AskOracleObservation.from_text(
+                text=f"The Oracle is not available: {type(exc).__name__}: {exc}",
+                is_error=True,
+            )
+
+        context_section = (
+            f"\nAdditional context from the agent:\n{action.context}\n"
+            if action.context
+            else ""
+        )
+        user_prompt = _ORACLE_USER_PROMPT_TEMPLATE.format(
+            question=action.question,
+            context_section=context_section,
+        )
+        messages = [
+            Message(
+                role="system",
+                content=[TextContent(text=_ORACLE_SYSTEM_PROMPT)],
+            ),
+            Message(role="user", content=[TextContent(text=user_prompt)]),
+        ]
+
+        try:
+            llm_response = make_llm_completion(oracle_llm, messages)
+        except Exception as exc:
+            return AskOracleObservation.from_text(
+                text=(
+                    "The Oracle encountered an error and did not return a "
+                    f"response: {type(exc).__name__}: {exc}"
+                ),
+                is_error=True,
+            )
+
+        oracle_text = "".join(
+            content.text
+            for content in llm_response.message.content
+            if isinstance(content, TextContent)
+        ).strip()
+        if not oracle_text:
+            return AskOracleObservation.from_text(
+                text="The Oracle did not return a response.",
+                is_error=True,
+            )
+
+        return AskOracleObservation.from_text(text=oracle_text)

{openhands_tools-1.43.0 → openhands_tools-1.44.0}/openhands/tools/browser_use/impl.py

@@ -13,6 +13,7 @@ import threading
 from collections.abc import Callable, Coroutine
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Final, TypeVar
+from uuid import uuid4
 
 
 if TYPE_CHECKING:
@@ -356,6 +357,9 @@ class BrowserToolExecutor(ToolExecutor[BrowserAction, BrowserObservation]):
                 "allowed_domains": allowed_domains or [],
                 "executable_path": executable_path,
                 "chromium_sandbox": not running_as_root,
+                "user_data_dir": str(
+                    Path.home() / ".config" / "browseruse" / "profiles" / uuid4().hex
+                ),
                 **config,
             }
 
@@ -692,6 +696,14 @@ class BrowserToolExecutor(ToolExecutor[BrowserAction, BrowserObservation]):
             except Exception as e:
                 logger.warning(f"Error during browser cleanup: {e}")
             finally:
+                # Remove the browser profile directory to avoid disk accumulation.
+                # browser_use doesn't clean up the user_data_dir on shutdown.
+                user_data_dir = self._config.get("user_data_dir")
+                if user_data_dir and "browseruse/profiles/" in user_data_dir:
+                    try:
+                        shutil.rmtree(user_data_dir, ignore_errors=True)
+                    except Exception:
+                        pass
                 try:
                     # Always close the async executor
                     self._async_executor.close()

{openhands_tools-1.43.0 → openhands_tools-1.44.0}/openhands/tools/preset/__init__.py

@@ -26,6 +26,10 @@ from .default import (
 from .gemini import get_gemini_agent, get_gemini_tools
 from .gpt5 import get_gpt5_agent
 from .planning import get_planning_agent
+from .task_outcome import (
+    TaskOutcome,
+    TaskOutcomeStatus,
+)
 
 
 __all__ = [
@@ -36,4 +40,6 @@ __all__ = [
     "get_gpt5_agent",
     "get_planning_agent",
     "register_builtins_agents",
+    "TaskOutcome",
+    "TaskOutcomeStatus",
 ]

{openhands_tools-1.43.0 → openhands_tools-1.44.0}/openhands/tools/preset/default.py

@@ -1,6 +1,7 @@
 """Default preset configuration for OpenHands agents."""
 
 from pathlib import Path
+from typing import Any
 
 from openhands.sdk import Agent, agent_definition_to_factory, load_agents_from_dir
 from openhands.sdk.context.condenser import default_condenser
@@ -9,6 +10,8 @@ from openhands.sdk.llm.llm import LLM
 from openhands.sdk.logger import get_logger
 from openhands.sdk.subagent import AgentDefinition, register_agent_if_absent
 from openhands.sdk.tool import Tool
+from openhands.sdk.tool.builtins import BUILT_IN_TOOLS, FinishTool
+from openhands.sdk.tool.registry import list_registered_tools, register_tool
 
 
 logger = get_logger(__name__)
@@ -73,11 +76,26 @@ def get_default_condenser(llm: LLM) -> CondenserBase:
 def get_default_agent(
     llm: LLM,
     cli_mode: bool = False,
+    finish_tool_response_schema: Any | None = None,
 ) -> Agent:
     tools = get_default_tools(
         # Disable browser tools in CLI mode
         enable_browser=not cli_mode,
     )
+    agent_kwargs: dict[str, Any] = {}
+    if finish_tool_response_schema is not None:
+        if FinishTool.__name__ not in list_registered_tools():
+            register_tool(FinishTool.__name__, FinishTool)
+        tools.append(
+            Tool(
+                name=FinishTool.__name__,
+                params={"response_schema": finish_tool_response_schema},
+            )
+        )
+        agent_kwargs["include_default_tools"] = [
+            tool.__name__ for tool in BUILT_IN_TOOLS if tool is not FinishTool
+        ]
+
     agent = Agent(
         llm=llm,
         tools=tools,
@@ -85,6 +103,7 @@ def get_default_agent(
         condenser=get_default_condenser(
             llm=llm.model_copy(update={"usage_id": "condenser"})
         ),
+        **agent_kwargs,
     )
     return agent
 

openhands_tools-1.44.0/openhands/tools/preset/task_outcome.py

@@ -0,0 +1,35 @@
+"""Experimental structured task outcome models for conversation finish actions."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+TaskOutcomeStatus = Literal[
+    "success",
+    "partial_success",
+    "blocked",
+    "failed",
+    "unknown",
+]
+
+
+class TaskOutcome(BaseModel):
+    """Latest semantic outcome reported for a conversation task.
+
+    Experimental: this structured response model may change as task outcome
+    reporting is refined.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    status: TaskOutcomeStatus = Field(
+        description="Agent's semantic assessment of task completion."
+    )
+    summary: str = Field(
+        alias="outcome_summary",
+        description=(
+            "Concise outcome summary. Include what was completed, blockers, "
+            "required user action, and relevant next steps."
+        ),
+    )

{openhands_tools-1.43.0 → openhands_tools-1.44.0}/openhands_tools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-tools
-Version: 1.43.0
+Version: 1.44.0
 Summary: OpenHands Tools - Runtime tools for AI agents
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk

{openhands_tools-1.43.0 → openhands_tools-1.44.0}/openhands_tools.egg-info/SOURCES.txt

@@ -4,6 +4,9 @@ pyproject.toml
 ./openhands/tools/apply_patch/__init__.py
 ./openhands/tools/apply_patch/core.py
 ./openhands/tools/apply_patch/definition.py
+./openhands/tools/ask_oracle/__init__.py
+./openhands/tools/ask_oracle/definition.py
+./openhands/tools/ask_oracle/impl.py
 ./openhands/tools/browser_use/__init__.py
 ./openhands/tools/browser_use/definition.py
 ./openhands/tools/browser_use/event_storage.py
@@ -56,6 +59,7 @@ pyproject.toml
 ./openhands/tools/preset/gemini.py
 ./openhands/tools/preset/gpt5.py
 ./openhands/tools/preset/planning.py
+./openhands/tools/preset/task_outcome.py
 ./openhands/tools/preset/subagents/bash_runner.md
 ./openhands/tools/preset/subagents/code_explorer.md
 ./openhands/tools/preset/subagents/default.md
@@ -98,6 +102,9 @@ openhands/tools/py.typed
 openhands/tools/apply_patch/__init__.py
 openhands/tools/apply_patch/core.py
 openhands/tools/apply_patch/definition.py
+openhands/tools/ask_oracle/__init__.py
+openhands/tools/ask_oracle/definition.py
+openhands/tools/ask_oracle/impl.py
 openhands/tools/browser_use/__init__.py
 openhands/tools/browser_use/definition.py
 openhands/tools/browser_use/event_storage.py
@@ -150,6 +157,7 @@ openhands/tools/preset/default.py
 openhands/tools/preset/gemini.py
 openhands/tools/preset/gpt5.py
 openhands/tools/preset/planning.py
+openhands/tools/preset/task_outcome.py
 openhands/tools/preset/subagents/bash_runner.md
 openhands/tools/preset/subagents/code_explorer.md
 openhands/tools/preset/subagents/default.md

{openhands_tools-1.43.0 → openhands_tools-1.44.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-tools"
-version = "1.43.0"
+version = "1.44.0"
 description = "OpenHands Tools - Runtime tools for AI agents"
 
 requires-python = ">=3.12"