stcode 0.0.1a0__py3-none-any.whl

stcode/core/harness/tools/shell.py

@@ -0,0 +1,372 @@
+"""
+Shell tools — `bash`, and `bash_output` for the background case.
+
+Commands run with the user's privileges; containerize before any autonomous run. From
+inside the process this module does four things:
+
+* **Refuses the unrecoverable** — a short denylist of damage no later turn could undo.
+  Not a security boundary (a script or base64 goes round it); it guards against a model
+  writing something destructive by accident.
+* **Asks proportionally.** `git status` and `rm -rf build/` are the same tool call, so
+  read-only commands drop to READ per call and the rest still ask.
+* **Never hangs.** stdin closed, pagers off, prompts disabled. A command that stops to
+  ask a question stops the turn and produces nothing to react to.
+* **Each call is a fresh process** — `cd`, `export` and `source` do not carry over. Pass
+  `cwd` instead. The model will assume otherwise, so the docstring says so outright.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import shlex
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Annotated
+
+from pydantic import Field
+
+from stcode.core.harness.approvals import ToolPermission
+from stcode.core.harness.context import HarnessContext
+from stcode.core.harness.tools.base import Runtime, ToolError, tool
+
+DEFAULT_TIMEOUT = 120.0
+MAX_TIMEOUT = 900.0
+BASH_MAX_OUTPUT = 16384
+
+NON_INTERACTIVE_ENV = {
+    "GIT_PAGER": "cat",
+    "PAGER": "cat",
+    "GIT_TERMINAL_PROMPT": "0",
+    "GIT_ASKPASS": "echo",
+    "DEBIAN_FRONTEND": "noninteractive",
+    "CI": "1",
+    "NO_COLOR": "1",
+    "TERM": "dumb",
+}
+"""Set on every command. `TERM=dumb` and `NO_COLOR` matter as much as the prompt
+suppressors: ANSI escapes are invisible to the reader and expensive in the context."""
+
+_DESTRUCTIVE = (
+    (re.compile(r"\bmkfs(\.\w+)?\b"), "filesystem format"),
+    (re.compile(r"\bdd\b[^|;]*\bof=/dev/"), "raw write to a block device"),
+    (re.compile(r">\s*/dev/(sd|nvme|hd|disk)"), "redirect onto a block device"),
+    (re.compile(r":\s*\(\s*\)\s*\{.*\|.*&\s*\}\s*;?\s*:"), "fork bomb"),
+    (re.compile(r"\b(shutdown|reboot|halt|poweroff)\b"), "host power control"),
+    (re.compile(r"\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba|z|k|fi)?sh\b"), "piping a download into a shell"),
+    (re.compile(r"\bchmod\s+-[a-zA-Z]*R[a-zA-Z]*\s+777\s+/\s*$"), "world-writable root"),
+    (re.compile(r"\bgit\s+(push\s+[^|;]*--force(?!-with-lease)|reset\s+--hard\s+\S*origin)"), "irreversible git history rewrite"),
+)
+"""Refused outright. The test for belonging here is "could the next turn undo it?", not
+"is it dangerous?". Deletion is judged by target instead, since `rm -rf build/` is
+fine."""
+
+_IRREPLACEABLE = frozenset(
+    {
+        "/", "/*", "~", "~/", "~/*", "$HOME", "$HOME/*", "${HOME}", "..", "../", "../*",
+        ".", "./", "./*", "*",
+        "/bin", "/boot", "/dev", "/etc", "/home", "/lib", "/lib64", "/opt", "/proc",
+        "/root", "/run", "/sbin", "/srv", "/sys", "/usr", "/var",
+    }
+)
+"""Delete targets with nothing behind them. `.` and `*` are here because from the
+session's cwd they mean the user's whole project."""
+
+
+def _deletes_something_irreplaceable(command: str) -> str | None:
+    """Whether any `rm` here points at a path that cannot be recreated.
+
+    Judged on the target, not the flags: `rm -rf node_modules/` and `rm -rf /` differ
+    only in the argument, and refusing on `-rf` would block routine cleanup until
+    whoever reads the refusals learns to ignore them.
+    """
+    for segment in _split_command(command):
+        if os.path.basename(segment[0]) != "rm":
+            continue
+        for argument in segment[1:]:
+            if argument.startswith("-"):
+                continue
+            normalized = argument.rstrip("/") + "/" if argument.endswith("/") else argument
+            if argument in _IRREPLACEABLE or normalized in _IRREPLACEABLE:
+                return f"deleting {argument!r}, which is not something a later turn could rebuild"
+    return None
+
+
+_INTERACTIVE = (
+    (re.compile(r"\bgit\s+(rebase|add|commit)\b[^|;]*\s-i\b"), "git's interactive mode"),
+    (re.compile(r"^\s*(vim?|nano|emacs|less|more|top|htop)\b"), "a full-screen program"),
+    (re.compile(r"\bssh\b(?![^|;]*\s-o\s*BatchMode)"), "ssh, which may prompt for a passphrase"),
+)
+"""Commands that wait for a human at a TTY there is no way to reach. Refused with an
+alternative rather than left to consume the whole timeout in silence."""
+
+_READ_ONLY_COMMANDS = frozenset(
+    {
+        "ls", "pwd", "cat", "head", "tail", "wc", "file", "stat", "du", "df", "tree",
+        "echo", "date", "whoami", "hostname", "uname", "which", "type", "env", "printenv",
+        "grep", "rg", "fd", "find", "sort", "uniq", "cut", "awk", "sed", "diff", "cmp",
+        "python", "python3", "node", "jq", "basename", "dirname", "realpath", "readlink",
+    }
+)
+_READ_ONLY_SUBCOMMANDS = {
+    "git": frozenset({"status", "log", "diff", "show", "branch", "remote", "config",
+                      "blame", "describe", "rev-parse", "ls-files", "shortlog", "tag"}),
+    "uv": frozenset({"tree", "version", "python"}),
+    "docker": frozenset({"ps", "images", "logs", "version", "inspect"}),
+    "npm": frozenset({"ls", "view", "outdated"}),
+    "cargo": frozenset({"tree", "metadata"}),
+}
+"""`sed` and `awk` are here for the overwhelmingly common case, a pipe filter. `sed -i`
+edits in place, so `is_read_only` checks for that rather than trusting the name."""
+
+
+@dataclass
+class BackgroundShell:
+    """A command still running after `bash` returned.
+
+    Output drains continuously into `buffer` rather than on demand: a process whose pipe
+    fills up blocks forever, and a build stalled at 64 KB with no error is close to
+    impossible to diagnose from outside.
+    """
+
+    id: str
+    command: str
+    process: asyncio.subprocess.Process
+    started_at: float = field(default_factory=time.monotonic)
+    buffer: list[str] = field(default_factory=list)
+    consumed: int = 0
+    pump: asyncio.Task[None] | None = None
+
+    @property
+    def running(self) -> bool:
+        return self.process.returncode is None
+
+    def drain(self) -> str:
+        """Everything printed since the last drain."""
+        chunk = "".join(self.buffer[self.consumed :])
+        self.consumed = len(self.buffer)
+        return chunk
+
+
+def _split_command(command: str) -> list[list[str]]:
+    """Best-effort split into the commands a line runs.
+
+    `shlex` is not a shell parser and this is not trying to be one — it is enough to
+    decide whether every segment of `git status | head -20` is read-only, and it fails
+    closed: an unparseable line is simply not read-only.
+    """
+    try:
+        tokens = shlex.split(command, comments=True)
+    except ValueError:
+        return []
+    segments: list[list[str]] = [[]]
+    for token in tokens:
+        if token in ("|", "||", "&&", ";", "&"):
+            segments.append([])
+        else:
+            segments[-1].append(token)
+    return [segment for segment in segments if segment]
+
+
+def is_read_only(command: str) -> bool:
+    """Whether every segment of `command` only observes the workspace."""
+    segments = _split_command(command)
+    if not segments:
+        return False
+    for segment in segments:
+        name = os.path.basename(segment[0])
+        if name == "sed" and any(arg.startswith("-i") for arg in segment[1:]):
+            return False  # in-place edit wearing a filter's name
+        if name in _READ_ONLY_SUBCOMMANDS:
+            arguments = [arg for arg in segment[1:] if not arg.startswith("-")]
+            if not arguments or arguments[0] not in _READ_ONLY_SUBCOMMANDS[name]:
+                return False
+            continue
+        if name not in _READ_ONLY_COMMANDS:
+            return False
+    return True
+
+
+def _refuse(command: str) -> str | None:
+    """The reason this command will not be run, or None."""
+    for pattern, why in _DESTRUCTIVE:
+        if pattern.search(command):
+            return (
+                f"refused: this looks like {why}, which no later turn could undo. "
+                "If you genuinely need it, ask the user to run it themselves."
+            )
+    deletion = _deletes_something_irreplaceable(command)
+    if deletion:
+        return (
+            f"refused: this is {deletion}. Name the specific subdirectory you mean, or "
+            "ask the user to do it themselves."
+        )
+    for pattern, why in _INTERACTIVE:
+        if pattern.search(command):
+            return (
+                f"refused: this invokes {why} and there is no terminal to answer it. "
+                "Use the non-interactive equivalent."
+            )
+    return None
+
+
+def _permission_for(arguments: dict[str, object]) -> ToolPermission:
+    command = str(arguments.get("command", ""))
+    return ToolPermission.READ if is_read_only(command) else ToolPermission.EXECUTE
+
+
+@tool(
+    permission=ToolPermission.EXECUTE,
+    permission_for=_permission_for,
+    max_output=BASH_MAX_OUTPUT,
+)
+async def bash(
+    command: str,
+    timeout: Annotated[float, Field(gt=0, le=MAX_TIMEOUT)] = DEFAULT_TIMEOUT,
+    background: bool = False,
+    cwd: str = "",
+    description: str = "",
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Run a shell command in the session's working directory.
+
+    Runs with your privileges. Prefer the dedicated tools where one fits — `read`,
+    `glob`, and `grep` are faster than `cat`, `find`, and `grep`, and their output is
+    shaped for you rather than for a terminal. Reach for this when you need a real
+    program: a test runner, a build, `git`, a package manager.
+
+    **Every call is a new process.** Nothing carries over between calls — not the
+    working directory, not `export`ed variables, not an activated virtualenv. `cd src`
+    in one call has no effect on the next one. To work in a subdirectory, pass `cwd`;
+    to use a virtualenv, call its binaries by path (`.venv/bin/pytest`) or prefix the
+    command (`uv run pytest`).
+
+    The command runs with no stdin and no pager, so anything that would stop to ask a
+    question fails instead of hanging. Quote paths containing spaces.
+
+    Use `background=True` for anything long-running you want to keep working alongside —
+    a dev server, a watch task, a full test suite. It returns a shell id immediately;
+    read from it with `bash_output`.
+
+    Args:
+        command: The command line to run.
+        timeout: Seconds to wait before giving up and killing it.
+        background: Return immediately and keep the command running.
+        cwd: Directory to run in, relative to the session root. Defaults to the
+            session root itself.
+        description: A 5-10 word description of what this does, shown to the user
+            while it runs. e.g. "Run the unit tests".
+    """
+    context = runtime.context
+    refusal = _refuse(command)
+    if refusal:
+        raise ToolError(f"`{command}` was not run — {refusal}")
+
+    working_dir = context.resolve(cwd) if cwd else context.cwd
+    if not working_dir.is_dir():
+        raise ToolError(f"`{command}` was not run — {working_dir} is not a directory.")
+
+    env = {**context.process_env(), **NON_INTERACTIVE_ENV}
+    if description:
+        await runtime.progress(description)
+
+    process = await asyncio.create_subprocess_shell(
+        command,
+        cwd=str(working_dir),
+        env=env,
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.STDOUT,
+        # Its own process group, so a timeout kills the whole pipeline rather than just
+        # the shell that spawned it, orphaning the actual work.
+        start_new_session=True,
+    )
+
+    if background:
+        return await _start_background(process, command, context)
+
+    try:
+        stdout, _ = await asyncio.wait_for(process.communicate(), timeout)
+    except asyncio.TimeoutError:
+        _kill_group(process)
+        await process.wait()
+        raise ToolError(
+            f"`{command}` was killed after {timeout:.0f}s. Raise `timeout` if it is "
+            "genuinely slow, or run it with background=True and poll `bash_output`."
+        ) from None
+
+    output = stdout.decode("utf-8", errors="replace").rstrip()
+    code = process.returncode or 0
+    if code == 0:
+        return output or "(no output)"
+    # Exit code last: the part the model most needs, and `elide` keeps the tail.
+    return f"{output}\n\n[exit {code}]" if output else f"[exit {code}, no output]"
+
+
+async def _start_background(
+    process: asyncio.subprocess.Process, command: str, context: HarnessContext
+) -> str:
+    shell = BackgroundShell(id=f"sh_{uuid.uuid4().hex[:8]}", command=command, process=process)
+
+    async def pump() -> None:
+        assert process.stdout is not None
+        while True:
+            line = await process.stdout.readline()
+            if not line:
+                break
+            shell.buffer.append(line.decode("utf-8", errors="replace"))
+        await process.wait()
+
+    shell.pump = asyncio.create_task(pump())
+    context.shells[shell.id] = shell
+    return (
+        f"Started `{command}` in the background as {shell.id} (pid {process.pid}).\n"
+        f"Read its output with bash_output({shell.id!r})."
+    )
+
+
+def _kill_group(process: asyncio.subprocess.Process) -> None:
+    try:
+        os.killpg(os.getpgid(process.pid), 9)
+    except (ProcessLookupError, PermissionError, OSError):
+        process.kill()
+
+
+@tool(permission=ToolPermission.READ, max_output=BASH_MAX_OUTPUT)
+async def bash_output(
+    shell_id: str,
+    kill: bool = False,
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Read new output from a background shell started by `bash(background=True)`.
+
+    Returns only what has been printed since the last time you read it, so polling a
+    long build does not re-read the whole log each turn.
+
+    Args:
+        shell_id: The id `bash` returned, e.g. `sh_1a2b3c4d`.
+        kill: Stop the process after reading whatever it has produced.
+    """
+    context = runtime.context
+    shell = context.shells.get(shell_id)
+    if shell is None:
+        known = ", ".join(context.shells) or "none"
+        raise ToolError(f"No background shell {shell_id!r}. Running: {known}.")
+
+    chunk = shell.drain()
+    if kill and shell.running:
+        _kill_group(shell.process)
+        await shell.process.wait()
+
+    elapsed = time.monotonic() - shell.started_at
+    if shell.running:
+        status = f"[{shell_id} still running, {elapsed:.0f}s elapsed]"
+    else:
+        status = f"[{shell_id} exited {shell.process.returncode} after {elapsed:.0f}s]"
+        context.shells.pop(shell_id, None)
+    return f"{chunk.rstrip()}\n\n{status}" if chunk.strip() else status
+
+
+__all__ = ["BackgroundShell", "bash", "bash_output", "is_read_only"]

stcode/core/harness/tools/skill.py

@@ -0,0 +1,66 @@
+"""
+`skill` — pull a set of instructions into context on demand.
+
+The catalogue is in the system prompt, one line per skill. That is all a session pays
+for a skill it never uses; this tool is the second half.
+
+Nine installed skills are roughly 90,000 tokens of instructions and 400 of catalogue.
+Loading everything upfront would spend most of a context window on advice about tasks
+the session is not doing.
+"""
+
+from __future__ import annotations
+
+from stcode.core.harness.approvals import ToolPermission
+from stcode.core.harness.context import HarnessContext
+from stcode.core.harness.tools.base import Runtime, ToolError, tool
+
+
+@tool(permission=ToolPermission.READ, max_output=65536, spill=False)
+async def skill(
+    name: str,
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Load a skill's full instructions by name.
+
+    Skills are pre-written procedures for specific kinds of work. The catalogue in your
+    system prompt lists what is available and when each applies — when a task matches
+    one of those descriptions, load it *before* starting, not after getting stuck.
+
+    What comes back is instructions for you to follow, not a report to relay. A skill
+    may point at further files in its own directory; read those with `read` as it tells
+    you to, rather than loading them speculatively.
+
+    Args:
+        name: The skill's name, exactly as listed in the catalogue.
+    """
+    registry = runtime.context.skills
+    if registry is None or not len(registry):
+        raise ToolError(
+            "No skills are available in this session. Proceed without one — skills are "
+            "an accelerator, not a prerequisite."
+        )
+
+    wanted = name.strip().lstrip("/")
+    found = registry.get(wanted)
+    if found is None:
+        near = [candidate for candidate in registry.names() if wanted.lower() in candidate.lower()]
+        suggestion = f" Did you mean: {', '.join(near)}?" if near else f" Available: {', '.join(registry.names())}."
+        raise ToolError(f"No skill named {wanted!r}.{suggestion}")
+
+    try:
+        body = found.load()
+    except OSError as exc:
+        raise ToolError(f"Could not read {found.path}: {exc.strerror}") from exc
+
+    # The root path is stated explicitly because the instructions reference sibling
+    # files relatively ("see reference.md"), and the agent's cwd is the project, not
+    # the skill. Without this line every such reference resolves to the wrong place.
+    return (
+        f"# Skill: {found.name}\n"
+        f"Files referenced below are relative to {found.root}\n\n"
+        f"{body}"
+    )
+
+
+__all__ = ["skill"]

stcode/core/harness/tools/todo.py

@@ -0,0 +1,62 @@
+"""
+Todo — `todo_write`, the tool that is not really a tool.
+
+A device to keep the plan in context. Nothing outside the agent reads these items, and
+writing one changes no file. What it does is force the plan through the model's own
+output, where it stays visible — a multi-step task tracked only in a model's head loses
+its last two items around the fourth tool call.
+
+The one rule that matters: *exactly one* item in progress. A list with four
+`in_progress` has stopped describing what is happening.
+"""
+
+from __future__ import annotations
+
+from stcode.core.harness.approvals import ToolPermission
+from stcode.core.harness.context import HarnessContext, TodoItem
+from stcode.core.harness.tools.base import Runtime, ToolError, tool
+
+
+@tool(permission=ToolPermission.READ, spill=False)
+async def todo_write(
+    todos: list[TodoItem],
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Record or update the task list for the current piece of work.
+
+    Use it for anything that takes more than a couple of steps, and update it *as you
+    go* — mark an item completed the moment it is done, not in a batch at the end. The
+    list is how you and the user both keep track of where the work has got to.
+
+    Skip it entirely for single-step tasks. A one-item todo list is ceremony.
+
+    Each item needs both phrasings: `content` in the imperative ("Add the retry test")
+    and `active_form` in the present participle ("Adding the retry test"), because the
+    UI shows the second one while the item is running.
+
+    Exactly one item may be `in_progress`. Mark an item completed only when it really
+    is — if tests fail or the implementation is partial, leave it in progress and add
+    an item for what is blocking it.
+
+    Args:
+        todos: The complete list, replacing whatever was there before. Send every item
+            each time, not just the ones that changed.
+    """
+    context = runtime.context
+    in_progress = [item for item in todos if item.status == "in_progress"]
+    if len(in_progress) > 1:
+        names = ", ".join(repr(item.content) for item in in_progress)
+        raise ToolError(
+            f"{len(in_progress)} items are in_progress ({names}). Exactly one at a time — "
+            "pick the one you are actually working on and leave the rest pending."
+        )
+    for item in todos:
+        if not item.active_form:
+            item.active_form = item.content
+
+    context.todos = list(todos)
+    done = sum(1 for item in todos if item.status == "completed")
+    return f"{context.render_todos()}\n\n[{done}/{len(todos)} complete]"
+
+
+__all__ = ["todo_write"]

stcode/core/harness/tools/web.py

@@ -0,0 +1,163 @@
+"""
+Web access — one tool, three Tavily endpoints, chosen by which arguments arrive.
+
+`web_search(query=...)` searches, `web_search(url=...)` extracts that page, both
+together crawls from that URL looking for the query. One tool rather than three: those
+are the same intent at three scopes, and the arguments already say which — not a
+decision the model should have to make before it knows what it will find.
+
+Web output is always huge; one search returns more tokens than most files in a repo. The
+low default result counts are for that, not to save credits.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+import httpx
+from pydantic import Field
+
+from stcode.core.harness.approvals import ToolPermission
+from stcode.core.harness.context import HarnessContext
+from stcode.core.harness.tools.base import Runtime, ToolError, tool
+
+TAVILY_BASE_URL = "https://api.tavily.com"
+WEB_MAX_OUTPUT = 24576
+"""Higher than other tools, and still the tool most likely to elide. The remainder is
+in `tool_out` — filter it in the REPL rather than asking for less next time."""
+
+_REQUEST_TIMEOUT = 90.0
+
+
+async def _post(key: str, endpoint: str, payload: dict[str, Any]) -> dict[str, Any]:
+    """One request to Tavily, with its failures translated into advice.
+
+    Status codes are mapped rather than surfaced raw: a model that reads "401" tries the
+    call again, while a model that reads "the key is rejected" stops and says so.
+    """
+    async with httpx.AsyncClient(timeout=_REQUEST_TIMEOUT) as client:
+        try:
+            response = await client.post(
+                f"{TAVILY_BASE_URL}/{endpoint}",
+                headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+                json={key: value for key, value in payload.items() if value is not None},
+            )
+        except httpx.TimeoutException:
+            raise ToolError(f"Tavily /{endpoint} timed out after {_REQUEST_TIMEOUT:.0f}s.") from None
+        except httpx.HTTPError as exc:
+            raise ToolError(f"Could not reach Tavily: {exc}") from exc
+
+    if response.status_code == 401:
+        raise ToolError("Tavily rejected the configured key. Do not retry.")
+    if response.status_code == 429:
+        raise ToolError("Tavily rate limit or credit limit reached. Do not retry this turn.")
+    if response.status_code >= 400:
+        raise ToolError(f"Tavily /{endpoint} returned {response.status_code}: {response.text[:400]}")
+    return response.json()  # type: ignore[no-any-return]
+
+
+@tool(permission=ToolPermission.NETWORK, max_output=WEB_MAX_OUTPUT, timeout=120.0)
+async def web_search(
+    query: str | None = None,
+    url: str | None = None,
+    max_results: Annotated[int, Field(ge=1, le=20)] = 5,
+    depth: Literal["basic", "advanced"] = "basic",
+    include_domains: list[str] | None = None,
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Search the web, read a specific page, or crawl a site — depending on what you pass.
+
+    * `query` alone — search the web and return the best matches with excerpts.
+    * `url` alone — fetch that one page and return its content as markdown.
+    * both — crawl outward from `url`, keeping pages relevant to `query`. Use this for
+      documentation sites, where the answer is on a page you cannot name in advance.
+
+    Your training data has a cutoff and this does not. Check here whenever the answer
+    depends on a current version number, a recent release, or an API that may have
+    changed — and prefer a project's own documentation URL over a general search.
+
+    Args:
+        query: What to search for, or what to look for while crawling. Write it as a
+            full question, not keywords.
+        url: A page to read, or the site to crawl from.
+        max_results: How many results to return. Keep it small; each one is long.
+        depth: `advanced` searches harder and costs more. Try `basic` first.
+        include_domains: Restrict a search to these domains, e.g. `["docs.python.org"]`.
+    """
+    if not query and not url:
+        raise ToolError("Pass `query` to search, `url` to read a page, or both to crawl a site.")
+    key = runtime.context.tool_config.tavily_key()
+    if not key:
+        raise ToolError(
+            "Web access needs a Tavily API key ([tools] tavily_api_key, or $TAVILY_API_KEY). "
+            "Ask the user to set it, or answer from the repository and your own knowledge "
+            "and say that you could not check the web."
+        )
+
+    if url and not url.startswith(("http://", "https://")):
+        url = f"https://{url}"
+
+    if query and url:
+        await runtime.progress(f"Crawling {url} for {query!r}")
+        payload = await _post(
+        key,
+            "crawl",
+            {"url": url, "instructions": query, "limit": max_results,
+             "extract_depth": depth, "format": "markdown"},
+        )
+        return _render_pages(payload.get("results", []), f"Crawl of {url} for {query!r}")
+
+    if url:
+        await runtime.progress(f"Reading {url}")
+        payload = await _post(
+            key, "extract", {"urls": [url], "extract_depth": depth, "format": "markdown"}
+        )
+        results = payload.get("results", [])
+        if not results:
+            failed = payload.get("failed_results", [])
+            reason = failed[0].get("error", "no content") if failed else "no content returned"
+            raise ToolError(f"Could not extract {url}: {reason}")
+        return _render_pages(results, f"Content of {url}")
+
+    await runtime.progress(f"Searching for {query!r}")
+    payload = await _post(
+        key,
+        "search",
+        {"query": query, "max_results": max_results, "search_depth": depth,
+         "include_answer": True, "include_domains": include_domains},
+    )
+    return _render_search(payload, query or "")
+
+
+def _render_search(payload: dict[str, Any], query: str) -> str:
+    results = payload.get("results", [])
+    if not results:
+        return f"No results for {query!r}. Try different wording or a narrower question."
+
+    parts: list[str] = [f"# Web search: {query}"]
+    answer = payload.get("answer")
+    if answer:
+        # Tavily's synthesized answer is a summary of the same sources listed below,
+        # so it is labelled as such — it is a starting point, not a citation.
+        parts.append(f"\n**Summary (Tavily's, not a source):** {answer}")
+
+    for index, result in enumerate(results, start=1):
+        title = result.get("title") or "(untitled)"
+        parts.append(
+            f"\n## {index}. {title}\n{result.get('url', '')}\n\n"
+            f"{(result.get('content') or '').strip()}"
+        )
+    return "\n".join(parts)
+
+
+def _render_pages(results: list[dict[str, Any]], heading: str) -> str:
+    if not results:
+        return f"{heading}: nothing was returned."
+    parts = [f"# {heading}"]
+    for result in results:
+        body = result.get("raw_content") or result.get("content") or ""
+        parts.append(f"\n## {result.get('url', '(unknown url)')}\n\n{body.strip()}")
+    return "\n".join(parts)
+
+
+__all__ = ["web_search"]