openhands-tools 1.26.0__tar.gz → 1.27.0__tar.gz

{openhands_tools-1.26.0 → openhands_tools-1.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-tools
-Version: 1.26.0
+Version: 1.27.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.26.0 → openhands_tools-1.27.0}/openhands/tools/__init__.py

@@ -29,6 +29,7 @@ from openhands.tools.preset.default import (
 from openhands.tools.task import TaskToolSet
 from openhands.tools.task_tracker import TaskTrackerTool
 from openhands.tools.terminal import TerminalTool
+from openhands.tools.workflow import WorkflowToolSet
 
 
 try:
@@ -44,6 +45,7 @@ __all__ = [
     "TaskToolSet",
     "TaskTrackerTool",
     "TerminalTool",
+    "WorkflowToolSet",
     "get_default_agent",
     "get_default_tools",
     "register_default_tools",

{openhands_tools-1.26.0 → openhands_tools-1.27.0}/openhands/tools/browser_use/logging_fix.py

@@ -15,7 +15,7 @@ from openhands.sdk.utils.deprecation import warn_cleanup
 
 warn_cleanup(
     "Monkey patching to prevent browser_use logging interference",
-    cleanup_by="1.26.0",
+    cleanup_by="1.31.0",
     details=(
         "This workaround should be removed once browser_use fixes the "
         "problematic logging configuration code. The upstream PR #3717 "

{openhands_tools-1.26.0 → openhands_tools-1.27.0}/openhands/tools/task/manager.py

@@ -106,6 +106,23 @@ class TaskManager:
         # when the parent persists, otherwise a temporary directory.
         self._persistence_dir: Path | None = None
 
+    def attach_parent(self, conversation: LocalConversation) -> None:
+        """Attach the parent conversation used to create sub-agent tasks.
+
+        Idempotent: if a parent conversation is already attached, subsequent
+        calls with the same conversation have no effect. Calls with a different
+        conversation are also ignored, but log a warning to surface potential
+        programming errors where two subsystems try to register different parents.
+        """
+        if (
+            self._parent_conversation is not None
+            and self._parent_conversation is not conversation
+        ):
+            logger.warning(
+                "attach_parent called with a different conversation; ignoring."
+            )
+        self._ensure_parent(conversation)
+
     def _ensure_parent(self, conversation: LocalConversation) -> None:
         if self._parent_conversation is None:
             self._parent_conversation = conversation

{openhands_tools-1.26.0 → openhands_tools-1.27.0}/openhands/tools/terminal/utils/command.py

@@ -2,16 +2,14 @@
 
 import re
 
-import tree_sitter_bash
-from tree_sitter import Language, Node, Parser, Tree
+from tree_sitter import Node
 
 from openhands.sdk.logger import get_logger
+from openhands.sdk.security.shell_parser import parse
 
 
 logger = get_logger(__name__)
 
-_BASH_LANGUAGE = Language(tree_sitter_bash.language())
-
 # Regions whose contents bash takes verbatim — escape doubling stops at
 # their boundaries so operators nested inside (e.g.) a double-quoted
 # string remain untouched. Walking does not recurse into these nodes.
@@ -32,12 +30,6 @@ _PRESERVE_TYPES: frozenset[str] = frozenset(
 _ESCAPE_PATTERN: re.Pattern[bytes] = re.compile(rb"\\([;&|<>])")
 
 
-def _parse(source: bytes) -> Tree:
-    # Parser is not thread-safe; the Language is. Construct a fresh
-    # Parser per call so concurrent callers cannot trample each other.
-    return Parser(_BASH_LANGUAGE).parse(source)
-
-
 def split_bash_commands(commands: str) -> list[str]:
     """Split a multi-statement bash input into top-level statements.
 
@@ -52,10 +44,10 @@ def split_bash_commands(commands: str) -> list[str]:
         return [""]
 
     source = commands.encode()
-    tree = _parse(source)
-    root = tree.root_node
+    result = parse(commands)
+    root = result.tree.root_node
 
-    if root.has_error:
+    if result.has_error:
         logger.debug(
             "tree-sitter-bash reported parse errors; returning input as-is\n"
             "[input]: %s",
@@ -88,8 +80,8 @@ def escape_bash_special_chars(command: str) -> str:
         return ""
 
     source = command.encode()
-    tree = _parse(source)
-    if tree.root_node.has_error:
+    result = parse(command)
+    if result.has_error:
         logger.debug(
             "tree-sitter-bash reported parse errors; returning input as-is\n"
             "[input]: %s",
@@ -106,7 +98,7 @@ def escape_bash_special_chars(command: str) -> str:
         for child in node.children:
             collect(child)
 
-    collect(tree.root_node)
+    collect(result.tree.root_node)
 
     out = bytearray()
     cursor = 0

openhands_tools-1.27.0/openhands/tools/workflow/__init__.py

@@ -0,0 +1,24 @@
+"""Dynamic workflow tool for sub-agent orchestration."""
+
+from openhands.tools.workflow.definition import (
+    WorkflowAction,
+    WorkflowObservation,
+    WorkflowTool,
+    WorkflowToolSet,
+)
+from openhands.tools.workflow.impl import (
+    WorkflowContext,
+    WorkflowExecutor,
+    WorkflowScriptError,
+)
+
+
+__all__ = [
+    "WorkflowAction",
+    "WorkflowContext",
+    "WorkflowExecutor",
+    "WorkflowObservation",
+    "WorkflowScriptError",
+    "WorkflowTool",
+    "WorkflowToolSet",
+]

openhands_tools-1.27.0/openhands/tools/workflow/definition.py

@@ -0,0 +1,179 @@
+"""Dynamic workflow tool definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, Literal
+
+from pydantic import Field
+
+from openhands.sdk.tool import (
+    Action,
+    Observation,
+    ToolAnnotations,
+    ToolDefinition,
+    register_tool,
+)
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.state import ConversationState
+    from openhands.tools.workflow.impl import WorkflowExecutor
+
+
+class WorkflowAction(Action):
+    """Schema for running a Python dynamic workflow script."""
+
+    name: str = Field(description="A short name for this workflow run.")
+    script: str = Field(
+        description=(
+            "Python workflow script to run. It must define `async def main(wf):` "
+            "and coordinate work only through the provided `wf` object."
+        )
+    )
+    max_concurrency: int = Field(
+        default=8,
+        ge=1,
+        le=64,
+        description=(
+            "Maximum number of sub-agent tasks to run concurrently. "
+            "Consider 2–4 for LLM-heavy workflows to avoid hitting API rate limits."
+        ),
+    )
+
+
+class WorkflowObservation(Observation):
+    """Observation from a dynamic workflow run."""
+
+    name: str = Field(description="The workflow name that was executed.")
+    status: Literal["completed", "error"] = Field(
+        description="The workflow execution status."
+    )
+
+
+_WORKFLOW_DESCRIPTION: Final[
+    str
+] = """Run a dynamic workflow written as Python orchestration code.
+
+Use this tool for large tasks that benefit from parallel sub-agents, such as
+codebase-wide audits, independent plan reviews, security sweeps, or discovery
+work where intermediate results should stay outside the main conversation.
+
+Provide a Python script that defines exactly this entry point:
+
+```python
+async def main(wf):
+    ...
+```
+
+The script coordinates sub-agents through the `wf` object. It should not read or
+write files, run shell commands, or perform the engineering work directly.
+Sub-agents should do that work through their normal OpenHands tools and security
+policy. Scripts should use only the documented `wf` methods; private `wf`
+attributes are rejected. Large reducer inputs may be truncated before being sent
+to the reducer sub-agent.
+
+Available `wf` methods:
+- `await wf.run_agent(prompt, subagent_type="general-purpose", description=None)`
+- `await wf.map_agents(items, prompt, subagent_type="general-purpose",
+  max_concurrency=None, description=None)`
+- `await wf.reduce_agent(items, prompt, subagent_type="general-purpose",
+  description=None)`
+- `wf.flatten(values)` — flatten one level of nesting (not recursive)
+
+`subagent_type` must be a sub-agent type registered in the parent application.
+Use the same type names you registered when building your agent.
+
+Scripts must use only the documented `wf` methods listed above; calling
+`wf.close()` or any other undocumented attribute is not supported.
+
+`print()` is available for debugging but writes to the server logs, not to
+the workflow observation seen by the LLM; use the return value of `main()` to
+surface results.
+
+If one or more `map_agents` items fail, the whole call raises an
+`ExceptionGroup`. The name `ExceptionGroup` is not available by name in the
+workflow sandbox, so scripts cannot use `except*` for selective group handling.
+A plain `except Exception` will still catch the entire group. To handle partial
+failures and collect all results, design sub-agent prompts to return an error
+sentinel value instead of raising.
+
+`map_agents` accepts either a callable prompt, such as
+`lambda item: f"Review this finding: {item}"`, or a string template containing
+`{item}`.
+
+Example:
+```python
+async def main(wf):
+    strategies = ["minimal fix", "test-first", "security-focused"]
+    plans = await wf.map_agents(
+        items=strategies,
+        subagent_type="general-purpose",
+        max_concurrency=3,
+        prompt=lambda strategy: f"Create a plan using this strategy: {strategy}",
+    )
+    critiques = await wf.map_agents(
+        items=plans,
+        subagent_type="code-reviewer",
+        prompt=lambda plan: f"Adversarially critique this plan: {plan}",
+    )
+    return await wf.reduce_agent(
+        items={"plans": plans, "critiques": critiques},
+        prompt="Synthesize the safest and simplest final plan.",
+    )
+```
+
+This MVP executes generated Python in-process after best-effort validation. Treat
+running a workflow as approving generated code execution.
+"""
+
+
+class WorkflowTool(ToolDefinition[WorkflowAction, WorkflowObservation]):
+    """Low-level tool for explicit executor injection.
+
+    Prefer ``WorkflowToolSet`` for standard SDK auto-create usage.
+    Use ``WorkflowTool`` when you need to inject a custom executor
+    (e.g., in tests or extensions).
+    """
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: ConversationState | None = None,  # noqa: ARG003
+        executor: WorkflowExecutor | None = None,
+        description: str = _WORKFLOW_DESCRIPTION,
+    ) -> Sequence[WorkflowTool]:
+        from openhands.tools.workflow.impl import WorkflowExecutor
+
+        return [
+            cls(
+                action_type=WorkflowAction,
+                observation_type=WorkflowObservation,
+                description=description,
+                annotations=ToolAnnotations(
+                    title="workflow",
+                    readOnlyHint=False,
+                    destructiveHint=True,
+                    idempotentHint=False,
+                    openWorldHint=True,
+                ),
+                executor=executor if executor is not None else WorkflowExecutor(),
+            )
+        ]
+
+
+class WorkflowToolSet(ToolDefinition[WorkflowAction, WorkflowObservation]):
+    """Tool set that creates the dynamic workflow tool."""
+
+    @classmethod
+    def create(
+        cls,
+        conv_state: ConversationState,  # noqa: ARG003
+    ) -> Sequence[WorkflowTool]:
+        from openhands.tools.workflow.impl import WorkflowExecutor
+
+        return WorkflowTool.create(executor=WorkflowExecutor())
+
+
+register_tool(WorkflowToolSet.name, WorkflowToolSet)
+register_tool(WorkflowTool.name, WorkflowTool)

openhands_tools-1.27.0/openhands/tools/workflow/impl.py

@@ -0,0 +1,461 @@
+"""Implementation of the dynamic workflow tool."""
+
+from __future__ import annotations
+
+import ast
+import asyncio
+import inspect
+import json as jsonlib
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, Protocol
+
+from openhands.sdk.logger import get_logger
+from openhands.sdk.tool import ToolExecutor
+from openhands.tools.task.manager import TaskManager
+from openhands.tools.workflow.definition import WorkflowObservation
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+    from openhands.tools.workflow.definition import WorkflowAction
+
+logger = get_logger(__name__)
+
+_MAX_SCRIPT_CHARS = 20_000
+_MAX_REDUCE_INPUT_CHARS = 12_000
+_WORKFLOW_TIMEOUT_SECONDS = 3600.0  # 1 hour; prevents indefinitely hung workflows
+_UNSAFE_CALLS = frozenset(
+    {
+        "breakpoint",
+        "compile",
+        "delattr",
+        "dir",
+        "eval",
+        "exec",
+        "getattr",
+        "globals",
+        "input",
+        "locals",
+        "open",
+        "setattr",
+        "vars",
+        "__import__",
+    }
+)
+# Attribute-root deny-list is intentionally narrow: scripts cannot import
+# modules, so only names that are pre-injected via _safe_globals() need to
+# be listed here. os and subprocess are the two that would be most harmful
+# if they were ever inadvertently exposed.
+_UNSAFE_ATTRIBUTE_ROOTS = frozenset({"os", "subprocess"})
+
+
+class WorkflowScriptError(ValueError):
+    """Raised when a workflow script is invalid or unsafe."""
+
+
+class _TaskLike(Protocol):
+    result: str | None
+    error: str | None
+
+
+class _TaskStarter(Protocol):
+    def start_task(
+        self,
+        prompt: str,
+        subagent_type: str = "default",
+        resume: str | None = None,
+        description: str | None = None,
+        conversation: LocalConversation | None = None,
+    ) -> _TaskLike: ...
+
+    def close(self) -> None: ...
+
+
+class WorkflowContext:
+    """Small capability object exposed to generated workflow scripts."""
+
+    def __init__(
+        self,
+        parent_conversation: LocalConversation,
+        max_concurrency: int,
+        manager: _TaskStarter | None = None,
+    ) -> None:
+        if max_concurrency < 1:
+            raise ValueError("max_concurrency must be at least 1")
+        self._parent_conversation = parent_conversation
+        self._max_concurrency = max_concurrency
+        if manager is None:
+            task_manager = TaskManager()
+            task_manager.attach_parent(parent_conversation)
+            self._manager = task_manager
+        else:
+            self._manager = manager
+        self._semaphore: asyncio.Semaphore | None = None
+        self._closed = False
+
+    @property
+    def _default_semaphore(self) -> asyncio.Semaphore:
+        if self._semaphore is None:
+            self._semaphore = asyncio.Semaphore(self._max_concurrency)
+        return self._semaphore
+
+    async def run_agent(
+        self,
+        prompt: str,
+        subagent_type: str = "general-purpose",
+        description: str | None = None,
+    ) -> str:
+        """Run a single sub-agent task and return its final result."""
+        async with self._default_semaphore:
+            return await self._run_agent_task(
+                prompt=prompt,
+                subagent_type=subagent_type,
+                description=description,
+            )
+
+    async def _run_agent_task(
+        self,
+        prompt: str,
+        subagent_type: str,
+        description: str | None,
+    ) -> str:
+        # Note: `_TaskStarter.start_task` accepts a `resume` parameter, but
+        # workflow sub-agents are always fresh tasks; resumption is intentionally
+        # not exposed through WorkflowContext in the MVP.
+        if self._closed:
+            raise WorkflowScriptError("WorkflowContext is already closed")
+        task = await asyncio.to_thread(
+            self._manager.start_task,
+            prompt=prompt,
+            subagent_type=subagent_type,
+            description=description,
+            conversation=self._parent_conversation,
+        )
+        if task.error:
+            raise RuntimeError(task.error)
+        return task.result or ""
+
+    async def map_agents(
+        self,
+        items: Sequence[Any],
+        prompt: Callable[[Any], str] | str,
+        subagent_type: str = "general-purpose",
+        max_concurrency: int | None = None,
+        description: Callable[[Any], str] | str | None = None,
+    ) -> list[str]:
+        """Run one sub-agent task per item and return results in item order.
+
+        A per-call ``max_concurrency`` caps concurrency for this map operation
+        only; it is silently capped at the context's ``max_concurrency`` limit.
+        """
+        if max_concurrency is not None and max_concurrency < 1:
+            raise ValueError("max_concurrency must be at least 1")
+        semaphore = (
+            asyncio.Semaphore(min(max_concurrency, self._max_concurrency))
+            if max_concurrency is not None
+            else self._default_semaphore
+        )
+
+        async def run_one(index: int, item: Any) -> str:
+            rendered_prompt = _render_required_template(prompt, item)
+            rendered_description = _render_template(description, item)
+            async with semaphore:
+                try:
+                    return await self._run_agent_task(
+                        prompt=rendered_prompt,
+                        subagent_type=subagent_type,
+                        description=rendered_description,
+                    )
+                except Exception as exc:
+                    raise RuntimeError(f"[item {index + 1}] {exc}") from exc
+
+        results = await asyncio.gather(
+            *(run_one(i, item) for i, item in enumerate(items)),
+            return_exceptions=True,
+        )
+        failures = [result for result in results if isinstance(result, BaseException)]
+        if failures:
+            exceptions = [
+                failure
+                if isinstance(failure, Exception)
+                else RuntimeError(str(failure))
+                for failure in failures
+            ]
+            raise ExceptionGroup(
+                "map_agents: one or more sub-agents failed",
+                exceptions,
+            )
+        return [str(result) for result in results]
+
+    async def reduce_agent(
+        self,
+        items: Any,
+        prompt: str,
+        subagent_type: str = "general-purpose",
+        description: str | None = None,
+    ) -> str:
+        """Run a single reducer sub-agent with serialized intermediate results.
+
+        Delegates to ``run_agent``, which acquires ``_default_semaphore``.
+        Workflow scripts always await operations sequentially, so the semaphore
+        is always fully available when ``reduce_agent`` is called.
+        """
+        return await self.run_agent(
+            prompt=f"{prompt}\n\nInput:\n{_format_value(items)}",
+            subagent_type=subagent_type,
+            description=description,
+        )
+
+    def flatten(self, values: list[Any]) -> list[Any]:
+        """Flatten one list level."""
+        flattened: list[Any] = []
+        for value in values:
+            if isinstance(value, list):
+                flattened.extend(value)
+            else:
+                flattened.append(value)
+        return flattened
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._manager.close()
+
+
+def _render_required_template(template: Callable[[Any], str] | str, item: Any) -> str:
+    if callable(template):
+        return str(template(item))
+    # Plain replace avoids Python's format mini-language attribute traversal
+    # (e.g. "{item._manager}"), which would bypass the AST private-attribute guard.
+    if "{item}" not in template:
+        logger.debug(
+            "map_agents string template does not contain '{item}'; "
+            "all sub-agents will receive the same prompt."
+        )
+    # Use json.dumps for non-str items so dicts/lists and scalars are consistently
+    # serialised as JSON (booleans → true/false, None → null), matching reduce_agent.
+    serialised = item if isinstance(item, str) else jsonlib.dumps(item, default=str)
+    return template.replace("{item}", serialised)
+
+
+def _render_template(
+    template: Callable[[Any], str] | str | None, item: Any
+) -> str | None:
+    if template is None:
+        return None
+    return _render_required_template(template, item)
+
+
+def _format_value(value: Any) -> str:
+    if isinstance(value, str):
+        text = value
+    else:
+        text = jsonlib.dumps(value, indent=2, default=str)
+    if len(text) <= _MAX_REDUCE_INPUT_CHARS:
+        return text
+    # Character-boundary truncation can split mid-token in JSON; element-boundary
+    # truncation for list/dict inputs would be cleaner but is deferred post-MVP.
+    return (
+        text[:_MAX_REDUCE_INPUT_CHARS]
+        + "\n... [truncated workflow intermediate results]"
+    )
+
+
+def validate_workflow_script(script: str) -> None:
+    """Perform best-effort validation for generated workflow scripts.
+
+    Note: The private-attribute guard checks the literal name ``wf``, so aliasing
+    (e.g. ``x = wf; x._attr``) can bypass the check. The attributes accessible
+    through ``WorkflowContext`` do not expose dangerous capabilities, so this is
+    a documentation gap rather than a security gap.
+    """
+    if len(script) > _MAX_SCRIPT_CHARS:
+        raise WorkflowScriptError(
+            f"Workflow script is too large: {len(script)} > {_MAX_SCRIPT_CHARS}"
+        )
+
+    try:
+        tree = ast.parse(script)
+    except SyntaxError as e:
+        raise WorkflowScriptError(f"Workflow script has invalid syntax: {e}") from e
+
+    main_defs = [
+        node
+        for node in tree.body
+        if isinstance(node, ast.AsyncFunctionDef) and node.name == "main"
+    ]
+    if len(main_defs) != 1:
+        raise WorkflowScriptError(
+            "Workflow script must define exactly one async main(wf)"
+        )
+
+    main_args = main_defs[0].args
+    if (
+        [a.arg for a in main_args.args] != ["wf"]
+        or main_args.kwonlyargs
+        or main_args.vararg
+        or main_args.kwarg
+        or main_args.defaults
+        or main_args.posonlyargs
+    ):
+        raise WorkflowScriptError("Workflow entry point must be `async def main(wf):`")
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            raise WorkflowScriptError("Workflow scripts may not import modules")
+        if isinstance(node, ast.Name) and node.id.startswith("__"):
+            raise WorkflowScriptError("Workflow scripts may not access dunder names")
+        if isinstance(node, ast.Attribute) and node.attr.startswith("__"):
+            raise WorkflowScriptError(
+                "Workflow scripts may not access dunder attributes"
+            )
+        if (
+            isinstance(node, ast.Attribute)
+            and _attribute_root_name(node) == "wf"
+            and (node.attr.startswith("_") or node.attr == "close")
+        ):
+            raise WorkflowScriptError(
+                "Workflow scripts may not access private wf attributes"
+                " or call wf.close()"
+            )
+        if (
+            isinstance(node, ast.Attribute)
+            and _attribute_root_name(node) in _UNSAFE_ATTRIBUTE_ROOTS
+        ):
+            raise WorkflowScriptError("Workflow scripts may not access unsafe modules")
+        if (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Name)
+            and node.func.id in _UNSAFE_CALLS
+        ):
+            raise WorkflowScriptError(f"Workflow scripts may not call `{node.func.id}`")
+
+
+def _attribute_root_name(node: ast.Attribute) -> str | None:
+    value = node.value
+    while isinstance(value, ast.Attribute):
+        value = value.value
+    return value.id if isinstance(value, ast.Name) else None
+
+
+def execute_workflow_script(script: str, context: WorkflowContext) -> Any:
+    """Validate and execute a workflow script from a synchronous context."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        pass
+    else:
+        raise WorkflowScriptError(
+            "Workflow scripts must be executed from a synchronous context"
+        )
+
+    validate_workflow_script(script)
+    namespace: dict[str, Any] = {}
+    exec(compile(script, "<dynamic-workflow>", "exec"), _safe_globals(), namespace)
+    main = namespace.get("main")
+    if not inspect.iscoroutinefunction(main):
+        raise WorkflowScriptError("Workflow entry point must be async")
+
+    async def _run_with_timeout() -> Any:
+        async with asyncio.timeout(_WORKFLOW_TIMEOUT_SECONDS):
+            return await main(context)
+
+    try:
+        return asyncio.run(_run_with_timeout())
+    except TimeoutError:
+        raise WorkflowScriptError(
+            f"Workflow timed out after {_WORKFLOW_TIMEOUT_SECONDS:.0f} seconds"
+        ) from None
+
+
+def _format_exception(error: Exception) -> str:
+    if isinstance(error, ExceptionGroup):
+        details = "\n".join(
+            f"  [{index}] {exception}"
+            for index, exception in enumerate(error.exceptions, start=1)
+        )
+        return f"{error.args[0]}:\n{details}"
+    return str(error)
+
+
+def _safe_globals() -> dict[str, Any]:
+    safe_builtins = {
+        "abs": abs,
+        "all": all,
+        "any": any,
+        "bool": bool,
+        "dict": dict,
+        "enumerate": enumerate,
+        "Exception": Exception,
+        "float": float,
+        "IndexError": IndexError,
+        "int": int,
+        "isinstance": isinstance,
+        "KeyError": KeyError,
+        "len": len,
+        "list": list,
+        "max": max,
+        "min": min,
+        "print": print,
+        "range": range,
+        "repr": repr,
+        "round": round,
+        "RuntimeError": RuntimeError,
+        "set": set,
+        "sorted": sorted,
+        "str": str,
+        "sum": sum,
+        "tuple": tuple,
+        # type() is included for 1-arg introspection (e.g. type(x).__name__).
+        # 3-arg class creation is permitted; methods DEFINED IN THE SCRIPT execute in
+        # restricted globals, and the AST validator blocks __dunder__ attribute access
+        # (closing __subclasses__()-based escapes). Calls to pre-existing injected
+        # objects such as wf are not re-sandboxed, but those expose only public wf API.
+        "type": type,
+        "TypeError": TypeError,
+        "ValueError": ValueError,
+        "zip": zip,
+        "format": format,
+    }
+    return {"__builtins__": safe_builtins}
+
+
+class WorkflowExecutor(ToolExecutor["WorkflowAction", WorkflowObservation]):
+    """Executor for the dynamic workflow tool."""
+
+    def __call__(
+        self,
+        action: WorkflowAction,
+        conversation: LocalConversation | None = None,
+    ) -> WorkflowObservation:
+        if conversation is None:
+            return WorkflowObservation.from_text(
+                text="Workflow tool requires a local conversation context.",
+                name=action.name,
+                status="error",
+                is_error=True,
+            )
+
+        context = WorkflowContext(
+            parent_conversation=conversation,
+            max_concurrency=action.max_concurrency,
+        )
+        try:
+            result = execute_workflow_script(action.script, context)
+            return WorkflowObservation.from_text(
+                text=str(result),
+                name=action.name,
+                status="completed",
+            )
+        except Exception as e:
+            error_text = _format_exception(e)
+            logger.warning("Workflow '%s' failed: %s", action.name, e, exc_info=True)
+            return WorkflowObservation.from_text(
+                text=error_text,
+                name=action.name,
+                status="error",
+                is_error=True,
+            )
+        finally:
+            context.close()

{openhands_tools-1.26.0 → openhands_tools-1.27.0}/openhands_tools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-tools
-Version: 1.26.0
+Version: 1.27.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.26.0 → openhands_tools-1.27.0}/openhands_tools.egg-info/SOURCES.txt

@@ -89,6 +89,9 @@ pyproject.toml
 ./openhands/tools/tom_consult/executor.py
 ./openhands/tools/utils/__init__.py
 ./openhands/tools/utils/timeout.py
+./openhands/tools/workflow/__init__.py
+./openhands/tools/workflow/definition.py
+./openhands/tools/workflow/impl.py
 openhands/tools/__init__.py
 openhands/tools/py.typed
 openhands/tools/apply_patch/__init__.py
@@ -179,6 +182,9 @@ openhands/tools/tom_consult/definition.py
 openhands/tools/tom_consult/executor.py
 openhands/tools/utils/__init__.py
 openhands/tools/utils/timeout.py
+openhands/tools/workflow/__init__.py
+openhands/tools/workflow/definition.py
+openhands/tools/workflow/impl.py
 openhands_tools.egg-info/PKG-INFO
 openhands_tools.egg-info/SOURCES.txt
 openhands_tools.egg-info/dependency_links.txt

{openhands_tools-1.26.0 → openhands_tools-1.27.0}/pyproject.toml

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