tether-sdk 0.0.2__py3-none-any.whl

tether/tools/agent.py

@@ -0,0 +1,190 @@
+"""Always-async multi-agent orchestration and SQLite FTS5 BM25 RAG (`agent`)."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+from tether.decorator import ToolSpec, build_tool_spec
+from tether.sandbox import SandboxPolicy
+from tether.skills import SkillLoader
+from tether.store import SQLiteStore
+
+
+def make_agent_tool(
+    store: SQLiteStore,
+    parent_session_id: str,
+    default_model: str,
+    parent_sandbox: SandboxPolicy,
+    skill_loader: SkillLoader,
+    worker_spawner: Callable[[str], int | None],
+    wait_timeout: float = 120.0,
+) -> ToolSpec:
+    help_str = (
+        "Usage: agent spawn [--skill s] [--model m] [--tools t] <goal> | "
+        "wait <id...> | query <id|--all> <q> [--top 3] | read <id> [--full] | send <id> <msg>\n"
+        "Desc : Spawn async sub-agents or query results via BM25 RAG."
+    )
+
+    async def _agent(args: list[str], stdin: str | None = None) -> str:
+        if not args or args[0] in ("--help", "-h"):
+            return help_str
+
+        sub = args[0]
+
+        if sub == "spawn":
+            skill_name: str | None = None
+            model_name: str | None = None
+            tools_list: list[str] = []
+            goal_parts: list[str] = []
+            i = 1
+            while i < len(args):
+                if args[i] == "--skill" and i + 1 < len(args):
+                    skill_name = args[i + 1]
+                    i += 2
+                elif args[i] == "--model" and i + 1 < len(args):
+                    model_name = args[i + 1]
+                    i += 2
+                elif args[i] == "--tools" and i + 1 < len(args):
+                    tools_list = [t.strip() for t in args[i + 1].split(",") if t.strip()]
+                    i += 2
+                else:
+                    goal_parts.append(args[i])
+                    i += 1
+
+            goal = " ".join(goal_parts).strip() or (stdin or "").strip()
+            if not goal:
+                return f"Error: missing `<goal>` for `agent spawn`.\n{help_str}"
+
+            if skill_name:
+                sk = skill_loader.load(skill_name)
+                if not sk:
+                    return f"Error: skill `{skill_name}` not found."
+                if not model_name and sk.model:
+                    model_name = sk.model
+                if not tools_list and sk.tools:
+                    tools_list = list(sk.tools)
+
+            child_sandbox = parent_sandbox.attenuate()
+            child = store.create_session(
+                goal=goal,
+                model=model_name or default_model,
+                skill=skill_name,
+                tools=tools_list,
+                sandbox_config=child_sandbox.to_dict(),
+                parent_id=parent_session_id,
+            )
+            worker_spawner(child.id)
+            return child.id
+
+        if sub == "status":
+            if len(args) < 2:
+                return f"Error: missing `<session_id>`.\n{help_str}"
+            rec = store.get_session(args[1])
+            if not rec:
+                return f"Error: session `{args[1]}` not found."
+            turns = store.get_turns(rec.id)
+            last_cmd = next((t.tool_cmd for t in reversed(turns) if t.tool_cmd), "-")
+            return (
+                f"{rec.id} [{rec.status}] step {rec.step_count}/{rec.max_steps} | "
+                f"model: {rec.model} | last: {last_cmd}"
+            )
+
+        if sub == "wait":
+            target_ids = [a for a in args[1:] if not a.startswith("-")]
+            if not target_ids:
+                return f"Error: specify one or more session IDs to wait for.\n{help_str}"
+
+            elapsed = 0.0
+            poll_interval = 0.05
+            while elapsed < wait_timeout:
+                all_done = True
+                for sid in target_ids:
+                    rec = store.get_session(sid)
+                    if rec and rec.status in ("PENDING", "RUNNING"):
+                        all_done = False
+                        break
+                if all_done:
+                    break
+                await asyncio.sleep(poll_interval)
+                elapsed += poll_interval
+
+            digests = [store.get_session_digest(sid) for sid in target_ids]
+            return "\n\n".join(digests)
+
+        if sub == "query":
+            if len(args) < 2:
+                return f"Error: usage `agent query <id|--all> <query> [--top 3]`.\n{help_str}"
+            target = args[1]
+            top_k = 3
+            q_parts: list[str] = []
+            i = 2
+            while i < len(args):
+                if args[i] == "--top" and i + 1 < len(args):
+                    try:
+                        top_k = int(args[i + 1])
+                    except ValueError:
+                        return "Error: `--top` expects an integer."
+                    i += 2
+                else:
+                    q_parts.append(args[i])
+                    i += 1
+            query = " ".join(q_parts).strip() or (stdin or "").strip()
+            if not query:
+                return f"Error: missing `<query>`.\n{help_str}"
+
+            if target == "--all":
+                children = store.list_sessions(parent_id=parent_session_id)
+                session_ids = [c.id for c in children]
+                if not session_ids:
+                    return "No child sub-agent sessions found."
+            else:
+                session_ids = [target]
+
+            hits = store.search_chunks(query, session_ids=session_ids, top_k=top_k)
+            if not hits:
+                return f"No BM25 RAG chunks matched `{query}` in {', '.join(session_ids)}."
+            blocks = [
+                f"[{h.session_id} {h.source_type}:{h.source_id}#{h.chunk_index}]\n{h.content}"
+                for h in hits
+            ]
+            return "\n\n---\n\n".join(blocks)
+
+        if sub == "read":
+            if len(args) < 2:
+                return f"Error: missing `<session_id>`.\n{help_str}"
+            sid = args[1]
+            full = "--full" in args
+            rec = store.get_session(sid)
+            if not rec:
+                return f"Error: session `{sid}` not found."
+            if not full:
+                return store.get_session_digest(sid)
+            return rec.result or f"[{sid} {rec.status}: no final result yet]"
+
+        if sub == "send":
+            if len(args) < 2:
+                return f"Error: missing `<session_id>`.\n{help_str}"
+            sid = args[1]
+            msg = " ".join(args[2:]).strip() or (stdin or "").strip()
+            if not msg:
+                return f"Error: missing `<message>`.\n{help_str}"
+            rec = store.get_session(sid)
+            if not rec:
+                return f"Error: session `{sid}` not found."
+            store.enqueue_inbox(sid, msg)
+            if rec.status in ("COMPLETED", "FAILED", "PENDING"):
+                store.update_session(sid, status="PENDING")
+                worker_spawner(sid)
+                return f"Queued message and resumed session `{sid}`."
+            return f"Queued message into running session `{sid}` inbox."
+
+        return f"Error: unknown subcommand `{sub}`.\n{help_str}"
+
+    return build_tool_spec(
+        _agent,
+        name="agent",
+        description="Spawn async sub-agents and query their work via BM25 RAG",
+        custom_help=help_str,
+        raw_dispatch=True,
+    )

tether/tools/bash.py

@@ -0,0 +1,29 @@
+"""Sandboxed shell execution tool (`bash`)."""
+
+from __future__ import annotations
+
+from tether.decorator import ToolSpec, build_tool_spec
+from tether.sandbox import SandboxPolicy
+
+
+def make_bash_tool(sandbox: SandboxPolicy) -> ToolSpec:
+    help_str = (
+        "Usage: bash <command> (or pass script via stdin)\n"
+        "Desc : Run shell command inside workspace sandbox."
+    )
+
+    async def _bash(args: list[str], stdin: str | None = None) -> str:
+        if args and args[0] in ("--help", "-h"):
+            return help_str
+        cmd_str = " ".join(args).strip()
+        if not cmd_str and not stdin:
+            return f"Error: missing `<command>`.\n{help_str}"
+        return await sandbox.execute_bash(cmd_str, stdin=stdin)
+
+    return build_tool_spec(
+        _bash,
+        name="bash",
+        description="Execute sandboxed shell commands",
+        custom_help=help_str,
+        raw_dispatch=True,
+    )

tether/tools/done.py

@@ -0,0 +1,33 @@
+"""Mandatory explicit task completion tool (`done`)."""
+
+from __future__ import annotations
+
+from tether.decorator import ToolSpec, build_tool_spec
+
+
+def make_done_tool() -> ToolSpec:
+    help_str = (
+        "Usage: done [answer] (or pass multiline report via stdin)\n"
+        "Desc : Complete the task and submit final deliverable."
+    )
+
+    def _done(args: list[str], stdin: str | None = None) -> str:
+        if args and args[0] in ("--help", "-h"):
+            return help_str
+        body_parts: list[str] = []
+        if args:
+            body_parts.append(" ".join(args).strip())
+        if stdin and stdin.strip():
+            body_parts.append(stdin.strip())
+        final_text = "\n\n".join(body_parts).strip()
+        if not final_text:
+            return f"Error: provide final deliverable via `stdin` or argument.\n{help_str}"
+        return final_text
+
+    return build_tool_spec(
+        _done,
+        name="done",
+        description="Complete task and submit final deliverable",
+        custom_help=help_str,
+        raw_dispatch=True,
+    )

tether/tools/edit.py

@@ -0,0 +1,107 @@
+"""Workspace-jailed file viewing and stdin patching tool (`edit`)."""
+
+from __future__ import annotations
+
+from tether.decorator import ToolSpec, build_tool_spec
+from tether.sandbox import SandboxPolicy
+
+
+def _parse_line_range(spec: str, total_lines: int) -> tuple[int, int] | str:
+    if ":" not in spec:
+        try:
+            n = int(spec)
+            return max(1, n), min(total_lines, n)
+        except ValueError:
+            return f"invalid line range `{spec}` (expected `start:end`)."
+    left, right = spec.split(":", 1)
+    try:
+        start = int(left) if left else 1
+        end = int(right) if right else total_lines
+    except ValueError:
+        return f"invalid line range `{spec}` (expected integers `start:end`)."
+    start = max(1, start)
+    end = min(max(start, end), max(1, total_lines))
+    return start, end
+
+
+def make_edit_tool(sandbox: SandboxPolicy) -> ToolSpec:
+    help_str = (
+        "Usage: edit view <path> [--lines a:b] | edit write <path> [stdin] | "
+        "edit replace <path> --lines a:b [stdin]\n"
+        "Desc : View numbered lines, write file from stdin, or replace line range."
+    )
+
+    def _edit(args: list[str], stdin: str | None = None) -> str:
+        if not args or args[0] in ("--help", "-h"):
+            return help_str
+
+        sub = args[0]
+        if sub == "view":
+            if len(args) < 2:
+                return f"Error: missing `<path>`.\n{help_str}"
+            target = sandbox.resolve_safe_path(args[1], write=False)
+            if not target.is_file():
+                return f"Error: file `{args[1]}` not found."
+            lines = target.read_text(encoding="utf-8", errors="replace").splitlines()
+            start, end = 1, min(len(lines), 100)
+            if "--lines" in args:
+                idx = args.index("--lines")
+                if idx + 1 >= len(args):
+                    return f"Error: `--lines` requires `start:end`.\n{help_str}"
+                rng = _parse_line_range(args[idx + 1], len(lines))
+                if isinstance(rng, str):
+                    return f"Error: {rng}"
+                start, end = rng
+            numbered = [f"{i:4d}: {lines[i - 1]}" for i in range(start, end + 1)]
+            header = f"[{args[1]} lines {start}-{end} of {len(lines)}]"
+            return "\n".join([header, *numbered])
+
+        if sub == "write":
+            if len(args) < 2:
+                return f"Error: missing `<path>`.\n{help_str}"
+            if stdin is None:
+                return f"Error: `edit write` requires file content in `stdin`.\n{help_str}"
+            target = sandbox.resolve_safe_path(args[1], write=True)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(stdin, encoding="utf-8")
+            line_cnt = len(stdin.splitlines())
+            return f"Wrote {len(stdin):,} chars ({line_cnt} lines) to `{args[1]}`."
+
+        if sub == "replace":
+            if len(args) < 2 or "--lines" not in args:
+                return (
+                    f"Error: `edit replace` requires `<path> --lines start:end` "
+                    f"and `stdin`.\n{help_str}"
+                )
+            if stdin is None:
+                return f"Error: `edit replace` requires replacement block in `stdin`.\n{help_str}"
+            target = sandbox.resolve_safe_path(args[1], write=True)
+            if not target.is_file():
+                return f"Error: file `{args[1]}` not found."
+            idx = args.index("--lines")
+            if idx + 1 >= len(args):
+                return f"Error: `--lines` requires `start:end`.\n{help_str}"
+            lines = target.read_text(encoding="utf-8", errors="replace").splitlines()
+            rng = _parse_line_range(args[idx + 1], len(lines))
+            if isinstance(rng, str):
+                return f"Error: {rng}"
+            start, end = rng
+            replacement_lines = stdin.splitlines()
+            updated = lines[: start - 1] + replacement_lines + lines[end:]
+            target.write_text(
+                "\n".join(updated) + ("\n" if stdin.endswith("\n") or lines else ""),
+                encoding="utf-8",
+            )
+            return (
+                f"Replaced lines {start}:{end} in `{args[1]}` with {len(replacement_lines)} lines."
+            )
+
+        return f"Error: unknown subcommand `{sub}`.\n{help_str}"
+
+    return build_tool_spec(
+        _edit,
+        name="edit",
+        description="View, create, or patch workspace files via stdin",
+        custom_help=help_str,
+        raw_dispatch=True,
+    )

tether/tools/mem.py

@@ -0,0 +1,93 @@
+"""Working scratchpad (`pin`/`unpin`), FTS5 BM25 RAG (`search`), and observation `recall`."""
+
+from __future__ import annotations
+
+from tether.decorator import ToolSpec, build_tool_spec
+from tether.store import SQLiteStore
+
+
+def make_mem_tool(store: SQLiteStore, session_id: str) -> ToolSpec:
+    help_str = (
+        "Usage: mem pin <key> <val> | mem unpin <key> | mem search <query> [--obs id] [--top 3] | "
+        "mem recall <obs_id>\n"
+        "Desc : Pin facts, search folded observations via BM25, or recall raw output."
+    )
+
+    def _mem(args: list[str], stdin: str | None = None) -> str:
+        if not args or args[0] in ("--help", "-h"):
+            return help_str
+
+        sub = args[0]
+        if sub == "pin":
+            if len(args) < 2:
+                return f"Error: missing `<key>`.\n{help_str}"
+            key = args[1]
+            val = " ".join(args[2:]).strip() if len(args) > 2 else (stdin or "").strip()
+            if not val:
+                return f"Error: missing `<val>` (pass inline or via `stdin`).\n{help_str}"
+            store.set_pin(session_id, key, val)
+            return f"Pinned `{key}`."
+
+        if sub == "unpin":
+            if len(args) < 2:
+                return f"Error: missing `<key>`.\n{help_str}"
+            removed = store.remove_pin(session_id, args[1])
+            return f"Unpinned `{args[1]}`." if removed else f"Key `{args[1]}` not found."
+
+        if sub == "list":
+            pins = store.get_pins(session_id)
+            if not pins:
+                return "No pinned facts."
+            return "\n".join(f"- {k}: {v}" for k, v in pins.items())
+
+        if sub == "search":
+            obs_filter: str | None = None
+            top_k = 3
+            q_parts: list[str] = []
+            i = 1
+            while i < len(args):
+                if args[i] == "--obs" and i + 1 < len(args):
+                    obs_filter = args[i + 1]
+                    i += 2
+                elif args[i] == "--top" and i + 1 < len(args):
+                    try:
+                        top_k = int(args[i + 1])
+                    except ValueError:
+                        return "Error: `--top` expects an integer."
+                    i += 2
+                else:
+                    q_parts.append(args[i])
+                    i += 1
+            query = " ".join(q_parts).strip() or (stdin or "").strip()
+            if not query:
+                return f"Error: missing `<query>`.\n{help_str}"
+            hits = store.search_chunks(
+                query,
+                session_ids=[session_id],
+                source_id=obs_filter,
+                top_k=top_k,
+            )
+            if not hits:
+                return f"No matching chunks for `{query}`."
+            formatted = [
+                f"[{h.source_type}:{h.source_id}#{h.chunk_index}]\n{h.content}" for h in hits
+            ]
+            return "\n\n---\n\n".join(formatted)
+
+        if sub == "recall":
+            if len(args) < 2:
+                return f"Error: missing `<obs_id>`.\n{help_str}"
+            obs = store.get_observation(session_id, args[1])
+            if not obs:
+                return f"Error: observation `{args[1]}` not found."
+            return f"[{obs.id} `{obs.cmd}`]\n{obs.raw_output}"
+
+        return f"Error: unknown subcommand `{sub}`.\n{help_str}"
+
+    return build_tool_spec(
+        _mem,
+        name="mem",
+        description="Pin working memory facts or BM25-search/recall folded observations",
+        custom_help=help_str,
+        raw_dispatch=True,
+    )

tether/tools/web.py

@@ -0,0 +1,222 @@
+"""Zero-config web search (DuckDuckGo Lite + Brave/Tavily/SearXNG env override) and reader."""
+
+from __future__ import annotations
+
+import html
+import os
+import re
+import urllib.parse
+from html.parser import HTMLParser
+
+import httpx
+
+from tether.decorator import ToolSpec, build_tool_spec
+
+
+class _HTMLToTextParser(HTMLParser):
+    """Lightweight stdlib HTML-to-Markdown/text extractor."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._skip_depth = 0
+        self._parts: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        t = tag.lower()
+        if t in ("script", "style", "noscript", "svg", "head", "nav", "footer"):
+            self._skip_depth += 1
+            return
+        if self._skip_depth > 0:
+            return
+        if t in ("h1", "h2", "h3", "h4"):
+            level = int(t[1])
+            self._parts.append(f"\n\n{'#' * level} ")
+        elif t in ("p", "div", "section", "article", "br", "tr"):
+            self._parts.append("\n")
+        elif t == "li":
+            self._parts.append("\n- ")
+
+    def handle_endtag(self, tag: str) -> None:
+        t = tag.lower()
+        if t in ("script", "style", "noscript", "svg", "head", "nav", "footer"):
+            self._skip_depth = max(0, self._skip_depth - 1)
+        elif self._skip_depth == 0 and t in ("p", "h1", "h2", "h3", "h4", "ul", "ol"):
+            self._parts.append("\n")
+
+    def handle_data(self, data: str) -> None:
+        if self._skip_depth == 0:
+            cleaned = re.sub(r"[ \t]+", " ", data)
+            self._parts.append(cleaned)
+
+    def get_text(self) -> str:
+        raw = "".join(self._parts)
+        lines = [line.strip() for line in raw.splitlines()]
+        collapsed = "\n".join(lines)
+        return re.sub(r"\n{3,}", "\n\n", collapsed).strip()
+
+
+def html_to_markdown(raw_html: str, max_chars: int = 8000) -> str:
+    """Convert raw HTML into compact markdown-friendly text."""
+    parser = _HTMLToTextParser()
+    parser.feed(raw_html)
+    text = parser.get_text()
+    if len(text) > max_chars:
+        return f"{text[:max_chars]}\n... [truncated {len(text) - max_chars:,} chars]"
+    return text
+
+
+def _unwrap_ddg_url(href: str) -> str:
+    if "uddg=" in href:
+        parsed = urllib.parse.urlparse(href)
+        qs = urllib.parse.parse_qs(parsed.query)
+        if "uddg" in qs and qs["uddg"]:
+            return urllib.parse.unquote(qs["uddg"][0])
+    return href
+
+
+async def search_web_backend(query: str, max_results: int = 5) -> str:
+    """Search the web via SearXNG/Brave/Tavily if configured, else DuckDuckGo HTML."""
+    headers = {
+        "User-Agent": (
+            "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+            "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
+        )
+    }
+
+    searx_url = os.environ.get("SEARXNG_URL")
+    brave_key = os.environ.get("BRAVE_API_KEY")
+    tavily_key = os.environ.get("TAVILY_API_KEY")
+
+    async with httpx.AsyncClient(timeout=20.0, follow_redirects=True, headers=headers) as client:
+        if searx_url:
+            resp = await client.get(
+                f"{searx_url.rstrip('/')}/search",
+                params={"q": query, "format": "json"},
+            )
+            resp.raise_for_status()
+            items = (resp.json().get("results") or [])[:max_results]
+            return _format_results(
+                [(i.get("title", ""), i.get("url", ""), i.get("content", "")) for i in items]
+            )
+
+        if brave_key:
+            resp = await client.get(
+                "https://api.search.brave.com/res/v1/web/search",
+                params={"q": query, "count": max_results},
+                headers={"X-Subscription-Token": brave_key, "Accept": "application/json"},
+            )
+            resp.raise_for_status()
+            items = ((resp.json().get("web") or {}).get("results") or [])[:max_results]
+            return _format_results(
+                [(i.get("title", ""), i.get("url", ""), i.get("description", "")) for i in items]
+            )
+
+        if tavily_key:
+            resp = await client.post(
+                "https://api.tavily.com/search",
+                json={"api_key": tavily_key, "query": query, "max_results": max_results},
+            )
+            resp.raise_for_status()
+            items = (resp.json().get("results") or [])[:max_results]
+            return _format_results(
+                [(i.get("title", ""), i.get("url", ""), i.get("content", "")) for i in items]
+            )
+
+        # Default zero-config DuckDuckGo HTML endpoint
+        resp = await client.post(
+            "https://html.duckduckgo.com/html/",
+            data={"q": query},
+        )
+        resp.raise_for_status()
+        body = resp.text
+
+    link_re = re.compile(
+        r'<a[^>]+class="[^"]*result__a[^"]*"[^>]+href="([^"]+)"[^>]*>(.*?)</a>',
+        re.DOTALL,
+    )
+    snip_re = re.compile(
+        r'<a[^>]+class="[^"]*result__snippet[^"]*"[^>]*>(.*?)</a>',
+        re.DOTALL,
+    )
+    links = link_re.findall(body)
+    snippets = snip_re.findall(body)
+
+    results: list[tuple[str, str, str]] = []
+    for idx, (raw_href, raw_title) in enumerate(links[:max_results]):
+        title = html.unescape(re.sub(r"<[^>]+>", "", raw_title)).strip()
+        url = _unwrap_ddg_url(html.unescape(raw_href).strip())
+        snippet = ""
+        if idx < len(snippets):
+            snippet = html.unescape(re.sub(r"<[^>]+>", "", snippets[idx])).strip()
+        results.append((title, url, snippet))
+
+    return _format_results(results)
+
+
+def _format_results(items: list[tuple[str, str, str]]) -> str:
+    if not items:
+        return "No search results found."
+    out: list[str] = []
+    for idx, (title, url, snippet) in enumerate(items, 1):
+        out.append(f"{idx}. {title}\n   URL: {url}\n   {snippet}".strip())
+    return "\n\n".join(out)
+
+
+def make_web_tool(max_fetch_chars: int = 8000) -> ToolSpec:
+    help_str = (
+        "Usage: web search <query> [--max 5] | web fetch <url>\n"
+        "Desc : Search the web or fetch clean markdown text from a URL."
+    )
+
+    async def _web(args: list[str], stdin: str | None = None) -> str:
+        if not args or args[0] in ("--help", "-h"):
+            return help_str
+        sub = args[0]
+        if sub == "search":
+            max_res = 5
+            query_parts: list[str] = []
+            i = 1
+            while i < len(args):
+                if args[i] == "--max" and i + 1 < len(args):
+                    try:
+                        max_res = int(args[i + 1])
+                    except ValueError:
+                        return "Error: `--max` expects an integer."
+                    i += 2
+                else:
+                    query_parts.append(args[i])
+                    i += 1
+            query = " ".join(query_parts).strip() or (stdin or "").strip()
+            if not query:
+                return f"Error: missing `<query>`.\n{help_str}"
+            return await search_web_backend(query, max_results=max_res)
+
+        if sub == "fetch":
+            if len(args) < 2:
+                return f"Error: missing `<url>`.\n{help_str}"
+            url = args[1].strip()
+            if not url.startswith(("http://", "https://")):
+                return "Error: URL must start with http:// or https://."
+            headers = {"User-Agent": "Tether-MicroHarness/0.1"}
+            async with httpx.AsyncClient(
+                timeout=20.0, follow_redirects=True, headers=headers
+            ) as client:
+                resp = await client.get(url)
+                resp.raise_for_status()
+                ctype = resp.headers.get("content-type", "")
+                if "html" in ctype.lower() or "<html" in resp.text[:500].lower():
+                    return html_to_markdown(resp.text, max_chars=max_fetch_chars)
+                text = resp.text.strip()
+                if len(text) > max_fetch_chars:
+                    return f"{text[:max_fetch_chars]}\n... [truncated]"
+                return text
+
+        return f"Error: unknown subcommand `{sub}`.\n{help_str}"
+
+    return build_tool_spec(
+        _web,
+        name="web",
+        description="Search the web or fetch clean URL text",
+        custom_help=help_str,
+        raw_dispatch=True,
+    )