Sync ResearchHarness runtime update

VERSION

@@ -1 +1 @@
-v0.0.38
+v0.0.39

agent_base/react_agent.py

@@ -20,6 +20,7 @@ from agent_base.provider_compat import apply_sampling_params
 from agent_base.prompt import composed_system_prompt
 from agent_base.session_state import AgentSessionState, CompactionRecord, persist_session_state, resolve_session_state_path
 from agent_base.trace_utils import FlatTraceWriter
+from agent_base.tools.custom import build_custom_tool_map
 from agent_base.tools.tooling import normalize_workspace_root
 from agent_base.tools.tool_extra import StrReplaceEditor
 from agent_base.tools.tool_file import Edit, Glob, Grep, Read, ReadImage, ReadPDF, Write
@@ -645,6 +646,16 @@ def tool_execution_batches(tool_names: Sequence[str]) -> list[list[int]]:
     return batches
 
 
+def normalized_image_inputs(images: Optional[str | Path | Sequence[str | Path]]) -> list[str | Path]:
+    if images is None:
+        return []
+    if isinstance(images, (str, Path)):
+        return [images]
+    if isinstance(images, Sequence) and not isinstance(images, (str, bytes)):
+        return list(images)
+    raise ValueError("images must be a path or a sequence of paths.")
+
+
 class MultiTurnReactAgent(BaseAgent):
     def __init__(
         self,
@@ -652,16 +663,34 @@ class MultiTurnReactAgent(BaseAgent):
         llm: Optional[Dict] = None,
         trace_dir: Optional[str] = None,
         role_prompt: Optional[str] = None,
+        workspace_root: Optional[str] = None,
+        custom_tools: Optional[Sequence[Any]] = None,
         max_llm_calls: Optional[int] = None,
         max_rounds: Optional[int] = None,
         max_runtime_seconds: Optional[int] = None,
     ):
         if not isinstance(llm, dict):
             raise ValueError("llm must be a dict configuration.")
+        custom_tool_map = build_custom_tool_map(custom_tools)
+        conflicting_tools = [name for name in custom_tool_map if name in ALL_TOOL_MAP]
+        if conflicting_tools:
+            raise ValueError(f"Custom tool names conflict with built-in tools: {conflicting_tools}")
+        tool_registry = {**ALL_TOOL_MAP, **custom_tool_map}
         requested_tools = self.resolve_function_list(function_list)
         if requested_tools is None:
             requested_tools = list(AVAILABLE_TOOL_MAP.keys())
-        unknown_tools = [tool for tool in requested_tools if tool not in ALL_TOOL_MAP]
+        for tool_name in custom_tool_map:
+            if tool_name not in requested_tools:
+                requested_tools.append(tool_name)
+        duplicate_tools: list[str] = []
+        seen_tools: set[str] = set()
+        for tool_name in requested_tools:
+            if tool_name in seen_tools and tool_name not in duplicate_tools:
+                duplicate_tools.append(tool_name)
+            seen_tools.add(tool_name)
+        if duplicate_tools:
+            raise ValueError(f"Duplicate tools requested: {duplicate_tools}")
+        unknown_tools = [tool for tool in requested_tools if tool not in tool_registry]
         if unknown_tools:
             raise ValueError(f"Unknown tools requested: {unknown_tools}")
         if "model" not in llm or not str(llm["model"]).strip():
@@ -669,7 +698,7 @@ class MultiTurnReactAgent(BaseAgent):
         if "generate_cfg" not in llm or not isinstance(llm["generate_cfg"], dict):
             raise ValueError('llm["generate_cfg"] must be a dict.')
 
-        self.tool_map = {tool_name: ALL_TOOL_MAP[tool_name] for tool_name in requested_tools}
+        self.tool_map = {tool_name: tool_registry[tool_name] for tool_name in requested_tools}
         self.tool_names = list(self.tool_map.keys())
         self.model = str(llm["model"])
         self.llm_generate_cfg = llm["generate_cfg"]
@@ -677,6 +706,7 @@ class MultiTurnReactAgent(BaseAgent):
         self.trace_path: Optional[Path] = None
         self.session_state_path: Optional[Path] = None
         self.role_prompt = self.resolve_role_prompt(role_prompt)
+        self.workspace_root = normalize_workspace_root(workspace_root) if workspace_root else None
         self.max_llm_calls = int(max_llm_calls) if max_llm_calls is not None else max_llm_calls_per_run()
         self.max_rounds = int(max_rounds) if max_rounds is not None else max_agent_rounds()
         self.max_runtime_seconds = (
@@ -873,9 +903,34 @@ class MultiTurnReactAgent(BaseAgent):
                 )
         return token_count
 
