stcode 0.0.1a0__py3-none-any.whl

stcode/core/harness/tools/files.py

@@ -0,0 +1,276 @@
+"""
+File tools — `read`, `write`, `edit`.
+
+One design, not three: **an agent may only change what it has looked at.** `read`
+records what it saw; `write` and `edit` refuse a file this session has not read, and
+warn when it changed underneath them. The cost is asymmetric — a refused edit costs one
+turn, an overwritten file the agent never read costs work that no longer exists.
+
+`edit` matches an exact, unique string, not a line range or a diff: line numbers go
+stale the moment anything above them moves, and a fuzzy match silently edits the wrong
+place, while a unique literal either matches once or fails loudly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+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
+
+MAX_LINE_LENGTH = 2000
+"""Chars per line before it is cut. A minified bundle is one line of hundreds of
+thousands of chars, and without this a single `read` blows the whole context window."""
+
+DEFAULT_READ_LIMIT = 2000
+"""Lines returned when the caller does not say. Enough for almost any source file, small
+enough that reading a log by accident is survivable."""
+
+READ_MAX_OUTPUT = 32768
+"""`read` shows more than other tools before eliding — file contents are the ground
+truth an agent reasons from, and a half-seen function is worse than a slow turn."""
+
+_BINARY_SNIFF_BYTES = 8192
+
+
+def _is_binary(path: Path) -> bool:
+    """A NUL byte in the first pages — what `grep` and `git` use, and right about source
+    trees far more often than any extension list."""
+    try:
+        with path.open("rb") as handle:
+            return b"\x00" in handle.read(_BINARY_SNIFF_BYTES)
+    except OSError:
+        return False
+
+
+def number_lines(lines: list[str], start: int = 1) -> str:
+    """Render with line numbers, `cat -n` style.
+
+    Not decoration: they are how the agent cites `file.py:42`, how `edit` failures are
+    explained, and how a second read lines up with the first.
+    """
+    return "\n".join(f"{start + offset:6d}\t{line}" for offset, line in enumerate(lines))
+
+
+@tool(permission=ToolPermission.READ, max_output=READ_MAX_OUTPUT)
+async def read(
+    path: str,
+    offset: Annotated[int, Field(ge=0)] = 0,
+    limit: Annotated[int | None, Field(ge=1)] = None,
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Read a file from the filesystem and return it with line numbers.
+
+    Prefer reading a whole file over guessing which part matters: the numbers you get
+    back are what you cite in your answer and what `edit` needs to be unambiguous. For
+    a file too large to take in one go, page through it with `offset`.
+
+    Reading a file is also what earns you the right to change it — `write` and `edit`
+    both refuse to touch a file this session has not read.
+
+    Args:
+        path: File to read. Absolute, or relative to the session's working directory.
+        offset: 0-based line to start at. Use when paging through a large file.
+        limit: How many lines to return. Defaults to 2000.
+    """
+    context = runtime.context
+    target = context.resolve(path)
+
+    if not target.exists():
+        near = _suggest_neighbours(target)
+        raise ToolError(f"{target} does not exist.{near}")
+    if target.is_dir():
+        raise ToolError(f"{target} is a directory. Use `ls` to list it, or `glob` to find files in it.")
+    if _is_binary(target):
+        size = target.stat().st_size
+        raise ToolError(
+            f"{target} is a binary file ({size:,} bytes) and cannot be read as text. "
+            "Use `bash` with a tool that understands its format."
+        )
+
+    text = target.read_text(encoding="utf-8", errors="replace")
+    context.note_read(target)
+
+    if not text:
+        return f"{target} exists but is empty (0 bytes)."
+
+    lines = text.splitlines()
+    window = lines[offset : offset + (limit or DEFAULT_READ_LIMIT)]
+    if not window:
+        raise ToolError(
+            f"{target} has {len(lines):,} lines; offset {offset} is past the end."
+        )
+
+    clipped = [
+        line if len(line) <= MAX_LINE_LENGTH else f"{line[:MAX_LINE_LENGTH]}… [line truncated]"
+        for line in window
+    ]
+    body = number_lines(clipped, start=offset + 1)
+
+    shown_to = offset + len(window)
+    if shown_to < len(lines):
+        body += (
+            f"\n\n[showing lines {offset + 1}-{shown_to} of {len(lines):,}; "
+            f"continue with offset={shown_to}]"
+        )
+    return body
+
+
+@tool(permission=ToolPermission.WRITE)
+async def write(
+    path: str,
+    content: str,
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Write `content` to `path`, replacing whatever is there. Creates parent directories.
+
+    This replaces the entire file. To change part of one, use `edit` — a whole-file
+    rewrite of a file you only partly understand silently drops the parts you did not
+    reproduce.
+
+    Never write documentation, READMEs, or summary files unless they were asked for.
+
+    Args:
+        path: File to write. Absolute, or relative to the working directory.
+        content: The complete new contents of the file.
+    """
+    context = runtime.context
+    target = context.ensure_writable(path)
+
+    existed = target.exists()
+    if existed:
+        if target.is_dir():
+            raise ToolError(f"{target} is a directory.")
+        if not context.has_read(target):
+            raise ToolError(
+                f"{target} already exists and this session has not read it. Read it "
+                "first — overwriting a file you have not seen destroys work you cannot "
+                "get back."
+            )
+        if context.changed_since_read(target):
+            raise ToolError(
+                f"{target} changed on disk since you read it. Read it again, then decide "
+                "whether your change still applies."
+            )
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+    context.note_read(target)
+
+    verb = "Updated" if existed else "Created"
+    return f"{verb} {target} ({len(content.splitlines()):,} lines, {len(content):,} bytes)."
+
+
+@tool(permission=ToolPermission.WRITE)
+async def edit(
+    path: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool = False,
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Replace an exact string in a file. The match must be unique unless `replace_all`.
+
+    Include enough surrounding context in `old_string` to make it unique — usually two
+    or three lines is plenty. If the edit fails because the string appears more than
+    once, widen it rather than switching to `replace_all`: "there are three of these and
+    I meant the second" is a different intent from "change all three".
+
+    Preserve the file's existing indentation exactly. `read` prefixes every line with a
+    line number and a tab; that prefix is not part of the file, and including it in
+    `old_string` is the most common reason an edit finds no match.
+
+    Args:
+        path: File to edit.
+        old_string: Exact text to find, including its indentation.
+        new_string: Text to replace it with. Must differ from `old_string`.
+        replace_all: Replace every occurrence instead of requiring exactly one.
+    """
+    context = runtime.context
+    target = context.ensure_writable(path)
+
+    if old_string == new_string:
+        raise ToolError("`old_string` and `new_string` are identical — nothing to do.")
+    if not target.exists():
+        raise ToolError(f"{target} does not exist. Use `write` to create it.")
+    if not context.has_read(target):
+        raise ToolError(f"Read {target} before editing it.")
+    if context.changed_since_read(target):
+        raise ToolError(
+            f"{target} changed on disk since you read it. Read it again before editing."
+        )
+
+    original = target.read_text(encoding="utf-8", errors="replace")
+    occurrences = original.count(old_string)
+
+    if occurrences == 0:
+        raise ToolError(
+            f"`old_string` was not found in {target}.\n"
+            f"{_mismatch_hint(original, old_string)}"
+        )
+    if occurrences > 1 and not replace_all:
+        raise ToolError(
+            f"`old_string` appears {occurrences} times in {target}. Add surrounding "
+            "lines until it is unique, or pass replace_all=True if you mean all of them."
+        )
+
+    updated = original.replace(old_string, new_string)
+    target.write_text(updated, encoding="utf-8")
+    context.note_read(target)
+
+    count = f"{occurrences} occurrences" if replace_all and occurrences > 1 else "1 occurrence"
+    return f"Edited {target} ({count} replaced).\n\n{_edit_preview(updated, new_string)}"
+
+
+def _edit_preview(text: str, needle: str, context_lines: int = 4) -> str:
+    """Show the edited region with line numbers, so the agent sees what it produced.
+
+    A bare confirmation invites the agent to assume the edit landed as imagined. This is
+    how a wrong-but-successful edit gets noticed now instead of three turns later.
+    """
+    index = text.find(needle.split("\n", 1)[0]) if needle else -1
+    if index < 0:
+        return ""
+    line_number = text.count("\n", 0, index)
+    lines = text.splitlines()
+    start = max(line_number - context_lines, 0)
+    end = min(line_number + needle.count("\n") + context_lines + 1, len(lines))
+    return number_lines(lines[start:end], start=start + 1)
+
+
+def _mismatch_hint(text: str, needle: str) -> str:
+    """Say *why* a match failed when the reason is recoverable in one step."""
+    stripped = "\n".join(line.strip() for line in needle.splitlines())
+    haystack = "\n".join(line.strip() for line in text.splitlines())
+    if stripped and stripped in haystack:
+        return (
+            "The text is present but its indentation differs. Read the file again and "
+            "copy the leading whitespace exactly."
+        )
+    first = needle.split("\n", 1)[0].strip()
+    if first and first in text:
+        return (
+            f"Its first line ({first[:60]!r}) is present, so the mismatch is further "
+            "down — a trailing space, a tab, or a line ending. Re-read that region."
+        )
+    return "Read the file and copy the target text from what you see."
+
+
+def _suggest_neighbours(target: Path, limit: int = 5) -> str:
+    """A missing file is usually a typo or the wrong directory. Say which."""
+    parent = target.parent
+    if not parent.is_dir():
+        return f" Its parent directory {parent} does not exist either."
+    siblings = sorted(p.name for p in parent.iterdir() if not p.name.startswith("."))
+    if not siblings:
+        return ""
+    return f" {parent} contains: {', '.join(siblings[:limit])}" + (
+        f", … ({len(siblings)} entries)" if len(siblings) > limit else ""
+    )
+
+
+__all__ = ["edit", "number_lines", "read", "write"]

stcode/core/harness/tools/interact.py

@@ -0,0 +1,72 @@
+"""
+Human in the loop — `ask_user_question`.
+
+Meant to be used rarely. An agent that asks at every fork is slower than doing the work
+and worse company than a colleague who makes reasonable calls; one that never asks
+builds the wrong thing confidently. The test is whether the answer would change what
+gets built.
+
+It is the one tool that hands control back: `runtime.ask` blocks the turn until the UI
+answers. With no user attached there is no `on_ask`, and it says so instead of hanging.
+"""
+
+from __future__ import annotations
+
+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 Question, Runtime, ToolError, tool
+
+
+@tool(permission=ToolPermission.INTERACTIVE, spill=False)
+async def ask_user_question(
+    question: str,
+    options: Annotated[list[str] | None, Field(max_length=4)] = None,
+    header: str = "",
+    multi_select: bool = False,
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Ask the user a question and wait for their answer.
+
+    Only for decisions that are genuinely theirs: a product choice with no right
+    answer, a trade-off you cannot resolve from the code, an ambiguity where two
+    readings lead to materially different work. Anything you can settle by reading the
+    repository, following an existing convention, or picking the obvious default, settle
+    yourself and say what you assumed.
+
+    Do not use it to ask whether to continue, whether your plan looks right, or to
+    report progress. Those stop the work without advancing the decision.
+
+    Ask everything you need in one call rather than trickling questions across turns.
+
+    Args:
+        question: The full question, ending in a question mark. Be specific about what
+            differs between the choices.
+        options: Two to four concrete choices. Put your recommendation first and mark it
+            "(recommended)". The user can always answer something else.
+        header: A 1-3 word label for the decision, e.g. "Auth method", "Storage".
+        multi_select: Allow more than one option to be chosen. For choices that are not
+            mutually exclusive.
+    """
+    if not question.strip():
+        raise ToolError("`question` is empty.")
+    if options is not None and len(options) < 2:
+        raise ToolError(
+            "Give at least two options, or none at all — a single option is not a choice."
+        )
+
+    answer = await runtime.ask(
+        Question(
+            question=question.strip(),
+            header=header.strip(),
+            options=list(options or []),
+            multi_select=multi_select,
+        )
+    )
+    return f"The user answered: {answer}"
+
+
+__all__ = ["ask_user_question"]

stcode/core/harness/tools/registry.py

@@ -0,0 +1,113 @@
+"""
+Tool registry — which tools exist, and which an agent may see.
+
+Holding tools by name is trivial; *selecting* them is where the architecture shows up. A
+sub-agent spawned with `tools=["read", "grep"]` must not reach `write`, and plan mode
+must not advertise tools it forbids — being offered a capability and then refused it
+wastes a turn and reads, to the model, like a bug to work around.
+
+Selection is by name *and* permission, and unknown names raise: a typo that quietly
+produced a smaller tool set would get diagnosed as "the model is being lazy".
+
+Beside `base.py` and `schema.py` because it belongs to the tool subsystem, not to the
+facade: it knows what a `Tool` is, and `Harness` knows it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Iterator, Sequence
+
+from stcode.core.common.tools import ToolDefinition
+from stcode.core.harness.approvals import ApprovalMode, is_forbidden
+from stcode.core.harness.tools.base import Tool, ToolError
+
+
+class ToolRegistry:
+    """A named collection of tools."""
+
+    def __init__(self, tools: Iterable[Tool[Any]] = ()) -> None:
+        self._tools: dict[str, Tool[Any]] = {}
+        for entry in tools:
+            self.register(entry)
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools
+
+    def __iter__(self) -> Iterator[Tool[Any]]:
+        return iter(self._tools.values())
+
+    def __getitem__(self, name: str) -> Tool[Any]:
+        try:
+            return self._tools[name]
+        except KeyError:
+            raise ToolError(f"No tool named {name!r}. Available: {', '.join(self.names())}.") from None
+
+    def get(self, name: str) -> Tool[Any] | None:
+        return self._tools.get(name)
+
+    def names(self) -> list[str]:
+        return sorted(self._tools)
+
+    def register(self, entry: Tool[Any], *, replace: bool = False) -> None:
+        """Add a tool. Refuses to shadow an existing name unless asked to.
+
+        Silent replacement is the failure this guards: an MCP server taking over the
+        name `read` would redirect every file read in the session, with nothing in the
+        log to say so.
+        """
+        if entry.name in self._tools and not replace:
+            raise ToolError(
+                f"A tool named {entry.name!r} is already registered. Pass replace=True "
+                "if shadowing it is intended."
+            )
+        self._tools[entry.name] = entry
+
+    def extend(self, tools: Iterable[Tool[Any]], *, replace: bool = False) -> None:
+        for entry in tools:
+            self.register(entry, replace=replace)
+
+    def select(
+        self,
+        names: Sequence[str] | None = None,
+        *,
+        approval_mode: ApprovalMode | None = None,
+    ) -> list[Tool[Any]]:
+        """The tools an agent may use, by name and by what the mode permits.
+
+        `names=None` means everything registered. Tools the mode forbids are dropped
+        rather than advertised-and-refused; ones that merely need approval are kept,
+        since asking is a normal part of using them.
+        """
+        if names is None:
+            chosen = list(self._tools.values())
+        else:
+            unknown = [name for name in names if name not in self._tools]
+            if unknown:
+                raise ToolError(
+                    f"Unknown tool(s): {', '.join(unknown)}. Available: {', '.join(self.names())}."
+                )
+            chosen = [self._tools[name] for name in names]
+
+        if approval_mode is None:
+            return chosen
+        return [entry for entry in chosen if not is_forbidden(approval_mode, entry.permission)]
+
+    def definitions(
+        self,
+        names: Sequence[str] | None = None,
+        *,
+        approval_mode: ApprovalMode | None = None,
+    ) -> list[ToolDefinition]:
+        """What goes on the wire to a provider.
+
+        Sorted by name, so the list is byte-identical between turns with the same tool
+        set — prompt caching depends on tool definitions not reordering.
+        """
+        chosen = self.select(names, approval_mode=approval_mode)
+        return [entry.to_tool_definition() for entry in sorted(chosen, key=lambda t: t.name)]
+
+
+__all__ = ["ToolRegistry"]

stcode/core/harness/tools/repl.py

@@ -0,0 +1,97 @@
+"""
+`repl` — a persistent Python interpreter for the session.
+
+The namespace lives in a subprocess (`core/repl/`) and survives between calls. Two jobs,
+both about keeping bulk out of the context window:
+
+* **MCP-as-code.** Tool definitions in the prompt prefix cost 10-30k tokens every turn;
+  the same servers under `.stcode/mcp_servers/` cost a grep and an import.
+* **`tool_out`.** What `elide` cut is injected here under the result's `output_id`, so
+  eliding loses nothing — the whole value is one slice away.
+
+Not for sub-agents, and not a replacement for `read`/`edit`/`bash`.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field
+
+from stcode.core.common.truncate import DEFAULT_VIEW_LIMIT
+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
+
+REPL_MAX_OUTPUT = DEFAULT_VIEW_LIMIT
+"""The same cap every other tool gets. The REPL has no claim to a bigger one — the whole
+point of a persistent namespace is that the bulk stays in a variable."""
+
+
+@tool(permission=ToolPermission.EXECUTE, max_output=REPL_MAX_OUTPUT, spill=False)
+async def repl(
+    code: str,
+    timeout: Annotated[float, Field(gt=0, le=900)] = DEFAULT_TIMEOUT,
+    runtime: Runtime[HarnessContext] = None,  # type: ignore[assignment]
+) -> str:
+    """Run Python in this session's persistent interpreter and return what it printed.
+
+    The namespace persists for the whole session: a variable you set now is still there
+    twenty turns from now. Use that. Assign results to names, and print only the part
+    you need to reason about — output is capped at 8192 characters, and the variable
+    holding the rest is still there to slice.
+
+    Top-level `await` works — use it. Do not call `asyncio.run(...)`: it opens its own
+    event loop and closes it when the cell ends, which drops anything the namespace was
+    holding open, such as an MCP server connection.
+
+    `tool_out` is a dict already in the namespace. When a tool result was elided, the
+    whole value is in there under the id the elision named — slice it here rather than
+    calling the tool again.
+
+    Reach for this when a result is too big to want in full, or when you need to compute
+    over something rather than read it: parse a large JSON payload and print three
+    fields, filter ten thousand rows down to the four that matter, call an MCP tool from
+    `.stcode/mcp_servers/`. For editing files and running commands, use the dedicated
+    tools — they are shorter and their output is shaped for you.
+
+    Args:
+        code: Python to execute. Multi-line is normal; this is a cell, not a line.
+        timeout: Seconds before the cell is interrupted. The namespace survives a
+            timeout, so whatever the cell managed to build is still inspectable.
+    """
+    backend = runtime.context.repl
+    if backend is None:
+        raise ToolError(
+            "This session has no REPL attached, so `repl` cannot run. Use the direct "
+            "tools (read/write/edit/bash/glob/grep) instead."
+        )
+
+    result = await backend.execute(code, timeout=timeout, on_stream=_stream_to(runtime))
+    view = result.view(REPL_MAX_OUTPUT)
+
+    if result.ok:
+        return view or "(no output)"
+    # Outcome names the failure mode; the view carries the traceback. Both matter: a
+    # timeout and an exception need different next moves, and `view()` alone does not
+    # distinguish them.
+    return f"[{result.outcome}]\n{view}" if view else f"[{result.outcome}] (no output)"
+
+
+def _stream_to(runtime: Runtime[HarnessContext]):  # type: ignore[no-untyped-def]
+    """Forward the cell's output to the UI as it arrives.
+
+    A session that looks hung is a real UX problem, and a REPL cell is the longest
+    thing a turn can contain. Progress here is the difference between "working" and
+    "frozen".
+    """
+
+    async def on_stream(name: str, text: str) -> None:
+        await runtime.progress(text)
+
+    return on_stream
+
+
+__all__ = ["DEFAULT_TIMEOUT", "REPL_MAX_OUTPUT", "repl"]