openhands-tools 1.55.0__tar.gz → 1.56.0__tar.gz

{openhands_tools-1.55.0 → openhands_tools-1.56.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-tools
-Version: 1.55.0
+Version: 1.56.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.56.0/openhands/tools/child_conversation/__init__.py

@@ -0,0 +1,36 @@
+"""Child-conversation tool package.
+
+Provides the ``start_child_conversation`` tool: a server-executed tool that
+starts a child conversation on the same backend as its parent and returns the
+child's id and launch status to the parent agent. The launch itself is
+delegated over HTTP to a child-launch endpoint, which defaults to the
+agent-server running the tool (``POST /api/conversations/{id}/children``) and
+can be pointed elsewhere via the ``launch_url`` tool parameter so a hosting
+backend can run its own provisioning lifecycle.
+
+Usage:
+    from openhands.tools.child_conversation import StartChildConversationTool
+
+    agent = Agent(
+        llm=llm,
+        tools=[Tool(name=StartChildConversationTool.name)],
+    )
+
+The tool is registered by the agent-server; it is not part of the default
+tool preset because it requires a server to create the child on.
+"""
+
+from openhands.tools.child_conversation.definition import (
+    StartChildConversationAction,
+    StartChildConversationObservation,
+    StartChildConversationTool,
+)
+from openhands.tools.child_conversation.impl import StartChildConversationExecutor
+
+
+__all__ = [
+    "StartChildConversationAction",
+    "StartChildConversationExecutor",
+    "StartChildConversationObservation",
+    "StartChildConversationTool",
+]

openhands_tools-1.56.0/openhands/tools/child_conversation/definition.py

@@ -0,0 +1,162 @@
+"""Action, observation, and tool definitions for start_child_conversation."""
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, ClassVar, Literal, 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
+
+
+class StartChildConversationAction(Action):
+    """Action that starts a child conversation on the parent's backend."""
+
+    task: str = Field(
+        description=(
+            "Self-contained brief for the child: the goal, relevant files or "
+            "paths, constraints, and the expected deliverable. The child cannot "
+            "see this conversation's history."
+        )
+    )
+    title: str | None = Field(
+        default=None, description="Optional short title for the child conversation."
+    )
+    isolation: Literal["worktree", "shared"] = Field(
+        default="worktree",
+        description=(
+            "'worktree' gives the child its own git worktree and branch when the "
+            "workspace is a git repository; 'shared' runs it in the same directory."
+        ),
+    )
+
+    @property
+    def visualize(self) -> Text:
+        content = Text()
+        content.append("Start child conversation", style="bold cyan")
+        if self.title:
+            content.append(f": {self.title}")
+        content.append(f" [{self.isolation}]\n")
+        content.append(self.task)
+        return content
+
+
+class StartChildConversationObservation(Observation):
+    """Result of a child conversation launch."""
+
+    conversation_id: str | None = None
+    parent_conversation_id: str | None = None
+    status: str | None = None
+    title: str | None = None
+    url: str | None = None
+    workspace: str | None = None
+    isolation: Literal["worktree", "shared"] | None = None
+
+    @property
+    def visualize(self) -> Text:
+        content = Text()
+        if self.is_error:
+            content.append("Child conversation launch failed", style="bold red")
+            content.append("\n")
+            content.append(self.text)
+            return content
+        content.append("Started child conversation", style="bold green")
+        if self.title:
+            content.append(f" '{self.title}'")
+        if self.conversation_id:
+            content.append(f" ({self.conversation_id})")
+        if self.status:
+            content.append(f" - {self.status}")
+        if self.url:
+            content.append("\n")
+            content.append(self.url, style="underline")
+        return content
+
+
+_DESCRIPTION = (
+    "Start a child conversation that runs on the same backend as this "
+    "conversation, with its own agent and history, to work on a delegated task "
+    "in parallel.\n\n"
+    "The child inherits this conversation's configuration and workspace. `task` "
+    "must be a self-contained brief: the child has no access to this "
+    "conversation's history, so include the goal, relevant paths, constraints "
+    "and the expected deliverable. Use `title` to name it. `isolation` controls "
+    "the workspace: `worktree` (default) gives the child its own git worktree "
+    "and branch when the workspace is a git repository; the worktree starts "
+    "from the repository's default branch, not from this conversation's branch "
+    "or uncommitted changes, so use `shared` when the child must see them. "
+    "`shared` runs it in the same directory; backends that manage workspaces "
+    "themselves may ignore this and report what was applied.\n\n"
+    "The result contains the child's conversation id, its initial status and, "
+    "when available, a URL. Report the id and URL to the user. A launch is not "
+    "idempotent: call this once per task and do not retry a launch that already "
+    "returned a conversation id."
+)
+
+
+class StartChildConversationTool(
+    ToolDefinition[StartChildConversationAction, StartChildConversationObservation]
+):
+    """Tool that launches a same-backend child conversation."""
+
+    # Attached by the host that provides the launcher (the agent-server, or a
+    # hosting backend through ``launch_url``), not picked from the catalog.
+    user_selectable: ClassVar[bool] = False
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: "ConversationState",
+        launch_url: str | None = None,
+        **params,
+    ) -> Sequence[Self]:
+        """Create the tool bound to the current conversation.
+
+        Args:
+            conv_state: State of the conversation that becomes the parent.
+            launch_url: Optional child-launch endpoint. Defaults to the
+                agent-server running this tool; a hosting backend can point it
+                at its own launcher.
+        """
+        if params:
+            raise ValueError(
+                "StartChildConversationTool does not accept parameters: "
+                f"{sorted(params)}"
+            )
+
+        # Import here to keep module import light and avoid import cycles.
+        from openhands.tools.child_conversation.impl import (
+            StartChildConversationExecutor,
+        )
+
+        executor = StartChildConversationExecutor(
+            parent_conversation_id=conv_state.id, launch_url=launch_url
+        )
+        return [
+            cls(
+                description=_DESCRIPTION,
+                action_type=StartChildConversationAction,
+                observation_type=StartChildConversationObservation,
+                executor=executor,
+                annotations=ToolAnnotations(
+                    readOnlyHint=False,
+                    destructiveHint=False,
+                    idempotentHint=False,
+                    openWorldHint=True,
+                ),
+            )
+        ]
+
+
+# Automatically register when this module is imported.
+register_tool(StartChildConversationTool.name, StartChildConversationTool)

