rockycode 0.1.0__py3-none-any.whl

rockycode/engine/artifact.py

@@ -0,0 +1,367 @@
+"""Artifact tool — generate a self-contained HTML page and open it.
+
+One tool: ``create_artifact``.  The model supplies body content (or a full
+document); rockycode wraps a fragment in its themed page and opens it.
+
+Static (default):  write the file and open it via ``file://`` — no server.
+Live (opt-in):     ``ArtifactServer`` serves it over ``http://localhost`` and
+                   the open tab auto-reloads whenever rocky rebuilds the same
+                   artifact.  Lazy-started on the first artifact (asked once),
+                   or from the start with ``--live``.  Local only.
+
+The TUI sets ``engine.artifact_target`` — an async callable that decides live
+vs static (asking once), lazy-starts the server, and returns the running
+``ArtifactServer`` (live) or ``None`` (static).
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import secrets
+import webbrowser
+from pathlib import Path
+from urllib.parse import quote, unquote
+
+from rockycode.engine.tools import Tool, _fn_schema
+
+ARTIFACT_DIR = ".rockycode/artifacts"
+MAX_ARTIFACT_CHARS = 500_000  # 500 KB — generous for inline-SVG/data-URI HTML
+
+
+def _open_browser(url: str) -> None:
+    """Best-effort browser open.
+
+    Suppressed when ROCKYCODE_ARTIFACT_NO_BROWSER=1: an embedding editor (the
+    VS Code extension) sets it because it opens the URL from the tool output
+    itself — without this, every artifact opened twice. The output lines
+    ("url: ...", "opened in browser: file://...") are the extension's parse
+    surface and must keep their format either way.
+    """
+    if os.getenv("ROCKYCODE_ARTIFACT_NO_BROWSER") == "1":
+        return
+    try:
+        webbrowser.open(url)
+    except Exception:  # noqa: BLE001 — best-effort
+        pass
+
+
+def _safe_filename(name: str) -> str:
+    """Sanitise *name* into a safe file stem (<=80 chars)."""
+    safe = "".join(c if c.isalnum() or c in "._- " else "_" for c in name)
+    return safe.strip().replace(" ", "_")[:80] or "artifact"
+
+
+def _extract_body(html: str) -> str:
+    """Reduce model HTML to themable body content.
+
+    The model often emits a whole <html> document with its own (usually dark)
+    theme — DeepSeek loves to. We keep only the inner <body> and strip every
+    <style> block, so rocky's light-purple theme always wins. A plain fragment
+    is returned with just its <style> blocks removed.
+    """
+    low = html.lower()
+    i = low.find("<body")
+    if i != -1:
+        start = low.find(">", i)
+        end = low.rfind("</body>")
+        if start != -1 and end != -1:
+            html = html[start + 1:end]
+    return re.sub(r"(?is)<style\b.*?</style>", "", html)
+
+
+def _artifact_html(title: str, body: str) -> str:
+    """Wrap *body* in rockycode's light, soft-purple themed page.
+
+    Palette tracks rockycode/palette.py + ROCKY_THEME_LIGHT.
+    """
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>{title}</title>
+<style>
+:root {{ --bg:#f6f4fb; --card:#ffffff; --panel:#ece8f7; --border:#ddd4ef;
+       --text:#2a2a38; --dim:#5a5e7a; --heading:#6a4ca3; --accent:#7c5cba; --brand:#bb9af7; }}
+* {{ box-sizing:border-box; margin:0; padding:0; }}
+body {{ font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
+       background:var(--bg); color:var(--text); line-height:1.6; max-width:900px; margin:0 auto; padding:2rem; }}
+h1 {{ color:var(--heading); border-bottom:2px solid var(--border); padding-bottom:.5rem; margin-bottom:.75rem; font-weight:650; }}
+h2 {{ color:var(--accent); margin:1.5rem 0 .5rem; font-size:1.15rem; }}
+.card {{ background:var(--card); border:1px solid var(--border); border-radius:10px;
+        padding:1rem 1.1rem; margin:1rem 0; box-shadow:0 1px 3px rgba(106,76,163,0.06); }}
+.tag {{ display:inline-block; padding:.1rem .55rem; border-radius:10px; font-size:.72rem; font-weight:600; }}
+.tag-purple {{ background:#efe9fb; color:#6a4ca3; }}
+.tag-amber {{ background:#f7efe0; color:#8a6420; }}
+.tag-red {{ background:#fbe9eb; color:#b23a44; }}
+table {{ width:100%; border-collapse:collapse; margin:.5rem 0; }}
+th,td {{ border:1px solid var(--border); padding:.45rem .65rem; text-align:left; font-size:.85rem; }}
+th {{ background:var(--panel); color:var(--heading); }}
+pre {{ background:var(--panel); border:1px solid var(--border); border-radius:8px; padding:.85rem; overflow-x:auto; font-size:.82rem; }}
+code {{ font-family:ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,monospace; color:var(--heading); }}
+a {{ color:var(--accent); }}
+</style>
+</head>
+<body>
+<h1>{title}</h1>
+{body}
+</body>
+</html>"""
+
+
+def _reload_script(sse_url: str, name: str) -> str:
+    """A tiny SSE client: reload this page when its artifact is rebuilt."""
+    return f"""
+<script>
+(function() {{
+  try {{
+    const es = new EventSource("{sse_url}");
+    es.addEventListener("reload", function(e) {{
+      let d = {{}}; try {{ d = JSON.parse(e.data); }} catch(_) {{}}
+      if (!d.name || d.name === "{name}") location.reload();
+    }});
+  }} catch(_) {{}}
+}})();
+</script>"""
+
+
+def _inject_reload(doc: str, sse_url: str, name: str) -> str:
+    """Insert the live-reload script before </body> (or append)."""
+    script = _reload_script(sse_url, name)
+    idx = doc.lower().rfind("</body>")
+    return doc[:idx] + script + doc[idx:] if idx != -1 else doc + script
+
+
+def build_artifact_tools(*, workdir: Path, engine=None) -> dict[str, Tool]:
+    """Return {create_artifact} bound to *workdir*.
+
+    At call time the tool consults ``engine.artifact_target`` (set by the TUI)
+    to decide live vs static and obtain the running server.
+    """
+    artifact_dir = workdir / ARTIFACT_DIR
+
+    async def create_artifact(title: str, html: str) -> str:
+        """Save a self-contained HTML artifact and open it in the browser."""
+        if len(html) > MAX_ARTIFACT_CHARS:
+            return (
+                f"[error] artifact too large: {len(html):,} chars "
+                f"(max {MAX_ARTIFACT_CHARS:,}).  simplify the content."
+            )
+        artifact_dir.mkdir(parents=True, exist_ok=True)
+
+        # The TUI decides live vs static (asking once on first use, lazy-starting
+        # the server). Headless/bench have no target → static file://.
+        target = getattr(engine, "artifact_target", None)
+        server = await target() if target is not None else None
+
+        stem = _safe_filename(title)
+        doc = _artifact_html(title, _extract_body(html))
+
+        if server is not None:
+            # Live: stable name, overwrite in place, auto-reload the open tab.
+            path = artifact_dir / f"{stem}.html"
+            existed = path.exists()
+            doc = _inject_reload(doc, f"{server.base_url}/api/events?t={server.token}", stem)
+            path.write_text(doc, encoding="utf-8")
+            # Percent-encode: CJK stems survive _safe_filename (isalnum), and a
+            # raw non-ASCII URL gets mangled by webbrowser/terminal handlers.
+            # ?t= is the per-session nonce every server endpoint requires.
+            url = f"{server.base_url}/artifacts/{quote(stem)}?t={server.token}"
+            if existed:
+                await server.broadcast("reload", {"name": stem})  # open tab refreshes
+                return f"[ok] artifact '{title}' updated live — {len(doc):,} chars\n  url: {url}"
+            _open_browser(url)
+            return f"[ok] artifact '{title}' opened live — {len(doc):,} chars\n  url: {url}"
+
+        # Static: unique filename, file://.
+        path = artifact_dir / f"{stem}.html"
+        n = 1
+        while path.exists():
+            path = artifact_dir / f"{stem}_{n}.html"
+            n += 1
+        path.write_text(doc, encoding="utf-8")
+        file_uri = path.resolve().as_uri()
+        _open_browser(file_uri)
+        return (
+            f"[ok] artifact saved — {len(doc):,} chars\n"
+            f"  file: {path}\n"
+            f"  opened in browser: {file_uri}"
+        )
+
+    schema = _fn_schema(
+        "create_artifact",
+        "Create a visual artifact (report, diagram, dashboard, summary) and open "
+        "it in the browser. Use for output better seen outside the terminal. "
+        "Provide the BODY content ONLY — headings (<h1>/<h2>), paragraphs, cards "
+        "(<div class='card'>), tables, <pre>/<code>, inline SVG/Mermaid. Do NOT "
+        "write <html>/<head>/<style>, and do NOT set your own colors or "
+        "background — rockycode applies its own LIGHT theme (soft purple on "
+        "near-white). Use the provided classes: card, tag/tag-purple/tag-amber/"
+        "tag-red. No external CDN/network references. Reuse the SAME title to "
+        "update in place (in live mode the open tab auto-refreshes).",
+        {
+            "title": {
+                "type": "string",
+                "description": "Short descriptive title (also the filename; reuse to update).",
+            },
+            "html": {
+                "type": "string",
+                "description": (
+                    "Body content only — no <html>/<head>/<style> and no color/background "
+                    "styles (rocky themes it). Use rocky's classes; embed SVG/Mermaid inline."
+                ),
+            },
+        },
+        ["title", "html"],
+    )
+    return {"create_artifact": Tool(name="create_artifact", schema=schema, fn=create_artifact)}
+
+
+# ------------------------------------------------------------------
+# ArtifactServer — live mode (host browser reaches localhost)
+# ------------------------------------------------------------------
+
+class ArtifactServer:
+    """Serve artifact files over localhost + an SSE stream for live reload.
+
+    Every endpoint requires the per-session nonce (``?t=<token>``, audit #7):
+    localhost services are reachable by any local process and — via the
+    browser — probeable by any web page the user has open, so unauthenticated
+    ``/list``/``/api/events`` would leak artifact names and reload activity.
+    The token is baked into every URL rocky emits (open link, /list entries,
+    the injected reload script); it never needs to be typed.
+
+    Binding: 127.0.0.1 by default. Inside Docker (ROCKYCODE_IN_DOCKER) it must
+    bind 0.0.0.0 — Docker can't forward a published port to the container's
+    127.0.0.1 — so the compose/run mapping MUST publish the port on host
+    loopback only (``127.0.0.1:PORT:PORT``, as docker-compose.yml does);
+    publishing bare ``PORT:PORT`` would expose the server to the LAN.
+    Lifecycle: ``await start()`` when live mode turns on, ``await stop()`` on
+    exit.
+    """
+
+    def __init__(self, workdir: Path) -> None:
+        self.workdir = workdir
+        self.artifact_dir = workdir / ARTIFACT_DIR
+        self.port: int = 0
+        # Unguessable per-session nonce gating every endpoint (see class doc).
+        self.token: str = secrets.token_urlsafe(16)
+        self._app: "web.Application | None" = None
+        self._runner: "web.AppRunner | None" = None
+        self._sse_queues: set["asyncio.Queue"] = set()
+
+    def _require_token(self, request: "web.Request") -> None:
+        """401 unless the request carries the session token (?t=...)."""
+        from aiohttp import web
+
+        if not secrets.compare_digest(request.query.get("t", ""), self.token):
+            raise web.HTTPUnauthorized(text="missing or invalid artifact token")
+
+    async def broadcast(self, event_type: str, data: dict | None = None) -> None:
+        """Push an SSE event to all connected clients."""
+        import json as _json
+        chunk = f"event: {event_type}\ndata: {_json.dumps(data or {})}\n\n"
+        for q in list(self._sse_queues):
+            try:
+                q.put_nowait(chunk)
+            except asyncio.QueueFull:
+                self._sse_queues.discard(q)
+
+    async def start(self) -> None:
+        from aiohttp import web
+
+        self._app = web.Application()
+        self._app.router.add_get("/artifacts/{name}", self._serve_artifact)
+        self._app.router.add_get("/list", self._list_artifacts)
+        self._app.router.add_get("/api/events", self._handle_events)
+
+        self._runner = web.AppRunner(self._app)
+        await self._runner.setup()
+        # Host: loopback. Docker: 0.0.0.0 is required (the published port forwards
+        # to the container bridge, not its 127.0.0.1) — but compose binds the host
+        # side to 127.0.0.1, so the server is never LAN-exposed.
+        bind_host = "0.0.0.0" if os.environ.get("ROCKYCODE_IN_DOCKER") else "127.0.0.1"
+        fixed_port = int(os.environ["ROCKYCODE_ARTIFACT_PORT"]) if "ROCKYCODE_ARTIFACT_PORT" in os.environ else 0
+        site = web.TCPSite(self._runner, bind_host, fixed_port)
+        await site.start()
+        for sock in site._server.sockets:
+            self.port = sock.getsockname()[1]
+            break
+
+    @property
+    def base_url(self) -> str:
+        return f"http://localhost:{self.port}"
+
+    async def _serve_artifact(self, request: "web.Request") -> "web.Response":
+        from aiohttp import web
+
+        self._require_token(request)
+        # unquote: percent-encoded requests must match on-disk stems (which are
+        # stored decoded, CJK and all). Stems never contain '%' (_safe_filename
+        # maps it to '_'), so decoding an already-decoded name is a no-op.
+        name = unquote(request.match_info.get("name", "index"))
+        safe = _safe_filename(name)
+        if safe != name:
+            raise web.HTTPBadRequest(text="invalid artifact name")
+        fpath = self.artifact_dir / f"{safe}.html"
+        if not fpath.exists():
+            raise web.HTTPNotFound(text="artifact not found")
+        return web.FileResponse(fpath, headers={"Content-Type": "text/html; charset=utf-8"})
+
+    async def _list_artifacts(self, request: "web.Request") -> "web.Response":
+        from aiohttp import web
+
+        self._require_token(request)
+        files = sorted(self.artifact_dir.glob("*.html"), key=lambda p: p.stat().st_mtime, reverse=True)
+        items = [
+            {"name": f.stem, "size": f.stat().st_size,
+             "url": f"{self.base_url}/artifacts/{quote(f.stem)}?t={self.token}"}
+            for f in files[:50]
+        ]
+        return web.json_response(items)
+
+    async def _handle_events(self, request: "web.Request") -> "web.StreamResponse":
+        """SSE endpoint — streams reload events to open artifact tabs.
+
+        No CORS header: the only consumer is the reload script injected into
+        artifact pages served from this same origin. A wildcard here let any
+        web page EventSource the stream cross-origin (audit #7).
+        """
+        from aiohttp import web
+
+        self._require_token(request)
+        resp = web.StreamResponse(
+            status=200,
+            reason="OK",
+            headers={
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+        await resp.prepare(request)
+        queue: "asyncio.Queue" = asyncio.Queue(maxsize=64)
+        self._sse_queues.add(queue)
+        try:
+            await resp.write(b"event: connected\ndata: {}\n\n")
+            while True:
+                chunk = await asyncio.wait_for(queue.get(), timeout=30)
+                await resp.write(chunk.encode())
+        except asyncio.TimeoutError:
+            try:
+                await resp.write(b": keepalive\n\n")
+            except (ConnectionResetError, ConnectionError):
+                pass
+        except (ConnectionResetError, ConnectionError):
+            pass
+        finally:
+            self._sse_queues.discard(queue)
+        return resp
+
+    async def stop(self) -> None:
+        if self._runner is not None:
+            await self._runner.cleanup()
+            self._runner = None
+            self._app = None

rockycode/engine/budget.py

@@ -0,0 +1,90 @@
+"""Budget caps for autonomous (goal) mode.
+
+An overnight run stops — with a graceful finalize, never a crash — the moment it
+hits ANY configured cap: a spend ceiling (in the user's currency, priced from
+the real DeepSeek tables incl. the peak-hour surcharge), a wallclock limit, or a
+total-token budget. The user sets any subset or takes the recommended defaults;
+before the run we surface the worst-case spend so there are no surprises.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+from rockycode.pricing import UsageLedger
+
+# Recommended ceilings per currency (real numbers, not a conversion — the user
+# overrides freely). A night, and a spend the user is comfortable leaving alone.
+_RECOMMENDED_USD = {"usd": 5.0, "cny": 35.0}
+_RECOMMENDED_SECONDS = 8 * 3600
+
+
+@dataclass
+class GoalBudget:
+    max_usd: Optional[float] = None       # spend ceiling, in `currency`
+    max_seconds: Optional[float] = None   # wallclock limit
+    max_tokens: Optional[int] = None      # total (prompt + completion) tokens
+    currency: str = "usd"
+    _t0: float = field(default=0.0, init=False, repr=False)
+
+    def start(self) -> None:
+        self._t0 = time.monotonic()
+
+    def elapsed(self) -> float:
+        return time.monotonic() - self._t0 if self._t0 else 0.0
+
+    def exceeded(self, ledger: UsageLedger) -> Optional[str]:
+        """A human reason if any cap is now hit, else None. Checked each step;
+        the caller finalizes gracefully on a non-None result."""
+        if self.max_seconds is not None and self.elapsed() >= self.max_seconds:
+            return f"wallclock cap ({_dur(self.max_seconds)}) reached"
+        if self.max_usd is not None:
+            spent = ledger.cost(self.currency)
+            if spent >= self.max_usd:
+                return (f"spend cap ({_money(self.max_usd, self.currency)}) reached — "
+                        f"{_money(spent, self.currency)} spent")
+        if self.max_tokens is not None:
+            t = ledger.totals()
+            if t["prompt"] + t["completion"] >= self.max_tokens:
+                return f"token cap ({self.max_tokens:,}) reached"
+        return None
+
+    def describe(self) -> str:
+        parts = []
+        if self.max_usd is not None:
+            parts.append(_money(self.max_usd, self.currency))
+        if self.max_seconds is not None:
+            parts.append(_dur(self.max_seconds))
+        if self.max_tokens is not None:
+            parts.append(f"{self.max_tokens:,} tokens")
+        return " or ".join(parts) if parts else "NO LIMIT (not recommended)"
+
+    def preflight_note(self) -> str:
+        """One line shown before the run so the potential spend is explicit."""
+        if self.max_usd is not None:
+            return f"stops at {self.describe()} — up to {_money(self.max_usd, self.currency)} of API spend"
+        if self.max_tokens is not None or self.max_seconds is not None:
+            return (f"stops at {self.describe()} — no hard $ cap, so watch the token/time "
+                    f"limit (add max_usd for a spend ceiling)")
+        return "WARNING: no budget cap set — an overnight run could spend without limit"
+
+
+def recommended(currency: str = "usd") -> GoalBudget:
+    return GoalBudget(
+        max_usd=_RECOMMENDED_USD.get(currency, 5.0),
+        max_seconds=_RECOMMENDED_SECONDS,
+        currency=currency,
+    )
+
+
+def _money(amount: float, currency: str) -> str:
+    return f"{'¥' if currency == 'cny' else '$'}{amount:.2f}"
+
+
+def _dur(seconds: float) -> str:
+    h, rem = divmod(int(seconds), 3600)
+    m = rem // 60
+    if h and m:
+        return f"{h}h{m}m"
+    return f"{h}h" if h else f"{m}m"

rockycode/engine/checks.py

@@ -0,0 +1,157 @@
+"""Post-edit checks — run the project's OWN linter / type-checker and report.
+
+The lightweight alternative to an LSP stack (see lsp.py): instead of a
+language-server protocol, run the analyzers a human runs, auto-detected from the
+repo. Same value ("did my change break lint/types?") at a fraction of the
+machinery, and it matches what Claude Code does.
+
+SAFETY: only DECLARATIVE analyzers are auto-run — ruff and tsc read config but
+don't execute repo-authored code, and pyflakes has no config at all. We
+deliberately do NOT auto-run mypy / eslint / `npm run lint`: their config can
+load repo-authored plugins or scripts, which in a cloned repo is arbitrary code
+execution (the same untrusted-clone vector we harden elsewhere). When no linter
+is installed we fall back to BUNDLED pyflakes, so check_code always does
+something useful on Python.
+
+SAFETY (binary resolution): check-tool binaries are resolved from rocky's OWN
+PATH only — NEVER from workdir/.venv. A cloned repo is untrusted; a trojan
+`.venv/bin/pyright` there would be arbitrary code execution the moment
+check_code (or goal-mode verify()) runs it — and check_code is risk="safe", so
+it never prompts. Any resolved path that lands under workdir is refused too (an
+activated project venv, or `.` on PATH). See _resolve.
+
+  detect_checks(workdir)   -> [(label, argv)]
+  run_checks(workdir)      -> str
+  build_check_tool(workdir) -> {"check_code": Tool}   # the model-callable tool
+"""
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import shutil
+import sys
+from pathlib import Path
+
+
+def _pyflakes_available() -> bool:
+    return importlib.util.find_spec("pyflakes") is not None
+
+
+def _under(path: Path, root: Path) -> bool:
+    """True if *path* is *root* or lives beneath it (both resolved)."""
+    try:
+        path, root = path.resolve(), root.resolve()
+    except OSError:
+        return True  # unresolvable → treat as unsafe (fail closed)
+    return path == root or root in path.parents
+
+
+def _resolve(tool: str, workdir: Path) -> str | None:
+    """Find *tool* on rocky's OWN PATH — never inside the (untrusted) *workdir*.
+
+    We deliberately do NOT look in workdir/.venv or any project-local dir: a
+    cloned repo could ship a trojan `.venv/bin/pyright`, and check_code (risk=
+    "safe", and auto-run by goal-mode verify()) would execute it with no prompt.
+    So resolution is PATH-only, and a PATH hit that resolves to somewhere under
+    workdir (an activated project venv, or `.` on PATH) is refused as well —
+    check_code only ever runs a binary from rocky's own environment. A user who
+    wants a project-only linter can put it on PATH themselves. (pyflakes is
+    bundled with rocky and invoked via sys.executable, so Python always has a
+    fallback that needs no external binary.)
+    """
+    found = shutil.which(tool)
+    if not found:
+        return None
+    if _under(Path(found), workdir):
+        return None  # binary lives under the untrusted repo — refuse it
+    return found
+
+
+def detect_checks(workdir: Path) -> list[tuple[str, list[str]]]:
+    """Return [(label, argv)] of applicable SAFE fast checks for *workdir*.
+
+    Only DECLARATIVE analyzers — ruff, pyright, tsc read config but never
+    execute repo-authored code, and pyflakes has no config. (mypy/eslint/npm are
+    excluded: their configs can load repo plugins/scripts = RCE in a cloned
+    repo.) Binaries resolve from rocky's own PATH only, never workdir/.venv
+    (see _resolve), so a trojan project-local binary is never executed.
+    """
+    checks: list[tuple[str, list[str]]] = []
+    has_py = (workdir / "pyproject.toml").exists() or any(workdir.glob("*.py"))
+    if has_py:
+        ruff = _resolve("ruff", workdir)
+        if ruff:
+            checks.append(("ruff", [ruff, "check", "."]))
+        elif _pyflakes_available():
+            # Bundled fallback: pure-Python, no config, catches real bugs
+            # (undefined names, unused imports) — the F-rules ruff also runs.
+            checks.append(("pyflakes", [sys.executable, "-m", "pyflakes", "."]))
+        pyright = _resolve("pyright", workdir)
+        if pyright:  # declarative config, no plugin code-exec → safe to auto-run
+            checks.append(("pyright", [pyright]))
+    tsc = _resolve("tsc", workdir)
+    if (workdir / "tsconfig.json").exists() and tsc:
+        checks.append(("tsc", [tsc, "--noEmit"]))
+    return checks
+
+
+async def _run_one(argv: list[str], workdir: Path, timeout: int) -> tuple[int, str]:
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *argv,
+            cwd=str(workdir),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+    except (FileNotFoundError, OSError) as e:
+        return 127, f"could not run {argv[0]}: {e}"
+    try:
+        out, _ = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+    except asyncio.TimeoutError:
+        proc.kill()
+        return 124, f"{argv[0]} timed out after {timeout}s"
+    return proc.returncode or 0, out.decode(errors="replace")
+
+
+async def run_checks(workdir: Path, *, timeout: int = 120, tail: int = 15) -> str:
+    """Run every detected check; return a concise report ('' if nothing applies).
+
+    A non-zero exit shows the last *tail* lines so the model sees the concrete
+    errors without the whole log.
+    """
+    checks = detect_checks(workdir)
+    if not checks:
+        return ""
+    blocks: list[str] = []
+    for label, argv in checks:
+        code, out = await _run_one(argv, workdir, timeout)
+        if code == 0:
+            blocks.append(f"[ok] {label} — no issues")
+        else:
+            body = "\n  ".join(out.strip().splitlines()[-tail:])
+            blocks.append(f"[FAILED] {label} (exit {code})\n  {body}")
+    return "\n".join(blocks)
+
+
+def build_check_tool(workdir: Path) -> dict:
+    """The model-callable `check_code` tool: run the project's checks on demand."""
+    from rockycode.engine.tools import Tool, _fn_schema
+
+    async def check_code() -> str:
+        report = await run_checks(workdir)
+        return report or (
+            "[no checks] no supported linter / type-checker for this project "
+            "(ruff or bundled pyflakes for Python, tsc for TypeScript)."
+        )
+
+    schema = _fn_schema(
+        "check_code",
+        "Run the project's own linter / type-checker — ruff and pyright (or "
+        "bundled pyflakes when ruff isn't installed) for Python, tsc for "
+        "TypeScript — resolved from rocky's PATH, and report "
+        "errors. Call it after editing to verify you didn't introduce lint or "
+        "type errors — grounded feedback, not a guess. Read-only; project-wide.",
+        {},
+        [],
+    )
+    return {"check_code": Tool(name="check_code", schema=schema, fn=check_code, risk="safe")}