@senad-d/branchme 0.3.6 → 0.3.9

package/src/github-feedback.ts

@@ -0,0 +1,252 @@
+import {
+  GITHUB_API_BASE_URL, GITHUB_GRAPHQL_TIMEOUT_MS, GITHUB_JOB_LOG_TIMEOUT_MS, PULL_REQUEST_FEEDBACK_BODY_LIMIT_CHARS,
+  PULL_REQUEST_FEEDBACK_LOG_JOB_LIMIT, PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS, PULL_REQUEST_FEEDBACK_LOG_TAIL_BYTES,
+  PULL_REQUEST_FEEDBACK_LOG_TAIL_LINES, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES, PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS,
+} from "./constants.ts";
+import {
+  encodePathSegment, fetchGitHubResponse, gitHubJsonHeaders, isRecord, parseGitHubJson, pullRequestNumberField,
+  readBoundedResponseText, requireFetchImplementation, requireGitHubResponseObject, validateGitHubRepository,
+  type PullRequestFetchOptions,
+} from "./github.ts";
+import { redactSecrets } from "./redaction.ts";
+import type {
+  GitHubRepository, PullRequestFeedbackCheck, PullRequestFeedbackComment, PullRequestFeedbackDetails,
+  PullRequestFeedbackReview, PullRequestFeedbackThread,
+} from "./types.ts";
+
+// One GraphQL request reads review threads with their resolution state, review summaries, conversation
+// comments and the head commit's check rollup; REST has no thread resolution state.
+const FEEDBACK_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      number url headRefOid
+      reviewThreads(first: 100) { totalCount nodes { isResolved isOutdated path line comments(first: 20) { nodes { author { login } body url } } } }
+      reviews(last: 50) { nodes { author { login } state body url } }
+      comments(last: 50) { totalCount nodes { author { login } body url } }
+      commits(last: 1) { nodes { commit { statusCheckRollup { state contexts(first: 100) { totalCount nodes {
+        __typename
+        ... on CheckRun { name conclusion databaseId detailsUrl }
+        ... on StatusContext { context state targetUrl }
+      } } } } } }
+    }
+  }
+}`;
+
+const FAILING_CHECK_CONCLUSIONS = new Set(["FAILURE", "TIMED_OUT", "STARTUP_FAILURE", "ACTION_REQUIRED", "CANCELLED"]);
+const FAILING_STATUS_STATES = new Set(["FAILURE", "ERROR"]);
+const ANSI_ESCAPE_PATTERN = /\u001b\[[0-9;]*[A-Za-z]/gu;
+const LOG_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z ?/u;
+const UNSAFE_TEXT_PATTERN = /[\p{Cc}\p{Cf}\u2028\u2029]/gu;
+
+function safeText(value: unknown, token: string, limit: number): string {
+  if (typeof value !== "string") return "";
+  const text = redactSecrets(value, [token]).replace(UNSAFE_TEXT_PATTERN, (character) => (character === "\n" ? "\n" : " ")).trim();
+  return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+
+function nodes(connection: unknown): Record<string, unknown>[] {
+  if (!isRecord(connection) || !Array.isArray(connection.nodes)) return [];
+  return connection.nodes.filter(isRecord);
+}
+
+function totalCount(connection: unknown): number {
+  return isRecord(connection) && typeof connection.totalCount === "number" ? connection.totalCount : 0;
+}
+
+function parseComment(node: Record<string, unknown>, token: string): PullRequestFeedbackComment {
+  const author = isRecord(node.author) ? safeText(node.author.login, token, 100) : "";
+  return {
+    author: author || "ghost",
+    body: safeText(node.body, token, PULL_REQUEST_FEEDBACK_BODY_LIMIT_CHARS),
+    url: safeText(node.url, token, 300),
+  };
+}
+
+function parseThreads(connection: unknown, token: string): Pick<PullRequestFeedbackDetails, "unresolvedThreads" | "resolvedThreadCount" | "outdatedThreadCount"> {
+  const unresolvedThreads: PullRequestFeedbackThread[] = [];
+  let resolvedThreadCount = 0;
+  let outdatedThreadCount = 0;
+  for (const thread of nodes(connection)) {
+    if (thread.isResolved === true) resolvedThreadCount += 1;
+    else if (thread.isOutdated === true) outdatedThreadCount += 1;
+    else {
+      unresolvedThreads.push({
+        path: safeText(thread.path, token, 300),
+        line: typeof thread.line === "number" ? thread.line : null,
+        comments: nodes(thread.comments).map((comment) => parseComment(comment, token)),
+      });
+    }
+  }
+  return { unresolvedThreads, resolvedThreadCount, outdatedThreadCount };
+}
+
+function parseReviews(connection: unknown, token: string): PullRequestFeedbackReview[] {
+  return nodes(connection)
+    .map((review) => ({ ...parseComment(review, token), state: safeText(review.state, token, 40) }))
+    .filter((review) => review.body !== "" || review.state === "CHANGES_REQUESTED");
+}
+
+function parseCheck(node: Record<string, unknown>, token: string): PullRequestFeedbackCheck | null {
+  if (node.__typename === "CheckRun") {
+    const conclusion = typeof node.conclusion === "string" ? node.conclusion : "";
+    if (!FAILING_CHECK_CONCLUSIONS.has(conclusion)) return null;
+    const detailsUrl = safeText(node.detailsUrl, token, 300);
+    const isActionsJob = detailsUrl.includes("/actions/runs/") && typeof node.databaseId === "number";
+    return { name: safeText(node.name, token, 200), conclusion, url: detailsUrl, jobId: isActionsJob ? node.databaseId as number : null };
+  }
+  const state = typeof node.state === "string" ? node.state : "";
+  if (!FAILING_STATUS_STATES.has(state)) return null;
+  return { name: safeText(node.context, token, 200), conclusion: state, url: safeText(node.targetUrl, token, 300), jobId: null };
+}
+
+async function postFeedbackQuery(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions): Promise<Record<string, unknown>> {
+  const controller = new AbortController();
+  const timer = setTimeout(controller.abort.bind(controller), GITHUB_GRAPHQL_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+  try {
+    const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), `${GITHUB_API_BASE_URL}/graphql`, {
+      method: "POST",
+      headers: gitHubJsonHeaders(token),
+      body: JSON.stringify({ query: FEEDBACK_QUERY, variables: { owner: repository.owner, repo: repository.repo, number } }),
+      signal,
+    }, "GitHub pull request feedback lookup failed", token);
+    if (!response.ok) throw new Error(`GitHub pull request feedback lookup returned HTTP ${response.status}.`);
+    const body = await readBoundedResponseText(response, signal, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES);
+    if (body.truncated) throw new Error("GitHub pull request feedback exceeded the response byte limit.");
+    const payload = requireGitHubResponseObject(parseGitHubJson(body.text, "GitHub pull request feedback response", token), "Pull request feedback");
+    if (Array.isArray(payload.errors) && payload.errors.length > 0) {
+      const messages = payload.errors.map((error) => (isRecord(error) ? safeText(error.message, token, 300) : "")).filter(Boolean);
+      throw new Error(`GitHub pull request feedback query failed: ${messages.join("; ") || "unknown GraphQL error"}`);
+    }
+    return payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readResponseTail(response: Response, signal: AbortSignal): Promise<string> {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  let tail = Buffer.alloc(0);
+  try {
+    while (true) {
+      signal.throwIfAborted();
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value || value.byteLength === 0) continue;
+      tail = Buffer.concat([tail, Buffer.from(value)]);
+      if (tail.byteLength > PULL_REQUEST_FEEDBACK_LOG_TAIL_BYTES) tail = tail.subarray(tail.byteLength - PULL_REQUEST_FEEDBACK_LOG_TAIL_BYTES);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return tail.toString("utf8");
+}
+
+// Keep the lines leading up to the last error annotation; without one, the end of the log.
+export function extractLogTail(log: string, token: string): string {
+  const lines = log.split(/\r?\n/u).map((line) => line.replace(ANSI_ESCAPE_PATTERN, "").replace(LOG_TIMESTAMP_PATTERN, "")).filter((line) => line.trim() !== "");
+  let end = lines.length;
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (lines[index].includes("##[error]")) {
+      end = index + 1;
+      break;
+    }
+  }
+  const excerpt = lines.slice(Math.max(0, end - PULL_REQUEST_FEEDBACK_LOG_TAIL_LINES), end).join("\n");
+  const text = safeText(excerpt, token, Number.MAX_SAFE_INTEGER);
+  return text.length <= PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS ? text : `…${text.slice(text.length - PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS + 1)}`;
+}
+
+async function attachJobLog(repository: GitHubRepository, check: PullRequestFeedbackCheck, token: string, options: PullRequestFetchOptions): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(controller.abort.bind(controller), GITHUB_JOB_LOG_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+  try {
+    const url = `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/actions/jobs/${check.jobId}/logs`;
+    const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), url, {
+      method: "GET", headers: gitHubJsonHeaders(token), signal,
+    }, "GitHub job log lookup failed", token);
+    if (!response.ok) {
+      check.logError = `job log returned HTTP ${response.status}`;
+      return;
+    }
+    check.logTail = extractLogTail(await readResponseTail(response, signal), token);
+  } catch (error) {
+    check.logError = safeText(error instanceof Error ? error.message : String(error), token, 300);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function getPullRequestFeedback(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestFeedbackDetails> {
+  validateGitHubRepository(repository);
+  pullRequestNumberField(number);
+  const payload = await postFeedbackQuery(repository, number, token, options);
+  const data = isRecord(payload.data) ? payload.data : {};
+  const pullRequest = isRecord(data.repository) && isRecord(data.repository.pullRequest) ? data.repository.pullRequest : null;
+  if (!pullRequest) throw new Error(`Pull request #${number} was not found in ${repository.owner}/${repository.repo}.`);
+  if (pullRequestNumberField(pullRequest.number) !== number) throw new Error("GitHub returned a different pull request number.");
+
+  const commit = nodes(pullRequest.commits)[0];
+  const rollup = isRecord(commit?.commit) && isRecord(commit.commit.statusCheckRollup) ? commit.commit.statusCheckRollup : null;
+  const contexts = rollup ? nodes(rollup.contexts) : [];
+  const failingChecks = contexts.map((node) => parseCheck(node, token)).filter((check): check is PullRequestFeedbackCheck => check !== null);
+  // ponytail: logs for the first few failing Actions jobs only; raise the limit if wide matrices hide the cause.
+  const logChecks = failingChecks.filter((item) => item.jobId !== null).slice(0, PULL_REQUEST_FEEDBACK_LOG_JOB_LIMIT);
+  await Promise.all(logChecks.map((check) => attachJobLog(repository, check, token, options)));
+
+  const threadNodes = nodes(pullRequest.reviewThreads);
+  const commentNodes = nodes(pullRequest.comments);
+  return {
+    repository,
+    number,
+    url: safeText(pullRequest.url, token, 300),
+    headSha: safeText(pullRequest.headRefOid, token, 64),
+    checksState: rollup ? safeText(rollup.state, token, 40) : null,
+    ...parseThreads(pullRequest.reviewThreads, token),
+    reviews: parseReviews(pullRequest.reviews, token),
+    comments: commentNodes.map((comment) => parseComment(comment, token)).filter((comment) => comment.body !== ""),
+    failingChecks,
+    omitted: {
+      threads: Math.max(0, totalCount(pullRequest.reviewThreads) - threadNodes.length),
+      comments: Math.max(0, totalCount(pullRequest.comments) - commentNodes.length),
+      checks: rollup ? Math.max(0, totalCount(rollup.contexts) - contexts.length) : 0,
+    },
+  };
+}
+
+function indent(text: string): string {
+  return text.split("\n").map((line) => `    ${line}`).join("\n");
+}
+
+function formatThread(thread: PullRequestFeedbackThread): string {
+  const location = thread.line === null ? thread.path : `${thread.path}:${thread.line}`;
+  return [`- ${location}`, ...thread.comments.map((comment) => `  @${comment.author}: ${comment.body}`)].join("\n");
+}
+
+function formatCheck(check: PullRequestFeedbackCheck): string {
+  const lines = [`- ${check.name}: ${check.conclusion} ${check.url}`.trimEnd()];
+  if (check.logTail) lines.push(`  Log tail (job ${check.jobId}):`, indent(check.logTail));
+  if (check.logError) lines.push(`  Log unavailable: ${check.logError}`);
+  return lines.join("\n");
+}
+
+export function formatPullRequestFeedback(details: PullRequestFeedbackDetails): string {
+  const omittedThreads = details.omitted.threads ? `; ${details.omitted.threads} beyond the first 100 not read` : "";
+  const omittedComments = details.omitted.comments ? ` (latest 50; ${details.omitted.comments} older not read)` : "";
+  const omittedChecks = details.omitted.checks ? ` (${details.omitted.checks} checks beyond the first 100 not read)` : "";
+  const sections = [
+    `PR #${details.number} feedback at head ${details.headSha.slice(0, 12)}; checks ${details.checksState ?? "not reported"}. ${details.url}`,
+    `Unresolved review threads: ${details.unresolvedThreads.length} (${details.resolvedThreadCount} resolved and ${details.outdatedThreadCount} outdated not listed${omittedThreads}).`,
+    ...details.unresolvedThreads.map(formatThread),
+    `Reviews with a body or requested changes: ${details.reviews.length}.`,
+    ...details.reviews.map((review) => `- @${review.author} ${review.state}: ${review.body}`),
+    `Conversation comments: ${details.comments.length}${omittedComments}.`,
+    ...details.comments.map((comment) => `- @${comment.author}: ${comment.body}`),
+    `Failing checks: ${details.failingChecks.length}${omittedChecks}.`,
+    ...details.failingChecks.map(formatCheck),
+  ];
+  const text = sections.join("\n");
+  return text.length <= PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS ? text : `${text.slice(0, PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS - 40)}\n… [truncated; full data in details]`;
+}