openhands_tools-1.56.0/openhands/tools/child_conversation/impl.py

@@ -0,0 +1,155 @@
+"""Executor for the start_child_conversation tool."""
+
+import json
+import os
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+import httpx
+from pydantic import ValidationError
+
+from openhands.sdk.conversation.request import (
+    StartChildConversationRequest,
+    StartChildConversationResponse,
+)
+from openhands.sdk.logger import get_logger
+from openhands.sdk.tool.tool import ToolExecutor
+from openhands.tools.child_conversation.definition import (
+    StartChildConversationAction,
+    StartChildConversationObservation,
+)
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+
+
+logger = get_logger(__name__)
+
+# Same seam ``LookupSecret`` uses to reach the agent-server that runs this tool.
+INTERNAL_SERVER_URL_ENV = "OH_INTERNAL_SERVER_URL"
+DEFAULT_INTERNAL_SERVER_URL = "http://127.0.0.1:8000"
+# v1 and v0 names of the agent-server session key, as exported by the server.
+SESSION_API_KEY_ENVS = ("OH_SESSION_API_KEYS_0", "SESSION_API_KEY")
+SESSION_API_KEY_HEADER = "X-Session-API-Key"
+# A launch may include worktree or sandbox provisioning; mirror the MCP tool
+# timeout rather than httpx's 5 second default.
+CHILD_LAUNCH_TIMEOUT_SECONDS = 300.0
+
+
+def default_launch_url(parent_conversation_id: UUID) -> str:
+    """Child-launch endpoint of the agent-server running this tool."""
+    base = os.getenv(INTERNAL_SERVER_URL_ENV, DEFAULT_INTERNAL_SERVER_URL).rstrip("/")
+    return f"{base}/api/conversations/{parent_conversation_id}/children"
+
+
+def session_api_key_headers() -> dict[str, str]:
+    """Auth header for the launcher, taken from the agent-server's own env.
+
+    The key identifies this server to its launcher, as it does for the
+    server's webhook subscribers. ``launch_url`` is chosen by whoever assembles
+    the conversation's agent, and the header grants that party nothing new: a
+    hosting backend minted the key, and a direct caller had to present one to
+    create the conversation.
+    """
+    for env_name in SESSION_API_KEY_ENVS:
+        value = os.getenv(env_name)
+        if value:
+            return {SESSION_API_KEY_HEADER: value}
+    return {}
+
+
+def _response_detail(response: httpx.Response) -> str:
+    try:
+        detail = response.json().get("detail")
+    except (ValueError, AttributeError):
+        detail = None
+    if isinstance(detail, str) and detail:
+        return detail
+    if detail is not None:
+        return json.dumps(detail)
+    return response.text[:500]
+
+
+class StartChildConversationExecutor(
+    ToolExecutor[StartChildConversationAction, StartChildConversationObservation]
+):
+    """POST the launch request to the child-launch endpoint and report back.
+
+    The executor is deliberately backend-agnostic: it only knows the wire
+    contract (``StartChildConversationRequest`` in,
+    ``StartChildConversationResponse`` out) and where to send it. By default it
+    targets the agent-server that runs this tool, authenticated with that
+    server's own session API key from the environment.
+    """
+
+    def __init__(
+        self,
+        parent_conversation_id: UUID,
+        launch_url: str | None = None,
+        timeout: float = CHILD_LAUNCH_TIMEOUT_SECONDS,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self.parent_conversation_id = parent_conversation_id
+        self.launch_url = launch_url
+        self.timeout = timeout
+        self._transport = transport
+
+    def __call__(
+        self,
+        action: StartChildConversationAction,
+        conversation: "LocalConversation | None" = None,  # noqa: ARG002
+    ) -> StartChildConversationObservation:
+        url = self.launch_url or default_launch_url(self.parent_conversation_id)
+        try:
+            payload = StartChildConversationRequest(
+                task=action.task, title=action.title, isolation=action.isolation
+            ).model_dump(mode="json")
+        except ValidationError as exc:
+            return self._error(f"Invalid child conversation request: {exc}")
+
+        try:
+            with httpx.Client(
+                timeout=self.timeout, transport=self._transport
+            ) as client:
+                response = client.post(
+                    url, json=payload, headers=session_api_key_headers()
+                )
+            response.raise_for_status()
+            result = StartChildConversationResponse.model_validate(response.json())
+        except httpx.HTTPStatusError as exc:
+            return self._error(
+                "Child conversation launch failed "
+                f"({exc.response.status_code}): {_response_detail(exc.response)}"
+            )
+        except httpx.TimeoutException:
+            return self._error(
+                "Child conversation launch timed out after "
+                f"{self.timeout:.0f} seconds. The child may still have been "
+                "created; check with the user before retrying."
+            )
+        except (httpx.HTTPError, ValueError, ValidationError) as exc:
+            logger.warning("start_child_conversation failed against %s: %s", url, exc)
+            return self._error(
+                f"Child conversation launch failed: {type(exc).__name__}: {exc}"
+            )
+
+        summary = (
+            f"Started child conversation {result.conversation_id} "
+            f"(status: {result.status}).\n"
+            f"{json.dumps(result.model_dump(mode='json'), indent=2)}"
+        )
+        return StartChildConversationObservation.from_text(
+            text=summary,
+            conversation_id=str(result.conversation_id),
+            parent_conversation_id=str(result.parent_conversation_id),
+            status=result.status,
+            title=result.title,
+            url=result.url,
+            workspace=result.workspace,
+            isolation=result.isolation,
+        )
+
+    @staticmethod
+    def _error(message: str) -> StartChildConversationObservation:
+        return StartChildConversationObservation.from_text(text=message, is_error=True)

{openhands_tools-1.55.0 → openhands_tools-1.56.0}/openhands/tools/terminal/terminal/tmux_terminal.py

@@ -2,6 +2,7 @@
 
 import logging
 import os
+import sys
 import time
 import uuid
 from collections.abc import Iterator, Mapping
@@ -75,7 +76,7 @@ def _install_libtmux_redaction_filter() -> None:
 
 
 @contextmanager
-def _socket_creation_lock() -> Iterator[None]:
+def _socket_creation_lock(socket_dir: Path | None = None) -> Iterator[None]:
     """Serialize socket creation with the agent-server's startup cleanup.
 
     A tmux socket exists between ``new-session`` and the recording of its owner
@@ -85,7 +86,8 @@ def _socket_creation_lock() -> Iterator[None]:
     directory, which is the one path every process sharing ``TMUX_TMPDIR``
     agrees on even while tmux has not created any socket yet.
     """
-    socket_dir = Path(os.environ.get("TMUX_TMPDIR", "/tmp")) / f"tmux-{os.getuid()}"
+    if socket_dir is None:
+        socket_dir = Path(os.environ.get("TMUX_TMPDIR", "/tmp")) / f"tmux-{os.getuid()}"
     # tmux refuses a socket directory that is group/world accessible, and
     # FileLock would create it with the umask default, so create it 0700 first.
     socket_dir.mkdir(parents=True, exist_ok=True)
@@ -124,9 +126,26 @@ def _new_owned_session(
     lock. Startup cleanup in another process takes the same lock, so it can
     never observe the socket before its owner is published.
     """
-    with _socket_creation_lock():
+    socket_name = f"{TMUX_SOCKET_NAME}-{uuid.uuid4().hex}"
+    socket_dir = Path(os.environ.get("TMUX_TMPDIR", "/tmp")) / f"tmux-{os.getuid()}"
+    socket_path = socket_dir / socket_name
+    # sun_path includes a NUL byte; limits are 108 on Linux and 104 on macOS/BSD.
+    max_socket_path = 107 if sys.platform.startswith("linux") else 103
+    fallback = (
+        os.name == "posix"
+        and len(os.fsencode(os.path.realpath(socket_path))) > max_socket_path
+    )
+    if fallback:
+        socket_dir = Path("/tmp") / f"tmux-{os.getuid()}"
+        # libtmux resolves socket_name using the process-wide TMUX_TMPDIR, so
+        # use an explicit path without changing other sessions' environment.
+        logger.warning("tmux socket path is too long; using %s", socket_dir)
+
+    with _socket_creation_lock(socket_dir):
         server = libtmux.Server(
-            socket_name=f"{TMUX_SOCKET_NAME}-{uuid.uuid4().hex}", environment=dict(env)
+            socket_name=None if fallback else socket_name,
+            socket_path=str(socket_dir / socket_name) if fallback else None,
+            environment=dict(env),
         )
         session = server.new_session(
             session_name=session_name,

{openhands_tools-1.55.0 → openhands_tools-1.56.0}/openhands_tools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-tools
-Version: 1.55.0
+Version: 1.56.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.55.0 → openhands_tools-1.56.0}/openhands_tools.egg-info/SOURCES.txt

@@ -14,6 +14,9 @@ pyproject.toml
 ./openhands/tools/browser_use/logging_fix.py
 ./openhands/tools/browser_use/recording.py
 ./openhands/tools/browser_use/server.py
+./openhands/tools/child_conversation/__init__.py
+./openhands/tools/child_conversation/definition.py
+./openhands/tools/child_conversation/impl.py
 ./openhands/tools/delegate/__init__.py
 ./openhands/tools/delegate/definition.py
 ./openhands/tools/delegate/impl.py
@@ -112,6 +115,9 @@ openhands/tools/browser_use/impl.py
 openhands/tools/browser_use/logging_fix.py
 openhands/tools/browser_use/recording.py
 openhands/tools/browser_use/server.py
+openhands/tools/child_conversation/__init__.py
+openhands/tools/child_conversation/definition.py
+openhands/tools/child_conversation/impl.py
 openhands/tools/delegate/__init__.py
 openhands/tools/delegate/definition.py
 openhands/tools/delegate/impl.py

{openhands_tools-1.55.0 → openhands_tools-1.56.0}/pyproject.toml

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