openhands-tools 1.29.2__tar.gz → 1.30.0__tar.gz

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-tools
-Version: 1.29.2
+Version: 1.30.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.29.2 → openhands_tools-1.30.0}/openhands/tools/apply_patch/core.py

@@ -59,7 +59,9 @@ def assemble_changes(
                     old_content=old_content,
                 )
             else:
-                assert False
+                raise DiffError(
+                    f"Unexpected state: path '{path}' exists in neither orig nor dest"
+                )
     return commit
 
 
@@ -95,13 +97,15 @@ class Parser(BaseModel):
         return False
 
     def startswith(self, prefix: str | tuple[str, ...]) -> bool:
-        assert self.index < len(self.lines), f"Index: {self.index} >= {len(self.lines)}"
+        if self.index >= len(self.lines):
+            raise DiffError(f"Unexpected end of patch at index {self.index}")
         if self.lines[self.index].startswith(prefix):
             return True
         return False
 
     def read_str(self, prefix: str = "", return_everything: bool = False) -> str:
-        assert self.index < len(self.lines), f"Index: {self.index} >= {len(self.lines)}"
+        if self.index >= len(self.lines):
+            raise DiffError(f"Unexpected end of patch at index {self.index}")
         line = self.lines[self.index]
         if line.startswith(prefix):
             text = line if return_everything else line[len(prefix) :]
@@ -116,11 +120,15 @@ class Parser(BaseModel):
                 if path in self.patch.actions:
                     raise DiffError(f"Update File Error: Duplicate Path: {path}")
                 move_to = self.read_str("*** Move to: ")
+                if move_to and (".." in move_to.split("/") or move_to.startswith("/")):
+                    raise DiffError(
+                        f"Update File Error: Invalid move path '{move_to}': "
+                        "must be a relative path without '..' components"
+                    )
                 if path not in self.current_files:
                     raise DiffError(f"Update File Error: Missing File: {path}")
                 text = self.current_files[path]
                 action = self.parse_update_file(text)
-                # TODO: Check move_to is valid
                 action.move_path = move_to
                 self.patch.actions[path] = action
                 continue
@@ -359,7 +367,10 @@ def identify_files_needed(text: str) -> list[str]:
 
 
 def _get_updated_file(text: str, action: PatchAction, path: str) -> str:
-    assert action.type == ActionType.UPDATE
+    if action.type != ActionType.UPDATE:
+        raise DiffError(
+            f"_get_updated_file: expected UPDATE action for '{path}', got {action.type}"
+        )
     orig_lines = text.split("\n")
     dest_lines = []
     orig_index = 0
@@ -375,7 +386,6 @@ def _get_updated_file(text: str, action: PatchAction, path: str) -> str:
                 f"_get_updated_file: {path}: orig_index {orig_index} > "
                 f"chunk.orig_index {chunk.orig_index}"
             )
-        assert orig_index <= chunk.orig_index
         dest_lines.extend(orig_lines[orig_index : chunk.orig_index])
         delta = chunk.orig_index - orig_index
         orig_index += delta
@@ -389,8 +399,16 @@ def _get_updated_file(text: str, action: PatchAction, path: str) -> str:
     delta = len(orig_lines) - orig_index
     orig_index += delta
     dest_index += delta
-    assert orig_index == len(orig_lines)
-    assert dest_index == len(dest_lines)
+    if orig_index != len(orig_lines):
+        raise DiffError(
+            f"_get_updated_file: {path}: did not consume all original lines "
+            f"(orig_index={orig_index}, len={len(orig_lines)})"
+        )
+    if dest_index != len(dest_lines):
+        raise DiffError(
+            f"_get_updated_file: {path}: dest line count mismatch "
+            f"(dest_index={dest_index}, len={len(dest_lines)})"
+        )
     return "\n".join(dest_lines)
 
 
