@senad-d/branchme 0.3.8 → 0.3.10

package/src/github-feedback.ts

@@ -2,6 +2,7 @@ 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,
+  PULL_REQUEST_REPLY_BODY_LIMIT_CHARS,
 } from "./constants.ts";
 import {
   encodePathSegment, fetchGitHubResponse, gitHubJsonHeaders, isRecord, parseGitHubJson, pullRequestNumberField,
@@ -10,22 +11,24 @@ import {
 } from "./github.ts";
 import { redactSecrets } from "./redaction.ts";
 import type {
-  GitHubRepository, PullRequestFeedbackCheck, PullRequestFeedbackComment, PullRequestFeedbackDetails,
-  PullRequestFeedbackReview, PullRequestFeedbackThread,
+  GitHubRepository, PullRequestFeedbackAnnotation, PullRequestFeedbackCheck, PullRequestFeedbackComment, PullRequestFeedbackDetails,
+  PullRequestFeedbackReview, PullRequestFeedbackThread, PullRequestReplyDetails, PullRequestReplyInput,
 } 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.
+// Ids, times and the viewer let an agent reply to a thread and skip its own earlier replies.
 const FEEDBACK_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  viewer { login }
   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 } }
+      id number url headRefOid
+      reviewThreads(first: 100) { totalCount nodes { id isResolved isOutdated path line comments(first: 20) { nodes { id author { login } createdAt body url } } } }
+      reviews(last: 50) { nodes { id author { login } submittedAt state body url } }
+      comments(last: 50) { totalCount nodes { id author { login } createdAt body url } }
       commits(last: 1) { nodes { commit { statusCheckRollup { state contexts(first: 100) { totalCount nodes {
         __typename
-        ... on CheckRun { name conclusion databaseId detailsUrl }
+        ... on CheckRun { name conclusion databaseId detailsUrl annotations(first: 20) { nodes { path location { start { line } } annotationLevel message } } }
         ... on StatusContext { context state targetUrl }
       } } } } } }
     }
@@ -34,6 +37,8 @@ const FEEDBACK_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
 
 const FAILING_CHECK_CONCLUSIONS = new Set(["FAILURE", "TIMED_OUT", "STARTUP_FAILURE", "ACTION_REQUIRED", "CANCELLED"]);
 const FAILING_STATUS_STATES = new Set(["FAILURE", "ERROR"]);
+const REPORTED_ANNOTATION_LEVELS = new Set(["FAILURE", "WARNING"]);
+const ANNOTATION_MESSAGE_LIMIT_CHARS = 500;
 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;
@@ -53,16 +58,19 @@ function totalCount(connection: unknown): number {
   return isRecord(connection) && typeof connection.totalCount === "number" ? connection.totalCount : 0;
 }
 
