shellbent 0.1.0__py3-none-any.whl

shellbent-0.1.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: shellbent
+Version: 0.1.0
+Summary: mini-swe-agent 2.4.6 model classes and named tools for a thesis on agent tool surfaces
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mini-swe-agent==2.4.6
+Requires-Dist: ripgrep-bin==15.2.0; sys_platform == 'linux'

shellbent-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+thesis_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+thesis_tools/args.py,sha256=ZcSDZ2YmJcdBdRHuH9jYciIzvcTUgGgrhnmtmxGjzPI,1649
+thesis_tools/model.py,sha256=juoW0f5gZMKIckOBCrs-j0UKepcY7Ar0NMksAc7oaf8,17285
+thesis_tools/read.py,sha256=uIt3WXOOG-WrjcAV-ZT5ArE_PqzkvTcUokCbSzmEF_U,5420
+thesis_tools/search.py,sha256=kVZq7Oo0IIbjGYz3bWTqwDab1WW80PpTbrNlkInyurg,7985
+shellbent-0.1.0.dist-info/METADATA,sha256=VVfncNNxHcRuS1HkwwIWHQGN1XgLxclhDwuNuceVfq4,316
+shellbent-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+shellbent-0.1.0.dist-info/licenses/LICENSE,sha256=Y7EDeoDYcAiZCDcVCfOelB2z4xa9gogiWZdsoiV73jc,1074
+shellbent-0.1.0.dist-info/RECORD,,

shellbent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

shellbent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Posztos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thesis_tools/args.py

@@ -0,0 +1,31 @@
+"""Argument checking shared by the tool CLIs. Each tool gets its JSON arguments as one argv string, checks them
+against its own schema and reports problems as the tool result, in pi's message format."""
+
+import json
+
+
+def validate(raw_args, tool, error):
+    """Parses the JSON arguments and checks them against `tool`'s schema (an OpenAI function tool dict). Returns
+    the kwargs for the tool function. Bad arguments raise `error` (the tool's own exception class) with the message
+    the model sees. No type conversion. Unknown keys are ignored, like in pi; this also drops the `why_this_tool`
+    and `why_not_<tool>` keys that the reason prompts add."""
+    try:
+        args = json.loads(raw_args)
+    except ValueError as e:
+        raise error(f"Error parsing tool call arguments: {e}.") from e
+    if not isinstance(args, dict):
+        raise error("Tool call arguments must be a JSON object.")
+    name = tool["function"]["name"]
+    params = tool["function"]["parameters"]
+    props = params["properties"]
+    types = {"string": str, "boolean": bool, "number": (int, float)}
+    errors = [f"  - /{key}: Expected required property" for key in params.get("required", []) if key not in args]
+    for key, value in args.items():
+        if key in props and not isinstance(value, types[props[key]["type"]]):
+            errors.append(f"  - /{key}: Expected {props[key]['type']}")
+    if errors:
+        raise error(
+            f'Validation failed for tool "{name}":\n' + "\n".join(errors)
+            + f"\n\nReceived arguments:\n{json.dumps(args, indent=2)}"
+        )
+    return {key: value for key, value in args.items() if key in props}

thesis_tools/model.py