package/src/github.ts

@@ -380,7 +380,7 @@ function truncate(value: string): string {
 
 export { redactSecrets } from "./redaction.ts";
 
-function encodePathSegment(value: string): string {
+export function encodePathSegment(value: string): string {
   return encodeURIComponent(value);
 }
 
@@ -433,7 +433,7 @@ function validatePullRequestInput(input: unknown): asserts input is PullRequestI
   if (typeof input.draft !== "boolean") throw new Error("draft must be a boolean.");
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
+export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
@@ -442,7 +442,7 @@ function stringField(value: unknown, field: string): string {
   return value;
 }
 
-function pullRequestNumberField(value: unknown): number {
+export function pullRequestNumberField(value: unknown): number {
   if (typeof value !== "number" || !Number.isFinite(value) || !Number.isSafeInteger(value) || value <= 0) {
     throw new Error("GitHub response pull request number must be a finite positive safe integer.");
   }
@@ -458,7 +458,7 @@ function throwIfResponseReadAborted(signal: AbortSignal | undefined): void {
   if (signal?.aborted) throw new Error("GitHub pull request response read was aborted.");
 }
 
-async function readBoundedResponseText(response: Response, signal: AbortSignal | undefined): Promise<BoundedResponseBody> {
+export async function readBoundedResponseText(response: Response, signal: AbortSignal | undefined, limitBytes = GITHUB_RESPONSE_BODY_LIMIT_BYTES): Promise<BoundedResponseBody> {
   throwIfResponseReadAborted(signal);
   if (!response.body) return { text: "", truncated: false };
 
@@ -474,7 +474,7 @@ async function readBoundedResponseText(response: Response, signal: AbortSignal |
       if (done) break;
       if (!value || value.byteLength === 0) continue;
 
-      const remainingBytes = GITHUB_RESPONSE_BODY_LIMIT_BYTES - capturedBytes;
+      const remainingBytes = limitBytes - capturedBytes;
       if (remainingBytes > 0) {
         const capturedChunk = value.byteLength <= remainingBytes ? value : value.subarray(0, remainingBytes);
         chunks.push(Buffer.from(capturedChunk));
@@ -495,7 +495,7 @@ async function readBoundedResponseText(response: Response, signal: AbortSignal |
   return { text: truncated ? `${text}… [truncated]` : text, truncated };
 }
 
-function gitHubJsonHeaders(token: string): Record<string, string> {
+export function gitHubJsonHeaders(token: string): Record<string, string> {
   return {
     Accept: "application/vnd.github+json",
     Authorization: `Bearer ${token}`,
@@ -505,7 +505,7 @@ function gitHubJsonHeaders(token: string): Record<string, string> {
   };
 }
 
-function requireFetchImplementation(fetchImpl: typeof fetch | undefined): typeof fetch {
+export function requireFetchImplementation(fetchImpl: typeof fetch | undefined): typeof fetch {
   if (typeof fetchImpl !== "function") throw new Error("fetch is unavailable in this Node.js runtime.");
   return fetchImpl;
 }
@@ -515,7 +515,7 @@ function redactedErrorMessage(error: unknown, tokens: readonly string[]): string
   return redactSecrets(message, tokens);
 }
 
-async function fetchGitHubResponse(
+export async function fetchGitHubResponse(
   fetchImpl: typeof fetch,
   url: string,
   init: RequestInit,
@@ -542,7 +542,7 @@ async function readGitHubResponseBody(
   }
 }
 
-function parseGitHubJson(text: string, responseContext: string, token: string): unknown {
+export function parseGitHubJson(text: string, responseContext: string, token: string): unknown {
   try {
     return JSON.parse(text);
   } catch (error) {
@@ -550,7 +550,7 @@ function parseGitHubJson(text: string, responseContext: string, token: string):
   }
 }
 
-function requireGitHubResponseObject(payload: unknown, responseContext: string): Record<string, unknown> {
+export function requireGitHubResponseObject(payload: unknown, responseContext: string): Record<string, unknown> {
   if (!isRecord(payload)) throw new Error(`${responseContext} was not an object.`);
   return payload;
 }

package/src/tools/branchme-tools.ts

@@ -52,6 +52,7 @@ import { collectGitContext, formatGitContext } from "../git-context.ts";
 import { fetchRemote } from "../git-discovery.ts";
 import { formatConflictPathList, integrateBranch } from "../git-integration.ts";
 import { retireBranch } from "../git-retirement.ts";
+import { withBlockerGuidance } from "../blocker-guidance.ts";
 import { formatLandBranch, landBranch } from "../git-landing.ts";
 import {
   createOrReuseGitHubPullRequest,
@@ -546,7 +547,13 @@ async function requireGitHubHeadMatchesLocalBranch(
   );
 }
 
-export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "exec">, options: BranchMeToolOptions = {}): void {
+function registerGuidedTool(host: Pick<ExtensionAPI, "registerTool">, tool: Parameters<ExtensionAPI["registerTool"]>[0]): void {
+  host.registerTool(withBlockerGuidance(tool));
+}
+
+export function registerBranchMeTools(host: Pick<ExtensionAPI, "registerTool" | "exec">, options: BranchMeToolOptions = {}): void {
+  // Every tool error carries Blocked/Resolve lines for known blockers.
+  const pi = { exec: host.exec.bind(host), registerTool: registerGuidedTool.bind(undefined, host) } as Pick<ExtensionAPI, "registerTool" | "exec">;
   registerWorkflowTools(pi, options);
   pi.registerTool({
     name: LIST_BRANCHES_TOOL_NAME,

package/src/tools/workflow-tools.ts

@@ -2,12 +2,13 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
-  CONCLUDE_MERGE_TOOL_NAME, GIT_CONTEXT_VALUE_LIMIT_CHARS, PULL_REQUEST_STATUS_TOOL_NAME, TRACK_BRANCH_TOOL_NAME,
-  UPDATE_FROM_BASE_TOOL_NAME,
+  CONCLUDE_MERGE_TOOL_NAME, GIT_CONTEXT_VALUE_LIMIT_CHARS, PULL_REQUEST_FEEDBACK_TOOL_NAME, PULL_REQUEST_STATUS_TOOL_NAME,
+  TRACK_BRANCH_TOOL_NAME, UPDATE_FROM_BASE_TOOL_NAME,
 } from "../constants.ts";
 import { getGitRoot, requireCurrentBranch, safeWorktreeValue } from "../git.ts";
 import { concludeMerge, formatConflictPathList } from "../git-integration.ts";
 import { findGitHubPullRequest, getGitHubPullRequest, resolveGitHubRepository, resolveGitHubToken } from "../github.ts";
+import { formatPullRequestFeedback, getPullRequestFeedback } from "../github-feedback.ts";
 import type { ConcludeMergeDetails, PullRequestStatusDetails } from "../types.ts";
 import type { BranchMeToolOptions } from "./branchme-tools.ts";
 import { trackBranch, updateFromBase, type UpdateFromBaseDetails } from "../git-workflow.ts";
@@ -42,7 +43,7 @@ export function formatUpdateFromBase(details: UpdateFromBaseDetails): string {
 export function formatConcludeMerge(details: ConcludeMergeDetails): string {
   const branch = branchLabel(details.branch);
   if (details.status === "aborted") {
-    return `conclude_merge: aborted. git merge --abort restored ${branch} to HEAD ${shortCommit(details.head)}; MERGE_HEAD ${shortCommit(details.mergeHead)} is cleared, no Git operation is in progress, and the working tree is clean.`;
+    return `conclude_merge: aborted. git merge --abort restored ${branch} to HEAD ${shortCommit(details.head)}; MERGE_HEAD ${shortCommit(details.mergeHead)} is cleared, no Git operation is in progress, and tracked files are clean.`;
   }
   const count = details.resolvedPaths.length;
   return formatConflictPathList(
@@ -90,6 +91,36 @@ export function registerWorkflowTools(pi: Pick<ExtensionAPI, "registerTool" | "e
       };
     },
   });
+  pi.registerTool({
+    name: PULL_REQUEST_FEEDBACK_TOOL_NAME,
+    label: "Pull Request Feedback",
+    description: "pull_request_feedback reads what a same-repository GitHub PR asks to be fixed: unresolved review threads with their comments, review summaries, conversation comments, and the head commit's failing checks with the log tail of up to three failing GitHub Actions jobs. Resolved and outdated threads are counted, not listed. No mutations.",
+    promptSnippet: "pull_request_feedback: read a PR's unresolved review comments and failing checks with their log tails",
+    promptGuidelines: [
+      "Use pull_request_feedback with number to collect the review comments and failing checks a follow-up must address; number and headBranch are mutually exclusive.",
+      "Without number, pull_request_feedback reads the most recently updated PR for headBranch or the current branch.",
+      "pull_request_feedback never comments, resolves threads, reruns checks, or edits the PR; a job log that cannot be read is reported per check, not as a failure of the call.",
+    ],
+    parameters: Type.Object({
+      number: Type.Optional(Type.Integer({ minimum: 1, description: "Exact PR number; mutually exclusive with headBranch." })),
+      headBranch: Type.Optional(Type.String({ minLength: 1, description: "Head branch to look up; defaults to current branch when number is omitted." })),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      if (params.number !== undefined && params.headBranch !== undefined) throw new Error("Supply number or headBranch, not both.");
+      const rootCtx = { cwd: await getGitRoot(pi, ctx, signal) };
+      const repository = await resolveGitHubRepository(pi, rootCtx, signal, options.env);
+      const token = (await resolveGitHubToken(options.env, { cwd: rootCtx.cwd, signal })).token;
+      const requestOptions = { fetchImpl: options.fetchImpl, signal };
+      let number = params.number;
+      if (number === undefined) {
+        const found = await findGitHubPullRequest(repository, params.headBranch ?? await requireCurrentBranch(pi, rootCtx, signal), token, requestOptions);
+        if (!found) return { content: [{ type: "text", text: "No matching pull request found." }], details: { action: "pull_request_feedback", feedback: null } };
+        number = found.number;
+      }
+      const feedback = await getPullRequestFeedback(repository, number, token, requestOptions);
+      return { content: [{ type: "text", text: formatPullRequestFeedback(feedback) }], details: { action: "pull_request_feedback", feedback } };
+    },
+  });
   pi.registerTool({
     name: UPDATE_FROM_BASE_TOOL_NAME,
     label: "Update From Base",

package/src/types.ts

@@ -601,6 +601,46 @@ export interface PullRequestStatusDetails extends PullRequestDetails {
   mergeCommitSha: string | null;
 }
 
+export interface PullRequestFeedbackComment {
+  author: string;
+  body: string;
+  url: string;
+}
+
+export interface PullRequestFeedbackThread {
+  path: string;
+  line: number | null;
+  comments: PullRequestFeedbackComment[];
+}
+
+export interface PullRequestFeedbackReview extends PullRequestFeedbackComment {
+  state: string;
+}
+
+export interface PullRequestFeedbackCheck {
+  name: string;
+  conclusion: string;
+  url: string;
+  jobId: number | null;
+  logTail?: string;
+  logError?: string;
+}
+
+export interface PullRequestFeedbackDetails {
+  repository: GitHubRepository;
+  number: number;
+  url: string;
+  headSha: string;
+  checksState: string | null;
+  unresolvedThreads: PullRequestFeedbackThread[];
+  resolvedThreadCount: number;
+  outdatedThreadCount: number;
+  reviews: PullRequestFeedbackReview[];
+  comments: PullRequestFeedbackComment[];
+  failingChecks: PullRequestFeedbackCheck[];
+  omitted: { threads: number; comments: number; checks: number };
+}
+
 export interface PullRequestInput {
   headBranch: string;
   baseBranch: string;