-function parseComment(node: Record<string, unknown>, token: string): PullRequestFeedbackComment {
+function parseComment(viewer: string | null, token: string, node: Record<string, unknown>): PullRequestFeedbackComment {
   const author = isRecord(node.author) ? safeText(node.author.login, token, 100) : "";
   return {
+    id: safeText(node.id, token, 200),
     author: author || "ghost",
+    byViewer: viewer !== null && author === viewer,
+    createdAt: safeText(node.createdAt ?? node.submittedAt, token, 40),
     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"> {
+function parseThreads(connection: unknown, viewer: string | null, token: string): Pick<PullRequestFeedbackDetails, "unresolvedThreads" | "resolvedThreadCount" | "outdatedThreadCount"> {
   const unresolvedThreads: PullRequestFeedbackThread[] = [];
   let resolvedThreadCount = 0;
   let outdatedThreadCount = 0;
@@ -71,35 +79,55 @@ function parseThreads(connection: unknown, token: string): Pick<PullRequestFeedb
     else if (thread.isOutdated === true) outdatedThreadCount += 1;
     else {
       unresolvedThreads.push({
+        id: safeText(thread.id, token, 200),
         path: safeText(thread.path, token, 300),
         line: typeof thread.line === "number" ? thread.line : null,
-        comments: nodes(thread.comments).map((comment) => parseComment(comment, token)),
+        comments: nodes(thread.comments).map(parseComment.bind(undefined, viewer, token)),
       });
     }
   }
   return { unresolvedThreads, resolvedThreadCount, outdatedThreadCount };
 }
 
-function parseReviews(connection: unknown, token: string): PullRequestFeedbackReview[] {
+function parseReviews(connection: unknown, viewer: string | null, token: string): PullRequestFeedbackReview[] {
   return nodes(connection)
-    .map((review) => ({ ...parseComment(review, token), state: safeText(review.state, token, 40) }))
+    .map((review) => ({ ...parseComment(viewer, token, review), state: safeText(review.state, token, 40) }))
     .filter((review) => review.body !== "" || review.state === "CHANGES_REQUESTED");
 }
 
+function parseAnnotation(token: string, node: Record<string, unknown>): PullRequestFeedbackAnnotation | null {
+  const level = typeof node.annotationLevel === "string" ? node.annotationLevel : "";
+  if (!REPORTED_ANNOTATION_LEVELS.has(level)) return null;
+  const start = isRecord(node.location) && isRecord(node.location.start) ? node.location.start : null;
+  return {
+    path: safeText(node.path, token, 300),
+    line: typeof start?.line === "number" ? start.line : null,
+    level,
+    message: safeText(node.message, token, ANNOTATION_MESSAGE_LIMIT_CHARS),
+  };
+}
+
 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 annotations = nodes(node.annotations)
+      .map(parseAnnotation.bind(undefined, token))
+      .filter((annotation): annotation is PullRequestFeedbackAnnotation => annotation !== null);
+    return { name: safeText(node.name, token, 200), conclusion, url: detailsUrl, jobId: isActionsJob ? node.databaseId as number : null, annotations };
   }
   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 };
+  return { name: safeText(node.context, token, 200), conclusion: state, url: safeText(node.targetUrl, token, 300), jobId: null, annotations: [] };
 }
 
 async function postFeedbackQuery(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions): Promise<Record<string, unknown>> {
+  return postGraphQL(FEEDBACK_QUERY, { owner: repository.owner, repo: repository.repo, number }, token, options, "GitHub pull request feedback");
+}
+
+async function postGraphQL(query: string, variables: Record<string, unknown>, token: string, options: PullRequestFetchOptions, label: string): 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;
@@ -107,16 +135,16 @@ async function postFeedbackQuery(repository: GitHubRepository, number: number, t
     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 } }),
+      body: JSON.stringify({ query, variables }),
       signal,
-    }, "GitHub pull request feedback lookup failed", token);
-    if (!response.ok) throw new Error(`GitHub pull request feedback lookup returned HTTP ${response.status}.`);
+    }, `${label} lookup failed`, token);
+    if (!response.ok) throw new Error(`${label} 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 (body.truncated) throw new Error(`${label} exceeded the response byte limit.`);
+    const payload = requireGitHubResponseObject(parseGitHubJson(body.text, `${label} response`, token), label);
     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"}`);
