taskboy 0.1.1__py3-none-any.whl

taskboy/adapters/github_api.py

@@ -0,0 +1,564 @@
+"""github pull-request operations as permission-aware in-process mcp tools (TOL-001/004/005/006/007).
+
+credentials never reach the model or the task env: every call fetches a fresh broker token.
+writes are idempotent (check github, and the artifacts table where github can't tell — ORC-012),
+recorded as artifacts, and bounded before entering model context. git itself (clone/commit/
+push) stays in Bash via the credential helper; these tools cover the api surface.
+"""
+
+import json
+import logging
+import re
+
+from taskboy.adapters._util import OUTPUT_LIMIT, _error, _text, wrap
+from taskboy.models import Task
+from taskboy.redact import redactor
+from taskboy.store import Store
+
+logger = logging.getLogger("taskboy.github")
+
+GITHUB_API = "https://api.github.com"
+ALLOWED_REVIEW_EVENTS = {"COMMENT", "REQUEST_CHANGES"}  # APPROVE is added per-task for the reviewing persona (issue #75)
+TAG_RE = re.compile(r"^v\d+\.\d+\.\d+$")
+BRANCH_ALREADY_GONE = {404, 422}  # github's "ref does not exist" statuses for a missing branch
+COMMENT_PREVIEW_CHARS = 400
+COMMENT_PREVIEW_MARKER = " …(truncated)"
+
+
+class GitHubStatusError(RuntimeError):
+    """carries the http status (and optional Retry-After) so callers can special-case specific failures
+    (e.g. a missing ref, or a secondary rate limit) without reparsing the message string."""
+
+    def __init__(self, status: int, message: str, retry_after: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.retry_after = retry_after
+
+
+class GitHubAdapter:
+    def __init__(self, broker, store: Store, task: Task, approved_repos: list[str], on_milestone=None, main_broker=None, reviewer_broker=None, bot_name: str = "Agent", other_bot_name: str = "Reviewer", can_approve: bool = False):
+        self.broker = broker
+        self.store = store
+        self.task = task
+        self.approved_repos = approved_repos
+        self.on_milestone = on_milestone  # async (message) -> None; artifact auto-milestones (SLK-006)
+        self.main_broker = main_broker
+        self.bot_brokers = [bot_broker for bot_broker in (main_broker, reviewer_broker) if bot_broker is not None]
+        self.bot_name = bot_name
+        self.other_bot_name = other_bot_name
+        self.can_approve = can_approve
+
+    # -- tools -------------------------------------------------------------------
+
+    async def create_pull_request(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        head = str(args.get("head", "")).strip()
+        base = str(args.get("base", "")).strip() or "main"
+        if not head:
+            return _error("head branch is required")
+
+        # idempotency check: github's own open-pr-by-head state is authoritative, so a retry after
+        # close_pull_request or a crash-after-create just finds no open pr and proceeds (issue #113).
+        owner = repo.split("/", 1)[0]
+        existing = await self._request("GET", f"/repos/{repo}/pulls?head={owner}:{head}&state=open")
+        if existing:
+            pr = existing[0]
+            self._record_pr(repo, pr)
+            return _text(f"an open pull request already exists for branch {head}: {pr['html_url']} — update it instead of creating another")
+
+        body = str(args.get("body", "")).rstrip() + f"\n\n---\nRequested via Slack — taskboy task `{self.task.task_id}`."
+        pr = await self._request("POST", f"/repos/{repo}/pulls", {"title": str(args.get("title", "")), "head": head, "base": base, "body": body})
+        self._record_pr(repo, pr)
+        self.store.add_artifact(self.task.task_id, "branch", f"{repo}:{head}")
+        if self.on_milestone:
+            await self.on_milestone(f"Opened pull request {pr['html_url']}")
+        return _text(f"created pull request #{pr['number']}: {pr['html_url']}")
+
+    async def get_pull_request(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        pr = await self._request("GET", f"/repos/{repo}/pulls/{int(args['number'])}")
+        trimmed = {key: pr.get(key) for key in ("number", "title", "state", "html_url", "user", "body", "head", "base", "mergeable_state", "changed_files", "additions", "deletions", "draft", "created_at", "updated_at")}
+        trimmed["user"] = (pr.get("user") or {}).get("login")
+        trimmed["body"] = str(pr.get("body") or "")[:2000]
+        trimmed["head"] = (pr.get("head") or {}).get("ref")
+        trimmed["head_sha"] = (pr.get("head") or {}).get("sha")
+        trimmed["base"] = (pr.get("base") or {}).get("ref")
+        trimmed["requested_reviewers"] = [(reviewer or {}).get("login") for reviewer in pr.get("requested_reviewers") or []]
+        return _text(json.dumps(trimmed))
+
+    async def list_pull_requests(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        state = str(args.get("state") or "open").lower()
+        if state not in {"open", "closed", "all"}:
+            return _error("state must be open, closed, or all")
+        pulls = await self._request("GET", f"/repos/{repo}/pulls?state={state}&per_page=100&sort=created&direction=desc")
+        lines = []
+        for pr in pulls:
+            status = str(pr.get("state") or "") + (", draft" if pr.get("draft") else "")
+            lines.append(f"#{pr.get('number')} [{status}] {(pr.get('user') or {}).get('login')}: {pr.get('title')} (head {str((pr.get('head') or {}).get('sha') or '')[:7]}, updated {pr.get('updated_at')})")
+        return _text("\n".join(lines) or "no pull requests")
+
+    async def list_pr_files(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        number = int(args["number"])
+        page = max(int(args.get("page") or 1), 1)
+        files = await self._request("GET", f"/repos/{repo}/pulls/{number}/files?per_page=10&page={page}")
+        headers = []
+        patches = []
+        for item in files:
+            header = f"--- {item.get('filename')} ({item.get('status')}, +{item.get('additions', 0)}/-{item.get('deletions', 0)})"
+            headers.append(header)
+            patch = str(item.get("patch") or "")
+            if len(patch) > 1500:
+                marker = "\n…(patch truncated — fetch the full diff with git)"
+                patch = patch[: 1500 - len(marker)] + marker
+            if patch:
+                patches.append(f"patch for {item.get('filename')}:\n{patch}")
+        sections = headers + (["", "patches:", *patches] if patches else [])
+        return _text("\n".join(sections) or "no files")
+
+    async def list_pr_comments(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        number = int(args["number"])
+        offset = max(int(args.get("offset", 0) or 0), 0)
+        comment_id_raw = args.get("comment_id")
+        author = str(args.get("author") or "").strip().lower()
+        if author == "me":
+            own_login, login_error = await self._resolve_own_login()
+            if login_error or not own_login:
+                return _error(f"cannot resolve your own login for author='me' ({login_error})")
+            author = own_login
+        issue_comments = await self._paginated(f"/repos/{repo}/issues/{number}/comments")
+        review_comments = await self._paginated(f"/repos/{repo}/pulls/{number}/comments")
+
+        if comment_id_raw is not None:
+            return self._one_comment(int(comment_id_raw), issue_comments, review_comments, offset)
+
+        resolution_by_comment: dict[int, bool] = {}
+        try:
+            for thread in await self._review_threads(repo, number):
+                for comment in (thread.get("comments") or {}).get("nodes") or []:
+                    comment_id = comment.get("databaseId")
+                    if comment_id is not None:
+                        resolution_by_comment[int(comment_id)] = bool(thread.get("isResolved"))
+        except Exception:
+            logger.debug("could not annotate review thread status for %s#%s", repo, number, exc_info=True)
+        # combine before sorting so "newest-appearing-last" holds across both kinds, not just within each
+        combined = [("issue", comment) for comment in issue_comments] + [("review", comment) for comment in review_comments]
+        combined.sort(key=lambda item: str(item[1].get("created_at") or ""))
+        lines = []
+        for kind, comment in combined:
+            comment_id_value = comment.get("id")
+            comment_resolution = resolution_by_comment.get(int(comment_id_value)) if comment_id_value is not None else None
+            comment_author = str((comment.get("user") or {}).get("login") or "")
+            if author and comment_author.lower() != author:
+                continue
+            status = ""
+            if kind == "review" and comment_resolution is not None:
+                status = " (resolved)" if comment_resolution else " (unresolved)"
+            location = self._review_comment_location(comment) if kind == "review" else ""
+            label = f"{kind}, {location}" if location else kind
+            body = str(comment.get("body", ""))
+            preview = body[:COMMENT_PREVIEW_CHARS] + (COMMENT_PREVIEW_MARKER if len(body) > COMMENT_PREVIEW_CHARS else "")
+            lines.append(f"[{comment.get('id')}] [{comment.get('created_at')}] {comment_author} ({label}): {preview}{status}")
+        if not lines:
+            total = len(issue_comments) + len(review_comments)
+            return _text("no comments" if not total else f"no comments matched the filters (there are {total} in total)")
+        # tail_fit always favors the newest lines, so offset skips from the newest end too — otherwise
+        # a caller paging with offset would keep landing back on the same tail-fitted chunk
+        selected = lines[: max(len(lines) - offset, 0)]
+        if not selected:
+            return _text(f"no comments past offset {offset} (there are {len(lines)} in total)")
+        return _text(self._tail_fit(selected, offset))
+
+    @staticmethod
+    def _tail_fit(selected: list[str], offset: int) -> str:
+        """newest lines win when the output cap bites, so the latest comments aren't the ones dropped."""
+        joined = "\n".join(selected)
+        if len(joined) <= OUTPUT_LIMIT:
+            return joined
+        reserve = 120  # room for the "earlier comments not shown" marker below
+        kept: list[str] = []
+        used = 0
+        for line in reversed(selected):
+            used += len(line) + (1 if kept else 0)
+            if used > OUTPUT_LIMIT - reserve:
+                break
+            kept.insert(0, line)
+        dropped = len(selected) - len(kept)
+        # next page must skip what offset already skipped plus what we just showed
+        next_offset = offset + len(kept)
+        marker = f"…({dropped} earlier comment(s) not shown — pass offset={next_offset} to see them, or narrow with author/comment_id)\n"
+        return marker + "\n".join(kept)
+
+    def _one_comment(self, comment_id: int, issue_comments: list[dict], review_comments: list[dict], body_offset: int) -> dict:
+        """offset is chars into the body, not a comment index."""
+        for kind, comments in (("issue", issue_comments), ("review", review_comments)):
+            for comment in comments:
+                if comment.get("id") == comment_id:
+                    author = (comment.get("user") or {}).get("login")
+                    prefix = f"[{comment.get('id')}] [{comment.get('created_at')}] {author} ({kind}): "
+                    body = str(comment.get("body") or "")
+                    return _text(self._paged_text(prefix, body, body_offset))
+        return _error(f"comment {comment_id} was not found on this pull request (checked both issue and review comments)")
+
+    @staticmethod
+    def _paged_text(prefix: str, body: str, offset: int) -> str:
+        if body and offset >= len(body):
+            return f"{prefix}(no content past offset {offset} — this comment's body is {len(body)} chars long)"
+        remaining = body[offset:]
+        available = OUTPUT_LIMIT - len(prefix)
+        if len(remaining) <= available:
+            return prefix + remaining
+        reserve = 80  # room for the continuation marker below, sized generously for its numbers
+        chunk = remaining[: max(available - reserve, 0)]
+        end = offset + len(chunk)
+        marker = f"\n…(showing chars {offset}-{end} of {len(body)} — pass offset={end} to continue)"
+        return prefix + chunk + marker
+
+    async def comment_on_pull_request(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        number = int(args["number"])
+        comment = await self._request("POST", f"/repos/{repo}/issues/{number}/comments", {"body": str(args.get("body", ""))})
+        self.store.add_artifact(self.task.task_id, "pr_comment", f"{repo}#{number}/comment/{comment['id']}", comment.get("html_url"))
+        return _text(f"commented: {comment.get('html_url')}")
+
+    async def create_pr_review(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        event = str(args.get("event", "COMMENT")).upper()
+        allowed_events = ALLOWED_REVIEW_EVENTS | ({"APPROVE"} if self.can_approve else set())
+        if event not in allowed_events:
+            return _error(f"review event {event!r} is not permitted; use {' or '.join(sorted(allowed_events))}")
+        number = int(args["number"])
+        # the follow-up loop only acts on REQUEST_CHANGES/APPROVE, so the reviewing persona's APPROVE and COMMENT both hinge on authorship (issue #75)
+        if self.can_approve and event in ("APPROVE", "COMMENT"):
+            main_login, lookup_error = await self._resolve_main_login()
+            if main_login is None and event == "APPROVE":
+                return _error(f"cannot verify pull request authorship — main-agent identity lookup unavailable ({lookup_error})")
+            # COMMENT fails open on a lookup blip — blocking the reviewer's reviews of human prs is worse than one unenforced comment
+            if main_login is not None:
+                pr = await self._request("GET", f"/repos/{repo}/pulls/{number}")
+                author_login = str((pr.get("user") or {}).get("login") or "").lower()
+                if event == "APPROVE" and author_login != main_login:
+                    return _error(f"APPROVE is only permitted on pull requests authored by {self.other_bot_name} — it's the review loop's exit signal (issue #75), not a general human-PR approval")
+                if event == "COMMENT" and author_login == main_login:
+                    return _error(f"COMMENT is not permitted on pull requests authored by {self.other_bot_name} — use REQUEST_CHANGES or APPROVE so the review loop can act on the outcome")
+        payload: dict = {"body": str(args.get("body", "")), "event": event}
+        comments_json = str(args.get("comments_json") or "").strip()
+        if comments_json:
+            try:
+                comments = json.loads(comments_json)
+            except json.JSONDecodeError:
+                return _error("comments_json must be valid json")
+            if not isinstance(comments, list):
+                return _error("comments_json must be a list of path, line, and body objects")
+            normalized = []
+            for comment in comments:
+                if not isinstance(comment, dict) or not isinstance(comment.get("path"), str) or not isinstance(comment.get("line"), int) or not isinstance(comment.get("body"), str):
+                    return _error("comments_json must be a list of path, line, and body objects")
+                normalized.append({"path": comment["path"], "line": comment["line"], "body": comment["body"], "side": str(comment.get("side") or "RIGHT")})
+            payload["comments"] = normalized
+        review = await self._request("POST", f"/repos/{repo}/pulls/{number}/reviews", payload)
+        self.store.add_artifact(self.task.task_id, "pr_comment", f"{repo}#{number}/review/{review['id']}", review.get("html_url"))
+        return _text(f"posted {event} review on {repo}#{number}")
+
+    async def reply_to_pr_comment(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        number = int(args["number"])
+        reply = await self._request("POST", f"/repos/{repo}/pulls/{number}/comments/{int(args['comment_id'])}/replies", {"body": str(args.get("body", ""))})
+        self.store.add_artifact(self.task.task_id, "pr_comment", f"{repo}#{number}/comment/{reply['id']}", reply.get("html_url"))
+        return _text(f"replied: {reply.get('html_url')}")
+
+    async def close_pull_request(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        number = int(args["number"])
+        pr = await self._request("GET", f"/repos/{repo}/pulls/{number}")
+        if pr.get("state") == "closed":
+            return _text(f"pull request #{number} is already closed: {pr.get('html_url')}")
+        pr = await self._request("PATCH", f"/repos/{repo}/pulls/{number}", {"state": "closed"})
+        if self.on_milestone:
+            await self.on_milestone(f"Closed pull request {pr['html_url']}")
+        return _text(f"closed pull request #{number}: {pr['html_url']}")
+
+    async def delete_branch(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        branch = str(args.get("branch", "")).strip()
+        if branch.startswith("refs/heads/"):
+            branch = branch[len("refs/heads/") :]
+        if not branch:
+            return _error("branch is required")
+        if not branch.startswith("agent/"):
+            return _error("only agent/-prefixed branches can be deleted")
+        try:
+            await self._request("DELETE", f"/repos/{repo}/git/refs/heads/{branch}")
+        except GitHubStatusError as status_error:
+            if status_error.status not in BRANCH_ALREADY_GONE:
+                raise
+            return _text(f"branch {branch} in {repo} is already deleted")
+        return _text(f"deleted branch {branch} from {repo}")
+
+    async def create_release(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        tag_name = str(args.get("tag_name", "")).strip()
+        if not TAG_RE.match(tag_name):
+            return _error("tag_name must look like vX.Y.Z (e.g. v1.4.0)")
+        body = str(args.get("body", "")).strip()
+        if not body:
+            return _error("body (release notes) is required")
+        # idempotency layer 1: we already published this tag's release (ORC-012)
+        for artifact in self.store.artifacts_for(self.task.task_id):
+            if artifact["kind"] == "release" and artifact["external_id"] == f"{repo}@{tag_name}":
+                return _text(f"a release for {tag_name} already exists: {artifact['url']} — nothing to do")
+        payload = {"tag_name": tag_name, "name": str(args.get("name", "")).strip() or tag_name, "body": body}
+        target_commitish = str(args.get("target_commitish", "")).strip()
+        if target_commitish:
+            payload["target_commitish"] = target_commitish
+        # idempotency layer 2: github rejects an already-cut tag with 422; treat that as done rather than surfacing a raw api error (crash-after-create window)
+        try:
+            release = await self._request("POST", f"/repos/{repo}/releases", payload)
+        except GitHubStatusError as exc:
+            if exc.status == 422:
+                return _text(f"a release for {tag_name} already exists on {repo} — nothing to do")
+            raise
+        self.store.add_artifact(self.task.task_id, "release", f"{repo}@{tag_name}", release.get("html_url"))
+        if self.on_milestone:
+            await self.on_milestone(f"Published release {tag_name}: {release['html_url']}")
+        return _text(f"created release {tag_name}: {release['html_url']}")
+
+    async def resolve_pr_thread(self, args: dict) -> dict:
+        repo, error = self._check_repo(args)
+        if error:
+            return error
+        known_logins, unresolved = await self._resolve_bot_logins()
+        detail = f" ({'; '.join(unresolved)})" if unresolved else ""
+        if not known_logins:
+            return _error(f"cannot verify thread authorship — resolution unavailable for this task{detail}")
+        number = int(args["number"])
+        comment_id = int(args["comment_id"])
+        thread = next(
+            (thread for thread in await self._review_threads(repo, number) if any(comment.get("databaseId") == comment_id for comment in ((thread.get("comments") or {}).get("nodes") or []))),
+            None,
+        )
+        if thread is None:
+            return _error("comment id was not found in this pull request's review threads; pass a review-comment id from list_pr_comments")
+        comments = (thread.get("comments") or {}).get("nodes") or []
+        root_login = str((((comments[0] if comments else {}).get("author") or {}).get("login")) or "")
+        if root_login.lower() not in known_logins:
+            # a partly-degraded identity lookup can still refuse one of our own threads, so name the failure here too
+            return _error(f"only review threads started by {self.bot_name} or {self.other_bot_name} can be resolved{detail}")
+        if thread.get("isResolved"):
+            return _text(f"review thread for comment {comment_id} on {repo}#{number} is already resolved")
+        data = await self._graphql(
+            """mutation ResolveReviewThread($id: ID!) {
+  resolveReviewThread(input: {threadId: $id}) { thread { isResolved } }
+}""",
+            {"id": thread["id"]},
+        )
+        if not (((data.get("resolveReviewThread") or {}).get("thread") or {}).get("isResolved")):
+            raise RuntimeError("github did not confirm that the review thread was resolved")
+        return _text(f"resolved review thread for comment {comment_id} on {repo}#{number}")
+
+    # -- plumbing ------------------------------------------------------------------
+
+    async def _resolve_main_login(self) -> tuple[str | None, str | None]:
+        """the main agent's login, resolved lazily like `_resolve_bot_logins` (#72) — used to gate APPROVE to agent-authored PRs."""
+        if self.main_broker is None:
+            return None, "no main-agent broker configured for this task"
+        return await self._resolve_login_for(self.main_broker)
+
+    async def _resolve_own_login(self) -> tuple[str | None, str | None]:
+        """the acting persona's own login — `self.broker` is whichever bot is running this task — for `author: "me"` in `list_pr_comments`."""
+        return await self._resolve_login_for(self.broker)
+
+    @staticmethod
+    async def _resolve_login_for(broker) -> tuple[str | None, str | None]:
+        """shared by `_resolve_main_login` and `_resolve_own_login`, which differ only in which broker they read."""
+        try:
+            return f"{await broker.app_slug()}[bot]".lower(), None
+        except Exception as exc:
+            return None, str(exc)
+
+    async def _resolve_bot_logins(self) -> tuple[set[str], list[str]]:
+        """logins for either persona, resolved lazily because a build-time snapshot can be permanently incomplete (#72)."""
+        logins: set[str] = set()
+        errors: list[str] = []
+        for broker in self.bot_brokers:
+            try:
+                # the bare app slug, which is how graphql reports a bot author — REST's "{slug}[bot]" shape is not used here
+                logins.add((await broker.app_slug()).lower())
+            except Exception as exc:
+                errors.append(str(exc))
+        return logins, errors
+
+    def _review_comment_location(self, comment: dict) -> str:
+        path = comment["path"]
+        # line goes null once the diff position goes stale, hence the original_line fallback
+        line = comment.get("line") or comment.get("original_line")
+        location = f"{path}:{line}" if line else path
+        in_reply_to = comment.get("in_reply_to_id")
+        return f"{location}, reply-to {in_reply_to}" if in_reply_to is not None else location
+
+    def _check_repo(self, args: dict) -> tuple[str, dict | None]:
+        repo = str(args.get("repo", "")).strip()
+        if repo not in self.approved_repos:
+            return repo, _error(f"repository {repo!r} is not on the approved list {self.approved_repos}")
+        return repo, None
+
+    def _record_pr(self, repo: str, pr: dict) -> None:
+        self.store.add_artifact(self.task.task_id, "pull_request", f"{repo}#{pr['number']}", pr.get("html_url"))
+
+    async def _paginated(self, path: str) -> list[dict]:
+        """github defaults to 30 items/page; page through at 100 until a short page ends the walk."""
+        items: list[dict] = []
+        page = 1
+        while True:
+            batch = await self._request("GET", f"{path}?per_page=100&page={page}") or []
+            items.extend(batch)
+            if len(batch) < 100:
+                return items
+            page += 1
+
+    async def _request(self, method: str, path: str, payload: dict | None = None):
+        """the http seam — patched in unit tests. token fetched per call, never stored (TOL-007)."""
+        import aiohttp
+
+        token = await self.broker.token_for_task(self.task.task_id)
+        headers = {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"}
+        async with aiohttp.ClientSession() as session:
+            async with session.request(method, GITHUB_API + path, json=payload, headers=headers) as response:
+                if response.status >= 300:
+                    body = redactor.redact(await response.text())[:300]
+                    retry_after = response.headers.get("Retry-After")
+                    raise GitHubStatusError(response.status, f"github api {method} {path} failed: {response.status} — {body}", retry_after=retry_after)
+                if response.status == 204:
+                    return None
+                return await response.json()
+
+    async def _graphql(self, query: str, variables: dict) -> dict:
+        """the graphql http seam — patched separately in unit tests."""
+        import aiohttp
+
+        token = await self.broker.token_for_task(self.task.task_id)
+        headers = {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"}
+        async with aiohttp.ClientSession() as session:
+            async with session.post(GITHUB_API + "/graphql", json={"query": query, "variables": variables}, headers=headers) as response:
+                if response.status >= 300:
+                    raise RuntimeError(redactor.redact(f"github graphql failed: {response.status}"))
+                payload = await response.json()
+                if payload.get("errors"):
+                    raise RuntimeError(redactor.redact(f"github graphql failed: {json.dumps(payload['errors'])}"))
+                return payload.get("data") or {}
+
+    async def _review_threads(self, repo: str, number: int) -> list[dict]:
+        owner, name = repo.split("/", 1)
+        nodes: list[dict] = []
+        cursor = None
+        while True:
+            data = await self._graphql(
+                """query ReviewThreads($owner: String!, $name: String!, $number: Int!, $after: String) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: 100, after: $after) {
+        nodes {
+          id
+          isResolved
+          comments(first: 100) { nodes { databaseId author { login } } }
+        }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+  }
+}""",
+                {"owner": owner, "name": name, "number": number, "after": cursor},
+            )
+            review_threads = (((data.get("repository") or {}).get("pullRequest") or {}).get("reviewThreads")) or {}
+            nodes.extend(review_threads.get("nodes") or [])
+            page_info = review_threads.get("pageInfo") or {}
+            cursor = page_info.get("endCursor")
+            if not page_info.get("hasNextPage") or not cursor:
+                return nodes
+
+
+def build_github_server(adapter: GitHubAdapter):
+    """expose the adapter as mcp tools; names become mcp__github__<name> in allowed_tools."""
+    from claude_agent_sdk import create_sdk_mcp_server, tool
+
+    tools = [
+        tool("create_pull_request", "Create a pull request. Include a Summary, Testing performed, and Known limitations in the body.", {"repo": str, "title": str, "head": str, "base": str, "body": str})(wrap(adapter.create_pull_request, logger)),
+        tool("get_pull_request", "Get one pull request's metadata.", {"repo": str, "number": int})(wrap(adapter.get_pull_request, logger)),
+        tool(
+            "list_pull_requests",
+            "List pull requests in a repository. State defaults to open and may be open, closed, or all.",
+            {"type": "object", "properties": {"repo": {"type": "string"}, "state": {"type": "string"}}, "required": ["repo"]},
+        )(wrap(adapter.list_pull_requests, logger)),
+        tool(
+            "list_pr_files",
+            "List changed files and bounded patches for a pull request, 10 per page. Fetch full diffs with git.",
+            {"type": "object", "properties": {"repo": {"type": "string"}, "number": {"type": "integer"}, "page": {"type": "integer"}}, "required": ["repo", "number"]},
+        )(wrap(adapter.list_pr_files, logger)),
+        tool(
+            "list_pr_comments",
+            f"List comments and review comments on a pull request, newest-appearing-last, bodies previewed at {COMMENT_PREVIEW_CHARS} chars. Optional author filter narrows the list and combines with offset; pass comment_id instead to page that one comment's body.",
+            {
+                "type": "object",
+                "properties": {
+                    "repo": {"type": "string"},
+                    "number": {"type": "integer"},
+                    "offset": {"type": "integer", "description": "if truncated, skip this many of the most-recently-shown comments (the truncation marker gives the right value); with comment_id, this is characters into that body to resume from instead"},
+                    "author": {"type": "string", "description": 'login, exact match; pass "me" for the acting persona\'s own login'},
+                    "comment_id": {"type": "integer", "description": "page this one comment's body (issue or review) instead of a filtered list; ignores author"},
+                },
+                "required": ["repo", "number"],
+            },
+        )(wrap(adapter.list_pr_comments, logger)),
+        tool("comment_on_pull_request", "Post a comment on a pull request.", {"repo": str, "number": int, "body": str})(wrap(adapter.comment_on_pull_request, logger)),
+        tool(
+            "create_pr_review",
+            "Post a review (COMMENT or REQUEST_CHANGES, and APPROVE for the reviewing persona) on a pull request, optionally with inline comments_json.",
+            {
+                "type": "object",
+                "properties": {"repo": {"type": "string"}, "number": {"type": "integer"}, "body": {"type": "string"}, "event": {"type": "string"}, "comments_json": {"type": "string"}},
+                "required": ["repo", "number", "body", "event"],
+            },
+        )(wrap(adapter.create_pr_review, logger)),
+        tool("reply_to_pr_comment", "Reply to a specific pull request review comment.", {"repo": str, "number": int, "comment_id": int, "body": str})(wrap(adapter.reply_to_pr_comment, logger)),
+        tool(
+            "resolve_pr_thread",
+            f"Resolve a pull request review thread, identified by any review comment id in it. Only threads started by {adapter.bot_name} or {adapter.other_bot_name} can be resolved; use it once the thread's finding is verifiably fixed.",
+            {"repo": str, "number": int, "comment_id": int},
+        )(wrap(adapter.resolve_pr_thread, logger)),
+        tool("close_pull_request", "Close a pull request without merging it. Idempotent — already-closed pull requests are reported, not re-closed.", {"repo": str, "number": int})(wrap(adapter.close_pull_request, logger)),
+        tool("delete_branch", "Delete a branch. Only agent/-prefixed branches can be deleted; protected and default branches are refused.", {"repo": str, "branch": str})(wrap(adapter.delete_branch, logger)),
+        tool(
+            "create_release",
+            "Create a GitHub release with a new tag (vX.Y.Z) and release notes. The tag is created from target_commitish (default branch when omitted); name defaults to the tag.",
+            {
+                "type": "object",
+                "properties": {"repo": {"type": "string"}, "tag_name": {"type": "string"}, "body": {"type": "string"}, "name": {"type": "string"}, "target_commitish": {"type": "string"}},
+                "required": ["repo", "tag_name", "body"],
+            },
+        )(wrap(adapter.create_release, logger)),
+    ]
+    return create_sdk_mcp_server(name="github", version="1.0.0", tools=tools)