@shipfox/api-integration-github 12.2.0 → 12.5.0

package/src/core/agent-tools.ts

@@ -8,6 +8,7 @@ import type {
   OpenAgentToolsSessionInput,
 } from '@shipfox/api-integration-spi';
 import {Octokit} from 'octokit';
+import {mapGithubError} from '#api/client.js';
 import {
   createGithubInstallationTokenProvider,
   type GithubInstallationTokenProvider,
@@ -48,6 +49,44 @@ type GithubToolCallResult = {
   structuredContent?: Record<string, unknown> | undefined;
 };
 
+const GITHUB_GRAPHQL_ROUTE = 'POST /graphql';
+const GITHUB_ARTIFACT_ARCHIVE_FORMAT = 'zip';
+const GITHUB_ARTIFACT_DOWNLOAD_ROUTE = `GET /repos/{owner}/{repo}/actions/artifacts/{resource_id}/${GITHUB_ARTIFACT_ARCHIVE_FORMAT}`;
+const GITHUB_ARTIFACT_DOWNLOAD_TIMEOUT_MS = 30_000;
+const NO_PENDING_REVIEW_MESSAGE =
+  'No pending pull request review found for the authenticated GitHub user.';
+
+const LATEST_PENDING_REVIEW_QUERY = `
+  query LatestPendingPullRequestReview($owner: String!, $repo: String!, $pullNumber: Int!) {
+    viewer {
+      login
+    }
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $pullNumber) {
+        reviews(last: 100, states: [PENDING]) {
+          nodes {
+            id
+            author {
+              login
+            }
+            createdAt
+          }
+        }
+      }
+    }
+  }
+`;
+
+const ADD_PENDING_REVIEW_COMMENT_MUTATION = `
+  mutation AddCommentToPendingReview($input: AddPullRequestReviewThreadInput!) {
+    addPullRequestReviewThread(input: $input) {
+      thread {
+        id
+      }
+    }
+  }
+`;
+
 export class GithubAgentToolsProvider
   implements
     AgentToolsProvider<
@@ -108,15 +147,39 @@ export class GithubAgentToolsProvider
           );
         }
         const client = (this.options.createClient ?? createOctokitClient)(token.token);
+        const method =
+          typeof call.arguments.method === 'string' ? call.arguments.method : undefined;
 
-        try {
-          const response = await client.request(operation.route, operation.parameters);
-          return githubToolResult(tool.id as GithubAgentToolId, response.data);
-        } catch (error) {
-          if (error instanceof GithubIntegrationProviderError)
-            return githubToolError(error.message);
-          throw error;
+        if (operation.kind === 'graphql') {
+          const data = await mapGithubError(() =>
+            addCommentToPendingReview(client, operation.parameters),
+          );
+          return data === undefined
+            ? githubToolError(NO_PENDING_REVIEW_MESSAGE)
+            : githubToolResult(tool.id as GithubAgentToolId, data);
+        }
+
+        const operationParameters = await mapGithubError(() =>
+          resolvePendingReviewParameters(
+            client,
+            operation.parameters,
+            tool.id as GithubAgentToolId,
+            method,
+          ),
+        );
+        if (operationParameters === undefined) {
+          return githubToolError(NO_PENDING_REVIEW_MESSAGE);
         }
+        const response = await mapGithubError(() =>
+          client.request(operation.route, operationParameters),
+        );
+        return githubToolResult(
+          tool.id as GithubAgentToolId,
+          response.data,
+          response,
+          operationParameters,
+          operation.route,
+        );
       },
     };
   }
@@ -130,8 +193,16 @@ export interface GithubAgentToolsProviderOptions {
   createClient?: GithubToolClientFactory | undefined;
 }
 
+export interface GithubToolResponse {
+  data: unknown;
+  headers?: Record<string, string | number | undefined> | undefined;
+  status?: number | undefined;
+  url?: string | undefined;
+}
+
 export interface GithubToolClient {
-  request(route: string, parameters: Record<string, unknown>): Promise<{data: unknown}>;
+  request(route: string, parameters: Record<string, unknown>): Promise<GithubToolResponse>;
+  graphql?: ((query: string, variables: Record<string, unknown>) => Promise<unknown>) | undefined;
 }
 
 export type GithubToolClientFactory = (token: string) => GithubToolClient;
