@shipfox/api-integration-github 12.2.0 → 12.5.0

package/src/core/agent-tools.test.ts

@@ -1,10 +1,14 @@
+import {RequestError} from 'octokit';
 import type {GithubApiClient} from '#api/client.js';
 import {DEFAULT_JOB_LOG_TAIL_LINES} from '#core/actions-logs.js';
 import {
   type GithubAgentToolId,
   GithubAgentToolsProvider,
+  type GithubToolClient,
   githubAgentToolCatalog,
   githubAgentToolSelectionCatalog,
+  githubOperationRoute,
+  projectGithubOperationParameters,
 } from '#core/agent-tools.js';
 import {createGithubIntegrationProvider} from '#index.js';
 
@@ -200,6 +204,331 @@ const expectedCatalogRows = [
   },
 ];
 
+type GithubOperationRouteCase = {
+  toolId: GithubAgentToolId;
+  method?: string;
+  args: Record<string, unknown>;
+  expectedRoute: string;
+  runtimeInjectedProperties?: readonly string[];
+};
+
+const githubOperationRouteCases = [
+  {
+    toolId: 'issue_read',
+    method: 'get',
+    args: {issue_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/issues/{issue_number}',
+  },
+  {
+    toolId: 'issue_read',
+    method: 'get_comments',
+    args: {issue_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/issues/{issue_number}/comments',
+  },
+  {
+    toolId: 'issue_read',
+    method: 'get_sub_issues',
+    args: {issue_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/issues/{issue_number}/sub_issues',
+  },
+  {
+    toolId: 'issue_read',
+    method: 'get_parent',
+    args: {issue_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/issues/{issue_number}/parent',
+  },
+  {
+    toolId: 'issue_read',
+    method: 'get_labels',
+    args: {issue_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/issues/{issue_number}/labels',
+  },
+  {
+    toolId: 'list_issue_types',
+    args: {owner: 'shipfox'},
+    expectedRoute: 'GET /orgs/{owner}/issue-types',
+  },
+  {
+    toolId: 'list_issue_types',
+    args: {owner: 'shipfox', repo: 'platform'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/issue-types',
+  },
+  {
+    toolId: 'list_issues',
+    args: {},
+    expectedRoute: 'GET /repos/{owner}/{repo}/issues',
+  },
+  {
+    toolId: 'search_issues',
+    args: {},
+    expectedRoute: 'GET /search/issues',
+  },
+  {
+    toolId: 'add_issue_comment',
+    args: {issue_number: 1, body: 'Comment'},
+    expectedRoute: 'POST /repos/{owner}/{repo}/issues/{issue_number}/comments',
+  },
+  {
+    toolId: 'add_issue_comment',
+    args: {issue_number: 1, reaction: '+1'},
+    expectedRoute: 'POST /repos/{owner}/{repo}/issues/{issue_number}/reactions',
+  },
+  {
+    toolId: 'add_issue_comment',
+    args: {issue_number: 1, reaction: '+1', body: 'Comment'},
+    expectedRoute: 'POST /repos/{owner}/{repo}/issues/{issue_number}/comments',
+  },
+  {
+    toolId: 'add_issue_comment',
+    args: {comment_id: 1, reaction: '+1'},
+    expectedRoute: 'POST /repos/{owner}/{repo}/issues/comments/{comment_id}/reactions',
+  },
+  {
+    toolId: 'issue_write',
+    method: 'create',
+    args: {},
+    expectedRoute: 'POST /repos/{owner}/{repo}/issues',
+  },
+  {
+    toolId: 'issue_write',
+    method: 'update',
+    args: {issue_number: 1},
+    expectedRoute: 'PATCH /repos/{owner}/{repo}/issues/{issue_number}',
+  },
+  {
+    toolId: 'sub_issue_write',
+    method: 'add',
+    args: {issue_number: 1},
+    expectedRoute: 'POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues',
+  },
+  {
+    toolId: 'sub_issue_write',
+    method: 'remove',
+    args: {issue_number: 1, sub_issue_id: 2},
+    expectedRoute: 'DELETE /repos/{owner}/{repo}/issues/{issue_number}/sub_issues/{sub_issue_id}',
+  },
+  {
+    toolId: 'sub_issue_write',
+    method: 'reprioritize',
+    args: {issue_number: 1, sub_issue_id: 2, after_id: 3},
+    expectedRoute: 'PATCH /repos/{owner}/{repo}/issues/{issue_number}/sub_issues/priority',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get',
+    args: {pull_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/pulls/{pull_number}',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_diff',
+    args: {pull_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/pulls/{pull_number}',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_status',
+    args: {pull_number: 1, ref: 'main'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/commits/{ref}/status',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_files',
+    args: {pull_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/pulls/{pull_number}/files',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_commits',
+    args: {pull_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/pulls/{pull_number}/commits',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_review_comments',
+    args: {pull_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/pulls/{pull_number}/comments',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_reviews',
+    args: {pull_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_comments',
+    args: {pull_number: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/issues/{pull_number}/comments',
+  },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_check_runs',
+    args: {pull_number: 1, ref: 'main'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/commits/{ref}/check-runs',
+  },
+  {
+    toolId: 'list_pull_requests',
+    args: {},
+    expectedRoute: 'GET /repos/{owner}/{repo}/pulls',
+  },
+  {
+    toolId: 'search_pull_requests',
+    args: {},
+    expectedRoute: 'GET /search/issues',
+  },
+  {
+    toolId: 'create_pull_request',
+    args: {},
+    expectedRoute: 'POST /repos/{owner}/{repo}/pulls',
+  },
+  {
+    toolId: 'update_pull_request',
+    args: {pull_number: 1},
+    expectedRoute: 'PATCH /repos/{owner}/{repo}/pulls/{pull_number}',
+  },
+  {
+    toolId: 'add_reply_to_pull_request_comment',
+    args: {pull_number: 1, comment_id: 2, body: 'Reply'},
+    expectedRoute: 'POST /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies',
+  },
+  {
+    toolId: 'add_reply_to_pull_request_comment',
+    args: {comment_id: 2, reaction: '+1'},
+    expectedRoute: 'POST /repos/{owner}/{repo}/pulls/comments/{comment_id}/reactions',
+  },
+  {
+    toolId: 'merge_pull_request',
+    args: {pull_number: 1},
+    expectedRoute: 'PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge',
+  },
+  {
+    toolId: 'update_pull_request_branch',
+    args: {pull_number: 1},
+    expectedRoute: 'PUT /repos/{owner}/{repo}/pulls/{pull_number}/update-branch',
+  },
+  {
+    toolId: 'pull_request_review_write',
+    method: 'create',
+    args: {pull_number: 1},
+    expectedRoute: 'POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
+  },
+  {
+    toolId: 'pull_request_review_write',
+    method: 'submit_pending',
+    args: {pull_number: 1},
+    runtimeInjectedProperties: ['review_id'],
+    expectedRoute: 'POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/events',
+  },
+  {
+    toolId: 'pull_request_review_write',
+    method: 'delete_pending',
+    args: {pull_number: 1},
+    runtimeInjectedProperties: ['review_id'],
+    expectedRoute: 'DELETE /repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}',
+  },
+  {
+    toolId: 'add_comment_to_pending_review',
+    args: {pull_number: 1, path: 'src/index.ts', body: 'Comment'},
+    expectedRoute: 'POST /graphql',
+  },
+  {
+    toolId: 'actions_list',
+    method: 'list_workflows',
+    args: {},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/workflows',
+  },
+  {
+    toolId: 'actions_list',
+    method: 'list_workflow_runs',
+    args: {resource_id: 'workflow'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/workflows/{resource_id}/runs',
+  },
+  {
+    toolId: 'actions_list',
+    method: 'list_workflow_jobs',
+    args: {resource_id: 'run'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/runs/{resource_id}/jobs',
+  },
+  {
+    toolId: 'actions_list',
+    method: 'list_workflow_run_artifacts',
+    args: {resource_id: 'run'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/runs/{resource_id}/artifacts',
+  },
+  {
+    toolId: 'actions_get',
+    method: 'get_workflow',
+    args: {resource_id: 'workflow'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/workflows/{resource_id}',
+  },
+  {
+    toolId: 'actions_get',
+    method: 'get_workflow_run',
+    args: {resource_id: 'run'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/runs/{resource_id}',
+  },
+  {
+    toolId: 'actions_get',
+    method: 'get_workflow_job',
+    args: {resource_id: 'job'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/jobs/{resource_id}',
+  },
+  {
+    toolId: 'actions_get',
+    method: 'download_workflow_run_artifact',
+    args: {resource_id: 'artifact'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/artifacts/{resource_id}/zip',
+  },
+  {
+    toolId: 'actions_get',
+    method: 'get_workflow_run_usage',
+    args: {resource_id: 'run'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/runs/{resource_id}/timing',
+  },
+  {
+    toolId: 'actions_get',
+    method: 'get_workflow_run_logs_url',
+    args: {resource_id: 'run'},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/runs/{resource_id}/logs',
+  },
+  {
+    toolId: 'actions_run_trigger',
+    method: 'run_workflow',
+    args: {workflow_id: 'ci.yml', ref: 'main'},
+    expectedRoute: 'POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches',
+  },
+  {
+    toolId: 'actions_run_trigger',
+    method: 'rerun_workflow_run',
+    args: {run_id: 1},
+    expectedRoute: 'POST /repos/{owner}/{repo}/actions/runs/{run_id}/rerun',
+  },
+  {
+    toolId: 'actions_run_trigger',
+    method: 'rerun_failed_jobs',
+    args: {run_id: 1},
+    expectedRoute: 'POST /repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs',
+  },
+  {
+    toolId: 'actions_run_trigger',
+    method: 'cancel_workflow_run',
+    args: {run_id: 1},
+    expectedRoute: 'POST /repos/{owner}/{repo}/actions/runs/{run_id}/cancel',
+  },
+  {
+    toolId: 'actions_run_trigger',
+    method: 'delete_workflow_run_logs',
+    args: {run_id: 1},
+    expectedRoute: 'DELETE /repos/{owner}/{repo}/actions/runs/{run_id}/logs',
+  },
+  {
+    toolId: 'get_job_logs',
+    args: {job_id: 1},
+    expectedRoute: 'GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs',
+  },
+] satisfies readonly GithubOperationRouteCase[];
+
 describe('github agent tool catalog', () => {
   it('matches the GitHub MCP-style tool rows', () => {
     const rows = githubAgentToolCatalog.map(
@@ -216,6 +545,57 @@ describe('github agent tool catalog', () => {
     expect(rows).toEqual(expectedCatalogRows);
   });
 
+  it('covers every catalog operation with an exact route case', () => {
+    const catalogOperationKeys = githubAgentToolCatalog.flatMap(
+      (entry) =>
+        entry.methods?.map((method) => operationKey(entry.id, method.id)) ?? [
+          operationKey(entry.id),
+        ],
+    );
+    const routeCaseOperationKeys = githubOperationRouteCases.map(({toolId, method}) =>
+      operationKey(toolId, method),
+    );
+
+    expect([...new Set(routeCaseOperationKeys)].sort()).toEqual(
+      [...new Set(catalogOperationKeys)].sort(),
+    );
+  });
+
+  it.each(
+    githubOperationRouteCases,
+  )('asserts the $toolId.$method route and its input placeholders', ({
+    toolId,
+    method,
+    args,
+    expectedRoute,
+    runtimeInjectedProperties = [],
+  }) => {
+    const route = githubOperationRoute(toolId, method, args);
+
+    expect(route).toBe(expectedRoute);
+    if (route === undefined) return;
+
+    const inputProperties = new Set(Object.keys(inputSchemaFor(toolId).properties ?? {}));
+    const undeclaredArguments = Object.keys(args).filter((name) => !inputProperties.has(name));
+    expect(undeclaredArguments).toEqual([]);
+
+    const projectedParameters = projectGithubOperationParameters(toolId, method, args);
+    const injectedProperties = new Set([
+      ...runtimeInjectedProperties,
+      ...Object.keys(projectedParameters).filter(
+        (name) => !inputProperties.has(name) && !Object.hasOwn(args, name),
+      ),
+    ]);
+    const placeholders = Array.from(route.matchAll(/\{([^{}]+)\}/g), (match) => match[1]).filter(
+      (name): name is string => name !== undefined,
+    );
+    const undeclaredPlaceholders = placeholders.filter(
+      (name) => !inputProperties.has(name) && !injectedProperties.has(name),
+    );
+
+    expect(undeclaredPlaceholders).toEqual([]);
+  });
+
   it('defines descriptions and schemas for every tool and method', () => {
     const entriesMissingCatalogData = githubAgentToolCatalog.filter(
       (entry) =>
@@ -369,6 +749,287 @@ describe('github agent tool catalog', () => {
     });
   });
 
+  it('returns artifact download metadata without buffering archive bytes', async () => {
+    const request = vi.fn(() =>
+      Promise.resolve({
+        status: 302,
+        headers: {
+          location: 'https://objects.example/artifact.zip?token=temporary',
+          'content-type': 'application/zip',
+          'content-length': '1234',
+        },
+        data: new ArrayBuffer(1024),
+      }),
+    );
+    const result = await callGithubToolWithRequest(
+      'actions_get',
+      {
+        method: 'download_workflow_run_artifact',
+        owner: 'shipfox',
+        repo: 'platform',
+        resource_id: '42',
+      },
+      request,
+    );
+    const expected = {
+      archive_format: 'zip',
+      download_url: 'https://objects.example/artifact.zip?token=temporary',
+      artifact_id: '42',
+      content_type: 'application/zip',
+      size_bytes: 1234,
+    };
+
+    expect(request).toHaveBeenCalledWith(
+      'GET /repos/{owner}/{repo}/actions/artifacts/{resource_id}/zip',
+      {owner: 'shipfox', repo: 'platform', resource_id: '42'},
+    );
+    expect(result).toEqual({
+      content: [{type: 'text', text: JSON.stringify(expected)}],
+      structuredContent: expected,
+    });
+  });
+
+  it('fails artifact downloads without a redirect URL instead of returning an empty success', async () => {
+    const result = await callGithubToolWithRequest(
+      'actions_get',
+      {
+        method: 'download_workflow_run_artifact',
+        owner: 'shipfox',
+        repo: 'platform',
+        resource_id: '42',
+      },
+      vi.fn(() =>
+        Promise.resolve({
+          status: 302,
+          headers: {},
+          data: new ArrayBuffer(0),
+        }),
+      ),
+    );
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'GitHub artifact download did not return a download URL'}],
+    });
+  });
+
+  it('projects get_diff request headers through the provider session', async () => {
+    const request = vi.fn(() => Promise.resolve({data: 'diff --git a/file b/file'}));
+    const result = await callGithubToolWithRequest(
+      'pull_request_read',
+      {
+        method: 'get_diff',
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+      },
+      request,
+    );
+
+    expect(request).toHaveBeenCalledWith('GET /repos/{owner}/{repo}/pulls/{pull_number}', {
+      owner: 'shipfox',
+      repo: 'platform',
+      pull_number: 2,
+      headers: {accept: 'application/vnd.github.diff'},
+    });
+    expect(result).toEqual({
+      content: [{type: 'text', text: '{"result":"diff --git a/file b/file"}'}],
+      structuredContent: {result: 'diff --git a/file b/file'},
+    });
+  });
+
+  it('projects issue comment reactions through the provider session', async () => {
+    const request = vi.fn(() => Promise.resolve({data: {id: 7}}));
+    const result = await callGithubToolWithRequest(
+      'add_issue_comment',
+      {owner: 'shipfox', repo: 'platform', issue_number: 1, reaction: '+1'},
+      request,
+    );
+
+    expect(request).toHaveBeenCalledWith(
+      'POST /repos/{owner}/{repo}/issues/{issue_number}/reactions',
+      {owner: 'shipfox', repo: 'platform', issue_number: 1, content: '+1'},
+    );
+    expect(result).toEqual({
+      content: [{type: 'text', text: '{"id":7}'}],
+      structuredContent: {id: 7},
+    });
+  });
+
+  it('adds a comment to the latest pending review through GraphQL', async () => {
+    const request = vi.fn();
+    const graphql = vi
+      .fn()
+      .mockResolvedValueOnce({
+        viewer: {login: 'shipfox-ai[bot]'},
+        repository: {
+          pullRequest: {
+            reviews: {
+              nodes: [
+                {
+                  id: 'review-older',
+                  author: {login: 'shipfox-ai[bot]'},
+                  createdAt: '2026-08-09T10:00:00Z',
+                },
+                {
+                  id: 'review-latest',
+                  author: {login: 'shipfox-ai[bot]'},
+                  createdAt: '2026-08-09T10:01:00Z',
+                },
+              ],
+            },
+          },
+        },
+      })
+      .mockResolvedValueOnce({
+        addPullRequestReviewThread: {thread: {id: 'thread-1'}},
+      });
+    const provider = createAgentToolsProvider({request, graphql});
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [pendingReviewTool()],
+      scope: undefined,
+    });
+
+    const result = await session.call({
+      toolId: 'add_comment_to_pending_review',
+      arguments: {
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        path: 'src/agent-tools.ts',
+        body: 'Please handle this error.',
+        subject_type: 'LINE',
+        line: 42,
+        side: 'RIGHT',
+        start_line: 40,
+        start_side: 'RIGHT',
+      },
+    });
+
+    expect(request).not.toHaveBeenCalled();
+    expect(graphql).toHaveBeenNthCalledWith(
+      1,
+      expect.stringContaining('reviews(last: 100, states: [PENDING])'),
+      {owner: 'shipfox', repo: 'platform', pullNumber: 2},
+    );
+    expect(graphql).toHaveBeenNthCalledWith(
+      2,
+      expect.stringContaining('addPullRequestReviewThread'),
+      {
+        input: {
+          pullRequestReviewId: 'review-latest',
+          path: 'src/agent-tools.ts',
+          body: 'Please handle this error.',
+          subjectType: 'LINE',
+          line: 42,
+          side: 'RIGHT',
+          startLine: 40,
+          startSide: 'RIGHT',
+        },
+      },
+    );
+    expect(result).toEqual({
+      content: [
+        {
+          type: 'text',
+          text: '{"addPullRequestReviewThread":{"thread":{"id":"thread-1"}}}',
+        },
+      ],
+      structuredContent: {addPullRequestReviewThread: {thread: {id: 'thread-1'}}},
+    });
+  });
+
+  it('returns an explicit error when there is no pending review for the caller', async () => {
+    const request = vi.fn();
+    const graphql = vi.fn().mockResolvedValueOnce({
+      viewer: {login: 'shipfox-ai[bot]'},
+      repository: {
+        pullRequest: {
+          reviews: {
+            nodes: [
+              {
+                id: 'review-other-user',
+                author: {login: 'another-user'},
+                createdAt: '2026-08-09T10:00:00Z',
+              },
+            ],
+          },
+        },
+      },
+    });
+    const provider = createAgentToolsProvider({request, graphql});
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [pendingReviewTool()],
+      scope: undefined,
+    });
+
+    const result = await session.call({
+      toolId: 'add_comment_to_pending_review',
+      arguments: {
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        path: 'src/agent-tools.ts',
+        body: 'Please handle this error.',
+      },
+    });
+
+    expect(graphql).toHaveBeenCalledTimes(1);
+    expect(request).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: 'No pending pull request review found for the authenticated GitHub user.',
+        },
+      ],
+    });
+  });
+
+  it('maps Octokit 4xx failures to terminal provider errors', async () => {
+    const providerError = new RequestError('commit_id is missing', 422, {
+      request: {
+        method: 'POST',
+        url: 'https://api.github.com/repos/shipfox/platform/issues/1',
+        headers: {},
+      },
+    });
+    const provider = new GithubAgentToolsProvider({
+      getInstallationByConnectionId: vi.fn(() => Promise.resolve(installation())),
+      tokenProvider: {
+        getInstallationAccessToken: vi.fn(() =>
+          Promise.resolve({
+            token: 'installation-token',
+            expiresAt: new Date(),
+            permissions: {issues: 'read' as const},
+          }),
+        ),
+      },
+      createClient: vi.fn(() => ({
+        request: vi.fn(() => Promise.reject(providerError)),
+      })),
+    });
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [githubAgentToolCatalog[0]],
+      scope: undefined,
+    });
+
+    await expect(
+      session.call({
+        toolId: 'issue_read',
+        arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      }),
+    ).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: 'commit_id is missing',
+      status: 422,
+    });
+  });
+
   it('requires a ref for pull request status and check-run reads', async () => {
     const result = await callGithubTool(
       'pull_request_read',
@@ -382,6 +1043,173 @@ describe('github agent tool catalog', () => {
     });
   });
 
+  it.each([
+    {
+      method: 'submit_pending',
+      arguments: {
+        method: 'submit_pending',
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        body: 'Please address this before merging.',
+        event: 'REQUEST_CHANGES',
+      },
+      route: 'POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/events',
+      parameters: {
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        body: 'Please address this before merging.',
+        event: 'REQUEST_CHANGES',
+        review_id: 42,
+      },
+      data: {id: 42, state: 'CHANGES_REQUESTED'},
+    },
+    {
+      method: 'delete_pending',
+      arguments: {
+        method: 'delete_pending',
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+      },
+      route: 'DELETE /repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}',
+      parameters: {
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        review_id: 42,
+      },
+      data: {id: 42, state: 'PENDING'},
+    },
+  ] satisfies Array<{
+    method: 'submit_pending' | 'delete_pending';
+    arguments: Record<string, unknown>;
+    route: string;
+    parameters: Record<string, unknown>;
+    data: unknown;
+  }>)('$method resolves the latest pending review before writing', async (testCase) => {
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce({
+        data: [
+          {id: 40, state: 'APPROVED'},
+          {id: 41, state: 'PENDING'},
+          {id: 42, state: 'PENDING'},
+        ],
+      })
+      .mockResolvedValueOnce({data: testCase.data});
+
+    const result = await callGithubToolWithRequest(
+      'pull_request_review_write',
+      testCase.arguments,
+      request,
+    );
+
+    expect(result).toEqual({
+      content: [{type: 'text', text: JSON.stringify(testCase.data)}],
+      structuredContent: testCase.data,
+    });
+    expect(request).toHaveBeenNthCalledWith(
+      1,
+      'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
+      {
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        per_page: 100,
+        page: 1,
+      },
+    );
+    expect(request).toHaveBeenNthCalledWith(2, testCase.route, testCase.parameters);
+  });
+
+  it('resolves a pending review from a later review page', async () => {
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce({
+        data: Array.from({length: 100}, (_, index) => ({id: index + 1, state: 'APPROVED'})),
+      })
+      .mockResolvedValueOnce({data: [{id: 101, state: 'PENDING'}]})
+      .mockResolvedValueOnce({data: {id: 101, state: 'COMMENTED'}});
+
+    const result = await callGithubToolWithRequest(
+      'pull_request_review_write',
+      {
+        method: 'submit_pending',
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        body: 'Looks good.',
+        event: 'COMMENT',
+      },
+      request,
+    );
+
+    expect(result).toEqual({
+      content: [{type: 'text', text: JSON.stringify({id: 101, state: 'COMMENTED'})}],
+      structuredContent: {id: 101, state: 'COMMENTED'},
+    });
+    expect(request).toHaveBeenNthCalledWith(
+      1,
+      'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
+      {
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        per_page: 100,
+        page: 1,
+      },
+    );
+    expect(request).toHaveBeenNthCalledWith(
+      2,
+      'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
+      {
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        per_page: 100,
+        page: 2,
+      },
+    );
+    expect(request).toHaveBeenNthCalledWith(
+      3,
+      'POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/events',
+      {
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        body: 'Looks good.',
+        event: 'COMMENT',
+        review_id: 101,
+      },
+    );
+  });
+
+  it.each([
+    'submit_pending',
+    'delete_pending',
+  ] as const)('%s reports when no pending review exists', async (method) => {
+    const request = vi.fn(() => Promise.resolve({data: []}));
+
+    const result = await callGithubToolWithRequest(
+      'pull_request_review_write',
+      {method, owner: 'shipfox', repo: 'platform', pull_number: 2},
+      request,
+    );
+
+    expect(result).toEqual({
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: 'No pending pull request review found for the authenticated GitHub user.',
+        },
+      ],
+    });
+    expect(request).toHaveBeenCalledOnce();
+  });
+
   it.each([
     {
       toolId: 'list_issue_types',
@@ -479,10 +1307,33 @@ async function callGithubTool(
   toolId: GithubAgentToolId,
   arguments_: Record<string, unknown>,
   data: unknown,
+) {
+  return await callGithubToolWithRequest(
+    toolId,
+    arguments_,
+    vi.fn(() => Promise.resolve({data})),
+  );
+}
+
+async function callGithubToolWithRequest(
+  toolId: GithubAgentToolId,
+  arguments_: Record<string, unknown>,
+  request: GithubToolClient['request'],
 ) {
   const tool = githubAgentToolCatalog.find((entry) => entry.id === toolId);
   if (!tool) throw new Error(`Missing GitHub tool: ${toolId}`);
-  const provider = new GithubAgentToolsProvider({
+  const provider = createAgentToolsProvider({request});
+  const session = await provider.openSession({
+    connection: connection(),
+    tools: [tool],
+    scope: undefined,
+  });
+
+  return await session.call({toolId, arguments: arguments_});
+}
+
+function createAgentToolsProvider(client: GithubToolClient) {
+  return new GithubAgentToolsProvider({
     getInstallationByConnectionId: vi.fn(() => Promise.resolve(installation())),
     tokenProvider: {
       getInstallationAccessToken: vi.fn(() =>
@@ -498,15 +1349,14 @@ async function callGithubTool(
         }),
       ),
     },
-    createClient: vi.fn(() => ({request: vi.fn(() => Promise.resolve({data}))})),
-  });
-  const session = await provider.openSession({
-    connection: connection(),
-    tools: [tool],
-    scope: undefined,
+    createClient: vi.fn(() => client),
   });
+}
 
-  return await session.call({toolId, arguments: arguments_});
+function pendingReviewTool() {
+  const tool = githubAgentToolCatalog.find((entry) => entry.id === 'add_comment_to_pending_review');
+  if (!tool) throw new Error('Missing add_comment_to_pending_review tool');
+  return tool;
 }
 
 function connection() {
@@ -575,3 +1425,7 @@ function inputSchemaFor(id: (typeof githubAgentToolCatalog)[number]['id']) {
     oneOf?: unknown[] | undefined;
   };
 }
+
+function operationKey(toolId: GithubAgentToolId, method?: string) {
+  return `${toolId}.${method ?? ''}`;
+}