turnloop 0.1.0__py3-none-any.whl

turnloop/tools/task.py

@@ -0,0 +1,161 @@
+"""Task — delegate to a subagent.
+
+`parallel_safe = True`, so several Task calls in one assistant message fan out
+concurrently. The bound is the provider's `max_concurrent_requests`, applied
+through a limiter created once per provider — on the GLM deployment that is vLLM's
+`--max-num-seqs 16` for the whole process, and the parent's own in-flight request
+counts as one of them.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from turnloop.tools.base import Tool, ToolContext, ToolOutput
+
+SUBAGENT_TYPES = ("general", "explore", "verify")
+
+
+class TaskArgs(BaseModel):
+    description: str = Field(description="3-5 word label shown to the user.")
+    prompt: str = Field(
+        description="The full task. The subagent sees only this — include all context it needs."
+    )
+    subagent_type: str = Field(
+        default="general",
+        description="'general' (default), 'explore' (read-only search), 'verify' (check work).",
+    )
+
+
+class TaskTool(Tool):
+    name = "Task"
+    Args = TaskArgs
+    read_only = False  # a general subagent can write
+    parallel_safe = True
+    timeout_s = None  # bounded by the child's own iteration cap
+
+    descriptions = {
+        "terse": """
+Delegate a task to a subagent with its own context. Only its final answer returns
+to you. Types: general, explore (read-only search), verify. Several Task calls in
+one turn run in parallel.
+""",
+        "normal": """
+Delegate work to a subagent that has its own context window.
+
+- The subagent sees only your `prompt` — it cannot see this conversation. Include
+  every piece of context it needs.
+- Only its final message comes back to you. Its intermediate tool calls never
+  enter your context, which is the point: you pay for the answer, not the search.
+- It cannot ask you or the user questions, so make the task self-contained.
+- Types: `general` (full tools), `explore` (read-only, for searching), `verify`
+  (checks whether work is actually complete).
+- Issue several Task calls in one turn to run them in parallel.
+- Use it for: broad searches that would flood your context, and independent pieces
+  of work. Do not use it for a task you could finish in two tool calls — the
+  overhead is real.
+""",
+        "verbose": """
+Delegate work to a subagent that has its own context window.
+
+Arguments:
+- `description`: a 3-5 word label shown to the user while it runs.
+- `prompt`: the complete task. This is all the subagent will see.
+- `subagent_type`: `general`, `explore`, or `verify`.
+
+How it works:
+- The subagent starts fresh. It cannot see this conversation, your files, or your
+  reasoning. Anything it needs must be in `prompt`, including file paths and any
+  constraint you have already established.
+- It runs its own tool loop and returns a single final message. Its intermediate
+  steps never enter your context — that is the entire economic argument for using
+  it. A child that reads twenty files and reports three line numbers costs you
+  three line numbers.
+- It cannot spawn further subagents and cannot ask questions. Make the task
+  self-contained, and tell it what to do if it hits an ambiguity.
+- Its work counts against the same permission rules you are subject to.
+
+Subagent types:
+- `general`: all tools, including writes. For self-contained implementation work.
+- `explore`: read-only tools only. For "where is X", "what calls Y", "map this
+  directory". Safe to fan out, since it cannot modify anything.
+- `verify`: for checking whether stated work is actually complete — runs tests,
+  reads the changed files, reports what it observed.
+
+Parallelism:
+- Several Task calls in one assistant message run concurrently, bounded by the
+  provider's concurrency limit.
+- Give each one a genuinely independent task. Two children editing the same file
+  will conflict, and neither knows about the other.
+
+When not to use it:
+- Reading two known files. Just read them.
+- Anything needing back-and-forth with the user.
+- Work where you need to see the intermediate steps to judge the result.
+""",
+    }
+
+    async def run(self, args: TaskArgs, ctx: ToolContext) -> ToolOutput:
+        if ctx.depth >= 1:
+            return ToolOutput.error(
+                "A subagent cannot spawn further subagents. Do this work directly."
+            )
+
+        provider = ctx.extras.get("provider")
+        registry = ctx.extras.get("registry")
+        ui = ctx.extras.get("ui")
+        if provider is None or registry is None or ui is None:
+            return ToolOutput.error("subagents are not available in this context")
+
+        subagent_type = args.subagent_type if args.subagent_type in SUBAGENT_TYPES else "general"
+
+
+        limiter = ctx.extras.get("limiter")
+        if limiter is not None:
+            async with limiter:
+                result = await self._spawn(args, ctx, provider, registry, ui, subagent_type)
+        else:
+            result = await self._spawn(args, ctx, provider, registry, ui, subagent_type)
+
+        note = "\n\n[answer was condensed to fit]" if result.truncated else ""
+        return ToolOutput(
+            content=result.text + note,
+            display=(
+                f"{args.description} — {result.turns} turn(s), "
+                f"{result.tool_calls} tool call(s), ${result.cost_usd:.4f}"
+            ),
+            metrics={
+                "subagent_type": subagent_type,
+                "turns": result.turns,
+                "tool_calls": result.tool_calls,
+                "cost_usd": result.cost_usd,
+            },
+        )
+
+    async def _spawn(self, args: TaskArgs, ctx: ToolContext, provider, registry, ui,
+                     subagent_type: str):
+        from turnloop.agent.subagent import run_subagent
+
+        return await run_subagent(
+            prompt=args.prompt,
+            subagent_type=subagent_type,
+            provider=provider,
+            registry=registry,
+            permissions=ctx.permissions,
+            settings=ctx.settings,
+            cwd=ctx.cwd,
+            ui=ui,
+            parent_session=ctx.session,
+            limiter=ctx.extras.get("limiter"),
+        )
+
+    def summary(self, args: TaskArgs) -> str:  # type: ignore[override]
+        return f"Task[{args.subagent_type}] {args.description}"
+
+    def permission_target(self, args: TaskArgs) -> str:  # type: ignore[override]
+        return args.subagent_type
+
+    def is_read_only_for(self, args: TaskArgs) -> bool:  # type: ignore[override]
+        # An explore subagent has only read-only tools, so delegating to one is
+        # itself a read-only act — which makes it usable in plan mode.
+        return args.subagent_type == "explore"

turnloop/tools/textio.py

@@ -0,0 +1,87 @@
+"""Text file IO that does not mangle line endings.
+
+On Windows this is not a nicety. Python's default text mode translates "\\n" to
+"\\r\\n" on write, so a tool that reads a LF file and writes it back produces a
+diff on every single line. Conversely, writing LF into a CRLF repository does the
+same in reverse. Both make a one-line edit look like a rewrite in review.
+
+So: read bytes, decode explicitly, and write back with the newline style the file
+already had.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+CRLF = "\r\n"
+LF = "\n"
+
+
+BOM = ""
+
+
+def read_text(path: Path) -> str:
+    """Decode a file without newline translation, dropping any BOM.
+
+    Windows tooling writes UTF-8 with a BOM freely (PowerShell's `Set-Content
+    -Encoding utf8` does it by default). Leaving it in the string puts an invisible
+    U+FEFF at the start of line 1, which makes `ast.parse` fail with "invalid
+    non-printable character" and makes an exact-match Edit on the first line fail
+    for no visible reason. `has_bom` + `write_text` put it back.
+    """
+    return path.read_bytes().decode("utf-8-sig", errors="replace")
+
+
+def has_bom(path: Path) -> bool:
+    try:
+        return path.read_bytes().startswith(b"\xef\xbb\xbf")
+    except OSError:
+        return False
+
+
+def detect_newline(path: Path) -> str:
+    """The dominant newline style of an existing file, defaulting to LF."""
+    try:
+        head = path.read_bytes()[:65_536]
+    except OSError:
+        return LF
+    crlf = head.count(b"\r\n")
+    lf = head.count(b"\n") - crlf
+    if crlf > lf:
+        return CRLF
+    return LF
+
+
+def ends_with_newline(text: str) -> bool:
+    return text.endswith(("\n", "\r"))
+
+
+def write_text(path: Path, content: str, newline: str | None = None,
+               bom: bool = False) -> None:
+    """Write text with an explicit newline style, in binary mode.
+
+    `newline=None` means "whatever the string already contains" — used for new
+    files, where the caller's content is authoritative. `bom` restores a byte-order
+    mark the file already had, so editing a BOM'd file does not silently re-encode it.
+    """
+    if newline:
+        normalized = content.replace(CRLF, LF).replace("\r", LF)
+        if newline != LF:
+            normalized = normalized.replace(LF, newline)
+    else:
+        normalized = content
+    normalized = normalized.removeprefix(BOM)
+    path.write_bytes((BOM + normalized if bom else normalized).encode("utf-8"))
+
+
+def preserve_trailing_newline(original: str, updated: str) -> str:
+    """Keep the original file's trailing-newline convention.
+
+    A model that drops the final newline creates a spurious "\\ No newline at end
+    of file" hunk in every subsequent diff.
+    """
+    if ends_with_newline(original) and not ends_with_newline(updated):
+        return updated + ("\r\n" if original.endswith(CRLF) else "\n")
+    if not ends_with_newline(original) and ends_with_newline(updated):
+        return updated.rstrip("\r\n")
+    return updated