@@ -139,6 +210,7 @@ export type GithubToolClientFactory = (token: string) => GithubToolClient;
 interface GithubToolOperation {
   route: string;
   parameters: Record<string, unknown>;
+  kind: 'rest' | 'graphql';
 }
 
 function createOctokitClient(token: string): GithubToolClient {
@@ -148,7 +220,30 @@ function createOctokitClient(token: string): GithubToolClient {
     retry: {enabled: false},
   });
   return {
-    request: async (route, parameters) => await octokit.request(route, parameters),
+    request: async (route, parameters) => {
+      if (route !== GITHUB_ARTIFACT_DOWNLOAD_ROUTE) {
+        return await octokit.request(route, parameters);
+      }
+
+      const abortController = new AbortController();
+      const timeout = setTimeout(
+        () => abortController.abort(),
+        GITHUB_ARTIFACT_DOWNLOAD_TIMEOUT_MS,
+      );
+      try {
+        return await octokit.request(route, {
+          ...parameters,
+          request: {
+            redirect: 'manual',
+            parseSuccessResponseBody: false,
+            signal: abortController.signal,
+          },
+        });
+      } finally {
+        clearTimeout(timeout);
+      }
+    },
+    graphql: async (query, variables) => await octokit.graphql(query, variables),
   };
 }
 
@@ -167,10 +262,14 @@ function resolveGithubOperation(
   const route = githubOperationRoute(toolId, method, params);
   return route === undefined
     ? undefined
-    : {route, parameters: projectGithubOperationParameters(toolId, method, params)};
+    : {
+        route,
+        parameters: projectGithubOperationParameters(toolId, method, params),
+        kind: route === GITHUB_GRAPHQL_ROUTE ? 'graphql' : 'rest',
+      };
 }
 
