scootcli 0.1.0__py3-none-any.whl

scootcli/transport.py

@@ -0,0 +1,312 @@
+"""HTTP transport for provider APIs: pure stdlib, interruptible, streaming-aware.
+
+:class:`NativeTransport` speaks HTTP/1.1 over ``http.client``/``socket``/``ssl`` with no third-party
+dependency and no ``curl``. Its contract is tiny: ``request`` returns ``(status, body)`` and
+``stream_request`` yields body lines (SSE) ending with a ``HTTP_STATUS:<code>`` sentinel. Both honour a
+``cancel_event`` and abort the instant ESC is pressed (the socket is closed from a watcher thread).
+
+Connections are direct, or tunnelled through ``HTTPS_PROXY`` with ``CONNECT`` (no-auth or Basic);
+localhost and ``NO_PROXY`` hosts always connect directly. Plain ``http://`` URLs (a local Ollama, for
+instance) skip TLS.
+"""
+
+from __future__ import annotations
+
+import base64
+import http.client
+import json
+import os
+import socket
+import ssl
+import threading
+import time
+from typing import Iterator, List, Optional, Tuple
+from urllib.parse import urlsplit
+
+from .config import Config
+from .errors import Interrupted, NetworkError, ProxyError, RequestTimeout, SSLError, TransportError
+
+_STATUS_MARKER = "\nHTTP_STATUS:"
+
+# Fail fast if we can't even connect to the proxy/host (seconds); separate from the overall/idle
+# budget so a dead network is detected quickly while a slow-but-alive stream is allowed to continue.
+_CONNECT_TIMEOUT = 30
+
+
+def classify_native_error(exc: BaseException) -> TransportError:
+    """Map a socket/ssl/http error to a typed transport error with an actionable hint."""
+    if isinstance(exc, TransportError):
+        return exc
+    if isinstance(exc, ssl.SSLError):
+        return SSLError(str(exc) or "TLS error", hint="TLS handshake failed; check the endpoint URL and CA certificates")
+    if isinstance(exc, socket.timeout):
+        return RequestTimeout("request timed out", hint="slow or blocked network")
+    if isinstance(exc, socket.gaierror):
+        return NetworkError("cannot resolve host", hint="no internet, DNS failure, or a typo in the base URL")
+    if isinstance(exc, (ConnectionError, BrokenPipeError)):
+        return NetworkError(str(exc) or "connection failed", hint="is the endpoint up? check the base URL and proxy")
+    if isinstance(exc, OSError):
+        return NetworkError(str(exc) or "network error", hint="check network/proxy")
+    return TransportError(f"transport error: {exc}")
+
+
+def _parse_proxy(proxy_url: Optional[str]) -> Optional[Tuple[str, int, Optional[str]]]:
+    """Return ``(host, port, basic_auth_userpass_or_None)`` for a proxy URL, or ``None`` if unset."""
+    if not proxy_url:
+        return None
+    parts = urlsplit(proxy_url if "://" in proxy_url else "http://" + proxy_url)
+    host = parts.hostname
+    if not host:
+        return None
+    port = parts.port or 8080
+    basic = None
+    if parts.username:
+        basic = f"{parts.username}:{parts.password or ''}"
+    return host, port, basic
+
+
+def _split_url(url: str) -> Tuple[str, int, str]:
+    """Return ``(host, port, path_with_query)`` for an http(s) URL."""
+    parts = urlsplit(url)
+    host = parts.hostname or ""
+    port = parts.port or (443 if parts.scheme == "https" else 80)
+    path = parts.path or "/"
+    if parts.query:
+        path += "?" + parts.query
+    return host, port, path
+
+
+def _is_tls(url: str) -> bool:
+    return urlsplit(url).scheme.lower() != "http"
+
+
+_LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1", "0.0.0.0")
+
+
+def proxy_bypassed(host: str, no_proxy: Optional[str] = None) -> bool:
+    """Local hosts and anything listed in ``NO_PROXY`` (comma-separated, ``*`` for all) skip the proxy."""
+    h = (host or "").lower()
+    if h in _LOCAL_HOSTS or h.endswith(".localhost"):
+        return True
+    raw = no_proxy if no_proxy is not None else (os.environ.get("NO_PROXY") or os.environ.get("no_proxy") or "")
+    for entry in raw.split(","):
+        entry = entry.strip().lower().lstrip(".")
+        if not entry:
+            continue
+        if entry == "*" or h == entry or h.endswith("." + entry):
+            return True
+    return False
+
+
+class NativeTransport:
+    """Pure-stdlib HTTP transport with cooperative cancellation."""
+
+    def __init__(self, config: Config):
+        self.config = config
+
+    # ── public API ───────────────────────────────────────────────────────────────
+    def request(self, method, url, auth_token, auth_scheme="Bearer", body=None,
+                extra_headers=None, cancel_event=None) -> "tuple[int, str]":
+        holder: dict = {}
+        stop = threading.Event()
+        self._start_watch(holder, cancel_event, stop)
+        try:
+            resp = self._connect_and_request(
+                method, url, auth_token, auth_scheme, body, extra_headers, holder)
+            data = resp.read()
+            return resp.status, data.decode("utf-8", "replace").strip()
+        except Interrupted:
+            raise
+        except BaseException as exc:  # noqa: BLE001 - normalise to typed errors
+            if cancel_event is not None and cancel_event.is_set():
+                raise Interrupted("request cancelled by user")
+            raise classify_native_error(exc)
+        finally:
+            stop.set()
+            self._close(holder)
+
+    def stream_request(self, method, url, auth_token, auth_scheme="Bearer", body=None,
+                       extra_headers=None, cancel_event=None) -> Iterator[str]:
+        holder: dict = {}
+        stop = threading.Event()
+        self._start_watch(holder, cancel_event, stop)
+        try:
+            resp = self._connect_and_request(
+                method, url, auth_token, auth_scheme, body, extra_headers, holder)
+            yield from self._stream_lines(resp, resp.status, cancel_event)
+        except Interrupted:
+            raise
+        except GeneratorExit:
+            raise
+        except BaseException as exc:  # noqa: BLE001
+            if cancel_event is not None and cancel_event.is_set():
+                raise Interrupted("request cancelled by user")
+            raise classify_native_error(exc)
+        finally:
+            stop.set()
+            self._close(holder)
+
+    # ── request/response plumbing ────────────────────────────────────────────────
+    def _connect_and_request(self, method, url, auth_token, auth_scheme, body, extra_headers, holder):
+        host, port, path = _split_url(url)
+        sock = self._open_socket(host, port, _is_tls(url), holder)
+        holder["sock"] = sock
+        sock.settimeout(self.config.timeout)
+        body_bytes = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = self._headers(host, auth_token, auth_scheme, body_bytes, extra_headers)
+        self._write_request(sock, method, path, headers, body_bytes)
+        resp = http.client.HTTPResponse(sock, method=method.upper())
+        resp.begin()
+        return resp
+
+    def _headers(self, host, auth_token, auth_scheme, body_bytes, extra_headers) -> "list[tuple]":
+        headers = [
+            ("Host", host),
+            ("Accept", "*/*"),
+            ("Connection", "close"),  # server closes at end → clean EOF for read()/SSE
+        ]
+        if auth_token:
+            headers.append(("Authorization", f"{auth_scheme} {auth_token}"))
+        for raw in extra_headers or []:
+            key, _, value = raw.partition(":")
+            headers.append((key.strip(), value.strip()))
+        if body_bytes is not None:
+            headers.append(("Content-Type", "application/json"))
+            headers.append(("Content-Length", str(len(body_bytes))))
+        return headers
+
+    @staticmethod
+    def _write_request(sock, method, path, headers, body_bytes) -> None:
+        lines = [f"{method.upper()} {path} HTTP/1.1"]
+        lines += [f"{k}: {v}" for k, v in headers]
+        data = ("\r\n".join(lines) + "\r\n\r\n").encode("latin-1")
+        if body_bytes:
+            data += body_bytes
+        sock.sendall(data)
+
+    @staticmethod
+    def _stream_lines(resp, status: int, cancel_event) -> Iterator[str]:
+        """Yield SSE body lines as they arrive, then a trailing ``HTTP_STATUS:<code>`` sentinel."""
+        buf = ""
+        while True:
+            if cancel_event is not None and cancel_event.is_set():
+                raise Interrupted("request cancelled by user")
+            chunk = resp.read(1024)
+            if not chunk:
+                break
+            buf += chunk.decode("utf-8", "replace")
+            while "\n" in buf:
+                line, buf = buf.split("\n", 1)
+                yield line.rstrip("\r")
+        if buf:
+            yield buf.rstrip("\r")
+        yield f"{_STATUS_MARKER.strip()}{status}"
+
+    # ── connection + proxy tunnelling ────────────────────────────────────────────
+    def _open_socket(self, host: str, port: int, tls: bool, holder: dict):
+        proxy = _parse_proxy(self.config.proxy)
+        if proxy is None or proxy_bypassed(host):
+            raw = socket.create_connection((host, port), timeout=_CONNECT_TIMEOUT)
+        else:
+            raw = self._open_tunnel(host, port, proxy, holder)
+        holder["sock"] = raw
+        if not tls:
+            return raw
+        return ssl.create_default_context().wrap_socket(raw, server_hostname=host)
+
+    def _open_tunnel(self, host, port, proxy, holder):
+        """``CONNECT`` through the proxy (no-auth or Basic) and return the raw socket."""
+        phost, pport, basic = proxy
+        raw = socket.create_connection((phost, pport), timeout=_CONNECT_TIMEOUT)
+        holder["sock"] = raw
+        authorization = None
+        if basic:
+            authorization = "Basic " + base64.b64encode(basic.encode("utf-8")).decode("ascii")
+        self._send_connect(raw, host, port, authorization)
+        status, _auth_headers = self._read_connect_response(raw)
+        if status == 200:
+            return raw
+        raw.close()
+        hint = ("the proxy wants credentials: put them in HTTPS_PROXY as http://user:pass@host:port"
+                if status == 407 else "check HTTPS_PROXY")
+        raise ProxyError(f"proxy CONNECT failed (HTTP {status})", hint=hint)
+
+    @staticmethod
+    def _send_connect(raw, host, port, authorization: Optional[str]) -> None:
+        lines = [f"CONNECT {host}:{port} HTTP/1.1", f"Host: {host}:{port}"]
+        if authorization:
+            lines.append(f"Proxy-Authorization: {authorization}")
+        lines.append("Proxy-Connection: keep-alive")
+        raw.sendall(("\r\n".join(lines) + "\r\n\r\n").encode("latin-1"))
+
+    @staticmethod
+    def _read_connect_response(raw) -> "tuple[int, list]":
+        """Read a CONNECT response's status + ``Proxy-Authenticate`` headers, consuming any body."""
+        data = b""
+        while b"\r\n\r\n" not in data:
+            chunk = raw.recv(1)
+            if not chunk:
+                break
+            data += chunk
+        head, _, _ = data.partition(b"\r\n\r\n")
+        text = head.decode("latin-1")
+        status_line, _, header_block = text.partition("\r\n")
+        pieces = status_line.split(" ", 2)
+        status = int(pieces[1]) if len(pieces) > 1 and pieces[1].isdigit() else 0
+        auth: List[str] = []
+        length = 0
+        for line in header_block.split("\r\n"):
+            key, _, value = line.partition(":")
+            k = key.strip().lower()
+            if k == "proxy-authenticate":
+                auth.append(value.strip())
+            elif k == "content-length":
+                try:
+                    length = int(value.strip())
+                except ValueError:
+                    length = 0
+        if length:  # drain the response body so the socket is clean
+            remaining = length
+            while remaining > 0:
+                chunk = raw.recv(min(remaining, 4096))
+                if not chunk:
+                    break
+                remaining -= len(chunk)
+        return status, auth
+
+    # ── cancellation ─────────────────────────────────────────────────────────────
+    @staticmethod
+    def _start_watch(holder: dict, cancel_event, stop: threading.Event):
+        """Close the socket the moment ESC is pressed, unblocking any in-flight recv."""
+        if cancel_event is None:
+            return None
+
+        def _watch() -> None:
+            while not stop.is_set():
+                if cancel_event.is_set():
+                    sock = holder.get("sock")
+                    if sock is not None:
+                        try:
+                            sock.close()
+                        except OSError:
+                            pass
+                    return
+                time.sleep(0.05)
+
+        thread = threading.Thread(target=_watch, daemon=True)
+        thread.start()
+        return thread
+
+    @staticmethod
+    def _close(holder: dict) -> None:
+        sock = holder.get("sock")
+        if sock is not None:
+            try:
+                sock.close()
+            except OSError:
+                pass
+
+
+def make_transport(config: Config) -> NativeTransport:
+    """Factory kept for symmetry with the provider factory; there is one transport."""
+    return NativeTransport(config)