@@ -0,0 +1,327 @@
+"""The model classes behind the conditions. Pier selects one with --ak model_class=thesis_tools.model.<class>. The
+model class sends every LLM request and the tools list is part of it, so this is where the tool surface is set.
+
+BashModel is the baseline, with bash as the only tool. ToolsModel adds the named tools from the `tools` yaml key
+(search and/or read) next to bash. tool_directive is put in front of the search tool description, so it can change
+in the yaml without a new package version.
+
+reason_prompt adds a required `why_this_tool` string as the first parameter of every tool, and reason_against_prompt
+one `why_not_<tool>` string per other tool. The tool names are in the field names so the model cannot mix up which
+reason belongs to which tool. The fields are stored with the call in the trajectory and never reach the agent. A call
+with a missing, blank or misnamed field is refused. After MAX_REASON_REFUSALS refused responses in a row such calls
+run anyway, so a model that ignores the fields or gets them wrong does not loop and does not kill the trial.
+
+block_grep and block_read (ToolsModel only) are the leave-one-out configurations. A bash command that runs grep or rg
+(block_grep), or cat, head, nl or sed -n (block_read), is refused with a nudge to use the named tool instead. The
+same commands as a filter after a pipe stay allowed (ps aux | grep, git log | head), and heredoc bodies are not
+blocked.
+
+When we refuse a call, we do not run it and return a message saying what to do instead, with exit code 127. We do
+not return a format error, because mini-swe-agent ends a trial after 3 format errors in a row. The other calls in
+the same response still run.
+
+Both classes abort the trial on a context overflow.
+"""
+
+import copy
+import json
+import re
+import shlex
+import sys
+import time
+
+import litellm
+from minisweagent.models.litellm_model import LitellmModel, LitellmModelConfig
+from minisweagent.models.utils.actions_toolcall import BASH_TOOL, parse_toolcall_actions
+
+from thesis_tools.read import READ_TOOL
+from thesis_tools.search import SEARCH_TOOL
+
+NAMED_TOOLS = {"search": (SEARCH_TOOL, "thesis_tools.search"), "read": (READ_TOOL, "thesis_tools.read")}
+
+class BashModelConfig(LitellmModelConfig):
+    reason_prompt: str = ""
+    """Description of a required `why_this_tool` parameter put first in every tool's schema. Empty means no parameter."""
+    reason_against_prompt: str = ""
+    """Description of a required `why_not_<tool>` parameter per other tool, after `why_this_tool`. `{tool}` is
+    replaced by the other tool's name. Only used together with reason_prompt."""
+    min_request_interval: float = 0
+    """Seconds a trial waits at least between the starts of two model calls. Trials run in separate containers and
+    cannot share a rate limiter, so each one paces itself: with n parallel trials and a quota of C requests per hour,
+    n * 3600 / C keeps the whole run under the quota. 0 means no pacing (the default, fine without a quota)."""
+    max_rate_limit_wait: float = 7200
+    """Total seconds a trial may sleep on Retry-After waits (see rate_limit_wait) before the RateLimitError is
+    raised and ends the trial."""
+
+
+REASON_FIELD = "why_this_tool"
+
+
+def reason_fields(names, prompt, against):
+    """Maps each tool name to its reason parameters (field name -> description): REASON_FIELD, then why_not_<other>
+    per other tool if `against` is set. Empty dicts without a prompt."""
+    fields = {}
+    for name in names:
+        fields[name] = {REASON_FIELD: prompt.strip()} if prompt else {}
+        if prompt and against:
+            fields[name] |= {f"why_not_{o}": against.strip().replace("{tool}", o) for o in names if o != name}
+    return fields
+
+
+def add_reasons(tool, fields):
+    """Returns a copy of a tool schema with `fields` as its first, required parameters. Properties keep their order
+    in the JSON schema, and models fill the arguments in that order, so the reasons come before the action.
+    The original dict is untouched (BASH_TOOL and SEARCH_TOOL are module constants)."""
+    if not fields:
+        return tool
+    tool = copy.deepcopy(tool)
+    params = tool["function"]["parameters"]
+    params["properties"] = {k: {"type": "string", "description": v} for k, v in fields.items()} | params["properties"]
+    params["required"] = list(fields) + [k for k in params.get("required", []) if k not in fields]
+    return tool
+
+
+# after this many refused responses in a row, calls with missing reasons are no longer refused and just run, so
+# the model cannot loop
+MAX_REASON_REFUSALS = 3
+
+
+def reason_gap(tool_call, fields):
+    """Returns the refusal message if the call is missing a reason field, else None."""
+    try:
+        args = json.loads(tool_call.function.arguments)
+    except Exception:
+        return None
+    if not isinstance(args, dict):
+        return None
+    name = tool_call.function.name
+    missing = [f for f in fields.get(name, {}) if not str(args.get(f, "")).strip()]
+    if not missing:
+        return None
+    text = f"Nothing in this {name} call was run. It is missing {', '.join(missing)}."
+    wrong = [k for k in args if k.startswith("why_") and k not in fields[name]]
+    if wrong:
+        text += f" The {name} tool has no {', '.join(wrong)} argument."
+    return text + " Send the call again with every why_ argument filled in."
+
+
+RETRY_AFTER = re.compile(r"Retry after (\d+)s")
+
+
+def rate_limit_wait(error, default=60):
+    """Seconds to wait after a 429 from litellm's RateLimitError: the Retry-After header if present, else a
+    "(Retry after Ns)" in the message, else `default`. Providers with hourly or daily quotas answer with waits of up to
+    an hour; litellm's own backoff caps every sleep at 10 s and gives up long before that."""
+    headers = getattr(error, "headers", None) or getattr(getattr(error, "response", None), "headers", None) or {}
+    value = headers.get("retry-after") or headers.get("Retry-After")
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        pass
+    match = RETRY_AFTER.search(str(error))
+    return float(match.group(1)) if match else default
+
+
+class BashModel(LitellmModel):
+    """Baseline. A copy of mini-swe-agent's LitellmModel with two changes.
+
+    1. tools=[BASH_TOOL] is not hardcoded, we send self.tools instead, so ToolsModel can add tools.
+    2. the except block immediately stops the trial on a context overflow. Some providers send it as a plain
+       BadRequestError, which mini retries until the rate limit or the timeout kills the trial.
+       Re-raising it as ContextWindowExceededError makes mini abort right away.
+    3. rate limits (optional, both default off): min_request_interval paces the calls so a run stays under a
+       provider's request quota, and a RateLimitError that survives litellm's own retries (num_retries in
+       model_kwargs) is slept out for the Retry-After time and retried instead of ending the trial. Not needed
+       for a self-served model or a provider without quotas.
+    """
+
+    def __init__(self, *, config_class=BashModelConfig, **kwargs):
+        super().__init__(config_class=config_class, **kwargs)
+        self.last_request = -float("inf")
+        tools = self._tools()
+        names = [tool["function"]["name"] for tool in tools]
+        self.reason_fields = reason_fields(names, self.config.reason_prompt, self.config.reason_against_prompt)
+        self.tools = tuple(add_reasons(tool, self.reason_fields[name]) for tool, name in zip(tools, names))
+        self.reason_refusals = 0
+
+    def _tools(self):
+        """The tool surface of this condition, before the reason parameter is added. Subclasses override."""
+        return [BASH_TOOL]
+
+    def _parse_actions(self, response):
+        actions = super()._parse_actions(response)
+        return self.refuse_reason_gaps(response.choices[0].message.tool_calls or [], actions)
+
+    def refuse_reason_gaps(self, tool_calls, actions):
+        """Refuses every call that is missing a reason field. A response with all fields filled in resets the
+        count, and after MAX_REASON_REFUSALS refused responses in a row the calls run anyway."""
+        gaps = {tool_call.id: reason_gap(tool_call, self.reason_fields) for tool_call in tool_calls}
+        if not any(gaps.values()):
+            self.reason_refusals = 0
+            return actions
+        if self.reason_refusals >= MAX_REASON_REFUSALS:
+            return actions
+        self.reason_refusals += 1
+        for action in actions:
+            if gaps.get(action["tool_call_id"]):
+                action["command"] = refusal(gaps[action["tool_call_id"]])
+        return actions
+
+    def _query(self, messages, **kwargs):
+        slept = 0
+        while True:
+            pause = self.last_request + self.config.min_request_interval - time.monotonic()
+            if pause > 0:
+                time.sleep(pause)
+            self.last_request = time.monotonic()
+            try:
+                return litellm.completion(
+                    model=self.config.model_name,
+                    messages=messages,
+                    tools=self.tools,
+                    **(self.config.model_kwargs | kwargs),
+                )
+            except litellm.exceptions.BadRequestError as e:
+                if "maximum context length" in str(e) and not isinstance(e, litellm.exceptions.ContextWindowExceededError):
+                    raise litellm.exceptions.ContextWindowExceededError(
+                        str(e), self.config.model_name, getattr(e, "llm_provider", "")
+                    ) from e
+                raise
+            except litellm.exceptions.RateLimitError as e:
+                wait = rate_limit_wait(e) + 5  # the window reopens at a clock boundary, 5 s of slack for clock skew
+                if slept + wait > self.config.max_rate_limit_wait:
+                    raise
+                print(f"thesis_tools: rate limited, sleeping {wait:.0f}s ({str(e)[:200]})", file=sys.stderr, flush=True)
+                time.sleep(wait)
+                slept += wait
+
+
+class ToolsModelConfig(BashModelConfig):
+    tools: list[str] = ["search"]
+    """The named tools, in this order. Names are defined in NAMED_TOOLS."""
+    tool_directive: str = ""
+    """String put in front of the search tool description (to optionally nudge the model to use this tool). Empty means nothing is prepended."""
+    block_grep: bool = False
+    """Reject bash commands that run grep or rg as a command (not as a filter after a pipe)."""
+    block_read: bool = False
+    """Reject bash commands that run cat, head, nl or sed -n as a command (not as a filter after a pipe)."""
+
+
+# grep, rg, egrep or fgrep as a command word, not part of a longer token (--grep=, ./rg, my_grep, grep-exit) and not
+# directly after a single pipe. `git grep`, `xargs grep`, `cd x && grep` and `find | xargs grep` are all blocked.
+GREP_COMMAND = re.compile(r"(?<![\w./-])(?:grep|rg|egrep|fgrep)(?![\w-])")
+BLOCKED_GREP = "Nothing in this command was run. grep and rg are currently not available as commands for you. Use the search tool to find text in files."
+# a heredoc from its `<<WORD` line to the terminator line; the body is data (patch scripts, file contents), not commands
+HEREDOC = re.compile(r"<<-?\s*(['\"]?)(\w+)\1[^\n]*\n.*?\n\s*\2(?=\s|$)", re.S)
+
+
+def command_words(command):
+    """The command with heredoc bodies cut out, so the block rules only see what bash runs as commands."""
+    return HEREDOC.sub("<<HEREDOC", command)
+
+
+def after_pipe(command, pos):
+    """True if the command word at `pos` directly follows a single `|` (a filter, allowed by every block rule)."""
+    before = command[:pos].rstrip()
+    return before.endswith("|") and not before.endswith("||")
+
+
+def runs_grep(command):
+    """True if the bash command runs grep/rg as a command. A match right after a single `|` is a filter and allowed,
+    and a grep word after another one in the same segment is that grep's argument (`ps aux | grep -v grep`)."""
+    command = command_words(command)
+    previous = -1
+    for m in GREP_COMMAND.finditer(command):
+        argument = previous >= 0 and not SEGMENT_END.search(command, previous, m.start())
+        if not argument and not after_pipe(command, m.start()):
+            return True
+        previous = m.end()
+    return False
+
+
+# These five regexes are the parts of the rule (runs_read below) that decides whether a bash command reads a file.
+# READ_COMMAND finds cat, head, nl or sed standing as a command, not inside a longer token like ./cat, my_cat or
+# git cat-file (same word rule as GREP_COMMAND). SEGMENT_END marks where that command's arguments stop.
+# WRITE_REDIRECT checks those arguments for a heredoc or a stdout redirect, because `cat > file` and `cat <<EOF`
+# write a file. SED_QUIET checks for -n, because only `sed -n` prints lines and counts as reading. SED_IN_PLACE
+# checks for -i, because `sed -i` edits the file, even with -n.
+#
+# tail is left out on purpose. In the bash-only GLM run it polls logs of background jobs in 1,667 of 1,818 calls,
+# and the read tool has no way to read the end of a file (no negative offset). The pagers less and more are left
+# out too, because nobody runs them in a non-interactive shell and "more" is an English word that shows up in
+# commit messages.
+READ_COMMAND = re.compile(r"(?<![\w./-])(?:cat|head|nl|sed)(?![\w-])")
+SEGMENT_END = re.compile(r"\|\|?|;|&&|\n")  # the next |, ;, && or line break
+WRITE_REDIRECT = re.compile(r"<<|(?<!\d)>")  # 2> is stderr and does not count
+SED_QUIET = re.compile(r"\s-(?:[a-zA-Z]*n|-quiet|-silent)")  # also bundled, like -En or -ne
+SED_IN_PLACE = re.compile(r"\s-(?:[a-zA-Z]*i|-in-place)")
+BLOCKED_READ = "Nothing in this command was run. cat, head, nl and sed -n are currently not available as commands for you. Use the read tool to read files."
+
+
+def refusal(message):
+    """We run this instead of a blocked bash command or a call with a reason gap. It just prints the text telling the
+    agent what to do instead and exits with 127, so the agent sees a normal failed command and not a format error."""
+    return f"printf '%s\\n' {shlex.quote(message)}; exit 127"
+
+
+def runs_read(command):
+    """True if the bash command reads a file with cat, head, nl or sed -n as a command. Allowed: a filter after a
+    single `|`, `cat` that writes (heredoc or redirect), `sed` without -n or with -i (an edit, not a read), and a
+    command right inside $(...) or `...`, whose output becomes data for the outer command (javac -cp "$(cat cp.txt)")."""
+    command = command_words(command)
+    for m in READ_COMMAND.finditer(command):
+        if after_pipe(command, m.start()) or command[: m.start()].rstrip().endswith(("$(", "`")):
+            continue
+        args = SEGMENT_END.split(command[m.end():], 1)[0]
+        if m.group() == "cat" and WRITE_REDIRECT.search(args):
+            continue
+        if m.group() == "sed" and (not SED_QUIET.search(args) or SED_IN_PLACE.search(args)):
+            continue
+        return True
+    return False
+
+
+class ToolsModel(BashModel):
+    """Extension. Adds the named tools from config.tools next to bash. A named tool call becomes a shell command
+    that runs the tool's module in the container, so environment, observations and trajectories stay as in
+    mini-swe-agent."""
+
+    def __init__(self, **kwargs):
+        super().__init__(config_class=ToolsModelConfig, **kwargs)
+
+    def _tools(self):
+        tools = [BASH_TOOL]
+        for name in self.config.tools:
+            tool = NAMED_TOOLS[name][0]
+            if name == "search" and self.config.tool_directive:
+                tool = copy.deepcopy(tool)
+                tool["function"]["description"] = self.config.tool_directive.strip() + " " + tool["function"]["description"]
+            tools.append(tool)
+        return tools
+
+    def _parse_actions(self, response):
+        tool_calls = response.choices[0].message.tool_calls or []
+        if not tool_calls:
+            return super()._parse_actions(response)  # raises mini-swe-agent's "no tool calls" FormatError
+        finish_reason = response.choices[0].finish_reason
+        actions = []
+        for tool_call in tool_calls:
+            if tool_call.function.name in self.config.tools:
+                # the module checks the arguments itself and reports problems as its output
+                module = NAMED_TOOLS[tool_call.function.name][1]
+                command = shlex.join([sys.executable, "-m", module, tool_call.function.arguments])
+                actions.append({"command": command, "tool_call_id": tool_call.id})
+                continue
+            # bash and unknown tool names get mini-swe-agent's own checks
+            bash_actions = parse_toolcall_actions(
+                [tool_call],
+                format_error_template=self.config.format_error_template,
+                template_kwargs={"finish_reason": finish_reason},
+            )
+            for action in bash_actions:
+                if self.config.block_grep and runs_grep(action["command"]):
+                    action["command"] = refusal(BLOCKED_GREP)
+                elif self.config.block_read and runs_read(action["command"]):
+                    action["command"] = refusal(BLOCKED_READ)
+            actions += bash_actions
+        return self.refuse_reason_gaps(tool_calls, actions)