@@ -449,10 +467,14 @@ def apply_commit(
         if change.type == ActionType.DELETE:
             remove_fn(path)
         elif change.type == ActionType.ADD:
-            assert change.new_content is not None
+            if change.new_content is None:
+                raise DiffError(f"apply_commit: ADD change for '{path}' has no content")
             write_fn(path, change.new_content)
         elif change.type == ActionType.UPDATE:
-            assert change.new_content is not None
+            if change.new_content is None:
+                raise DiffError(
+                    f"apply_commit: UPDATE change for '{path}' has no content"
+                )
             if change.move_path:
                 write_fn(change.move_path, change.new_content)
                 remove_fn(path)
@@ -470,7 +492,8 @@ def process_patch(
 
     Returns (message, fuzz, commit)
     """
-    assert text.startswith("*** Begin Patch")
+    if not text.startswith("*** Begin Patch"):
+        raise DiffError("Invalid patch: must start with '*** Begin Patch'")
     paths = identify_files_needed(text)
     orig = load_files(paths, open_fn)
     patch, fuzz = text_to_patch(text, orig)

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/apply_patch/definition.py

@@ -77,7 +77,7 @@ class ApplyPatchExecutor(ToolExecutor[ApplyPatchAction, ApplyPatchObservation]):
             if not p.startswith("/")
             else Path(p).resolve()
         )
-        if not str(pth).startswith(str(self.workspace_root)):
+        if not pth.is_relative_to(self.workspace_root):
             raise DiffError("Absolute or escaping paths are not allowed")
         return pth
 

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/file_editor/editor.py

@@ -214,9 +214,11 @@ class FileEditor:
         if not occurrences:
             # We found no occurrences, possibly because of extra white spaces at
             # either the front or back of the string.
-            # Remove the white spaces and try again.
+            # Strip old_str to retry the *match* only. Do NOT strip new_str: it
+            # is the replacement content, and stripping it would silently drop
+            # meaningful leading/trailing whitespace (e.g. a Markdown hard line
+            # break or intentional indentation) the caller asked to write.
             old_str = old_str.strip()
-            new_str = new_str.strip()
             pattern = re.escape(old_str)
             occurrences = [
                 (

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/gemini/edit/impl.py

@@ -1,6 +1,5 @@
 """Edit tool executor implementation."""
 
-import os
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -43,11 +42,7 @@ class EditExecutor(ToolExecutor[EditAction, EditObservation]):
         new_string = action.new_string
         expected_replacements = action.expected_replacements
 
-        # Resolve path relative to workspace
-        if not os.path.isabs(file_path):
-            resolved_path = self.workspace_root / file_path
-        else:
-            resolved_path = Path(file_path)
+        resolved_path = (self.workspace_root / file_path).resolve()
 
         # Handle file creation (old_string is empty)
         if old_string == "":

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/preset/__init__.py

@@ -18,13 +18,18 @@ Notes:
   setups.
 """
 
-from .default import get_default_agent, register_builtins_agents
+from .default import (
+    discover_builtin_agents,
+    get_default_agent,
+    register_builtins_agents,
+)
 from .gemini import get_gemini_agent, get_gemini_tools
 from .gpt5 import get_gpt5_agent
 from .planning import get_planning_agent
 
 
 __all__ = [
+    "discover_builtin_agents",
     "get_default_agent",
     "get_gemini_agent",
     "get_gemini_tools",

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/preset/default.py

@@ -7,7 +7,7 @@ from openhands.sdk.context.condenser import default_condenser
 from openhands.sdk.context.condenser.base import CondenserBase
 from openhands.sdk.llm.llm import LLM
 from openhands.sdk.logger import get_logger
-from openhands.sdk.subagent import register_agent_if_absent
+from openhands.sdk.subagent import AgentDefinition, register_agent_if_absent
 from openhands.sdk.tool import Tool
 
 
@@ -89,20 +89,18 @@ def get_default_agent(
     return agent
 
 
-def register_builtins_agents(enable_browser: bool = True) -> list[str]:
-    """Load and register builtin agents from ``subagent/*.md``.
-    They are registered via `register_agent_if_absent` and will not
-    overwrite agents already registered by programmatic calls, plugins,
-    or project/user-level file-based definitions.
+def discover_builtin_agents(enable_browser: bool = True) -> list[AgentDefinition]:
+    """Load builtin agent definitions (``level='builtin'``) without registering them.
+
+    Non-mutating counterpart to ``register_builtins_agents``. Browser-only agents
+    are skipped when ``enable_browser`` is False.
+
     Args:
-        enable_browser: Whether browser tools are available. When False,
-            agents that require browser tools (e.g. web researcher) are
-            skipped.
+        enable_browser: When False, skip agents needing browser tools (web researcher).
+
     Returns:
-        List of agents which were actually registered.
+        Builtin agent definitions with ``level="builtin"``.
     """
-    register_default_tools(enable_browser=enable_browser)
-
     subagent_dir = Path(__file__).parent / "subagents"
     builtins_agents_def = load_agents_from_dir(subagent_dir)
 
@@ -115,6 +113,28 @@ def register_builtins_agents(enable_browser: bool = True) -> list[str]:
             if agent.name not in _browser_only_agents
         ]
 
+    return [
+        agent_def.model_copy(update={"level": "builtin"})
+        for agent_def in builtins_agents_def
+    ]
+
+
+def register_builtins_agents(enable_browser: bool = True) -> list[str]:
+    """Load and register builtin agents from ``subagent/*.md``.
+    They are registered via `register_agent_if_absent` and will not
+    overwrite agents already registered by programmatic calls, plugins,
+    or project/user-level file-based definitions.
+    Args:
+        enable_browser: Whether browser tools are available. When False,
+            agents that require browser tools (e.g. web researcher) are
+            skipped.
+    Returns:
+        List of agents which were actually registered.
+    """
+    register_default_tools(enable_browser=enable_browser)
+
+    builtins_agents_def = discover_builtin_agents(enable_browser=enable_browser)
+
     registered: list[str] = []
     for agent_def in builtins_agents_def:
         factory = agent_definition_to_factory(agent_def)

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/task/manager.py

@@ -312,6 +312,7 @@ class TaskManager:
             max_budget_per_run=max_budget_per_run,
             hook_config=hook_config,
             delete_on_close=True,
+            prompt_cache_key=str(parent.state.id),
         )
 
     def _get_sub_agent(self, subagent_type: str) -> Agent:

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/terminal/definition.py

@@ -2,7 +2,7 @@
 
 import os
 import platform
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import TYPE_CHECKING, Literal
 
 from pydantic import Field
@@ -288,6 +288,8 @@ class TerminalTool(ToolDefinition[TerminalAction, TerminalObservation]):
         terminal_type: Literal["tmux", "subprocess", "powershell"] | None = None,
         shell_path: str | None = None,
         executor: ToolExecutor | None = None,
+        *,
+        env: Mapping[str, str] | None = None,
     ) -> Sequence["TerminalTool"]:
         """Initialize TerminalTool with executor parameters.
 
@@ -305,6 +307,9 @@ class TerminalTool(ToolDefinition[TerminalAction, TerminalObservation]):
             shell_path: Path to the shell binary. On Unix this applies to the
                        subprocess backend; on Windows it can point to a
                        PowerShell executable.
+            env: Extra environment variables to add to the terminal session.
+                 These are client-controlled session settings and are not part
+                 of the LLM-facing TerminalAction schema.
         """
         # Import here to avoid circular imports
         from openhands.tools.terminal.impl import TerminalExecutor
@@ -321,6 +326,7 @@ class TerminalTool(ToolDefinition[TerminalAction, TerminalObservation]):
                 no_change_timeout_seconds=no_change_timeout_seconds,
                 terminal_type=terminal_type,
                 shell_path=shell_path,
+                env=env,
                 full_output_save_dir=conv_state.env_observation_persistence_dir,
             )
 

openhands_tools-1.30.0/openhands/tools/terminal/env.py

@@ -0,0 +1,39 @@
+"""Environment helpers for terminal backends."""
+
+import re
+from collections.abc import Mapping
+
+from openhands.sdk.utils import sanitized_env
+
+
+ENV_VAR_NAME_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def normalize_terminal_env(
+    extra_env: Mapping[str, str] | None,
+) -> dict[str, str] | None:
+    """Validate and copy client-provided terminal environment variables."""
+    if extra_env is None:
+        return None
+
+    normalized: dict[str, str] = {}
+    for key, value in extra_env.items():
+        if not isinstance(key, str) or not ENV_VAR_NAME_RE.match(key):
+            raise ValueError(f"Invalid terminal environment variable name: {key!r}")
+        if not isinstance(value, str):
+            raise TypeError(
+                "Terminal environment variable values must be strings: "
+                f"{key!r}={value!r}"
+            )
+        normalized[key] = value
+    return normalized
+
+
+def build_terminal_env(extra_env: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Return the sanitized process environment plus client-provided overrides."""
+    env = sanitized_env()
+    normalized = normalize_terminal_env(extra_env)
+    if normalized:
+        env.update(normalized)
+        env = sanitized_env(env)
+    return env

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/terminal/impl.py

@@ -1,6 +1,6 @@
-import re
 import threading
 import time
+from collections.abc import Mapping
 from contextlib import suppress
 from typing import TYPE_CHECKING, Literal
 
@@ -20,6 +20,10 @@ from openhands.tools.terminal.definition import (
     TerminalObservation,
     looks_like_python_literal_argument,
 )
+from openhands.tools.terminal.env import (
+    ENV_VAR_NAME_RE,
+    normalize_terminal_env,
+)
 from openhands.tools.terminal.terminal.factory import (
     _is_tmux_available,
     create_terminal_session,
@@ -55,10 +59,6 @@ _TMUX_RECOVERABLE_ERROR_MARKERS = (
 
 logger = get_logger(__name__)
 
-# Environment variable names must be alphanumeric + underscores, starting with
-# a letter or underscore. This guards against shell injection via key names.
-_ENV_VAR_NAME_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
-
 
 class TerminalExecutor(ToolExecutor[TerminalAction, TerminalObservation]):
     shell_path: str | None
@@ -70,6 +70,7 @@ class TerminalExecutor(ToolExecutor[TerminalAction, TerminalObservation]):
         no_change_timeout_seconds: int | None = None,
         terminal_type: Literal["tmux", "subprocess", "powershell"] | None = None,
         shell_path: str | None = None,
+        env: Mapping[str, str] | None = None,
         full_output_save_dir: str | None = None,
         max_panes: int = DEFAULT_MAX_PANES,
     ):
@@ -85,6 +86,7 @@ class TerminalExecutor(ToolExecutor[TerminalAction, TerminalObservation]):
             shell_path: Path to the shell binary. On Unix this applies to the
                        subprocess backend; on Windows it can point to a
                        PowerShell executable.
+            env: Extra environment variables to add to the terminal session.
             full_output_save_dir: Path to directory to save full output
                                   logs and files, used when truncation is needed.
             max_panes: Maximum number of concurrent panes in pool mode.
@@ -94,6 +96,7 @@ class TerminalExecutor(ToolExecutor[TerminalAction, TerminalObservation]):
         self._username = username
         self._no_change_timeout_seconds = no_change_timeout_seconds
         self._terminal_type = terminal_type
+        self._env = normalize_terminal_env(env)
         self._max_panes = max_panes
         self.full_output_save_dir: str | None = full_output_save_dir
 
@@ -115,6 +118,7 @@ class TerminalExecutor(ToolExecutor[TerminalAction, TerminalObservation]):
                 no_change_timeout_seconds=no_change_timeout_seconds,
                 terminal_type=terminal_type,
                 shell_path=shell_path,
+                env=self._env,
             )
             self._session.initialize()
             logger.info(
@@ -134,6 +138,7 @@ class TerminalExecutor(ToolExecutor[TerminalAction, TerminalObservation]):
         self._pool = TmuxPanePool(
             self._working_dir,
             self._username,
+            env=self._env,
             max_panes=self._max_panes,
         )
         self._pool.initialize()
@@ -288,7 +293,7 @@ class TerminalExecutor(ToolExecutor[TerminalAction, TerminalObservation]):
     ) -> str:
         valid: dict[str, str] = {}
         for key, value in env_vars.items():
-            if _ENV_VAR_NAME_RE.match(key):
+            if ENV_VAR_NAME_RE.match(key):
                 valid[key] = value
             else:
                 logger.warning("Skipping secret with invalid env var name: %r", key)
@@ -400,6 +405,7 @@ class TerminalExecutor(ToolExecutor[TerminalAction, TerminalObservation]):
             no_change_timeout_seconds=original_no_change_timeout,
             terminal_type=None,
             shell_path=self.shell_path,
+            env=self._env,
         )
         self._session.initialize()
 

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/terminal/terminal/factory.py

@@ -3,6 +3,7 @@
 import platform
 import subprocess
 import warnings
+from collections.abc import Mapping
 from typing import Literal
 
 from openhands.sdk.logger import get_logger
@@ -64,6 +65,7 @@ def _create_windows_terminal(
     username: str | None,
     no_change_timeout_seconds: int | None,
     shell_path: str | None,
+    env: Mapping[str, str] | None,
 ) -> TerminalSession:
     from openhands.tools.terminal.terminal.windows_terminal import WindowsTerminal
 
@@ -71,7 +73,12 @@ def _create_windows_terminal(
     if resolved_shell_path is None:
         raise RuntimeError("PowerShell is not available on this system")
 
-    terminal = WindowsTerminal(work_dir, username, shell_path=resolved_shell_path)
+    terminal = WindowsTerminal(
+        work_dir,
+        username,
+        shell_path=resolved_shell_path,
+        env=env,
+    )
     return TerminalSession(terminal, no_change_timeout_seconds)
 
 
@@ -81,6 +88,7 @@ def create_terminal_session(
     no_change_timeout_seconds: int | None = None,
     terminal_type: Literal["tmux", "subprocess", "powershell"] | None = None,
     shell_path: str | None = None,
+    env: Mapping[str, str] | None = None,
 ) -> TerminalSession:
     """Create an appropriate terminal session based on system capabilities.
 
@@ -92,6 +100,7 @@ def create_terminal_session(
             or 'powershell'). If None, auto-detect based on system capabilities.
         shell_path: Path to the shell binary. On Unix this is used for the
             subprocess backend; on Windows it can point to a PowerShell binary.
+        env: Extra environment variables to add to the terminal session.
 
     Returns:
         TerminalSession instance
@@ -106,7 +115,7 @@ def create_terminal_session(
             from openhands.tools.terminal.terminal.tmux_terminal import TmuxTerminal
 
             logger.info("Using forced TmuxTerminal")
-            terminal = TmuxTerminal(work_dir, username)
+            terminal = TmuxTerminal(work_dir, username, env=env)
             return TerminalSession(terminal, no_change_timeout_seconds)
 
         if terminal_type == "powershell":
@@ -116,6 +125,7 @@ def create_terminal_session(
                 username,
                 no_change_timeout_seconds,
                 shell_path,
+                env,
             )
 
         if terminal_type == "subprocess":
@@ -130,13 +140,14 @@ def create_terminal_session(
                     username,
                     no_change_timeout_seconds,
                     shell_path,
+                    env,
                 )
             from openhands.tools.terminal.terminal.subprocess_terminal import (
                 SubprocessTerminal,
             )
 
             logger.info("Using forced SubprocessTerminal")
-            terminal = SubprocessTerminal(work_dir, username, shell_path)
+            terminal = SubprocessTerminal(work_dir, username, shell_path, env=env)
             return TerminalSession(terminal, no_change_timeout_seconds)
 
         raise ValueError(f"Unknown session type: {terminal_type}")
@@ -148,13 +159,14 @@ def create_terminal_session(
             username,
             no_change_timeout_seconds,
             shell_path,
+            env,
         )
 
     if _is_tmux_available():
         from openhands.tools.terminal.terminal.tmux_terminal import TmuxTerminal
 
         logger.info("Auto-detected: Using TmuxTerminal (tmux available)")
-        terminal = TmuxTerminal(work_dir, username)
+        terminal = TmuxTerminal(work_dir, username, env=env)
         return TerminalSession(terminal, no_change_timeout_seconds)
 
     from openhands.tools.terminal.terminal.subprocess_terminal import (
@@ -168,5 +180,5 @@ def create_terminal_session(
     )
     logger.warning(_tmux_warning)
     warnings.warn(_tmux_warning, stacklevel=2)
-    terminal = SubprocessTerminal(work_dir, username, shell_path)
+    terminal = SubprocessTerminal(work_dir, username, shell_path, env=env)
     return TerminalSession(terminal, no_change_timeout_seconds)

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/terminal/terminal/subprocess_terminal.py

@@ -9,6 +9,7 @@ import subprocess
 import threading
 import time
 from collections import deque
+from collections.abc import Mapping
 
 
 if platform.system() == "Windows":
@@ -22,12 +23,15 @@ import pty
 import select
 
 from openhands.sdk.logger import get_logger
-from openhands.sdk.utils import sanitized_env
 from openhands.tools.terminal.constants import (
     CMD_OUTPUT_PS1_BEGIN,
     CMD_OUTPUT_PS1_END,
     HISTORY_LIMIT,
 )
+from openhands.tools.terminal.env import (
+    build_terminal_env,
+    normalize_terminal_env,
+)
 from openhands.tools.terminal.metadata import CmdOutputMetadata
 from openhands.tools.terminal.terminal import TerminalInterface
 from openhands.tools.terminal.terminal.interface import parse_ctrl_key
@@ -84,6 +88,7 @@ class SubprocessTerminal(TerminalInterface):
         work_dir: str,
         username: str | None = None,
         shell_path: str | None = None,
+        env: Mapping[str, str] | None = None,
     ):
         super().__init__(work_dir, username)
         self.PS1 = CmdOutputMetadata.to_ps1_prompt()
@@ -96,6 +101,7 @@ class SubprocessTerminal(TerminalInterface):
         self.reader_thread = None
         self._current_command_running = False
         self.shell_path = shell_path
+        self._env = normalize_terminal_env(env)
 
     # ------------------------- Lifecycle -------------------------
 
@@ -136,7 +142,7 @@ class SubprocessTerminal(TerminalInterface):
         logger.info(f"Using shell: {resolved_shell_path}")
 
         # Inherit environment variables from the parent process
-        env = sanitized_env()
+        env = build_terminal_env(self._env)
         # Disable interactive pagers (git, man, systemctl, ...) so commands that
         # auto-launch `less` on a TTY don't capture the PTY and wedge the session.
         env.setdefault("GIT_PAGER", "cat")

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/terminal/terminal/tmux_pane_pool.py

@@ -10,7 +10,7 @@ import threading
 import time
 import uuid
 from collections import deque
-from collections.abc import Iterator
+from collections.abc import Iterator, Mapping
 from contextlib import contextmanager, suppress
 from dataclasses import dataclass, field
 from typing import Final
@@ -18,13 +18,16 @@ from typing import Final
 import libtmux
 
 from openhands.sdk.logger import get_logger
-from openhands.sdk.utils import sanitized_env
 from openhands.tools.terminal.constants import (
     HISTORY_LIMIT,
     TMUX_SESSION_HEIGHT,
     TMUX_SESSION_WIDTH,
     TMUX_SOCKET_NAME,
 )
+from openhands.tools.terminal.env import (
+    build_terminal_env,
+    normalize_terminal_env,
+)
 from openhands.tools.terminal.terminal.tmux_terminal import TmuxTerminal
 
 
@@ -80,6 +83,7 @@ class TmuxPanePool:
 
     work_dir: str
     username: str | None = None
+    env: Mapping[str, str] | None = None
     max_panes: int = DEFAULT_MAX_PANES
 
     # tmux handles
@@ -105,6 +109,7 @@ class TmuxPanePool:
     def __post_init__(self) -> None:
         if self.max_panes < 1:
             raise ValueError(f"max_panes must be >= 1, but got {self.max_panes}.")
+        self.env = normalize_terminal_env(self.env)
         self._semaphore = threading.Semaphore(self.max_panes)
 
     def initialize(self) -> None:
@@ -112,7 +117,7 @@ class TmuxPanePool:
         if self._initialized:
             return
 
-        env = sanitized_env()
+        env = build_terminal_env(self.env)
         self._server = libtmux.Server(socket_name=TMUX_SOCKET_NAME, environment=env)
         session_name = f"openhands-pool-{self.username}-{uuid.uuid4()}"
         self._session = self._server.new_session(
@@ -182,7 +187,11 @@ class TmuxPanePool:
 
         # Use PooledTmuxTerminal which overrides close() to only kill
         # this terminal's window instead of the entire shared tmux session.
-        terminal = PooledTmuxTerminal(work_dir=self.work_dir, username=self.username)
+        terminal = PooledTmuxTerminal(
+            work_dir=self.work_dir,
+            username=self.username,
+            env=self.env,
+        )
         terminal.server = self._server  # type: ignore[assignment]
         terminal.session = self._session
         terminal.window = window

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/terminal/terminal/tmux_terminal.py

@@ -2,17 +2,21 @@
 
 import time
 import uuid
+from collections.abc import Mapping
 
 import libtmux
 
 from openhands.sdk.logger import get_logger
-from openhands.sdk.utils import sanitized_env
 from openhands.tools.terminal.constants import (
     HISTORY_LIMIT,
     TMUX_SESSION_HEIGHT,
     TMUX_SESSION_WIDTH,
     TMUX_SOCKET_NAME,
 )
+from openhands.tools.terminal.env import (
+    build_terminal_env,
+    normalize_terminal_env,
+)
 from openhands.tools.terminal.metadata import CmdOutputMetadata
 from openhands.tools.terminal.terminal import TerminalInterface
 from openhands.tools.terminal.terminal.interface import parse_ctrl_key
@@ -57,16 +61,18 @@ class TmuxTerminal(TerminalInterface):
         self,
         work_dir: str,
         username: str | None = None,
+        env: Mapping[str, str] | None = None,
     ):
         super().__init__(work_dir, username)
         self.PS1 = CmdOutputMetadata.to_ps1_prompt()
+        self._env = normalize_terminal_env(env)
 
     def initialize(self) -> None:
         """Initialize the tmux terminal session."""
         if self._initialized:
             return
 
-        env = sanitized_env()
+        env = build_terminal_env(self._env)
         # Disable interactive pagers (git, man, systemctl, ...) so commands that
         # auto-launch `less` on a TTY don't capture the pane and wedge the session.
         env.setdefault("GIT_PAGER", "cat")

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands/tools/terminal/terminal/windows_terminal.py

@@ -10,14 +10,18 @@ import subprocess
 import threading
 import time
 from collections import deque
+from collections.abc import Mapping
 
 from openhands.sdk.logger import get_logger
-from openhands.sdk.utils import sanitized_env
 from openhands.tools.terminal.constants import (
     CMD_OUTPUT_PS1_BEGIN,
     CMD_OUTPUT_PS1_END,
     HISTORY_LIMIT,
 )
+from openhands.tools.terminal.env import (
+    build_terminal_env,
+    normalize_terminal_env,
+)
 from openhands.tools.terminal.terminal.interface import (
     TerminalInterface,
     parse_ctrl_key,
@@ -70,6 +74,7 @@ class WindowsTerminal(TerminalInterface):
         work_dir: str,
         username: str | None = None,
         shell_path: str = "powershell.exe",
+        env: Mapping[str, str] | None = None,
     ):
         super().__init__(work_dir, username)
         self.process = None
@@ -77,6 +82,7 @@ class WindowsTerminal(TerminalInterface):
         self.output_lock = threading.Lock()
         self.reader_thread = None
         self.shell_path = shell_path
+        self._env = normalize_terminal_env(env)
         self._command_running_event = threading.Event()
         self._stop_reader = threading.Event()
         self._decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
@@ -96,7 +102,7 @@ class WindowsTerminal(TerminalInterface):
             creationflags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
             creationflags |= getattr(subprocess, "CREATE_NO_WINDOW", 0)
 
-        env = sanitized_env()
+        env = build_terminal_env(self._env)
         env.setdefault("PYTHONIOENCODING", "utf-8")
         env.setdefault("PYTHONUTF8", "1")
 

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/openhands_tools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-tools
-Version: 1.29.2
+Version: 1.30.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.29.2 → openhands_tools-1.30.0}/openhands_tools.egg-info/SOURCES.txt

@@ -15,7 +15,6 @@ pyproject.toml
 ./openhands/tools/delegate/definition.py
 ./openhands/tools/delegate/impl.py
 ./openhands/tools/delegate/visualizer.py
-./openhands/tools/delegate/templates/delegate_tool_description.j2
 ./openhands/tools/file_editor/__init__.py
 ./openhands/tools/file_editor/definition.py
 ./openhands/tools/file_editor/editor.py
@@ -70,6 +69,7 @@ pyproject.toml
 ./openhands/tools/terminal/constants.py
 ./openhands/tools/terminal/definition.py
 ./openhands/tools/terminal/descriptions.py
+./openhands/tools/terminal/env.py
 ./openhands/tools/terminal/impl.py
 ./openhands/tools/terminal/metadata.py
 ./openhands/tools/terminal/timeout_policy.py
@@ -108,7 +108,6 @@ openhands/tools/delegate/__init__.py
 openhands/tools/delegate/definition.py
 openhands/tools/delegate/impl.py
 openhands/tools/delegate/visualizer.py
-openhands/tools/delegate/templates/delegate_tool_description.j2
 openhands/tools/file_editor/__init__.py
 openhands/tools/file_editor/definition.py
 openhands/tools/file_editor/editor.py
@@ -163,6 +162,7 @@ openhands/tools/terminal/__init__.py
 openhands/tools/terminal/constants.py
 openhands/tools/terminal/definition.py
 openhands/tools/terminal/descriptions.py
+openhands/tools/terminal/env.py
 openhands/tools/terminal/impl.py
 openhands/tools/terminal/metadata.py
 openhands/tools/terminal/timeout_policy.py

{openhands_tools-1.29.2 → openhands_tools-1.30.0}/pyproject.toml

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

openhands_tools-1.29.2/openhands/tools/delegate/templates/delegate_tool_description.j2

@@ -1,27 +0,0 @@
-Delegation tool for spawning sub-agents and delegating tasks to them.
-
-This tool provides two commands:
-
-**spawn**: Initialize sub-agents with meaningful identifiers and optional types
-- Use descriptive identifiers that make sense for your use case (e.g., 'refactoring', 'run_tests', 'research')
-- Optionally specify agent types for specialized capabilities
-- Each identifier creates a separate sub-agent conversation
-- Examples:
-{% raw %}  - Default agents: {"command": "spawn", "ids": ["research", "implementation"]}
-  - Specialized agents: {"command": "spawn", "ids": ["research", "code"], "agent_types": ["researcher", "programmer"]}
-  - Mixed types: {"command": "spawn", "ids": ["research", "generic"], "agent_types": ["researcher"]}  # unspecified entries fall back to the default agent{% endraw %}
-
-**delegate**: Send tasks to specific sub-agents and wait for results
-- Use a dictionary mapping sub-agent identifiers to task descriptions
-- This is a blocking operation - waits for all sub-agents to complete
-- Returns a single observation containing results from all sub-agents
-- Example: {% raw %}{"command": "delegate", "tasks": {"research": "Find best practices for async code", "implementation": "Refactor the MyClass class"}}{% endraw %}
-
-**Available agent types:**
-{{ agent_types_info }}
-
-**Important Notes:**
-- Identifiers used in delegate must match those used in spawn
-- All operations are blocking and return comprehensive results
-- Sub-agents work in the same workspace as the main agent: {{ workspace_path }}
-- If you omit an agent type for an ID, a default general-purpose agent is used