hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/digest/http.py

@@ -0,0 +1,113 @@
+"""Read-only HTTP for the digest collectors: GET only, bounded retries.
+
+- 429: wait Retry-After (capped), retry a few times, then the source's
+  named rate-limit failure.
+- 5xx / network errors: short retries, then "<source> couldn't be reached".
+The token goes only into the Authorization header of requests to the
+source's own API; it is never logged.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, Optional
+from urllib.parse import urlsplit
+
+import httpx
+
+from hyperclaw.digest.errors import DigestError, Reason
+
+log = logging.getLogger("hyperclaw.digest")
+
+MAX_RETRIES = 3
+MAX_WAIT = 30.0
+TIMEOUT = 20.0
+
+
+@dataclass
+class SourceResult:
+    source: str
+    ok: bool = True
+    reason: Optional[Reason] = None
+    account: str = ""
+    items: list = field(default_factory=list)
+    notes: list = field(default_factory=list)
+
+
+class ReadOnlyHttp:
+    def __init__(self, base_url: str, headers: dict, *, rate_limited: Reason,
+                 unreachable: Reason, client: Optional[httpx.Client] = None,
+                 sleep: Callable[[float], None] = time.sleep):
+        self.base = require_https(base_url).rstrip("/")
+        self._headers = headers
+        self.rate_limited = rate_limited
+        self.unreachable = unreachable
+        self.client = client or httpx.Client(timeout=TIMEOUT, follow_redirects=False)
+        self.sleep = sleep
+
+    def get(self, path: str, params: Optional[dict] = None) -> httpx.Response:
+        url = f"{self.base}/{path.lstrip('/')}"
+        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 DigestError(self.unreachable, type(e).__name__)
+                self.sleep(min(2 ** attempt, MAX_WAIT))
+                continue
+            if resp.status_code == 429:
+                if attempt >= MAX_RETRIES:
+                    raise DigestError(self.rate_limited, "429 after retries")
+                self.sleep(_retry_after(resp))
+                continue
+            if resp.status_code >= 500:
+                if attempt >= MAX_RETRIES:
+                    raise DigestError(self.unreachable, f"HTTP {resp.status_code}")
+                self.sleep(min(2 ** attempt, MAX_WAIT))
+                continue
+            return resp
+        raise DigestError(self.unreachable, "retries exhausted")  # pragma: no cover
+
+    def close(self) -> None:
+        try:
+            self.client.close()
+        except Exception:
+            pass
+
+
+def require_https(url: str) -> str:
+    """Tokens go only over https (plain http only to this machine, for tests)."""
+    parts = urlsplit(url or "")
+    if parts.scheme == "https" and parts.hostname:
+        return url
+    if parts.scheme == "http" and parts.hostname in ("127.0.0.1", "localhost", "::1"):
+        return url
+    raise DigestError(Reason.INSECURE_URL, parts.scheme)
+
+
+def _retry_after(resp: httpx.Response) -> float:
+    try:
+        return max(0.0, min(float(resp.headers.get("Retry-After", "1")), MAX_WAIT))
+    except ValueError:
+        return 1.0
+
+
+def parse_time(value) -> Optional[datetime]:
+    """ISO-8601 (GitLab, with Z) or a Slack ts ('1696930000.000100')."""
+    if value is None or value == "":
+        return None
+    try:
+        if isinstance(value, (int, float)) or str(value).replace(".", "", 1).isdigit():
+            return datetime.fromtimestamp(float(value), tz=timezone.utc)
+        s = str(value).replace("Z", "+00:00")
+        dt = datetime.fromisoformat(s)
+        return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+    except (ValueError, OSError, OverflowError):
+        return None
+
+
+def clip(text: str, n: int) -> str:
+    text = " ".join(str(text or "").split())
+    return text if len(text) <= n else text[: n - 1] + "…"

hyperclaw/digest/redact.py

@@ -0,0 +1,32 @@
+"""Secrets are redacted from collected content before anything else sees it."""
+from __future__ import annotations
+
+import re
+
+from hyperclaw.truth_guard import redact_secrets as _base_redact
+
+_PATTERNS = [
+    (re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)",
+                re.S), "[REDACTED-private-key]"),
+    (re.compile(r"\bxox[abeoprsc]-[A-Za-z0-9-]{8,}"), "[REDACTED-slack-token]"),
+    (re.compile(r"\bxoxe\.xox[a-z]-[A-Za-z0-9.-]{8,}"), "[REDACTED-slack-token]"),
+    (re.compile(r"\bxapp-[A-Za-z0-9-]{8,}"), "[REDACTED-slack-token]"),
+    (re.compile(r"\bgl(?:pat|oas|dt|rt|ptt|cbt|ft|imt|soat|agent|ffct|wt)-[A-Za-z0-9_.-]{16,}"),
+     "[REDACTED-gitlab-token]"),
+    (re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"), "[REDACTED-aws-key]"),
+    (re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}"), "[REDACTED-jwt]"),
+    (re.compile(r"(?i)\b(bearer\s+)[A-Za-z0-9._~+/=-]{12,}"), r"\1[REDACTED]"),
+    (re.compile(r"(?i)\b((?:password|passwd|pwd|secret|api[_-]?key|access[_-]?token|token)"
+                r"\s*[:=]\s*)(\"[^\"]+\"|'[^']+'|\S+)"), r"\1[REDACTED]"),
+    (re.compile(r"\b([a-z][a-z0-9+.-]*://[^:/\s@]+:)[^@\s]+(@)"), r"\1[REDACTED]\2"),
+]
+
+
+def redact(text: str) -> str:
+    """Remove tokens, keys and passwords from a piece of collected text."""
+    if not text:
+        return ""
+    out = _base_redact(str(text))
+    for pat, repl in _PATTERNS:
+        out = pat.sub(repl, out)
+    return out

hyperclaw/digest/service.py

@@ -0,0 +1,271 @@
+"""Connect, run, deliver: the digest pipeline (docs/CONNECTED-DIGEST.md).
+
+Owner only: nothing here is reachable from a chat. ``run_digest`` refuses
+any scope but OWNER, delivery goes to the owner's Telegram chat(s) only, and
+every failure is reported with a fixed, named reason.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, Optional
+
+from hyperclaw.chat_scope import OWNER, owner_ids
+from hyperclaw.digest import state, tokens
+from hyperclaw.digest.errors import FIX, TEXT, DigestError, Reason
+from hyperclaw.digest.gitlab import GitLabCollector
+from hyperclaw.digest.http import SourceResult
+from hyperclaw.digest.redact import redact
+from hyperclaw.digest.slack import SlackCollector
+from hyperclaw.digest.summarize import summarize, v2_route
+
+log = logging.getLogger("hyperclaw.digest")
+
+LABEL = {"slack": "Slack", "gitlab": "GitLab"}
+NOT_CONNECTED = {"slack": Reason.SLACK_NOT_CONNECTED, "gitlab": Reason.GITLAB_NOT_CONNECTED}
+# Failure notices follow the notice standard (hyperclaw.notices): they name
+# the action, never imply success and never carry technical detail.
+GENERIC_FAILURE = ("Sorry, I couldn't build today's digest. Something went wrong on my side; "
+                   "details are in the HyperClaw log.")
+
+
+def make_collector(source: str, token: str, *, gitlab_url: str = "", client=None, sleep=None):
+    if source == "slack":
+        return SlackCollector(token, client=client, sleep=sleep)
+    if source == "gitlab":
+        return GitLabCollector(token, url=gitlab_url, client=client, sleep=sleep)
+    raise ValueError(f"unknown source {source!r}")
+
+
+# ── connect / disconnect ──────────────────────────────────────────────────
+
+def connect(source: str, token: str, *, gitlab_url: str = "", store=None,
+            client=None, sleep=None) -> dict:
+    """Verify read-only scopes, then store the token. Returns the non-secret
+    connection info. Raises a named DigestError; nothing is stored then."""
+    token = tokens.check_format(token)
+    col = make_collector(source, token, gitlab_url=gitlab_url, client=client, sleep=sleep)
+    try:
+        info = col.verify()
+    finally:
+        col.close()
+    st = store or tokens.store()
+    st.set(source, token)
+    meta = {k: v for k, v in info.items() if k in ("account", "workspace", "name", "scopes",
+                                                     "url", "expires_at", "user_id")}
+    meta["store"] = st.name
+    meta["connected_at"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    state.set_connection(source, meta)
+    return meta
+
+
+def disconnect(source: str) -> bool:
+    meta = state.connections().get(source) or {}
+    removed = False
+    for name in {meta.get("store") or tokens.backend_name(), "file"}:
+        try:
+            removed = tokens.store(name).delete(source) or removed
+        except DigestError:
+            pass
+    state.set_connection(source, None)
+    return removed or bool(meta)
+
+
+# ── run ───────────────────────────────────────────────────────────────────
+
+@dataclass
+class Outcome:
+    ok: bool
+    text: str                       # what is delivered (digest or failure notice)
+    reason: str = ""                # fixed reason text on failure
+    sources: dict = field(default_factory=dict)   # source -> "ok" | reason code
+
+
+def failure_notice(reasons: list) -> str:
+    """'Sorry, I couldn't build today's digest. <why>. <what to do>'
+    (hyperclaw.notices standard)."""
+    from hyperclaw.notices import failure_notice as standard
+    texts = [TEXT[r] for r in reasons]
+    fixes = [FIX[r] for r in reasons if r in FIX]
+    why = "; ".join(texts)
+    detail = (why[:1].upper() + why[1:] + ".") if why else ""
+    if fixes:
+        detail += " " + " ".join(dict.fromkeys(fixes))
+    return standard(what="build today's digest", detail=detail, retry=False)
+
+
+def _fmt_day(dt: datetime) -> str:
+    local = dt.astimezone()
+    return local.strftime("%a %d %b").replace(" 0", " ")
+
+
+def _fmt_since(dt: datetime) -> str:
+    local = dt.astimezone()
+    return local.strftime("%a %d %b %H:%M").replace(" 0", " ", 1)
+
+
+def sources_line(results: dict) -> str:
+    parts = []
+    for name, res in results.items():
+        if res.ok:
+            parts.append(f"{LABEL[name]} ok ({len(res.items)} items)")
+        else:
+            parts.append(f"{LABEL[name]} not read: {TEXT[res.reason]}")
+    return "Sources: " + " · ".join(parts)
+
+
+def _read_token(source: str, meta: dict) -> str:
+    return tokens.store(meta.get("store") or tokens.backend_name()).get(source)
+
+
+def collect(now: datetime, since: datetime, *, client=None, sleep=None) -> dict:
+    """source -> SourceResult for every connected source. Never raises for a
+    source failure: the result carries the named reason instead."""
+    results = {}
+    for source, meta in state.connections().items():
+        if source not in LABEL:
+            continue
+        col = None
+        try:
+            token = _read_token(source, meta)
+            if not token:
+                raise DigestError(NOT_CONNECTED[source])
+            col = make_collector(source, token, gitlab_url=meta.get("url", ""),
+                                 client=client, sleep=sleep)
+            col.verify()
+            results[source] = col.collect(since)
+        except DigestError as e:
+            log.warning("digest: %s not read: %s (%s)", source, e.reason.value, e.detail)
+            results[source] = SourceResult(source, ok=False, reason=e.reason)
+        finally:
+            if col is not None:
+                col.close()
+    return results
+
+
+def guard_results(results: dict, provider: str) -> dict:
+    """Restricted-client guard at the Slack/GitLab reader boundary: under an
+    outside model, every item that involves a restricted client (or can't be
+    checked) is withheld before the summary request is built, and a note
+    says so. The digest writes with HyperSpeed V2 only, so nothing is
+    withheld today; the boundary stays in place if that ever changes."""
+    from hyperclaw import client_guard
+    with client_guard.model_scope(provider):
+        for name, res in results.items():
+            if not res.ok:
+                continue
+            kept, n = client_guard.filter_items(res.items, name)
+            res.items = kept
+            if n:
+                res.notes.append(client_guard.message_note(n, name))
+    return results
+
+
+def run_digest(*, now: Optional[datetime] = None, scope: str = OWNER, registry=None,
+               client_factory: Optional[Callable] = None, http_client=None,
+               sleep=None) -> Outcome:
+    """Collect, summarize with V2, save as latest. Never raises a DigestError."""
+    if scope != OWNER:
+        return Outcome(False, failure_notice([Reason.NOT_OWNER]), TEXT[Reason.NOT_OWNER])
+    now = now or datetime.now(timezone.utc)
+    since = state.window_start(now)
+
+    def fail(reasons: list, sources: Optional[dict] = None) -> Outcome:
+        text = failure_notice(reasons)
+        state.record_run(now, False, text, reason=reasons[0].value, sources=sources)
+        return Outcome(False, text, "; ".join(TEXT[r] for r in reasons), sources or {})
+
+    if not state.connections():
+        return fail([Reason.NO_SOURCES])
+    try:
+        route = v2_route(registry)  # refuse before reading anything if V2 can't write it
+    except DigestError as e:
+        return fail([e.reason])
+
+    # v2_route only returns for HyperSpeed V2 (it raises for anything else).
+    prov = route[0] if isinstance(route, tuple) and route else None
+    results = guard_results(collect(now, since, client=http_client, sleep=sleep),
+                            getattr(prov, "name", "") or "hyperspeed")
+    sources = {n: ("ok" if r.ok else r.reason.value) for n, r in results.items()}
+    if not results or not any(r.ok for r in results.values()):
+        return fail([r.reason for r in results.values()] or [Reason.NO_SOURCES], sources)
+    try:
+        summary = summarize(results, f"the period since {_fmt_since(since)}",
+                            registry=registry, client_factory=client_factory)
+    except DigestError as e:
+        return fail([e.reason], sources)
+    text = "\n\n".join([f"Daily digest, {_fmt_day(now)} (since {_fmt_since(since)})",
+                        redact(summary), sources_line(results)])
+    state.record_run(now, True, text, sources=sources)
+    return Outcome(True, text, "", sources)
+
+
+# ── delivery ──────────────────────────────────────────────────────────────
+
+async def deliver(outcome: Outcome, send: Optional[Callable]) -> list:
+    """Send to the owner's Telegram chat(s) only. Returns the chat ids sent to.
+    The terminal copy is $HYPERCLAW_ROOT/digest/latest.txt (record_run)."""
+    sent = []
+    if not send or not (outcome.text or "").strip():
+        return sent
+    for chat_id in sorted(owner_ids("telegram")):
+        try:
+            if await send(int(chat_id), outcome.text):
+                sent.append(int(chat_id))
+        except Exception as e:
+            log.error("digest: Telegram delivery failed (%s)", type(e).__name__)
+    if not sent:
+        log.info("digest: no owner Telegram chat reached; saved to %s", state.latest_path())
+    return sent
+
+
+async def scheduled_run(send: Optional[Callable], **kw) -> Outcome:
+    """The connected_digest job body. Unexpected errors become the generic
+    notice; exception text never reaches a chat."""
+    try:
+        outcome = await asyncio.to_thread(lambda: run_digest(**kw))
+    except Exception as e:
+        log.error("digest: job failed (%s)", type(e).__name__, exc_info=True)
+        outcome = Outcome(False, GENERIC_FAILURE, "internal error")
+    await deliver(outcome, send)
+    return outcome
+
+
+# ── schedule gate / readiness / status ────────────────────────────────────
+
+def named_in_env() -> bool:
+    raw = os.environ.get("HYPERCLAW_SCHEDULER_JOBS", "")
+    return state.JOB_ID in {n.strip().lower() for n in raw.split(",")}
+
+
+def opted_in() -> bool:
+    return named_in_env() or state.opted_in_by_config()
+
+
+def ready(registry=None) -> tuple:
+    """(runnable, reason) for the scheduler: V2 configured + a source connected."""
+    try:
+        v2_route(registry)
+    except DigestError as e:
+        return False, e.text
+    if not state.connections():
+        return False, TEXT[Reason.NO_SOURCES]
+    return True, ""
+
+
+def status() -> dict:
+    from hyperclaw import unattended
+    data = state.load()
+    h, m = state.run_time()
+    return {
+        "connections": state.connections(),
+        "unattended": unattended.enabled(),
+        "opted_in": opted_in(),
+        "time": f"{h:02d}:{m:02d}",
+        "last_run": data.get("last_run", ""),
+        "last_result": data.get("last_result") or {},
+        "latest_path": str(state.latest_path()),
+    }

hyperclaw/digest/slack.py

@@ -0,0 +1,223 @@
+"""Slack collector: the owner's @mentions and DMs, read-only, own user token.
+
+Calls (GET): auth.test, search.messages, conversations.list,
+conversations.history, users.info (only when users:read is granted).
+See docs/CONNECTED-DIGEST.md §1 for the scope choice.
+"""
+from __future__ import annotations
+
+import os
+from datetime import datetime, timedelta
+from typing import Optional
+
+from hyperclaw.digest.errors import DigestError, Reason
+from hyperclaw.digest.http import ReadOnlyHttp, SourceResult, clip, log, parse_time
+from hyperclaw.digest.redact import redact
+from hyperclaw.taint import mark
+
+DEFAULT_API = "https://slack.com/api"
+API_ENV = "HYPERCLAW_DIGEST_SLACK_API"     # tests / Slack GovSlack only
+
+REQUIRED_SCOPES = frozenset({"search:read", "im:read", "im:history"})
+OPTIONAL_SCOPES = frozenset({"mpim:read", "mpim:history", "users:read"})
+
+MAX_MENTIONS = 50
+MAX_DM_CONVERSATIONS = 60
+MAX_DM_MESSAGES = 100
+MAX_PAGES = 10
+TEXT_CHARS = 400
+
+_EXPIRED = {"invalid_auth", "not_authed", "token_expired", "token_revoked",
+            "account_inactive"}
+
+
+def write_scopes(scopes) -> list:
+    """Scopes that are not read-only. Read-only = ends with ':read' or
+    ':history', or is 'identify'."""
+    bad = []
+    for s in scopes:
+        s = s.strip()
+        if not s:
+            continue
+        if s == "identify" or s.endswith(":read") or s.endswith(":history"):
+            continue
+        bad.append(s)
+    return sorted(bad)
+
+
+def is_user_token(token: str) -> bool:
+    t = token or ""
+    return t.startswith("xoxp-") or t.startswith("xoxe.xoxp-")
+
+
+class SlackCollector:
+    source = "slack"
+
+    def __init__(self, token: str, *, base_url: str = "", client=None, sleep=None):
+        if not is_user_token(token):
+            raise DigestError(Reason.SLACK_NOT_USER_TOKEN)
+        kw = {"client": client}
+        if sleep is not None:
+            kw["sleep"] = sleep
+        self.http = ReadOnlyHttp(base_url or os.environ.get(API_ENV, "") or DEFAULT_API,
+                                 {"Authorization": f"Bearer {token}"},
+                                 rate_limited=Reason.SLACK_RATE_LIMITED,
+                                 unreachable=Reason.SLACK_UNREACHABLE, **kw)
+        self.info: dict = {}
+        self._names: dict = {}
+
+    # ── API ───────────────────────────────────────────────────────────────
+    def _call(self, method: str, params: Optional[dict] = None):
+        resp = self.http.get(method, params)
+        if resp.status_code in (401, 403):
+            raise DigestError(Reason.SLACK_TOKEN_EXPIRED, f"HTTP {resp.status_code}")
+        try:
+            data = resp.json()
+        except ValueError:
+            raise DigestError(Reason.SLACK_UNREACHABLE, f"{method}: not JSON")
+        if not data.get("ok"):
+            err = str(data.get("error") or "")
+            if err in _EXPIRED:
+                raise DigestError(Reason.SLACK_TOKEN_EXPIRED, err)
+            if err == "missing_scope":
+                raise DigestError(Reason.SLACK_MISSING_SCOPE, f"{method}: {data.get('needed', '')}")
+            if err == "ratelimited":
+                raise DigestError(Reason.SLACK_RATE_LIMITED, method)
+            raise DigestError(Reason.SLACK_UNREACHABLE, f"{method}: {err}")
+        return data, resp
+
+    def verify(self) -> dict:
+        """auth.test + read-only scope check. Raises a named DigestError."""
+        data, resp = self._call("auth.test")
+        scopes = sorted({s.strip() for s in resp.headers.get("x-oauth-scopes", "").split(",")
+                         if s.strip()})
+        bad = write_scopes(scopes)
+        if bad:
+            raise DigestError(Reason.SLACK_WRITE_SCOPE, ",".join(bad))
+        missing = sorted(REQUIRED_SCOPES - set(scopes))
+        if missing:
+            raise DigestError(Reason.SLACK_MISSING_SCOPE, ",".join(missing))
+        self.info = {
+            "user_id": str(data.get("user_id") or ""),
+            "account": str(data.get("user") or ""),
+            "workspace": str(data.get("team") or ""),
+            "scopes": scopes,
+        }
+        return self.info
+
+    # ── collection ────────────────────────────────────────────────────────
+    def collect(self, since: datetime) -> SourceResult:
+        info = self.info or self.verify()
+        res = SourceResult(self.source, account=f"{info['account']} ({info['workspace']})")
+        self._mentions(info["user_id"], since, res)
+        self._dms(info["user_id"], since, set(info["scopes"]), res)
+        res.items = mark(res.items, "slack", "slack")   # connector content (hyperclaw.taint)
+        return res
+
+    def _name(self, user_id: str) -> str:
+        if not user_id:
+            return "someone"
+        if "users:read" not in set(self.info.get("scopes", ())):
+            return user_id
+        if user_id not in self._names:
+            try:
+                data, _ = self._call("users.info", {"user": user_id})
+                u = data.get("user") or {}
+                prof = u.get("profile") or {}
+                self._names[user_id] = (prof.get("display_name") or u.get("real_name")
+                                        or u.get("name") or user_id)
+            except DigestError as e:
+                if e.reason in (Reason.SLACK_TOKEN_EXPIRED, Reason.SLACK_RATE_LIMITED):
+                    raise
+                self._names[user_id] = user_id
+        return self._names[user_id]
+
+    def _mentions(self, uid: str, since: datetime, res: SourceResult) -> None:
+        day = (since - timedelta(days=1)).date().isoformat()
+        query = f"<@{uid}> after:{day}"
+        found = 0
+        page, pages = 1, 1
+        while page <= pages and page <= MAX_PAGES:
+            data, _ = self._call("search.messages", {"query": query, "sort": "timestamp",
+                                                      "sort_dir": "desc", "count": 100,
+                                                      "page": page})
+            msgs = data.get("messages") or {}
+            pages = int((msgs.get("paging") or {}).get("pages") or 1)
+            for m in msgs.get("matches") or []:
+                when = parse_time(m.get("ts"))
+                if not when or when < since:
+                    continue
+                if found >= MAX_MENTIONS:
+                    res.notes.append(f"More than {MAX_MENTIONS} mentions; the oldest are not shown.")
+                    return
+                ch = m.get("channel") or {}
+                where = "a DM" if ch.get("is_im") else (f"#{ch.get('name')}" if ch.get("name")
+                                                        else "a conversation")
+                res.items.append({
+                    "kind": "mention", "where": where,
+                    "from": m.get("username") or self._name(m.get("user", "")),
+                    "when": when.isoformat(timespec="minutes"),
+                    "text": redact(clip(m.get("text", ""), TEXT_CHARS)),
+                    "link": m.get("permalink", ""),
+                })
+                found += 1
+            page += 1
+
+    def _conversations(self, types: str) -> list:
+        out, cursor = [], ""
+        for _ in range(MAX_PAGES):
+            params = {"types": types, "limit": 200, "exclude_archived": "true"}
+            if cursor:
+                params["cursor"] = cursor
+            data, _ = self._call("conversations.list", params)
+            out.extend(data.get("channels") or [])
+            cursor = ((data.get("response_metadata") or {}).get("next_cursor") or "").strip()
+            if not cursor or len(out) >= MAX_DM_CONVERSATIONS:
+                break
+        if len(out) > MAX_DM_CONVERSATIONS:
+            out = out[:MAX_DM_CONVERSATIONS]
+        return out
+
+    def _dms(self, uid: str, since: datetime, scopes: set, res: SourceResult) -> None:
+        types = "im"
+        if {"mpim:read", "mpim:history"} <= scopes:
+            types = "im,mpim"
+        else:
+            res.notes.append("Group DMs were not read (the token has no mpim:read/mpim:history).")
+        convs = self._conversations(types)
+        if len(convs) >= MAX_DM_CONVERSATIONS:
+            res.notes.append(f"Only the first {MAX_DM_CONVERSATIONS} DM conversations were checked.")
+        count = 0
+        for conv in convs:
+            cid = conv.get("id")
+            if not cid:
+                continue
+            is_group = bool(conv.get("is_mpim"))
+            cursor = ""
+            for _ in range(MAX_PAGES):
+                params = {"channel": cid, "oldest": f"{since.timestamp():.6f}", "limit": 100}
+                if cursor:
+                    params["cursor"] = cursor
+                data, _ = self._call("conversations.history", params)
+                for m in data.get("messages") or []:
+                    if m.get("subtype") or m.get("user") == uid:
+                        continue      # joins/bots/edits, and the owner's own messages
+                    when = parse_time(m.get("ts"))
+                    if not when or when < since:
+                        continue
+                    if count >= MAX_DM_MESSAGES:
+                        res.notes.append(f"More than {MAX_DM_MESSAGES} DM messages; the rest are not shown.")
+                        return
+                    res.items.append({
+                        "kind": "group_dm" if is_group else "dm",
+                        "from": self._name(m.get("user", "")),
+                        "when": when.isoformat(timespec="minutes"),
+                        "text": redact(clip(m.get("text", ""), TEXT_CHARS)),
+                    })
+                    count += 1
+                cursor = ((data.get("response_metadata") or {}).get("next_cursor") or "").strip()
+                if not cursor or not data.get("has_more", bool(cursor)):
+                    break
+
+    def close(self) -> None:
+        self.http.close()