thesis_tools/read.py

@@ -0,0 +1,127 @@
+"""Read tool. A Python port of pi's read tool (earendil-works/pi @ 98d2e19 ),
+text files only. ToolsModel runs it in the task container as `python -m thesis_tools.read '<json args>'`.
+Differences from pi are marked "Deviation". Left out on purpose: images, the SSH-style pluggable file operations,
+abort signals, the UI renderers and pi's macOS filename variants (NFD, curly quotes, the no-break space in
+screenshot names), none of which exist in a benchmark container.
+"""
+
+import os
+import sys
+
+from thesis_tools.args import validate as validate_args
+
+DEFAULT_MAX_LINES = 2000
+DEFAULT_MAX_BYTES = 50 * 1024
+
+READ_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "read",
+        "description": (
+            "Read the contents of a file. Each line is prefixed with its line number. "
+            f"Output is truncated to {DEFAULT_MAX_LINES} lines or {DEFAULT_MAX_BYTES // 1024}KB (whichever is hit "
+            "first). Use offset/limit for large files. When you need the full file, continue with offset until complete."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Path to the file to read (relative or absolute)"},
+                "offset": {"type": "number", "description": "Line number to start reading from (1-indexed)"},
+                "limit": {"type": "number", "description": "Maximum number of lines to read"},
+            },
+            "required": ["path"],
+        },
+    },
+}
+
+
+class ReadError(Exception):
+    """An error the model sees as the tool result. Any other exception is a bug and crashes."""
+
+
+def format_size(size):
+    if size < 1024:
+        return f"{size}B"
+    if size < 1024 * 1024:
+        return f"{size / 1024:.1f}KB"
+    return f"{size / (1024 * 1024):.1f}MB"
+
+
+def truncate_head(lines):
+    """Keeps the first lines that fit into DEFAULT_MAX_LINES and DEFAULT_MAX_BYTES, never a partial line. Returns
+    (kept lines, what cut them: None, "lines", "bytes" or "first line" when even the first line is over the byte cap)."""
+    if len(lines) <= DEFAULT_MAX_LINES and sum(len(line.encode()) + 1 for line in lines) - 1 <= DEFAULT_MAX_BYTES:
+        return lines, None
+    if len(lines[0].encode()) > DEFAULT_MAX_BYTES:
+        return [], "first line"
+    kept, size = [], 0
+    for line in lines[:DEFAULT_MAX_LINES]:
+        size += len(line.encode()) + (1 if kept else 0)
+        if size > DEFAULT_MAX_BYTES:
+            return kept, "bytes"
+        kept.append(line)
+    return kept, "lines"
+
+
+def read(path, offset=None, limit=None):
+    """Returns the text the model sees. Expected problems (missing file, offset past the end) raise ReadError."""
+    file_path = os.path.abspath(os.path.expanduser(path))
+    if os.path.isdir(file_path):
+        raise ReadError(f"Path is a directory, not a file: {path}")
+    try:
+        with open(file_path, encoding="utf-8", errors="replace", newline="") as f:
+            text = f.read()
+    except OSError as e:
+        raise ReadError(f"Cannot read {path}: {e.strerror}") from e
+
+    # Deviation: pi counts the empty string after a final newline as a line, so its "of N" is one too high
+    # for every file that ends in a newline. We count lines the way nl and wc -l do.
+    if not text:
+        return "(empty file)"  # Deviation: pi returns the empty string, which models read as a failed call
+    all_lines = text.split("\n")
+    if text.endswith("\n"):
+        all_lines.pop()
+
+    # 1-indexed offset to a 0-indexed start
+    start = max(int(offset) - 1, 0) if offset else 0
+    if start >= len(all_lines):
+        raise ReadError(f"Offset {offset} is beyond end of file ({len(all_lines)} lines total)")
+    end = min(start + int(limit), len(all_lines)) if limit is not None else len(all_lines)
+
+    # Deviation: pi returns the raw text. We prefix every line with its number, as OpenCode and Claude Code do and as
+    # cat -n would, because the search tool reports file:line and this surface has no edit tool that needs the
+    # exact raw text. The caps apply to the numbered output, which is what the model gets.
+    numbered = [f"{n}: {line}" for n, line in enumerate(all_lines[start:end], start + 1)]
+    kept, cut_by = truncate_head(numbered)
+    if cut_by == "first line":
+        size = format_size(len(all_lines[start].encode()))
+        return (
+            f"[Line {start + 1} is {size}, exceeds {format_size(DEFAULT_MAX_BYTES)} limit. "
+            f"Use bash: sed -n '{start + 1}p' {path} | head -c {DEFAULT_MAX_BYTES}]"
+        )
+    output = "\n".join(kept)
+    last = start + len(kept)
+    if cut_by:
+        cap = f" ({format_size(DEFAULT_MAX_BYTES)} limit)" if cut_by == "bytes" else ""
+        output += f"\n\n[Showing lines {start + 1}-{last} of {len(all_lines)}{cap}. Use offset={last + 1} to continue.]"
+    elif last < len(all_lines):
+        output += f"\n\n[{len(all_lines) - last} more lines in file. Use offset={last + 1} to continue.]"
+    return output
+
+
+def validate(raw_args):
+    """Checks the JSON arguments against READ_TOOL's schema, see args.validate."""
+    return validate_args(raw_args, READ_TOOL, ReadError)
+
+
+def main():
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    try:
+        sys.stdout.write(read(**validate(sys.argv[1])))
+    except ReadError as e:
+        sys.stdout.write(str(e))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