scootcli/vision.py

@@ -0,0 +1,167 @@
+"""Image descriptions for the agent: pick a vision-capable model and ask it to describe attachments.
+
+No separate vision backend exists any more: vision is a capability of the provider layer. The model is
+``config.vision_model`` when set, otherwise the best vision-capable model among those the configured
+providers list (``models.VISION_TIER`` order), falling back to the session's own model.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .images import EncodedImage
+
+# Default instruction for the describe pass (kept model-agnostic).
+DESCRIBE_INSTRUCTION = (
+    "You are assisting a terminal coding agent. Describe the attached image(s) precisely and concisely "
+    "for a developer: UI elements, layout, visible text, code, diagrams, colours, and anything a coding "
+    "assistant would need to act. If the image shows code or an error message, transcribe the relevant "
+    "text verbatim. Output only the description — no preamble or commentary."
+)
+
+
+@dataclass
+class VisionResult:
+    """Neutral result of a describe call (provider-independent)."""
+
+    text: str
+    model: str = ""
+    usage: dict = field(default_factory=dict)
+
+
+def build_content(images: List[EncodedImage], instruction: str) -> list:
+    """Build a neutral multimodal ``content`` list (text + image_url parts with data URIs)."""
+    content: list = [{"type": "text", "text": instruction}]
+    for img in images:
+        content.append({"type": "text", "text": f"[{img.name}]"})
+        content.append({"type": "image_url", "image_url": {"url": img.data_uri, "detail": "high"}})
+    return content
+
+
+def pick_vision_model(config, provider, fallback: str = "") -> str:
+    """``config.vision_model`` if set; else the best vision-capable model the providers list; else ``fallback``."""
+    from .models import is_vision_model, resolve_vision
+
+    wanted = (getattr(config, "vision_model", "auto") or "auto").strip()
+    if wanted.lower() != "auto":
+        try:
+            from .providers.base import qualify
+
+            return qualify(provider.default_name, wanted) if hasattr(provider, "default_name") else wanted
+        except Exception:
+            return wanted
+    try:
+        infos = provider.list_models()
+    except Exception:
+        infos = []
+    ids = []
+    for m in infos:
+        mid = getattr(m, "id", None) or (m.get("id") if isinstance(m, dict) else None)
+        raw = getattr(m, "raw", None) or (m if isinstance(m, dict) else {})
+        if mid and is_vision_model({**raw, "id": mid}):
+            ids.append(mid)
+    if not fallback:
+        try:
+            fallback = config.resolve_model()
+        except Exception:
+            fallback = ""
+    return resolve_vision(ids, fallback=fallback)
+
+
+def describe_images(images: List[EncodedImage], provider, model: str, instruction: str = "",
+                    cancel_event=None) -> VisionResult:
+    """One describe call: a non-streaming chat whose user message carries the image parts."""
+    if not images:
+        return VisionResult(text="")
+    messages = [{"role": "user", "content": build_content(images, instruction or DESCRIBE_INSTRUCTION)}]
+    result = provider.chat(messages, model=model, max_tokens=1500, cancel_event=cancel_event)
+    return VisionResult(text=(result.content or "").strip(), model=result.model, usage=result.usage)
+
+
+def _augment(clean_text: str, blocks: "List[tuple]") -> str:
+    """Fold per-image descriptions back into the user's turn as clearly-separated, labelled text.
+
+    ``blocks`` is a list of ``(index, EncodedImage, description)``. Each image gets its own labelled
+    section (``Image N (name)``) so the model can tell them apart and diff/compare reliably.
+    """
+    n = len(blocks)
+    header = (f"The user attached {n} image(s); a visual description of each follows "
+              f"(labelled to match the [Image N] badges shown in the prompt).")
+    sections = [f"[Image {idx} — {img.name}]\n{desc}" for idx, img, desc in blocks]
+    body = header + "\n\n" + "\n\n".join(sections)
+    return f"{clean_text}\n\n{body}" if clean_text else body
+
+
+def fold_images_into_text(text, config, provider, ui=None, cancel_event=None, model: str = "") -> str:
+    """Detect image paths in ``text``, describe them, and return the text augmented with the result.
+
+    Best-effort and non-destructive: if images are disabled or none are found, ``text`` is returned
+    unchanged. Once images *are* detected, the raw paths are always stripped from the returned text —
+    on a describe failure a short "couldn't process" note is folded in instead of leaking the paths
+    (which the agent can't read and would get confused by). A genuine user interrupt is re-raised so
+    the caller can abort the turn cleanly rather than proceeding with a half-processed prompt.
+    """
+    if not getattr(config, "images", True) or provider is None:
+        return text
+
+    from .errors import Interrupted
+    from .images import extract_image_paths, to_data_uri
+
+    try:
+        clean, paths = extract_image_paths(text, root=getattr(config, "root", None))
+    except Exception:
+        return text
+    if not paths:
+        return text
+
+    def _note(reason: str) -> str:
+        # Never echo the raw file paths back into the conversation.
+        msg = f"[{len(paths)} image(s) were attached but could not be read right now ({reason}).]"
+        return f"{clean}\n\n{msg}".strip() if clean else msg
+
+    try:
+        max_bytes = getattr(config, "image_max_bytes", None) or 4 * 1024 * 1024
+        encoded: List[EncodedImage] = []
+        for p in paths:
+            try:
+                encoded.append(to_data_uri(p, max_bytes=max_bytes))
+            except Exception as exc:  # oversized/unreadable — skip it, keep going
+                if ui is not None and hasattr(ui, "assistant"):
+                    ui.assistant(f"skipping image {getattr(p, 'name', p)}: {exc}")
+        if not encoded:
+            return _note("encoding failed")
+        vision_model = pick_vision_model(config, provider, fallback=model)
+        if not vision_model:
+            return _note("no vision-capable model")
+
+        ce = cancel_event or threading.Event()
+
+        def _describe_each():
+            # Describe each image in its *own* call so a multi-image prompt gets a complete,
+            # correctly-attributed description per image (one shared call tends to merge or drop some).
+            out = []
+            for idx, img in enumerate(encoded, 1):
+                res = describe_images([img], provider, vision_model, cancel_event=ce)
+                out.append((idx, img, (res.text or "").strip()))
+            return out
+
+        if ui is not None and hasattr(ui, "activity"):
+            with ui.activity(f"looking at {len(encoded)} image(s)…", ce):
+                described = _describe_each()
+        else:
+            described = _describe_each()
+
+        blocks = [(idx, img, desc) for idx, img, desc in described if desc]
+        if not blocks:
+            return _note("no description returned")
+        if ui is not None and hasattr(ui, "assistant"):
+            ui.assistant(f"read {len(encoded)} image(s): "
+                         + ", ".join(img.name for img in encoded))
+        return _augment(clean, blocks)
+    except Interrupted:
+        raise  # a real user interrupt → let the caller abort the turn (don't leak raw paths)
+    except Exception:
+        return _note("vision unavailable")
+

scootcli/workspace.py

@@ -0,0 +1,105 @@
+"""Workspace context: a compact, deterministic map of the repo injected into the agent prompt.
+
+Giving the model an at-a-glance view of the project (git branch + a bounded directory tree) means it
+can orient without spending its first step(s) on ``list_dir``. It is intentionally cheap, read-only,
+and tightly bounded so it costs few tokens; it is recomputed once per user turn (see
+:meth:`scootcli.agent.Agent.run_turn`). Toggle with ``SCOOT_WORKSPACE_CONTEXT`` / ``--no-workspace``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import List
+
+_SKIP_DIRS = {
+    ".git", ".hg", ".svn", "__pycache__", ".mypy_cache", ".pytest_cache", ".ruff_cache",
+    "node_modules", ".venv", "venv", "dist", "build", ".idea", ".vscode", ".cache",
+    ".egg-info",
+}
+_MAX_DEPTH = 2
+_MAX_ENTRIES = 120
+_MAX_FILES_PER_DIR = 12
+_GIT_TIMEOUT = 2
+
+
+def _git_summary(root: Path) -> str:
+    """Best-effort ``branch, N uncommitted change(s)`` for a git repo, or '' if not one/available."""
+    def _git(*args) -> "subprocess.CompletedProcess | None":
+        try:
+            return subprocess.run(
+                ["git", "-C", str(root), *args],
+                capture_output=True, text=True, timeout=_GIT_TIMEOUT,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return None
+
+    head = _git("rev-parse", "--abbrev-ref", "HEAD")
+    if head is None or head.returncode != 0:
+        return ""
+    branch = head.stdout.strip() or "(detached)"
+    status = _git("status", "--porcelain")
+    dirty = 0
+    if status is not None and status.returncode == 0:
+        dirty = sum(1 for line in status.stdout.splitlines() if line.strip())
+    return f"branch {branch}, {dirty} uncommitted change(s)"
+
+
+def _is_hidden(name: str) -> bool:
+    return name.startswith(".") and name not in (".github", ".env.example")
+
+
+def render_tree(root: Path, max_depth: int = _MAX_DEPTH, max_entries: int = _MAX_ENTRIES) -> str:
+    """Return a compact indented tree (dirs first), depth- and entry-bounded."""
+    lines: List[str] = []
+    budget = max_entries
+
+    def walk(directory: Path, depth: int) -> None:
+        nonlocal budget
+        if depth > max_depth or budget <= 0:
+            return
+        try:
+            children = sorted(directory.iterdir(), key=lambda c: (c.is_file(), c.name.lower()))
+        except OSError:
+            return
+        dirs = [c for c in children if c.is_dir()
+                and c.name not in _SKIP_DIRS and not c.name.endswith(".egg-info")
+                and not _is_hidden(c.name)]
+        files = [c for c in children if c.is_file() and not _is_hidden(c.name)]
+        indent = "  " * depth
+        for child in dirs:
+            if budget <= 0:
+                break
+            budget -= 1
+            lines.append(f"{indent}{child.name}/")
+            walk(child, depth + 1)
+        shown = files[:_MAX_FILES_PER_DIR]
+        for child in shown:
+            if budget <= 0:
+                break
+            budget -= 1
+            lines.append(f"{indent}{child.name}")
+        if len(files) > len(shown) and budget > 0:
+            lines.append(f"{indent}… (+{len(files) - len(shown)} more files)")
+
+    walk(Path(root), 0)
+    if budget <= 0:
+        lines.append("… [truncated]")
+    return "\n".join(lines)
+
+
+def workspace_context(root, max_depth: int = _MAX_DEPTH, max_entries: int = _MAX_ENTRIES) -> str:
+    """Compose the workspace map (git summary + tree). Returns '' if nothing useful is available."""
+    root = Path(root)
+    if not root.is_dir():
+        return ""
+    parts: List[str] = []
+    git = _git_summary(root)
+    if git:
+        parts.append(f"- git: {git}")
+    tree = render_tree(root, max_depth, max_entries)
+    if tree:
+        indented = "\n".join("  " + line for line in tree.splitlines())
+        parts.append("- files:\n" + indented)
+    return "\n".join(parts)
+