-function githubOperationRoute(
+export function githubOperationRoute(
   toolId: GithubAgentToolId,
   method: string | undefined,
   args: Record<string, unknown>,
@@ -217,7 +316,7 @@ function githubOperationRoute(
     case 'sub_issue_write.remove':
       return `DELETE ${repoPath}/issues/${issue}/sub_issues/{sub_issue_id}`;
     case 'sub_issue_write.reprioritize':
-      return `PATCH ${repoPath}/issues/${issue}/sub_issues/{sub_issue_id}`;
+      return `PATCH ${repoPath}/issues/${issue}/sub_issues/priority`;
     case 'pull_request_read.get':
       return `GET ${repoPath}/pulls/${pull}`;
     case 'pull_request_read.get_diff':
@@ -245,7 +344,9 @@ function githubOperationRoute(
     case 'update_pull_request.':
       return `PATCH ${repoPath}/pulls/${pull}`;
     case 'add_reply_to_pull_request_comment.':
-      return `POST ${repoPath}/pulls/{comment_id}/replies`;
+      return args.reaction !== undefined && args.body === undefined
+        ? `POST ${repoPath}/pulls/comments/{comment_id}/reactions`
+        : `POST ${repoPath}/pulls/${pull}/comments/{comment_id}/replies`;
     case 'merge_pull_request.':
       return `PUT ${repoPath}/pulls/${pull}/merge`;
     case 'update_pull_request_branch.':
@@ -257,7 +358,7 @@ function githubOperationRoute(
     case 'pull_request_review_write.delete_pending':
       return `DELETE ${repoPath}/pulls/${pull}/reviews/{review_id}`;
     case 'add_comment_to_pending_review.':
-      return `POST ${repoPath}/pulls/${pull}/comments`;
+      return GITHUB_GRAPHQL_ROUTE;
     case 'actions_list.list_workflows':
       return `GET ${repoPath}/actions/workflows`;
     case 'actions_list.list_workflow_runs':
@@ -273,7 +374,7 @@ function githubOperationRoute(
     case 'actions_get.get_workflow_job':
       return `GET ${repoPath}/actions/jobs/${resource}`;
     case 'actions_get.download_workflow_run_artifact':
-      return `GET ${repoPath}/actions/artifacts/${resource}/{archive_format}`;
+      return GITHUB_ARTIFACT_DOWNLOAD_ROUTE;
     case 'actions_get.get_workflow_run_usage':
       return `GET ${repoPath}/actions/runs/${resource}/timing`;
     case 'actions_get.get_workflow_run_logs_url':
@@ -295,7 +396,65 @@ function githubOperationRoute(
   }
 }
 
-function projectGithubOperationParameters(
+async function addCommentToPendingReview(
+  client: GithubToolClient,
+  args: Record<string, unknown>,
+): Promise<unknown | undefined> {
+  if (client.graphql === undefined) {
+    throw new GithubIntegrationProviderError(
+      'malformed-provider-response',
+      'GitHub client does not support GraphQL operations',
+    );
+  }
+
+  const reviewLookup = await client.graphql(LATEST_PENDING_REVIEW_QUERY, {
+    owner: args.owner,
+    repo: args.repo,
+    pullNumber: args.pull_number,
+  });
+  const reviewId = latestPendingReviewNodeId(reviewLookup);
+  if (reviewId === undefined) return undefined;
+
+  const input: Record<string, unknown> = {
+    pullRequestReviewId: reviewId,
+    path: args.path,
+    body: args.body,
+    subjectType: args.subject_type,
+  };
+  if (args.line !== undefined) input.line = args.line;
+  if (args.side !== undefined) input.side = args.side;
+  if (args.start_line !== undefined) input.startLine = args.start_line;
+  if (args.start_side !== undefined) input.startSide = args.start_side;
+
+  return await client.graphql(ADD_PENDING_REVIEW_COMMENT_MUTATION, {input});
+}
+
+function latestPendingReviewNodeId(data: unknown): string | undefined {
+  if (!isRecord(data)) return undefined;
+
+  const viewer = isRecord(data.viewer) ? data.viewer.login : undefined;
+  if (typeof viewer !== 'string') return undefined;
+
+  const repository = isRecord(data.repository) ? data.repository : undefined;
+  const pullRequest =
+    repository && isRecord(repository.pullRequest) ? repository.pullRequest : undefined;
+  const reviews = pullRequest && isRecord(pullRequest.reviews) ? pullRequest.reviews : undefined;
+  const nodes = reviews && Array.isArray(reviews.nodes) ? reviews.nodes : [];
+
+  let latest: {createdAt: string; id: string} | undefined;
+  for (const node of nodes) {
+    if (!isRecord(node)) continue;
+    const author = isRecord(node.author) ? node.author.login : undefined;
+    const id = node.id;
+    const createdAt = node.createdAt;
+    if (author !== viewer || typeof id !== 'string' || typeof createdAt !== 'string') continue;
+    if (latest === undefined || createdAt > latest.createdAt) latest = {createdAt, id};
+  }
+
+  return latest?.id;
+}
+
+export function projectGithubOperationParameters(
   toolId: GithubAgentToolId,
   method: string | undefined,
   args: Record<string, unknown>,
@@ -312,8 +471,70 @@ function projectGithubOperationParameters(
   return parameters;
 }
 
-function githubToolResult(toolId: GithubAgentToolId, data: unknown): GithubToolCallResult {
-  const structuredContent = projectGithubToolOutput(toolId, data);
+async function resolvePendingReviewParameters(
+  client: GithubToolClient,
+  parameters: Record<string, unknown>,
+  toolId: GithubAgentToolId,
+  method: string | undefined,
+): Promise<Record<string, unknown> | undefined> {
+  if (!isPendingReviewOperation(toolId, method)) return parameters;
+
+  const reviewId = await latestPendingReviewId(client, parameters);
+  return reviewId === undefined ? undefined : {...parameters, review_id: reviewId};
+}
+
+function isPendingReviewOperation(toolId: GithubAgentToolId, method: string | undefined): boolean {
+  return (
+    toolId === 'pull_request_review_write' &&
+    (method === 'submit_pending' || method === 'delete_pending')
+  );
+}
+
+async function latestPendingReviewId(
+  client: GithubToolClient,
+  parameters: Record<string, unknown>,
+): Promise<number | undefined> {
+  const perPage = 100;
+  let page = 1;
+  let reviewId: number | undefined;
+
+  while (true) {
+    const response = await client.request('GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews', {
+      owner: parameters.owner,
+      repo: parameters.repo,
+      pull_number: parameters.pull_number,
+      per_page: perPage,
+      page,
+    });
+    if (!Array.isArray(response.data)) return undefined;
+
+    reviewId = latestPendingReviewIdOnPage(response.data) ?? reviewId;
+    if (response.data.length < perPage) return reviewId;
+    page += 1;
+  }
+}
+
+function latestPendingReviewIdOnPage(data: readonly unknown[]): number | undefined {
+  for (let index = data.length - 1; index >= 0; index -= 1) {
+    const review = data[index];
+    if (!isRecord(review) || review.state !== 'PENDING') continue;
+    if (typeof review.id === 'number' && Number.isSafeInteger(review.id)) return review.id;
+  }
+
+  return undefined;
+}
+
+function githubToolResult(
+  toolId: GithubAgentToolId,
+  data: unknown,
+  response?: GithubToolResponse,
+  parameters?: Record<string, unknown>,
+  route?: string,
+): GithubToolCallResult {
+  const structuredContent = projectGithubToolOutput(toolId, data, response, parameters, route);
+  if (structuredContent === undefined) {
+    return githubToolError('GitHub artifact download did not return a download URL');
+  }
   return {
     content: [{type: 'text', text: JSON.stringify(structuredContent)}],
     structuredContent,
@@ -323,7 +544,14 @@ function githubToolResult(toolId: GithubAgentToolId, data: unknown): GithubToolC
 function projectGithubToolOutput(
   toolId: GithubAgentToolId,
   data: unknown,
-): Record<string, unknown> {
+  response?: GithubToolResponse,
+  parameters?: Record<string, unknown>,
+  route?: string,
+): Record<string, unknown> | undefined {
+  if (route === GITHUB_ARTIFACT_DOWNLOAD_ROUTE) {
+    return projectGithubArtifactDownloadOutput(response, parameters);
+  }
+
   switch (toolId) {
     case 'list_issue_types':
       return {issue_types: data};
@@ -345,6 +573,30 @@ function projectGithubToolOutput(
   }
 }
 
+function projectGithubArtifactDownloadOutput(
+  response: GithubToolResponse | undefined,
+  parameters: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (response === undefined) return undefined;
+  const downloadUrl = response.headers?.location;
+  if (typeof downloadUrl !== 'string' || downloadUrl.length === 0) return undefined;
+
+  const output: Record<string, unknown> = {
+    archive_format: GITHUB_ARTIFACT_ARCHIVE_FORMAT,
+    download_url: downloadUrl,
+  };
+  if (typeof parameters?.resource_id === 'string') output.artifact_id = parameters.resource_id;
+
+  const contentType = response.headers?.['content-type'];
+  if (typeof contentType === 'string') output.content_type = contentType;
+
+  const contentLength = response.headers?.['content-length'];
+  const sizeBytes = typeof contentLength === 'number' ? contentLength : Number(contentLength);
+  if (Number.isSafeInteger(sizeBytes) && sizeBytes >= 0) output.size_bytes = sizeBytes;
+
+  return output;
+}
+
 function githubSearchItems(data: unknown): unknown {
   return isRecord(data) ? data.items : data;
 }

package/src/core/github-agent-tool-catalog.ts

@@ -670,7 +670,7 @@ export const githubAgentToolCatalog = [
     id: 'add_comment_to_pending_review',
     category: 'pull_requests',
     description:
-      "Add review comment to the requester's latest pending pull request review. A pending review needs to already exist to call this.",
+      "Add a review comment to the requester's latest pending pull request review. The comment remains part of that pending review until it is submitted; a pending review needs to already exist to call this.",
     sensitivity: 'write',
     sensitive: false,
     requiredScope: scopes.pullRequestsWrite,