thesis_tools/search.py

@@ -0,0 +1,195 @@
+"""Search tool. A Python port of pi's grep tool (earendil-works/pi @ 98d2e19, MIT,
+Copyright (c) 2025 Mario Zechner). ToolsModel runs it in the task container as
+`python -m thesis_tools.search '<json args>'`. Differences from pi are marked "Deviation".
+"""
+
+import functools
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from thesis_tools.args import validate as validate_args
+
+DEFAULT_LIMIT = 100
+DEFAULT_MAX_BYTES = 50 * 1024
+MAX_LINE_LENGTH = 500
+
+RG = Path(sys.executable).parent / "rg"
+
+SEARCH_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "search",
+        "description": (
+            "Search file contents for a pattern. Returns matching lines with file paths and line numbers. "
+            f"Respects .gitignore. Output is truncated to {DEFAULT_LIMIT} matches or "
+            f"{DEFAULT_MAX_BYTES // 1024}KB (whichever is hit first). "
+            f"Long lines are truncated to {MAX_LINE_LENGTH} chars."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string", "description": "Search pattern (regex or literal string)"},
+                "path": {
+                    "type": "string",
+                    "description": "Directory or file to search (default: current directory)",
+                },
+                "glob": {
+                    "type": "string",
+                    "description": "Filter files by glob pattern, e.g. '*.ts' or '**/*.spec.ts'",
+                },
+                "ignoreCase": {"type": "boolean", "description": "Case-insensitive search (default: false)"},
+                "literal": {
+                    "type": "boolean",
+                    "description": "Treat pattern as literal string instead of regex (default: false)",
+                },
+                "context": {
+                    "type": "number",
+                    "description": "Number of lines to show before and after each match (default: 0)",
+                },
+                "limit": {"type": "number", "description": "Maximum number of matches to return (default: 100)"},
+            },
+            "required": ["pattern"],
+        },
+    },
+}
+
+class SearchError(Exception):
+    """An error the model sees as the tool result. Any other exception is a bug and crashes."""
+
+
+@functools.cache
+def file_lines(file_path):
+    """Reads a file's lines, cached so a file with many matches is read only once. Empty if unreadable."""
+    try:
+        # newline="" so only "\n" ends a line, like in rg. otherwise a lone "\r" shifts the line numbers.
+        # Deviation: pi splits on "\r" too, which misaligns context lines in old Mac-style files.
+        with open(file_path, encoding="utf-8", errors="replace", newline="") as f:
+            return f.read().split("\n")
+    except OSError:
+        return []
+
+
+def truncate_line(line):
+    if len(line) <= MAX_LINE_LENGTH:
+        return line, False
+    return f"{line[:MAX_LINE_LENGTH]}... [truncated]", True
+
+
+def truncate_head(content):
+    """Cuts the whole output at 50KB, never mid-line. Returns (text, whether it cut)."""
+    if len(content.encode()) <= DEFAULT_MAX_BYTES:
+        return content, False
+    kept, size = [], 0
+    for i, line in enumerate(content.split("\n")):
+        size += len(line.encode()) + (1 if i else 0)
+        if size > DEFAULT_MAX_BYTES:
+            break
+        kept.append(line)
+    return "\n".join(kept), True
+
+
+def search(pattern, path=None, glob=None, ignoreCase=False, literal=False, context=0, limit=DEFAULT_LIMIT):
+    """Runs rg and returns the text the model sees. Expected problems (bad path, bad regex) raise SearchError."""
+    search_path = os.path.abspath(os.path.expanduser(path or "."))
+    if not os.path.exists(search_path):
+        raise SearchError(f"Path not found: {search_path}")
+    is_dir = os.path.isdir(search_path)
+
+    # how many lines to show above and below each match
+    context = max(int(context), 0)
+
+    # maximum number of matches to return
+    limit = max(int(limit), 1)
+
+    args = [RG, "--json", "--line-number", "--color=never", "--hidden"]
+    if ignoreCase:
+        args.append("--ignore-case")
+    if literal:
+        args.append("--fixed-strings")
+    if glob:
+        args += ["--glob", glob]
+    # Deviation: we exclude .git since hits in there aren't useful. pi doesn't, but most
+    # other harnesses do it this way. Has to come after the user's glob, the last glob wins in rg.
+    args += ["--glob", "!.git"]
+    args += ["--", pattern, search_path]
+
+    # we use the temporary file to write error messages into, since we only read stdout. a stderr pipe would fill up at 64KB
+    with tempfile.TemporaryFile() as stderr:
+        proc = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=stderr)
+        matches, limit_reached = [], False
+        for line in proc.stdout:
+            event = json.loads(line)
+            if event["type"] != "match":
+                continue
+            data = event["data"]
+            # rg sends "bytes" instead of "text" for paths that aren't valid UTF-8
+            file_path = data["path"].get("text")
+            if file_path:
+                matches.append((file_path, data["line_number"]))
+            if len(matches) >= limit:
+                limit_reached = True
+                proc.kill()
+                break
+        proc.stdout.close()
+        code = proc.wait()
+        stderr.seek(0)
+        stderr_text = stderr.read().decode(errors="replace").strip()
+
+    if not limit_reached and code not in (0, 1):
+        raise SearchError(stderr_text or f"ripgrep exited with code {code}")
+    if not matches:
+        return "No matches found"
+
+    lines_truncated = False
+    output_lines = []
+    # search is done, now we format each match as one line like "src/app.py:12: def target():".
+    # the model only sees this text, so it needs the file and line number to find the match again.
+    for file_path, line_number in matches:
+        # shorten the full path rg gives us. for a folder search, the path from that folder. for a file search, just the file name.
+        relative = os.path.relpath(file_path, search_path) if is_dir else os.path.basename(file_path)
+        lines = file_lines(file_path)
+        if not lines:
+            output_lines.append(f"{relative}:{line_number}: (unable to read file)")
+            continue
+        # print the match plus `context` lines above and below. ":" marks the match, "-" the lines around it
+        for current in range(max(1, line_number - context), min(len(lines), line_number + context) + 1):
+            text, cut = truncate_line(lines[current - 1].replace("\r", ""))
+            lines_truncated |= cut
+            sep = ":" if current == line_number else "-"
+            output_lines.append(f"{relative}{sep}{current}{sep} {text}")
+
+    output, bytes_truncated = truncate_head("\n".join(output_lines))
+    notices = []
+    if limit_reached:
+        notices.append(f"{limit} matches limit reached. Use limit={limit * 2} for more, or refine pattern")
+    if bytes_truncated:
+        notices.append(f"{DEFAULT_MAX_BYTES / 1024:.1f}KB limit reached")
+    if lines_truncated:
+        # Deviation: pi says "Use read tool to see full lines", and we dont have a read tool yet
+        notices.append(f"Some lines truncated to {MAX_LINE_LENGTH} chars. Use bash to see full lines")
+    if notices:
+        output += f"\n\n[{'. '.join(notices)}]"
+    return output
+
+
+def validate(raw_args):
+    """Checks the JSON arguments against SEARCH_TOOL's schema, see args.validate."""
+    return validate_args(raw_args, SEARCH_TOOL, SearchError)
+
+
+def main():
+    # always write UTF-8, so a container with an odd locale can't crash us on non-ASCII matches
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    try:
+        sys.stdout.write(search(**validate(sys.argv[1])))
+    except SearchError as e:
+        sys.stdout.write(str(e))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()