-    def run(self, prompt: str, workspace_root: Optional[str] = None) -> str:
+    def run(
+        self,
+        prompt: str,
+        workspace_root: Optional[str] = None,
+        images: Optional[str | Path | Sequence[str | Path]] = None,
+    ) -> str:
         """Run the agent on one prompt and return only the final result text."""
-        return self._run_session(prompt, workspace_root=workspace_root)["result_text"]
+        resolved_workspace_root = normalize_workspace_root(
+            workspace_root if workspace_root is not None else self.workspace_root
+        )
+        run_prompt = prompt
+        initial_content_parts: list[dict[str, Any]] = []
+        saved_image_paths: list[str] = []
+        for image_index, image_path in enumerate(normalized_image_inputs(images)):
+            saved_path, data_url = stage_image_file_for_input(
+                image_path,
+                workspace_root=resolved_workspace_root,
+                image_index=image_index,
+            )
+            saved_image_paths.append(saved_path)
+            initial_content_parts.extend(image_input_content_parts(data_url, saved_path))
+        if saved_image_paths:
+            run_prompt = append_saved_image_paths_to_prompt(prompt, saved_image_paths)
+        return self._run_session(
+            run_prompt,
+            workspace_root=str(resolved_workspace_root),
+            initial_content_parts=initial_content_parts or None,
+        )["result_text"]
 
     def _run_session(
         self,
@@ -891,7 +946,9 @@ class MultiTurnReactAgent(BaseAgent):
             raise ValueError("prompt must be a non-empty string.")
 
         prompt_text = prompt.strip()
-        resolved_workspace_root = normalize_workspace_root(workspace_root)
+        resolved_workspace_root = normalize_workspace_root(
+            workspace_root if workspace_root is not None else self.workspace_root
+        )
         start_time = time.time()
         trace_dir = self.trace_dir
         cur_date = today_date()

agent_base/tools/custom.py

@@ -0,0 +1,188 @@
+"""Python function tools for the public ResearchHarness embedding API."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Callable, Sequence as AbcSequence
+from types import UnionType
+from typing import Any, Literal, Sequence, Union, get_args, get_origin, get_type_hints
+
+from agent_base.tools.tooling import ToolBase
+
+
+TOOL_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]{0,63}$")
+CONTEXT_PARAMETER_NAMES = frozenset({"workspace_root", "runtime_deadline", "model_name"})
+
+
+class FunctionTool(ToolBase):
+    """ToolBase adapter for a validated Python function."""
+
+    def __init__(self, func: Callable[..., Any], *, name: str | None = None, description: str | None = None):
+        self.func = func
+        self._context_parameters: set[str] = set()
+        self.name = _resolve_tool_name(func, name)
+        self.description = _resolve_tool_description(func, description)
+        self.parameters = _schema_from_signature(func, self._context_parameters)
+        super().__init__()
+
+    def call(self, params: str | dict[str, Any], **kwargs: Any) -> Any:
+        parsed = self.parse_json_args(params)
+        call_kwargs = dict(parsed)
+        for name in self._context_parameters:
+            if name in kwargs:
+                call_kwargs[name] = kwargs[name]
+        return self.func(**call_kwargs)
+
+
+def tool(
+    func: Callable[..., Any] | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Callable[..., Any]:
+    """Mark a Python function as a ResearchHarness custom tool.
+
+    The decorated function remains directly callable. ResearchHarness converts it
+    into a ToolBase instance when passed to create_agent(tools=[...]).
+    """
+
+    def decorate(inner: Callable[..., Any]) -> Callable[..., Any]:
+        if not callable(inner):
+            raise TypeError("@tool can only decorate a callable.")
+        setattr(inner, "__researchharness_tool__", {"name": name, "description": description})
+        return inner
+
+    if func is None:
+        return decorate
+    return decorate(func)
+
+
+def build_custom_tool_map(custom_tools: Sequence[Any] | None) -> dict[str, ToolBase]:
+    """Validate and instantiate user-provided custom tools."""
+
+    resolved: dict[str, ToolBase] = {}
+    for item in custom_tools or []:
+        tool_obj = _coerce_custom_tool(item)
+        if tool_obj.name in resolved:
+            raise ValueError(f"Duplicate custom tool name: {tool_obj.name}")
+        resolved[tool_obj.name] = tool_obj
+    return resolved
+
+
+def _coerce_custom_tool(item: Any) -> ToolBase:
+    if isinstance(item, ToolBase):
+        return item
+    if callable(item):
+        metadata = getattr(item, "__researchharness_tool__", None)
+        if not isinstance(metadata, dict):
+            raise ValueError(
+                f"Custom tool function {getattr(item, '__name__', item)!r} must be decorated with @researchharness.tool."
+            )
+        return FunctionTool(
+            item,
+            name=metadata.get("name"),
+            description=metadata.get("description"),
+        )
+    raise ValueError(f"Custom tool must be a decorated function or ToolBase instance, got {type(item).__name__}.")
+
+
+def _resolve_tool_name(func: Callable[..., Any], override: str | None) -> str:
+    name = str(override or getattr(func, "__name__", "")).strip()
+    if not name:
+        raise ValueError("Custom tool name must be non-empty.")
+    if not TOOL_NAME_RE.fullmatch(name):
+        raise ValueError(
+            f"Invalid custom tool name {name!r}. Use 1-64 characters: letters, numbers, underscore, or hyphen; start with a letter or underscore."
+        )
+    return name
+
+
+def _resolve_tool_description(func: Callable[..., Any], override: str | None) -> str:
+    description = str(override or inspect.getdoc(func) or "").strip()
+    if not description:
+        raise ValueError(f"Custom tool {getattr(func, '__name__', '<callable>')!r} must have a docstring or description.")
+    return description
+
+
+def _schema_from_signature(func: Callable[..., Any], context_parameters: set[str]) -> dict[str, Any]:
+    signature = inspect.signature(func)
+    try:
+        hints = get_type_hints(func)
+    except Exception as exc:
+        raise ValueError(f"Could not resolve type hints for custom tool {func.__name__}: {exc}") from exc
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for param in signature.parameters.values():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            raise ValueError(f"Custom tool {func.__name__} may not use *args or **kwargs.")
+        if param.kind == inspect.Parameter.POSITIONAL_ONLY:
+            raise ValueError(f"Custom tool {func.__name__} may not use positional-only parameters.")
+        if param.name in CONTEXT_PARAMETER_NAMES:
+            if param.kind is not inspect.Parameter.KEYWORD_ONLY:
+                raise ValueError(f"Context parameter {param.name!r} in custom tool {func.__name__} must be keyword-only.")
+            context_parameters.add(param.name)
+            continue
+        if param.name not in hints:
+            raise ValueError(f"Custom tool {func.__name__} parameter {param.name!r} must have a type annotation.")
+        schema, nullable = _annotation_to_schema(hints[param.name], f"{func.__name__}.{param.name}")
+        if param.default is inspect.Parameter.empty and not nullable:
+            required.append(param.name)
+        elif param.default is not inspect.Parameter.empty:
+            schema["default"] = param.default
+        properties[param.name] = schema
+
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+        "additionalProperties": False,
+    }
+
+
+def _annotation_to_schema(annotation: Any, label: str) -> tuple[dict[str, Any], bool]:
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if annotation is Any:
+        raise ValueError(f"Custom tool parameter {label} may not use Any; use a concrete JSON-compatible type.")
+    if origin in (UnionType, Union):
+        non_none = [arg for arg in args if arg is not type(None)]
+        if len(non_none) == 1 and len(non_none) != len(args):
+            schema, _ = _annotation_to_schema(non_none[0], label)
+            return schema, True
+        raise ValueError(f"Custom tool parameter {label} uses an unsupported union type.")
+    if origin is Literal:
+        values = list(args)
+        if not values:
+            raise ValueError(f"Custom tool parameter {label} uses an empty Literal.")
+        value_types = {type(value) for value in values}
+        if len(value_types) != 1 or next(iter(value_types)) not in {str, int, float, bool}:
+            raise ValueError(f"Custom tool parameter {label} uses unsupported Literal values.")
+        schema, _ = _annotation_to_schema(type(values[0]), label)
+        schema["enum"] = values
+        return schema, False
+    if annotation is str:
+        return {"type": "string"}, False
+    if annotation is int:
+        return {"type": "integer"}, False
+    if annotation is float:
+        return {"type": "number"}, False
+    if annotation is bool:
+        return {"type": "boolean"}, False
+    if annotation is dict:
+        return {"type": "object"}, False
+    if annotation in (list, tuple):
+        return {"type": "array"}, False
+    if origin in (list, tuple, Sequence, AbcSequence):
+        item_schema: dict[str, Any] = {}
+        if args and args[0] is not Ellipsis:
+            item_schema, _ = _annotation_to_schema(args[0], label)
+        return {"type": "array", "items": item_schema}, False
+    if origin is dict:
+        key_type = args[0] if args else str
+        if key_type is not str:
+            raise ValueError(f"Custom tool parameter {label} dict keys must be str.")
+        return {"type": "object"}, False
+    raise ValueError(f"Custom tool parameter {label} has unsupported type annotation: {annotation!r}")