+      throw new Error(`${label} query failed: ${messages.join("; ") || "unknown GraphQL error"}`);
     }
     return payload;
   } finally {
@@ -184,6 +212,7 @@ export async function getPullRequestFeedback(repository: GitHubRepository, numbe
   pullRequestNumberField(number);
   const payload = await postFeedbackQuery(repository, number, token, options);
   const data = isRecord(payload.data) ? payload.data : {};
+  const viewer = isRecord(data.viewer) ? safeText(data.viewer.login, token, 100) || null : null;
   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.");
@@ -201,12 +230,14 @@ export async function getPullRequestFeedback(repository: GitHubRepository, numbe
   return {
     repository,
     number,
+    id: safeText(pullRequest.id, token, 200),
+    viewer,
     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 !== ""),
+    ...parseThreads(pullRequest.reviewThreads, viewer, token),
+    reviews: parseReviews(pullRequest.reviews, viewer, token),
+    comments: commentNodes.map(parseComment.bind(undefined, viewer, token)).filter((comment) => comment.body !== ""),
     failingChecks,
     omitted: {
       threads: Math.max(0, totalCount(pullRequest.reviewThreads) - threadNodes.length),
@@ -220,13 +251,31 @@ function indent(text: string): string {
   return text.split("\n").map((line) => `    ${line}`).join("\n");
 }
 
+function location(path: string, line: number | null): string {
+  return line === null ? path : `${path}:${line}`;
+}
+
+// "@alice (you) 2026-10-14T19:50:15Z" — the marker and time decide what is new.
+function byline(comment: PullRequestFeedbackComment): string {
+  return [`@${comment.author}`, comment.byViewer ? "(you)" : "", comment.createdAt].filter(Boolean).join(" ");
+}
+
+function idTag(kind: string, id: string): string {
+  return id ? `[${kind} ${id}] ` : "";
+}
+
 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");
+  return [
+    `- ${idTag("thread", thread.id)}${location(thread.path, thread.line)}`,
+    ...thread.comments.map((comment) => `  ${byline(comment)}: ${comment.body}`),
+  ].join("\n");
 }
 
 function formatCheck(check: PullRequestFeedbackCheck): string {
   const lines = [`- ${check.name}: ${check.conclusion} ${check.url}`.trimEnd()];
+  if (check.annotations.length > 0) {
+    lines.push("  Annotations:", ...check.annotations.map((item) => `    ${location(item.path, item.line)} ${item.level}: ${item.message}`));
+  }
   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");
@@ -238,15 +287,108 @@ export function formatPullRequestFeedback(details: PullRequestFeedbackDetails):
   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}`,
+    ...(details.viewer ? [`Token user: @${details.viewer}; comments marked (you) are its own earlier replies.`] : []),
     `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}`),
+    ...details.reviews.map((review) => `- ${byline(review)} ${review.state}: ${review.body}`),
     `Conversation comments: ${details.comments.length}${omittedComments}.`,
-    ...details.comments.map((comment) => `- @${comment.author}: ${comment.body}`),
+    ...details.comments.map((comment) => `- ${idTag("comment", comment.id)}${byline(comment)}: ${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]`;
 }
+
+const THREAD_OWNER_QUERY = `query($id: ID!) {
+  node(id: $id) { ... on PullRequestReviewThread { id isResolved pullRequest { number repository { name owner { login } } } } }
+}`;
+const PULL_REQUEST_EXISTS_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) { pullRequest(number: $number) { number } }
+}`;
+const THREAD_REPLY_MUTATION = `mutation($threadId: ID!, $body: String!) {
+  addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $threadId, body: $body }) { comment { url } }
+}`;
+const RESOLVE_THREAD_MUTATION = `mutation($threadId: ID!) {
+  resolveReviewThread(input: { threadId: $threadId }) { thread { isResolved } }
+}`;
+
+function validateReplyInput(input: PullRequestReplyInput): string {
+  pullRequestNumberField(input.number);
+  const body = typeof input.body === "string" ? input.body.trim() : "";
+  if (body === "") throw new Error("body is required and cannot be blank.");
+  if (body.length > PULL_REQUEST_REPLY_BODY_LIMIT_CHARS) throw new Error(`body exceeds ${PULL_REQUEST_REPLY_BODY_LIMIT_CHARS} characters.`);
+  if (input.resolve === true && !input.threadId) throw new Error("resolve requires threadId; conversation comments cannot be resolved.");
+  return body;
+}
+
+// The thread must belong to this pull request of this repository before anything is posted.
+async function requireThreadOfPullRequest(repository: GitHubRepository, input: PullRequestReplyInput, token: string, options: PullRequestFetchOptions): Promise<boolean> {
+  const payload = await postGraphQL(THREAD_OWNER_QUERY, { id: input.threadId }, token, options, "GitHub review thread");
+  const node = isRecord(payload.data) && isRecord(payload.data.node) ? payload.data.node : null;
+  const pullRequest = node && isRecord(node.pullRequest) ? node.pullRequest : null;
+  const owner = pullRequest && isRecord(pullRequest.repository) ? pullRequest.repository : null;
+  const ownerLogin = owner && isRecord(owner.owner) ? owner.owner.login : null;
+  if (!node || node.id !== input.threadId || pullRequest?.number !== input.number ||
+      typeof ownerLogin !== "string" || ownerLogin.toLowerCase() !== repository.owner.toLowerCase() ||
+      typeof owner?.name !== "string" || owner.name.toLowerCase() !== repository.repo.toLowerCase()) {
+    throw new Error(`Review thread ${safeText(input.threadId, token, 200)} is not a thread of pull request #${input.number} in ${repository.owner}/${repository.repo}; nothing was posted.`);
+  }
+  return node.isResolved === true;
+}
+
+async function replyToThread(repository: GitHubRepository, input: PullRequestReplyInput, body: string, token: string, options: PullRequestFetchOptions): Promise<PullRequestReplyDetails> {
+  const alreadyResolved = await requireThreadOfPullRequest(repository, input, token, options);
+  const reply = await postGraphQL(THREAD_REPLY_MUTATION, { threadId: input.threadId, body }, token, options, "GitHub review thread reply");
+  const added = isRecord(reply.data) && isRecord(reply.data.addPullRequestReviewThreadReply) ? reply.data.addPullRequestReviewThreadReply : null;
+  const commentUrl = added && isRecord(added.comment) ? safeText(added.comment.url, token, 300) : "";
+  if (!commentUrl) throw new Error("GitHub did not confirm the review thread reply.");
+  let resolved: boolean | null = null;
+  if (input.resolve === true) {
+    resolved = alreadyResolved;
+    if (!alreadyResolved) {
+      const result = await postGraphQL(RESOLVE_THREAD_MUTATION, { threadId: input.threadId }, token, options, "GitHub review thread resolution");
+      const thread = isRecord(result.data) && isRecord(result.data.resolveReviewThread) && isRecord(result.data.resolveReviewThread.thread)
+        ? result.data.resolveReviewThread.thread : null;
+      resolved = thread?.isResolved === true;
+    }
+  }
+  return { action: "reply_pull_request_feedback", repository, number: input.number, threadId: input.threadId ?? null, commentUrl, resolved };
+}
+
+async function commentOnPullRequest(repository: GitHubRepository, input: PullRequestReplyInput, body: string, token: string, options: PullRequestFetchOptions): Promise<PullRequestReplyDetails> {
+  // Issues and pull requests share numbers; confirming a pull request first keeps the comment off an issue.
+  // GraphQL, not the REST status read: a pull request from a fork is still this repository's pull request.
+  const found = await postGraphQL(PULL_REQUEST_EXISTS_QUERY, { owner: repository.owner, repo: repository.repo, number: input.number }, token, options, "GitHub pull request");
+  const pullRequest = isRecord(found.data) && isRecord(found.data.repository) ? found.data.repository.pullRequest : null;
+  if (!isRecord(pullRequest) || pullRequest.number !== input.number) {
+    throw new Error(`Pull request #${input.number} was not found in ${repository.owner}/${repository.repo}; nothing was posted.`);
+  }
+  const url = `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/issues/${input.number}/comments`;
+  const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), url, {
+    method: "POST", headers: gitHubJsonHeaders(token), body: JSON.stringify({ body }), signal: options.signal,
+  }, "GitHub pull request comment failed", token);
+  if (!response.ok) throw new Error(`GitHub pull request comment returned HTTP ${response.status}.`);
+  const text = await readBoundedResponseText(response, options.signal, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES);
+  const payload = requireGitHubResponseObject(parseGitHubJson(text.text, "GitHub pull request comment response", token), "Pull request comment");
+  const commentUrl = safeText(payload.html_url, token, 300);
+  if (!commentUrl) throw new Error("GitHub did not confirm the pull request comment.");
+  return { action: "reply_pull_request_feedback", repository, number: input.number, threadId: null, commentUrl, resolved: null };
+}
+
+/** Replies to one review thread (and optionally resolves it), or posts one conversation comment. */
+export async function replyPullRequestFeedback(repository: GitHubRepository, input: PullRequestReplyInput, token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestReplyDetails> {
+  validateGitHubRepository(repository);
+  const body = validateReplyInput(input);
+  return input.threadId
+    ? replyToThread(repository, input, body, token, options)
+    : commentOnPullRequest(repository, input, body, token, options);
+}
+
+export function formatPullRequestReply(details: PullRequestReplyDetails): string {
+  if (details.threadId === null) return `Commented on PR #${details.number}: ${details.commentUrl}`;
+  let resolution = "";
+  if (details.resolved !== null) resolution = details.resolved ? "; thread resolved" : "; thread NOT resolved";
+  return `Replied to thread ${details.threadId} on PR #${details.number}${resolution}: ${details.commentUrl}`;
+}

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,13 +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_FEEDBACK_TOOL_NAME, 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_REPLY_BODY_LIMIT_CHARS,
+  PULL_REQUEST_STATUS_TOOL_NAME, REPLY_PULL_REQUEST_FEEDBACK_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 { formatPullRequestFeedback, formatPullRequestReply, getPullRequestFeedback, replyPullRequestFeedback } 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";
@@ -43,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(
@@ -94,7 +94,7 @@ 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.",
+    description: "pull_request_feedback reads what a same-repository GitHub PR asks to be fixed: unresolved review threads (with thread ids) and their comments, review summaries, conversation comments (with ids), each with author and time and comments by the token's own user marked (you), and the head commit's failing checks with their file:line annotations and 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.",
@@ -121,6 +121,31 @@ export function registerWorkflowTools(pi: Pick<ExtensionAPI, "registerTool" | "e
       return { content: [{ type: "text", text: formatPullRequestFeedback(feedback) }], details: { action: "pull_request_feedback", feedback } };
     },
   });