turnloop/tools/todo.py

@@ -0,0 +1,140 @@
+"""TodoWrite — the agent's externalized plan.
+
+Cheap and unglamorous, and it changes behavior more than its size suggests: a
+written plan survives compaction (it is preserved verbatim), it stops the model
+from silently dropping the third of four requested items, and it gives the user
+something to watch during a long turn.
+
+Validating "exactly one in_progress" is not pedantry. A model that marks six items
+in progress has stopped tracking anything.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from turnloop.sessions.models import Todo
+from turnloop.tools.base import Tool, ToolContext, ToolOutput
+
+
+class TodoWriteArgs(BaseModel):
+    todos: list[Todo] = Field(description="The complete task list, replacing the previous one.")
+
+
+class TodoWriteTool(Tool):
+    name = "TodoWrite"
+    Args = TodoWriteArgs
+    read_only = True  # touches session state only, never the filesystem
+    parallel_safe = False
+
+    descriptions = {
+        "terse": """
+Maintain the task list. Send the whole list every time. Exactly one item
+in_progress. Mark items completed as you finish them.
+""",
+        "normal": """
+Track multi-step work.
+
+- Send the complete list on every call; it replaces the previous one.
+- Each item has `content` (imperative: "Add the retry test"), `activeForm`
+  (present continuous: "Adding the retry test"), and `status` (pending,
+  in_progress, completed).
+- Exactly one item may be in_progress.
+- Mark an item completed as soon as it is done, not in a batch at the end.
+- Use this for work with three or more steps, or when the user listed several
+  things. Skip it for single-step tasks — the overhead is not worth it.
+""",
+        "verbose": """
+Track multi-step work by maintaining a task list.
+
+Arguments:
+- `todos`: the complete list. Every call replaces the whole list, so include the
+  items that have not changed.
+
+Each item:
+- `content`: imperative form — "Add the retry test", "Fix the CRLF handling".
+- `activeForm`: present continuous, shown to the user while it runs — "Adding the
+  retry test".
+- `status`: `pending`, `in_progress`, or `completed`.
+
+Rules:
+- Exactly one item is in_progress at a time. Marking several defeats the purpose.
+- Mark an item completed immediately on finishing it. Batching completions at the
+  end means the list is wrong for the whole session.
+- Do not mark something completed if it partially works, if tests fail, or if you
+  could not verify it. Leave it in progress and say what is blocking.
+- Add newly discovered work as new items rather than expanding an existing one.
+
+When to use it: three or more distinct steps, or the user listed several things.
+When not to: a single edit, a question, or something purely conversational — the
+list would be noise.
+
+This list survives context compaction verbatim, so it is also how you remember
+your own plan across a long session.
+""",
+    }
+
+    async def run(self, args: TodoWriteArgs, ctx: ToolContext) -> ToolOutput:
+        in_progress = [t for t in args.todos if t.status == "in_progress"]
+        if len(in_progress) > 1:
+            return ToolOutput.error(
+                f"{len(in_progress)} items are in_progress: "
+                f"{', '.join(t.content[:40] for t in in_progress)}. "
+                "Exactly one item may be in progress — pick the one you are actually working on."
+            )
+
+        for todo in args.todos:
+            if not todo.activeForm:
+                todo.activeForm = _to_active(todo.content)
+
+        previous = {t.content: t.status for t in ctx.session.todos}
+        ctx.session.set_todos(args.todos)
+
+        newly_done = [
+            t.content for t in args.todos
+            if t.status == "completed" and previous.get(t.content) != "completed"
+        ]
+        counts = {
+            status: sum(1 for t in args.todos if t.status == status)
+            for status in ("pending", "in_progress", "completed")
+        }
+
+        lines = [f"Task list updated: {counts['completed']} done, "
+                 f"{counts['in_progress']} in progress, {counts['pending']} pending."]
+        if newly_done:
+            lines.append("Completed: " + "; ".join(newly_done))
+        if in_progress:
+            lines.append(f"Now: {in_progress[0].activeForm}")
+
+        return ToolOutput(
+            content="\n".join(lines),
+            display=ctx.session.todo_summary(),
+            metrics={"todos": len(args.todos), **counts},
+        )
+
+    def summary(self, args: TodoWriteArgs) -> str:  # type: ignore[override]
+        active = next((t for t in args.todos if t.status == "in_progress"), None)
+        return f"TodoWrite — {active.activeForm}" if active else "TodoWrite"
+
+
+def _to_active(content: str) -> str:
+    """Derive a present-continuous form when the model omits one."""
+    words = content.split()
+    if not words:
+        return content
+    verb = words[0]
+    lower = verb.lower()
+    irregular = {
+        "add": "Adding", "fix": "Fixing", "run": "Running", "write": "Writing",
+        "make": "Making", "get": "Getting", "set": "Setting", "put": "Putting",
+        "create": "Creating", "update": "Updating", "remove": "Removing",
+        "delete": "Deleting", "refactor": "Refactoring", "test": "Testing",
+        "implement": "Implementing", "verify": "Verifying", "check": "Checking",
+    }
+    if lower in irregular:
+        head = irregular[lower]
+    elif lower.endswith("e") and not lower.endswith(("ee", "ye", "oe")):
+        head = verb[:-1].capitalize() + "ing"
+    else:
+        head = verb.capitalize() + "ing"
+    return " ".join([head, *words[1:]])

turnloop/tools/webfetch.py

@@ -0,0 +1,235 @@
+"""WebFetch — retrieve a URL and answer a question about it.
+
+The design constraint is context, not networking. A documentation page is commonly
+50-150k characters; dropping that into a 57k-token window destroys the session. So
+the page is never returned raw: it is converted to text, capped, and then passed
+through the model with the caller's question, and only that answer enters the
+conversation.
+
+Redirects are followed only within the same host by default. A tool that fetches
+arbitrary URLs on a model's say-so is an SSRF primitive, and cross-host redirects
+are how that gets exploited.
+"""
+
+from __future__ import annotations
+
+import time
+from html.parser import HTMLParser
+from urllib.parse import urlparse
+
+import httpx
+from pydantic import BaseModel, Field
+
+from turnloop.tools.base import Tool, ToolContext, ToolOutput
+
+MAX_CHARS = 100_000
+CACHE_TTL_S = 15 * 60
+BLOCKED_HOSTS = {"localhost", "127.0.0.1", "0.0.0.0", "::1", "169.254.169.254"}
+
+_cache: dict[str, tuple[float, str]] = {}
+
+
+class WebFetchArgs(BaseModel):
+    url: str = Field(description="The URL to fetch. Must be http or https.")
+    prompt: str = Field(description="What to extract or answer from the page.")
+
+
+class WebFetchTool(Tool):
+    name = "WebFetch"
+    Args = WebFetchArgs
+    read_only = True
+    parallel_safe = True
+    timeout_s = 120.0
+
+    descriptions = {
+        "terse": """
+Fetch a URL and answer `prompt` about its content. Returns the answer, not the
+page. Use for documentation and specific pages you have a URL for.
+""",
+        "normal": """
+Fetch a web page and extract what you asked for.
+
+- `url` must be http or https.
+- `prompt` says what to extract; the page is summarized against it and you receive
+  the answer, not the raw HTML.
+- Results are cached for 15 minutes.
+- Use this when you have a specific URL — documentation, an issue, a spec. It is
+  not a search engine.
+""",
+        "verbose": """
+Fetch a web page and extract what you asked for.
+
+Arguments:
+- `url`: an http or https URL.
+- `prompt`: what you want from the page — "the migration steps for v3", "the
+  signature of the retry decorator".
+
+Behavior:
+- HTML is converted to text (scripts, styles and navigation removed) and capped at
+  100,000 characters.
+- That text is then passed through the model together with your prompt, and you
+  receive the extracted answer. The raw page never enters the conversation, because
+  a single documentation page can be larger than the entire context window.
+- Redirects are followed only within the same host. A cross-host redirect is
+  reported rather than followed.
+- Requests to localhost and link-local addresses are refused.
+- Responses are cached for 15 minutes, so re-fetching the same URL in one session
+  is free.
+
+This is not a search engine. If you do not have a URL, ask the user for one.
+""",
+    }
+
+    async def run(self, args: WebFetchArgs, ctx: ToolContext) -> ToolOutput:
+        parsed = urlparse(args.url)
+        if parsed.scheme not in ("http", "https"):
+            return ToolOutput.error(f"unsupported scheme {parsed.scheme!r}; use http or https")
+        host = (parsed.hostname or "").lower()
+        if host in BLOCKED_HOSTS or host.endswith(".local"):
+            return ToolOutput.error(
+                f"refusing to fetch {host}: local and link-local addresses are blocked"
+            )
+
+        cached = _cache.get(args.url)
+        if cached and time.monotonic() - cached[0] < CACHE_TTL_S:
+            text = cached[1]
+            from_cache = True
+        else:
+            try:
+                async with httpx.AsyncClient(
+                    timeout=httpx.Timeout(30.0, connect=10.0), follow_redirects=False
+                ) as client:
+                    response = await client.get(
+                        args.url, headers={"user-agent": "turnloop/0.1 (+coding agent)"}
+                    )
+                    if response.is_redirect:
+                        location = response.headers.get("location", "")
+                        target_host = (urlparse(location).hostname or host).lower()
+                        if target_host != host:
+                            return ToolOutput(
+                                content=(
+                                    f"{args.url} redirects to a different host: {location}\n"
+                                    "Not following it automatically. Call WebFetch again with "
+                                    "that URL if you want it."
+                                )
+                            )
+                        response = await client.get(location)
+            except httpx.HTTPError as exc:
+                return ToolOutput.error(f"fetch failed: {type(exc).__name__}: {exc}")
+
+            if response.status_code >= 400:
+                return ToolOutput.error(f"HTTP {response.status_code} from {args.url}")
+
+            content_type = response.headers.get("content-type", "")
+            body = response.text
+            text = html_to_text(body) if "html" in content_type else body
+            text = text[:MAX_CHARS]
+            _cache[args.url] = (time.monotonic(), text)
+            from_cache = False
+
+        if not text.strip():
+            return ToolOutput.error(f"{args.url} returned no readable text")
+
+        answer = await self._extract(text, args.prompt, ctx)
+        return ToolOutput(
+            content=answer,
+            display=f"WebFetch {args.url} ({len(text):,} chars{' cached' if from_cache else ''})",
+            metrics={"chars": len(text), "cached": from_cache},
+        )
+
+    async def _extract(self, text: str, prompt: str, ctx: ToolContext) -> str:
+        """Summarize the page against the prompt using the session's provider."""
+        provider = ctx.extras.get("provider")
+        if provider is None:
+            return f"(no provider available to summarize; first 4000 chars)\n\n{text[:4000]}"
+
+        from turnloop.core.events import MessageDone
+        from turnloop.core.messages import Message
+        from turnloop.providers.base import CompletionRequest
+
+        request = CompletionRequest(
+            messages=[
+                Message.user_text(
+                    f"{prompt}\n\nAnswer only from the page content below. If it does not "
+                    f"contain the answer, say so.\n\n---\n{text[:60_000]}"
+                )
+            ],
+            system=["Extract exactly what was asked from the supplied page. Be concise."],
+            tools=[],
+            max_tokens=2_000,
+            temperature=0.0,
+        )
+        try:
+            async for event in provider.stream(request):
+                if isinstance(event, MessageDone):
+                    return event.message.text.strip() or "(the model returned nothing)"
+        except Exception as exc:  # noqa: BLE001
+            return f"(summarization failed: {exc})\n\nFirst 4000 characters:\n{text[:4000]}"
+        return text[:4000]
+
+    def summary(self, args: WebFetchArgs) -> str:  # type: ignore[override]
+        return f"WebFetch {args.url}"
+
+
+class _TextExtractor(HTMLParser):
+    """HTML to text using only the standard library.
+
+    Not a full renderer, and it does not need to be: headings, paragraphs, list
+    items and code blocks carry essentially all the information in technical
+    documentation.
+    """
+
+    SKIP = {"script", "style", "noscript", "svg", "nav", "footer", "header", "form"}
+    BLOCK = {
+        "p", "div", "br", "li", "tr", "h1", "h2", "h3", "h4", "h5", "h6",
+        "pre", "blockquote", "section", "article", "table",
+    }
+
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.parts: list[str] = []
+        self._skip_depth = 0
+
+    def handle_starttag(self, tag: str, attrs) -> None:
+        if tag in self.SKIP:
+            self._skip_depth += 1
+        elif tag in self.BLOCK:
+            self.parts.append("\n")
+        if tag == "li":
+            self.parts.append("- ")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in self.SKIP and self._skip_depth:
+            self._skip_depth -= 1
+        elif tag in self.BLOCK:
+            self.parts.append("\n")
+
+    def handle_data(self, data: str) -> None:
+        if self._skip_depth:
+            return
+        if data.strip():
+            self.parts.append(data)
+
+    def text(self) -> str:
+        joined = "".join(self.parts)
+        lines = [" ".join(line.split()) for line in joined.splitlines()]
+        out: list[str] = []
+        blank = 0
+        for line in lines:
+            if not line:
+                blank += 1
+                if blank > 1:
+                    continue
+            else:
+                blank = 0
+            out.append(line)
+        return "\n".join(out).strip()
+
+
+def html_to_text(html: str) -> str:
+    parser = _TextExtractor()
+    try:
+        parser.feed(html)
+    except Exception:  # noqa: BLE001 - malformed HTML is the norm
+        pass
+    return parser.text()