morphsdk 0.2.5__py3-none-any.whl

morphsdk/_agent/parser.py

@@ -0,0 +1,163 @@
+"""Parsers for the string-format tool arguments the model emits.
+
+Faithful port of ``agent/parser.ts`` plus the range helpers from
+``agent/tools/finish.ts``.  These convert the loose, model-authored strings
+(``"1-50,80-90"``, ``"src/a.py:1-15 src/b.py"``) into structured ranges, exactly
+matching the TypeScript behaviour (including Windows drive-letter handling and
+whitespace-splitting of finish files).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable
+from typing import Callable
+
+from .types import FinishFileSpec, FinishLines
+
+_DRIVE_LETTER = re.compile(r"^[A-Za-z]:")
+_WHITESPACE = re.compile(r"\s+")
+
+
+def _parse_int(value: str) -> int | None:
+    """Mirror JS ``parseInt(v, 10)`` followed by ``Number.isFinite``: leading
+    integer prefix, ``None`` on failure."""
+    match = re.match(r"[+-]?\d+", value.strip())
+    return int(match.group()) if match else None
+
+
+def parse_read_lines(lines_str: str) -> dict[str, object]:
+    """Parse a ``read`` tool ``lines`` arg into ``{start,end}`` or ``{lines:[...]}``.
+
+    Mirrors ``parseReadLines``: a single range collapses to ``start``/``end``;
+    multiple ranges return a ``lines`` list of ``(start, end)`` tuples.
+    """
+    ranges: list[tuple[int, int]] = []
+    for range_str in lines_str.split(","):
+        trimmed = range_str.strip()
+        if not trimmed:
+            continue
+        parts = [_parse_int(p) for p in trimmed.split("-")]
+        if len(parts) >= 2 and parts[0] is not None and parts[1] is not None:
+            ranges.append((parts[0], parts[1]))
+        elif parts and parts[0] is not None:
+            ranges.append((parts[0], parts[0]))
+    if len(ranges) == 1:
+        return {"start": ranges[0][0], "end": ranges[0][1]}
+    if len(ranges) > 1:
+        return {"lines": ranges}
+    return {}
+
+
+def parse_finish_files(files_str: str) -> list[FinishFileSpec]:
+    """Parse a ``finish`` tool ``files`` arg into :class:`FinishFileSpec` list.
+
+    Splits on any whitespace (training uses space-separated; newlines also work),
+    then splits each token on the first ``:`` after any Windows drive prefix.
+    """
+    files: list[FinishFileSpec] = []
+    for line in _WHITESPACE.split(files_str.strip()):
+        trimmed = line.strip()
+        if not trimmed:
+            continue
+        search_from = 2 if _DRIVE_LETTER.match(trimmed) else 0
+        colon_idx = trimmed.find(":", search_from)
+        if colon_idx == -1:
+            files.append(FinishFileSpec(path=trimmed, lines="*"))
+            continue
+        file_path = trimmed[:colon_idx]
+        ranges_part = trimmed[colon_idx + 1 :]
+        if not ranges_part.strip() or ranges_part.strip() == "*":
+            files.append(FinishFileSpec(path=file_path, lines="*"))
+            continue
+        ranges: list[tuple[int, int]] = []
+        for range_str in ranges_part.split(","):
+            rt = range_str.strip()
+            if not rt:
+                continue
+            parts = [_parse_int(p) for p in rt.split("-")]
+            if len(parts) >= 2 and parts[0] is not None and parts[1] is not None:
+                ranges.append((parts[0], parts[1]))
+            elif parts and parts[0] is not None:
+                ranges.append((parts[0], parts[0]))
+        files.append(FinishFileSpec(path=file_path, lines=ranges if ranges else "*"))
+    return files
+
+
+def extract_path_from_command(command: str) -> str:
+    """Extract the directory path from an ``ls``/``find`` command string.
+
+    Mirrors ``extractPathFromCommand``: drop the binary token, then take the
+    first non-flag, non-pipe, non-paren token, defaulting to ``"."``.
+    """
+    tokens = _WHITESPACE.split(command.strip())
+    path_tokens = [
+        t
+        for t in tokens[1:]
+        if not t.startswith("-") and not t.startswith("|") and not t.startswith("\\(")
+    ]
+    return path_tokens[0] if path_tokens else "."
+
+
+def _merge_ranges(ranges: list[tuple[int, int]]) -> list[tuple[int, int]]:
+    """Sort and coalesce overlapping/adjacent ranges (mirrors ``mergeRanges``)."""
+    if not ranges:
+        return []
+    sorted_ranges = sorted(ranges, key=lambda r: r[0])
+    merged: list[tuple[int, int]] = []
+    cs, ce = sorted_ranges[0]
+    for s, e in sorted_ranges[1:]:
+        if s <= ce + 1:
+            ce = max(ce, e)
+        else:
+            merged.append((cs, ce))
+            cs, ce = s, e
+    merged.append((cs, ce))
+    return merged
+
+
+def _is_valid_range(rng: object) -> bool:
+    return (
+        isinstance(rng, (tuple, list))
+        and len(rng) >= 2
+        and isinstance(rng[0], int)
+        and isinstance(rng[1], int)
+        and rng[0] > 0
+        and rng[1] >= rng[0]
+    )
+
+
+def _extract_valid_ranges(lines: FinishLines) -> list[tuple[int, int]] | None:
+    if not isinstance(lines, list):
+        return None
+    valid = [(r[0], r[1]) for r in lines if _is_valid_range(r)]
+    return valid if valid else None
+
+
+async def read_finish_files(
+    files: list[FinishFileSpec],
+    reader: Callable[[str, int | None, int | None], Awaitable[list[str]]],
+) -> list[dict[str, object]]:
+    """Resolve finish files to concatenated content via *reader*.
+
+    Faithful port of ``readFinishFiles``: full files are read whole; ranged files
+    are merged, then each block is read and joined with the
+    ``// ... existing code, block starting at line N ...`` separators the TS uses.
+    Returns dicts with ``path`` / ``ranges`` / ``content``.
+    """
+    out: list[dict[str, object]] = []
+    for f in files:
+        valid_ranges = None if f.lines == "*" else _extract_valid_ranges(f.lines)
+        if f.lines == "*" or not valid_ranges:
+            lines = await reader(f.path, None, None)
+            out.append({"path": f.path, "ranges": "*", "content": "\n".join(lines)})
+        else:
+            ranges = _merge_ranges(valid_ranges)
+            chunks: list[str] = []
+            for i, (s, e) in enumerate(ranges):
+                if (i == 0 and s > 1) or i > 0:
+                    chunks.append(f"// ... existing code, block starting at line {s} ...")
+                lines = await reader(f.path, s, e)
+                chunks.append("\n".join(lines))
+            out.append({"path": f.path, "ranges": ranges, "content": "\n".join(chunks)})
+    return out

morphsdk/_agent/runner.py

@@ -0,0 +1,524 @@
+"""WarpGrep multi-turn agent loop (async core).
+
+Faithful port of ``agent/runner.ts``.  The loop:
+
+1. Builds an initial user message with the repo structure + search string.
+2. Each turn: enforces the context limit, calls the model, appends the assistant
+   message, executes any non-finish tool calls in parallel, appends tool results
+   plus a turn/budget hint.
+3. Stops on a ``finish`` call (resolving the selected files to content), when the
+   model stops emitting tool calls, on a model error, or at ``MAX_TURNS``.
+
+The chat-completions request shape (endpoint, model, body, tool schemas) is
+copied byte-for-byte from the TS so the paid API receives identical traffic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from morphsdk._providers.base import WarpGrepProvider
+from morphsdk._version import __version__
+
+from .config import DEFAULT_MODEL, DEFAULT_TIMEOUT_S, MAX_TURNS
+from .helpers import (
+    build_initial_state,
+    calculate_context_budget,
+    enforce_context_limit,
+    format_turn_message,
+)
+from .parser import parse_finish_files, read_finish_files
+from .tools import execute_tool
+from .types import (
+    AgentFinish,
+    AgentRunResult,
+    ChatMessage,
+    ResolvedContext,
+    ToolCallRef,
+    WarpGrepExecutionMetrics,
+    WarpGrepStep,
+    WarpGrepTurnMetrics,
+)
+
+_DEFAULT_API_URL = "https://api.morphllm.com"
+_RETRYABLE_STATUS = {429, 503}
+
+# Tool definitions sent to the model (OpenAI function-calling format).
+# Copied byte-for-byte from TOOL_SPECS in agent/runner.ts.
+TOOL_SPECS: list[dict[str, Any]] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "list_directory",
+            "description": "Execute ls or find commands to explore directory structure. Max 500 results. Common junk directories are excluded automatically.",  # noqa: E501
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Full ls or find command (e.g. ls -la src/, find . -maxdepth 2 -type f -name '*.py', find . -type d, ls -d */).",  # noqa: E501
+                    },
+                },
+                "required": ["command"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "grep_search",
+            "description": "Search for a regex pattern in file contents. Returns matching lines with file paths and line numbers. Case-insensitive. Respects .gitignore.",  # noqa: E501
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Regex pattern to search for in file contents (e.g. 'class\\s+\\w+Error', 'import|require|from', 'def (get|set|update)_user').",  # noqa: E501
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "File or directory to search in. Defaults to current working directory.",  # noqa: E501
+                    },
+                    "glob": {
+                        "type": "string",
+                        "description": "Glob pattern to filter files (e.g. '*.py', '*.{ts,tsx,js,jsx,py,go}', 'src/**/*.go', '!*.test.*').",  # noqa: E501
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Limit output to first N matching lines. Shows all matches if not specified.",  # noqa: E501
+                    },
+                },
+                "required": ["pattern"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "glob",
+            "description": "Find files by name/extension using glob patterns. Returns absolute paths sorted by modification time (newest first). Respects .gitignore. Max 100 results.",  # noqa: E501
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Glob pattern to match files (e.g. '*.py', 'src/**/*.js', '*.{ts,tsx}', 'test_*.py').",  # noqa: E501
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Directory to search in. Defaults to repository root.",
+                    },
+                },
+                "required": ["pattern"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read",
+            "description": "Read entire files or specific line ranges using absolute paths.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "File path to read, using absolute path (e.g. '/home/ubuntu/repo/src/main.py' or windows path).",  # noqa: E501
+                    },
+                    "lines": {
+                        "type": "string",
+                        "description": "Optional line range (e.g. '1-50' or '1-20,45-80'). Omit to read entire file.",  # noqa: E501
+                    },
+                },
+                "required": ["path"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "finish",
+            "description": "Submit final answer with all relevant code locations. Include imports and over-include rather than miss context.",  # noqa: E501
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "files": {
+                        "type": "string",
+                        "description": "One file per line as path:lines (e.g. 'src/auth.py:1-15,25-50\\nsrc/user.py'). Omit line range to include entire file.",  # noqa: E501
+                    },
+                },
+                "required": ["files"],
+            },
+        },
+    },
+]
+
+
+def _safe_parse_json(s: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(s)
+        return parsed if isinstance(parsed, dict) else {}
+    except (ValueError, TypeError):
+        return {}
+
+
+def _resolve_base_url(api_url: str | None) -> str:
+    """Mirror TS: append ``/v1`` only when the base URL has a root path."""
+    base = api_url or _DEFAULT_API_URL
+    # Strip a trailing slash for consistent joins.
+    trimmed = base.rstrip("/")
+    # TS: parsedUrl.pathname === '/' ? `${baseUrl}/v1` : baseUrl
+    # i.e. a bare host (no path) gets /v1 appended; an explicit path is used as-is.
+    from urllib.parse import urlparse
+
+    path = urlparse(base).path
+    if path in ("", "/"):
+        return f"{trimmed}/v1"
+    return trimmed
+
+
+async def call_model(
+    messages: list[ChatMessage],
+    model: str,
+    *,
+    api_key: str,
+    api_url: str | None = None,
+    timeout: float | None = None,
+    search_type: str | None = None,
+    max_retries: int = 3,
+) -> dict[str, Any]:
+    """POST one chat-completions request and return ``{content, tool_calls}``.
+
+    Request body matches the TS exactly: ``temperature=0.0``, ``max_tokens=2048``,
+    the warp-grep model, the full ``TOOL_SPECS`` tool list, an optional
+    ``search_type`` field, and the ``X-Morph-SDK-Version`` header.  Retries on
+    429/503 (mirroring the SDK base client), then one empty-response retry like TS.
+    """
+    base_url = _resolve_base_url(api_url)
+    endpoint = f"{base_url}/chat/completions"
+    timeout_s = timeout if timeout is not None else DEFAULT_TIMEOUT_S
+
+    body: dict[str, Any] = {
+        "model": model,
+        "temperature": 0.0,
+        "max_tokens": 2048,
+        "messages": [m.to_wire() for m in messages],
+        "tools": TOOL_SPECS,
+    }
+    if search_type:
+        body["search_type"] = search_type
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "X-Morph-SDK-Version": __version__,
+        "X-Morph-SDK-Lang": "python",
+    }
+
+    max_empty_retries = 1
+    async with httpx.AsyncClient(timeout=httpx.Timeout(timeout_s)) as client:
+        for attempt in range(max_empty_retries + 1):
+            data = await _post_with_retry(client, endpoint, body, headers, max_retries)
+            choice = (data.get("choices") or [{}])[0]
+            message = choice.get("message")
+            if not message:
+                if attempt == max_empty_retries:
+                    raise RuntimeError("Invalid response from model: no message in response")
+                await asyncio.sleep(0.2)
+                continue
+
+            tool_calls = [
+                ToolCallRef(
+                    id=tc["id"],
+                    name=tc["function"]["name"],
+                    arguments=tc["function"]["arguments"],
+                )
+                for tc in (message.get("tool_calls") or [])
+            ]
+            content = message.get("content")
+            if content or tool_calls:
+                return {"content": content, "tool_calls": tool_calls}
+
+            if attempt == max_empty_retries:
+                finish_reason = choice.get("finish_reason", "unknown")
+                raise RuntimeError(
+                    "Invalid response from model: no content and no tool_calls, "
+                    f"finish_reason={finish_reason}"
+                )
+            await asyncio.sleep(0.2)
+
+    raise RuntimeError("Invalid response from model")
+
+
+async def _post_with_retry(
+    client: httpx.AsyncClient,
+    endpoint: str,
+    body: dict[str, Any],
+    headers: dict[str, str],
+    max_retries: int,
+) -> dict[str, Any]:
+    """POST with 429/503 retry-with-backoff, mirroring ``_base.py`` semantics."""
+    delay = 1.0
+    last_exc: Exception | None = None
+    for attempt in range(max_retries + 1):
+        try:
+            res = await client.post(endpoint, json=body, headers=headers)
+        except httpx.TimeoutException as err:
+            last_exc = err
+            if attempt < max_retries:
+                await asyncio.sleep(min(delay, 30.0))
+                delay *= 2.0
+                continue
+            raise
+        if res.status_code in _RETRYABLE_STATUS and attempt < max_retries:
+            retry_after = res.headers.get("Retry-After")
+            wait = float(retry_after) if retry_after else min(delay, 30.0)
+            await asyncio.sleep(wait)
+            delay *= 2.0
+            continue
+        res.raise_for_status()
+        data: dict[str, Any] = res.json()
+        return data
+    if last_exc:
+        raise last_exc
+    raise RuntimeError("Max retries exceeded")
+
+
+async def run_warp_grep_streaming(
+    *,
+    search_term: str,
+    repo_root: str,
+    provider: WarpGrepProvider,
+    api_key: str,
+    api_url: str | None = None,
+    model: str | None = None,
+    timeout: float | None = None,
+    search_type: str | None = None,
+    max_turns: int | None = None,
+    max_retries: int = 3,
+) -> AsyncIterator[WarpGrepStep | AgentRunResult]:
+    """Run the agent loop, yielding a :class:`WarpGrepStep` per turn and finally
+    a single :class:`AgentRunResult` (the last item yielded).
+
+    Python generators cannot carry a separate return value the way TS async
+    generators do, so the final :class:`AgentRunResult` is yielded as the last
+    item.  Consumers distinguish steps from the result by type.
+
+    ``max_turns`` overrides the default per-run turn cap (:data:`MAX_TURNS`);
+    callers like the Explore subagent use it to scale search depth.
+    """
+    total_start = time.monotonic()
+    timeout_s = timeout if timeout is not None else DEFAULT_TIMEOUT_S
+    timings = WarpGrepExecutionMetrics(timeout_ms=int(timeout_s * 1000))
+
+    repo = repo_root or os.getcwd()
+    mdl = model or DEFAULT_MODEL
+    turn_cap = max_turns if max_turns is not None else MAX_TURNS
+    messages: list[ChatMessage] = []
+
+    initial_start = time.monotonic()
+    initial_state = await build_initial_state(repo, search_term, provider, search_type=search_type)
+    timings.initial_state_ms = int((time.monotonic() - initial_start) * 1000)
+    messages.append(ChatMessage(role="user", content=initial_state))
+
+    errors: list[dict[str, str]] = []
+    finish_meta: AgentFinish | None = None
+    termination_reason: str = "terminated"
+
+    for turn in range(1, turn_cap + 1):
+        turn_metrics = WarpGrepTurnMetrics(turn=turn)
+        enforce_context_limit(messages)
+
+        model_start = time.monotonic()
+        try:
+            response = await call_model(
+                messages,
+                mdl,
+                api_key=api_key,
+                api_url=api_url,
+                timeout=timeout_s,
+                search_type=search_type,
+                max_retries=max_retries,
+            )
+        except Exception as err:  # noqa: BLE001 - surface as terminated, like TS
+            errors.append({"message": str(err)})
+            turn_metrics.morph_api_ms = int((time.monotonic() - model_start) * 1000)
+            timings.turns.append(turn_metrics)
+            break
+        turn_metrics.morph_api_ms = int((time.monotonic() - model_start) * 1000)
+
+        tool_calls: list[ToolCallRef] = response["tool_calls"]
+        messages.append(
+            ChatMessage(
+                role="assistant",
+                content=response["content"],
+                tool_calls=tool_calls or None,
+            )
+        )
+
+        if not tool_calls:
+            errors.append({"message": "No tool calls produced by the model."})
+            termination_reason = "terminated"
+            timings.turns.append(turn_metrics)
+            break
+
+        yield WarpGrepStep(
+            turn=turn,
+            tool_calls=[
+                {"name": tc.name, "arguments": _safe_parse_json(tc.arguments)}
+                for tc in tool_calls
+            ],
+        )
+
+        finish_call = next((tc for tc in tool_calls if tc.name == "finish"), None)
+        if finish_call is not None:
+            args = _safe_parse_json(finish_call.arguments)
+            files_str = str(args.get("files") or "")
+            files = parse_finish_files(files_str)
+            finish_meta = AgentFinish(files=files)
+            termination_reason = "completed"
+
+            if not files:
+                payload = files_str or "No relevant code found."
+                timings.turns.append(turn_metrics)
+                timings.total_ms = int((time.monotonic() - total_start) * 1000)
+                yield AgentRunResult(
+                    termination_reason="completed",
+                    messages=messages,
+                    finish_payload=payload,
+                    finish_metadata=finish_meta,
+                    timings=timings,
+                )
+                return
+
+            timings.turns.append(turn_metrics)
+            break
+
+        tool_start = time.monotonic()
+        results = await asyncio.gather(
+            *(_run_one_tool(provider, tc, repo) for tc in tool_calls)
+        )
+        turn_metrics.local_tools_ms = int((time.monotonic() - tool_start) * 1000)
+
+        for tool_call_id, content in results:
+            messages.append(ChatMessage(role="tool", content=content, tool_call_id=tool_call_id))
+
+        turn_msg = format_turn_message(turn, turn_cap)
+        budget = calculate_context_budget(messages)
+        messages.append(ChatMessage(role="user", content=turn_msg + "\n" + budget))
+        timings.turns.append(turn_metrics)
+
+    if termination_reason != "completed" or finish_meta is None:
+        timings.total_ms = int((time.monotonic() - total_start) * 1000)
+        yield AgentRunResult(
+            termination_reason="terminated" if termination_reason != "error" else "error",
+            messages=messages,
+            errors=errors,
+            timings=timings,
+        )
+        return
+
+    # Build finish payload + resolve file contents for returned ranges.
+    parts = ["Relevant context found:"]
+    for f in finish_meta.files:
+        if f.lines == "*":
+            ranges = "*"
+        elif isinstance(f.lines, list):
+            ranges = ", ".join(f"{s}-{e}" for s, e in f.lines)
+        else:
+            ranges = "*"
+        parts.append(f"- {f.path}: {ranges}")
+    payload = "\n".join(parts)
+
+    finish_start = time.monotonic()
+    file_read_errors: list[dict[str, str]] = []
+
+    async def reader(p: str, s: int | None, e: int | None) -> list[str]:
+        resolved_path = p
+        if not p.startswith(repo):
+            relative = p[1:] if p.startswith("/") else p
+            resolved_path = os.path.join(repo, relative)
+        rr = await provider.read(path=resolved_path, start_line=s, end_line=e)
+        if rr.error:
+            file_read_errors.append({"path": resolved_path, "error": rr.error})
+            return [f"[couldn't find: {resolved_path}]"]
+        out: list[str] = []
+        for line in rr.lines:
+            idx = line.find("|")
+            out.append(line[idx + 1 :] if idx >= 0 else line)
+        return out
+
+    resolved_raw = await read_finish_files(finish_meta.files, reader)
+    timings.finish_resolution_ms = int((time.monotonic() - finish_start) * 1000)
+
+    if file_read_errors:
+        errors.extend(
+            {"message": f"File read error: {e['path']} - {e['error']}"} for e in file_read_errors
+        )
+
+    resolved = [
+        ResolvedContext(path=r["path"], ranges=r["ranges"], content=r["content"])  # type: ignore[arg-type]
+        for r in resolved_raw
+    ]
+    timings.total_ms = int((time.monotonic() - total_start) * 1000)
+    yield AgentRunResult(
+        termination_reason="completed",
+        messages=messages,
+        finish_payload=payload,
+        finish_metadata=finish_meta,
+        resolved=resolved,
+        errors=errors,
+        timings=timings,
+    )
+
+
+async def _run_one_tool(
+    provider: WarpGrepProvider, tc: ToolCallRef, repo_root: str
+) -> tuple[str, str]:
+    args = _safe_parse_json(tc.arguments)
+    try:
+        output = await execute_tool(provider, tc.name, args, repo_root)
+    except Exception as err:  # noqa: BLE001 - mirror TS .catch(err => String(err))
+        output = str(err)
+    return tc.id, output
+
+
+async def run_warp_grep(
+    *,
+    search_term: str,
+    repo_root: str,
+    provider: WarpGrepProvider,
+    api_key: str,
+    api_url: str | None = None,
+    model: str | None = None,
+    timeout: float | None = None,
+    search_type: str | None = None,
+    max_turns: int | None = None,
+    max_retries: int = 3,
+) -> AgentRunResult:
+    """Non-streaming convenience wrapper: drain the streaming generator and
+    return the final :class:`AgentRunResult`."""
+    result: AgentRunResult | None = None
+    async for item in run_warp_grep_streaming(
+        search_term=search_term,
+        repo_root=repo_root,
+        provider=provider,
+        api_key=api_key,
+        api_url=api_url,
+        model=model,
+        timeout=timeout,
+        search_type=search_type,
+        max_turns=max_turns,
+        max_retries=max_retries,
+    ):
+        if isinstance(item, AgentRunResult):
+            result = item
+    assert result is not None  # the generator always yields a final result
+    return result