hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/brief/google.py

@@ -0,0 +1,269 @@
+"""Read-only Google Docs and Sheets readers (GET only).
+
+Docs API v1 gives the title, the text and the links in a Doc (no Drive scope
+needed); Sheets API v4 gives a spreadsheet's title, tab names and values.
+Per-file failures are named (no access, deleted, couldn't be returned);
+whole-run failures (expired access, Google unreachable) raise a BriefError.
+No URL, file id or response body is ever logged: the logger gets reason
+codes only, and the brief's link filter is installed on the HTTP loggers.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional, Tuple
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+from hyperclaw.brief import links
+from hyperclaw.brief.errors import BriefError, Reason
+from hyperclaw.taint import source as taint_source
+
+log = logging.getLogger("hyperclaw.brief")
+
+DOCS_API = "https://docs.googleapis.com"
+SHEETS_API = "https://sheets.googleapis.com"
+TIMEOUT = 20.0
+MAX_RETRIES = 3
+MAX_WAIT = 30.0
+MAX_TEXT = 20_000          # characters kept per file
+MAX_ROWS = 300             # rows kept per tab
+MAX_COLS = 15
+MAX_TABS = 10
+
+
+def _api(env: str, default: str) -> str:
+    """API base. A loopback override exists for tests only."""
+    override = os.environ.get(env, "").strip()
+    if override and (urlsplit(override).hostname or "") in ("127.0.0.1", "localhost", "::1"):
+        return override.rstrip("/")
+    return default
+
+
+@dataclass
+class Link:
+    url: str
+    anchor: str
+
+
+@dataclass
+class DocContent:
+    title: str
+    text: str
+    links: List[Link] = field(default_factory=list)
+
+
+@dataclass
+class SheetContent:
+    title: str
+    tabs: List[Tuple[str, list]] = field(default_factory=list)   # (tab title, rows)
+
+    def text(self) -> str:
+        out = []
+        for tab, rows in self.tabs:
+            out.append(f"[tab: {tab}]")
+            for r in rows:
+                out.append(" | ".join(str(c) for c in r))
+        return "\n".join(out)[:MAX_TEXT]
+
+
+def new_client() -> httpx.Client:
+    return httpx.Client(timeout=TIMEOUT, follow_redirects=False)
+
+
+class FileError(Exception):
+    """A per-file failure with a skip reason (no access, deleted, ...)."""
+
+    def __init__(self, reason: Reason):
+        self.reason = reason
+        super().__init__(reason.value)
+
+
+class GoogleReader:
+    def __init__(self, token: str, *, client: Optional[httpx.Client] = None,
+                 sleep: Callable[[float], None] = time.sleep):
+        links.install_log_filter()
+        self._headers = {"Authorization": f"Bearer {token}"}
+        self.client = client or new_client()
+        self.sleep = sleep
+        self.docs_api = _api("HYPERCLAW_BRIEF_DOCS_API", DOCS_API)
+        self.sheets_api = _api("HYPERCLAW_BRIEF_SHEETS_API", SHEETS_API)
+
+    def close(self) -> None:
+        try:
+            self.client.close()
+        except Exception:
+            pass
+
+    # ── HTTP ──
+    def _get(self, url: str, params: Optional[list] = None) -> dict:
+        for attempt in range(MAX_RETRIES + 1):
+            try:
+                resp = self.client.get(url, params=params or [], headers=self._headers)
+            except httpx.HTTPError as e:
+                if attempt >= MAX_RETRIES:
+                    raise BriefError(Reason.GOOGLE_UNREACHABLE, type(e).__name__)
+                self.sleep(min(2 ** attempt, MAX_WAIT))
+                continue
+            code = resp.status_code
+            if code == 429:
+                if attempt >= MAX_RETRIES:
+                    raise BriefError(Reason.GOOGLE_RATE_LIMITED, "429")
+                self.sleep(_retry_after(resp))
+                continue
+            if code >= 500:
+                if attempt >= MAX_RETRIES:
+                    raise BriefError(Reason.GOOGLE_UNREACHABLE, f"HTTP {code}")
+                self.sleep(min(2 ** attempt, MAX_WAIT))
+                continue
+            if code == 401:
+                raise BriefError(Reason.GOOGLE_EXPIRED, "401")
+            if code == 403:
+                if _status(resp) == "PERMISSION_DENIED" and "scope" in _message(resp).lower():
+                    raise BriefError(Reason.GOOGLE_MISSING_SCOPE, "403 scope")
+                raise FileError(Reason.NO_ACCESS)
+            if code in (404, 410):
+                raise FileError(Reason.DELETED)
+            if code == 400:
+                # a Drive file that isn't a native Doc/Sheet (an uploaded .docx/.xlsx)
+                raise FileError(Reason.NOT_DOC_OR_SHEET)
+            if code != 200:
+                raise FileError(Reason.UNREADABLE)
+            try:
+                body = resp.json()
+            except Exception:
+                raise FileError(Reason.UNREADABLE)
+            if not isinstance(body, dict):
+                raise FileError(Reason.UNREADABLE)
+            return body
+        raise BriefError(Reason.GOOGLE_UNREACHABLE, "retries exhausted")  # pragma: no cover
+
+    # ── Docs ──
+    @taint_source("google_docs", "google")
+    def doc(self, file_id: str) -> DocContent:
+        body = self._get(f"{self.docs_api}/v1/documents/{quote(file_id, safe='')}",
+                         [("includeTabsContent", "true")])
+        title = str(body.get("title") or "").strip()
+        texts, found = [], []
+        tabs = body.get("tabs")
+        if isinstance(tabs, list) and tabs:
+            for tab in _walk_tabs(tabs):
+                dt = tab.get("documentTab") or {}
+                _content(((dt.get("body") or {}).get("content")) or [], texts, found)
+        else:
+            _content(((body.get("body") or {}).get("content")) or [], texts, found)
+        text = "".join(texts)
+        return DocContent(title=title, text=text[:MAX_TEXT], links=_merge_links(found))
+
+    # ── Sheets ──
+    @taint_source("google_sheets", "google")
+    def sheet(self, file_id: str) -> SheetContent:
+        base = f"{self.sheets_api}/v4/spreadsheets/{quote(file_id, safe='')}"
+        meta = self._get(base, [("fields", "properties.title,sheets.properties.title")])
+        title = str((meta.get("properties") or {}).get("title") or "").strip()
+        tab_names = [str((s.get("properties") or {}).get("title") or "")
+                     for s in (meta.get("sheets") or []) if isinstance(s, dict)][:MAX_TABS]
+        tabs = []
+        if tab_names:
+            ranges = [("ranges", f"'{t.replace(chr(39), chr(39) * 2)}'!A1:O{MAX_ROWS}")
+                      for t in tab_names]
+            vals = self._get(f"{base}/values:batchGet",
+                             ranges + [("majorDimension", "ROWS"),
+                                       ("valueRenderOption", "FORMATTED_VALUE")])
+            for name, vr in zip(tab_names, vals.get("valueRanges") or []):
+                rows = [[str(c) for c in (r or [])][:MAX_COLS]
+                        for r in (vr.get("values") or [])][:MAX_ROWS]
+                tabs.append((name, rows))
+        return SheetContent(title=title, tabs=tabs)
+
+
+def _walk_tabs(tabs: list):
+    for t in tabs:
+        if not isinstance(t, dict):
+            continue
+        yield t
+        yield from _walk_tabs(t.get("childTabs") or [])
+
+
+def _content(elements: list, texts: list, found: list) -> None:
+    for el in elements:
+        if not isinstance(el, dict):
+            continue
+        para = el.get("paragraph")
+        if para:
+            for pe in para.get("elements") or []:
+                tr = pe.get("textRun")
+                if tr:
+                    content = tr.get("content") or ""
+                    texts.append(content)
+                    url = ((tr.get("textStyle") or {}).get("link") or {}).get("url")
+                    if url:
+                        found.append((url, content))
+                rl = pe.get("richLink")
+                if rl:
+                    props = rl.get("richLinkProperties") or {}
+                    t = props.get("title") or ""
+                    texts.append(t)
+                    if props.get("uri"):
+                        found.append((props["uri"], t))
+            continue
+        table = el.get("table")
+        if table:
+            for row in table.get("tableRows") or []:
+                cells = []
+                for cell in row.get("tableCells") or []:
+                    sub: list = []
+                    _content(cell.get("content") or [], sub, found)
+                    cells.append(" ".join("".join(sub).split()))
+                texts.append(" | ".join(cells) + "\n")
+            continue
+        toc = el.get("tableOfContents")
+        if toc:
+            _content(toc.get("content") or [], [], [])
+
+
+def _merge_links(found: list) -> List[Link]:
+    """Consecutive runs of one link become one Link with the joined text;
+    the same link twice is kept once (first anchor wins)."""
+    out: List[Link] = []
+    seen = set()
+    prev_url = None
+    for url, text in found:
+        if out and url == prev_url:
+            out[-1].anchor += text
+            continue
+        prev_url = url
+        if url in seen:
+            continue
+        seen.add(url)
+        out.append(Link(url=url, anchor=text))
+    for lk in out:
+        lk.anchor = " ".join(lk.anchor.split())
+    return out
+
+
+def _retry_after(resp) -> float:
+    try:
+        return max(0.0, min(float(resp.headers.get("Retry-After", "1")), MAX_WAIT))
+    except ValueError:
+        return 1.0
+
+
+def _err(resp) -> dict:
+    try:
+        b = resp.json()
+        e = b.get("error") if isinstance(b, dict) else None
+        return e if isinstance(e, dict) else {}
+    except Exception:
+        return {}
+
+
+def _status(resp) -> str:
+    return str(_err(resp).get("status") or "")
+
+
+def _message(resp) -> str:
+    return str(_err(resp).get("message") or "")

hyperclaw/brief/google_auth.py

@@ -0,0 +1,294 @@
+"""Google sign-in for the brief: installed-app (Desktop) OAuth, loopback redirect.
+
+- The OAuth client (client id/secret) is a file the owner keeps outside the
+  repo; config.json ``brief.google_client_file`` holds only its path.
+- Only two read-only scopes are requested, nothing else (no Gmail, no Drive):
+  documents.readonly and spreadsheets.readonly. A grant that carries any
+  other scope is refused and nothing is stored; so is a grant missing one.
+- PKCE (S256) + a random state; the redirect goes to 127.0.0.1 on a random
+  port. The browser is opened only when asked (``open_browser``); otherwise
+  the address is shown for the owner to open.
+- The token is stored in $HYPERCLAW_ROOT/brief/google-token.json, 0600.
+  It is never printed, logged or sent to the model.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+import secrets
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Callable, Optional
+from urllib.parse import parse_qs, urlencode, urlsplit
+
+import httpx
+
+from hyperclaw.brief import store
+from hyperclaw.brief.errors import BriefError, Reason
+
+log = logging.getLogger("hyperclaw.brief")
+
+SCOPES = ("https://www.googleapis.com/auth/documents.readonly",
+          "https://www.googleapis.com/auth/spreadsheets.readonly")
+AUTH_URI = "https://accounts.google.com/o/oauth2/v2/auth"
+TOKEN_URI = "https://oauth2.googleapis.com/token"
+TIMEOUT = 20.0
+CONSENT_WAIT = 300.0
+DONE_PAGE = (b"<!doctype html><meta charset=utf-8><title>HyperAgents</title>"
+             b"<p>HyperAgents has your answer from Google. You can close this tab and go "
+             b"back to the terminal.</p>")
+
+
+def token_uri() -> str:
+    """Google's token endpoint. A loopback override exists for tests only."""
+    override = os.environ.get("HYPERCLAW_BRIEF_GOOGLE_TOKEN_URI", "").strip()
+    if override:
+        host = urlsplit(override).hostname or ""
+        if host in ("127.0.0.1", "localhost", "::1"):
+            return override
+    return TOKEN_URI
+
+
+# ── client file ───────────────────────────────────────────────────────────
+
+def client_file() -> str:
+    return str(store.config().get("google_client_file") or "")
+
+
+def load_client(path: Optional[str] = None) -> dict:
+    """{"client_id", "client_secret"} from a Desktop-app client JSON file.
+    With no file configured, a team install uses the team Google client from
+    its Hyper-signed team profile (hyperclaw.teamsetup.profile)."""
+    if not (path or client_file()):
+        try:
+            from hyperclaw.teamsetup.profile import google_client
+            team = google_client()
+        except Exception:
+            team = {}
+        if team:
+            return team
+    p = Path(os.path.expanduser(path or client_file() or ""))
+    if not str(p) or not p.is_file():
+        raise BriefError(Reason.GOOGLE_CLIENT_FILE, "missing")
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        raise BriefError(Reason.GOOGLE_CLIENT_FILE, "unparseable")
+    inst = data.get("installed") if isinstance(data, dict) else None
+    if not isinstance(inst, dict) or not inst.get("client_id") or not inst.get("client_secret"):
+        raise BriefError(Reason.GOOGLE_CLIENT_FILE, "not a desktop client")
+    return {"client_id": str(inst["client_id"]), "client_secret": str(inst["client_secret"])}
+
+
+# ── scopes ────────────────────────────────────────────────────────────────
+
+def check_scopes(granted: str) -> list:
+    got = sorted(set((granted or "").split()))
+    extra = [s for s in got if s not in SCOPES]
+    if extra:
+        raise BriefError(Reason.GOOGLE_EXTRA_SCOPE, f"{len(extra)} extra")
+    if set(SCOPES) - set(got):
+        raise BriefError(Reason.GOOGLE_MISSING_SCOPE)
+    return got
+
+
+# ── token storage ─────────────────────────────────────────────────────────
+
+def load_token() -> dict:
+    p = store.token_path()
+    if not p.exists():
+        return {}
+    if store.too_open(p):
+        raise BriefError(Reason.TOKEN_FILE_OPEN)
+    return store.read_json(p)
+
+
+def save_token(tok: dict) -> None:
+    store.write_json(store.token_path(), tok)
+
+
+def connected() -> bool:
+    try:
+        return bool(load_token().get("refresh_token"))
+    except BriefError:
+        return False
+
+
+def disconnect() -> bool:
+    try:
+        store.token_path().unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+# ── the consent flow ──────────────────────────────────────────────────────
+
+def _pkce() -> tuple:
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(48)).rstrip(b"=").decode()
+    challenge = base64.urlsafe_b64encode(
+        hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+class _Catcher:
+    """One-shot loopback HTTP server that waits for Google's redirect."""
+
+    def __init__(self):
+        self.result: dict = {}
+        self.event = threading.Event()
+        outer = self
+
+        class H(BaseHTTPRequestHandler):
+            def log_message(self, *a):       # never log the query (it holds the code)
+                pass
+
+            def do_GET(self):
+                q = {k: v[0] for k, v in parse_qs(urlsplit(self.path).query).items()}
+                if "code" in q or "error" in q:
+                    outer.result = q
+                    outer.event.set()
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.send_header("Content-Length", str(len(DONE_PAGE)))
+                self.end_headers()
+                self.wfile.write(DONE_PAGE)
+
+        self.httpd = HTTPServer(("127.0.0.1", 0), H)
+        self.port = self.httpd.server_address[1]
+        self.thread = threading.Thread(target=self._serve, daemon=True)
+
+    def _serve(self):
+        while not self.event.is_set():
+            self.httpd.handle_request()
+
+    def start(self):
+        self.httpd.timeout = 0.5
+        self.thread.start()
+
+    def close(self):
+        self.event.set()
+        try:
+            self.httpd.server_close()
+        except Exception:
+            pass
+
+
+def auth_url(client_id: str, redirect_uri: str, state: str, challenge: str) -> str:
+    return AUTH_URI + "?" + urlencode({
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "response_type": "code",
+        "scope": " ".join(SCOPES),
+        "access_type": "offline",
+        "prompt": "consent",
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    })
+
+
+def connect(*, client_path: Optional[str] = None, show: Callable[[str], None] = print,
+            open_browser: Optional[Callable[[str], object]] = None,
+            http: Optional[httpx.Client] = None, wait: float = CONSENT_WAIT,
+            on_listening: Optional[Callable[[str, str], None]] = None,
+            client: Optional[dict] = None) -> dict:
+    """Run the consent flow, verify the scopes, store the token.
+
+    ``on_listening(redirect_uri, state)`` is a test hook. Returns
+    {"scopes": [...]}; raises a named BriefError and stores nothing on failure."""
+    client = client or load_client(client_path)
+    verifier, challenge = _pkce()
+    state = secrets.token_urlsafe(24)
+    catcher = _Catcher()
+    redirect_uri = f"http://127.0.0.1:{catcher.port}"
+    catcher.start()
+    try:
+        url = auth_url(client["client_id"], redirect_uri, state, challenge)
+        show("Open this address in your browser and sign in with the Google account that can "
+             "see your Doc and Sheet. HyperAgents asks only to view Docs and Sheets "
+             "(read-only):\n\n" + url + "\n")
+        if open_browser:
+            try:
+                open_browser(url)
+            except Exception:
+                pass
+        if on_listening:
+            on_listening(redirect_uri, state)
+        if not catcher.event.wait(wait):
+            raise BriefError(Reason.GOOGLE_CONSENT, "timeout")
+        res = catcher.result
+    finally:
+        catcher.close()
+    if res.get("state") != state or res.get("error") or not res.get("code"):
+        raise BriefError(Reason.GOOGLE_CONSENT, "denied or state mismatch")
+    tok = _token_request({
+        "grant_type": "authorization_code",
+        "code": res["code"],
+        "redirect_uri": redirect_uri,
+        "client_id": client["client_id"],
+        "client_secret": client["client_secret"],
+        "code_verifier": verifier,
+    }, http)
+    scopes = check_scopes(tok.get("scope", ""))
+    if not tok.get("refresh_token"):
+        raise BriefError(Reason.GOOGLE_CONSENT, "no refresh token")
+    save_token({
+        "refresh_token": tok["refresh_token"],
+        "access_token": tok.get("access_token", ""),
+        "expiry": time.time() + float(tok.get("expires_in") or 0),
+        "scopes": scopes,
+        "connected_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+    })
+    return {"scopes": scopes}
+
+
+def _token_request(form: dict, http: Optional[httpx.Client] = None) -> dict:
+    c = http or httpx.Client(timeout=TIMEOUT, follow_redirects=False)
+    try:
+        resp = c.post(token_uri(), data=form)
+    except httpx.HTTPError as e:
+        raise BriefError(Reason.GOOGLE_UNREACHABLE, type(e).__name__)
+    finally:
+        if http is None:
+            c.close()
+    try:
+        body = resp.json()
+    except Exception:
+        body = {}
+    if resp.status_code == 200 and isinstance(body, dict) and body.get("access_token"):
+        return body
+    err = body.get("error") if isinstance(body, dict) else ""
+    if err in ("invalid_grant", "unauthorized_client", "invalid_client"):
+        raise BriefError(Reason.GOOGLE_EXPIRED, str(err))
+    if resp.status_code >= 500:
+        raise BriefError(Reason.GOOGLE_UNREACHABLE, f"HTTP {resp.status_code}")
+    raise BriefError(Reason.GOOGLE_CONSENT, f"HTTP {resp.status_code}")
+
+
+def access_token(http: Optional[httpx.Client] = None, now: Optional[float] = None) -> str:
+    """A valid access token, refreshed when needed. Scopes re-checked."""
+    tok = load_token()
+    if not tok.get("refresh_token"):
+        raise BriefError(Reason.GOOGLE_NOT_CONNECTED)
+    now = time.time() if now is None else now
+    if tok.get("access_token") and float(tok.get("expiry") or 0) - 60 > now:
+        check_scopes(" ".join(tok.get("scopes") or []))
+        return tok["access_token"]
+    client = load_client()
+    fresh = _token_request({
+        "grant_type": "refresh_token",
+        "refresh_token": tok["refresh_token"],
+        "client_id": client["client_id"],
+        "client_secret": client["client_secret"],
+    }, http)
+    scopes = check_scopes(fresh.get("scope") or " ".join(tok.get("scopes") or []))
+    tok.update({"access_token": fresh["access_token"], "scopes": scopes,
+                "expiry": now + float(fresh.get("expires_in") or 3600)})
+    save_token(tok)
+    return tok["access_token"]

hyperclaw/brief/links.py

@@ -0,0 +1,124 @@
+"""Links and file IDs never leave this machine's private config.
+
+- ``parse`` turns a pasted Google link into (kind, file id). Only the id is
+  stored (owner-only sources.json), never the link.
+- ``scrub`` removes every URL and anything shaped like a Google file id from
+  text before it reaches the model, the brief, a notice or a log line.
+- ``link_label`` names a linked file by the text it was linked from in the
+  master Doc (read from the source); a bare pasted link gets a neutral
+  "untitled link" label instead, so the link itself is never shown.
+- ``LinkLogFilter`` drops HTTP-client log records that carry a Google file
+  URL or a Telegram bot URL (httpx logs every request URL at INFO).
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+from typing import Iterable, Optional, Tuple
+from urllib.parse import parse_qs, urlsplit
+
+DOC = "doc"
+SHEET = "sheet"
+OTHER = "other"
+
+# Google file ids are long url-safe strings (typically 44 characters).
+_ID = r"[A-Za-z0-9_-]{20,}"
+ID_RE = re.compile(r"(?<![A-Za-z0-9_-])[A-Za-z0-9_-]{25,}(?![A-Za-z0-9_-])")
+URL_RE = re.compile(r"(?i)(?:https?://|www\.)[^\s<>\"'()\]]+")
+_BARE_GOOGLE = re.compile(r"(?i)\b(?:docs|drive|sheets)\.google\.com/[^\s<>\"']*")
+_PATH_ID = re.compile(rf"/d/(?:e/)?({_ID})")
+
+
+def parse(url: str) -> Tuple[str, Optional[str]]:
+    """(kind, file id). kind is DOC, SHEET or OTHER; id None when it can't be
+    told (OTHER is returned for every non-Google-Docs/Sheets link)."""
+    raw = (url or "").strip()
+    if not raw:
+        return OTHER, None
+    if "://" not in raw:
+        raw = "https://" + raw
+    try:
+        parts = urlsplit(raw)
+    except ValueError:
+        return OTHER, None
+    host = (parts.hostname or "").lower()
+    path = parts.path or ""
+    if host == "docs.google.com":
+        m = _PATH_ID.search(path)
+        fid = m.group(1) if m else None
+        if path.startswith("/document/") and fid and "/d/e/" not in path:
+            return DOC, fid
+        if path.startswith("/spreadsheets/") and fid and "/d/e/" not in path:
+            return SHEET, fid
+        return OTHER, fid
+    if host == "drive.google.com":
+        m = _PATH_ID.search(path)
+        fid = m.group(1) if m else (parse_qs(parts.query).get("id") or [None])[0]
+        return OTHER, fid
+    return OTHER, None
+
+
+def is_link(url: str) -> bool:
+    u = (url or "").strip().lower()
+    return u.startswith(("http://", "https://"))
+
+
+def key_for(file_id: str) -> str:
+    """Stable, non-reversible key for a file (snapshot keys, dedupe)."""
+    return hashlib.sha256(("hyperclaw-brief:" + (file_id or "")).encode()).hexdigest()[:16]
+
+
+def scrub(text: str, extra: Iterable[str] = ()) -> str:
+    """Remove URLs, Google file ids and any of ``extra`` (known ids) from text."""
+    if not text:
+        return ""
+    out = URL_RE.sub("[link]", str(text))
+    out = _BARE_GOOGLE.sub("[link]", out)
+    for x in extra:
+        if x:
+            out = out.replace(x, "[id]")
+    return ID_RE.sub("[id]", out)
+
+
+def contains_link_or_id(text: str, extra: Iterable[str] = ()) -> bool:
+    t = text or ""
+    if URL_RE.search(t) or _BARE_GOOGLE.search(t) or ID_RE.search(t):
+        return True
+    return any(x and x in t for x in extra)
+
+
+def link_label(anchor: str, n: int) -> str:
+    """The label shown for a linked file: its link text from the master Doc,
+    or "untitled link n" when the text is itself a link or carries an id."""
+    a = " ".join((anchor or "").split()).strip()
+    if not a or contains_link_or_id(a):
+        return f"untitled link {n}"
+    return a[:80]
+
+
+class LinkLogFilter(logging.Filter):
+    """Drop log records whose message carries a Google file URL or a
+    Telegram bot URL. Installed on the HTTP client loggers by the brief."""
+
+    _PAT = re.compile(r"(?i)(docs\.googleapis\.com|sheets\.googleapis\.com|docs\.google\.com|"
+                      r"drive\.google\.com|api\.telegram\.org/bot|oauth2\.googleapis\.com|"
+                      r"/v1/documents/|/v4/spreadsheets/)")
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        try:
+            msg = record.getMessage()
+        except Exception:
+            return True
+        return not self._PAT.search(msg)
+
+
+_FILTER = LinkLogFilter()
+
+
+def install_log_filter() -> None:
+    """Idempotent: attach the filter to the HTTP client loggers."""
+    for name in ("httpx", "httpcore", "urllib3", "urllib3.connectionpool"):
+        lg = logging.getLogger(name)
+        if _FILTER not in lg.filters:
+            lg.addFilter(_FILTER)