+  pi.registerTool({
+    name: REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME,
+    label: "Reply To Pull Request Feedback",
+    description: "reply_pull_request_feedback posts one reply on a pull request of this GitHub repository (including one opened from a fork): with threadId it replies in that review thread and, with resolve: true, resolves the thread; without threadId it posts one conversation comment. Works on open, merged and closed PRs. The thread must belong to the PR; nothing else is changed.",
+    promptSnippet: "reply_pull_request_feedback: answer a PR review thread (optionally resolving it) or post a PR comment",
+    promptGuidelines: [
+      "Use reply_pull_request_feedback with the thread ids pull_request_feedback reports ([thread <id>]); one call per thread, the body states what was done or why not.",
+      "Pass reply_pull_request_feedback resolve: true only for a thread whose request is fixed or already addressed; leave a thread open when it needs a person's decision.",
+      "Without threadId, reply_pull_request_feedback posts one conversation comment on the PR; conversation comments cannot be resolved.",
+      "reply_pull_request_feedback never edits or deletes comments, approves, requests changes, merges, or closes a PR.",
+    ],
+    parameters: Type.Object({
+      number: Type.Integer({ minimum: 1, description: "PR number." }),
+      body: Type.String({ minLength: 1, maxLength: PULL_REQUEST_REPLY_BODY_LIMIT_CHARS, description: "Markdown reply." }),
+      threadId: Type.Optional(Type.String({ minLength: 1, description: "Review thread id from pull_request_feedback; omit for a conversation comment." })),
+      resolve: Type.Optional(Type.Boolean({ description: "Resolve the thread after replying; requires threadId." })),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      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 details = await replyPullRequestFeedback(repository, params, token, { fetchImpl: options.fetchImpl, signal });
+      return { content: [{ type: "text", text: formatPullRequestReply(details) }], details };
+    },
+  });
   pi.registerTool({
     name: UPDATE_FROM_BASE_TOOL_NAME,
     label: "Update From Base",

package/src/types.ts

@@ -602,12 +602,19 @@ export interface PullRequestStatusDetails extends PullRequestDetails {
 }
 
 export interface PullRequestFeedbackComment {
+  /** GraphQL node id; empty when GitHub did not return one. */
+  id: string;
   author: string;
+  /** True when the token's own user wrote it (Mission's earlier replies). */
+  byViewer: boolean;
+  createdAt: string;
   body: string;
   url: string;
 }
 
 export interface PullRequestFeedbackThread {
+  /** Review thread node id, the target for replies and resolution. */
+  id: string;
   path: string;
   line: number | null;
   comments: PullRequestFeedbackComment[];
@@ -622,13 +629,25 @@ export interface PullRequestFeedbackCheck {
   conclusion: string;
   url: string;
   jobId: number | null;
+  annotations: PullRequestFeedbackAnnotation[];
   logTail?: string;
   logError?: string;
 }
 
+export interface PullRequestFeedbackAnnotation {
+  path: string;
+  line: number | null;
+  level: string;
+  message: string;
+}
+
 export interface PullRequestFeedbackDetails {
   repository: GitHubRepository;
   number: number;
+  /** Pull request node id. */
+  id: string;
+  /** Login of the token's user; null when GitHub did not return it. */
+  viewer: string | null;
   url: string;
   headSha: string;
   checksState: string | null;
@@ -641,6 +660,23 @@ export interface PullRequestFeedbackDetails {
   omitted: { threads: number; comments: number; checks: number };
 }
 
+export interface PullRequestReplyInput {
+  number: number;
+  body: string;
+  threadId?: string;
+  resolve?: boolean;
+}
+
+export interface PullRequestReplyDetails {
+  action: "reply_pull_request_feedback";
+  repository: GitHubRepository;
+  number: number;
+  threadId: string | null;
+  commentUrl: string;
+  /** Thread state after the call; null when resolution was not requested or this was a conversation comment. */
+  resolved: boolean | null;
+}
+
 export interface PullRequestInput {
   headBranch: string;
   baseBranch: string;