@shipfox/api-integration-github 12.5.0 → 12.7.0

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

@@ -12,6 +12,8 @@ import {
 } from '#core/agent-tools.js';
 import {createGithubIntegrationProvider} from '#index.js';
 
+const githubAppReviewUser = {login: 'shipfox-test[bot]'};
+
 const expectedCatalogRows = [
   {
     id: 'issue_read',
@@ -81,6 +83,7 @@ const expectedCatalogRows = [
       'get_files',
       'get_commits',
       'get_review_comments',
+      'get_review_threads',
       'get_reviews',
       'get_comments',
       'get_check_runs',
@@ -146,6 +149,14 @@ const expectedCatalogRows = [
     requiredScope: [{permission: 'pull_requests', access: 'write'}],
     methods: ['create', 'submit_pending', 'delete_pending'],
   },
+  {
+    id: 'pull_request_review_thread_write',
+    category: 'pull_requests',
+    sensitivity: 'write',
+    sensitive: false,
+    requiredScope: [{permission: 'pull_requests', access: 'write'}],
+    methods: ['resolve'],
+  },
   {
     id: 'add_comment_to_pending_review',
     category: 'pull_requests',
@@ -349,6 +360,12 @@ const githubOperationRouteCases = [
     args: {pull_number: 1},
     expectedRoute: 'GET /repos/{owner}/{repo}/pulls/{pull_number}/comments',
   },
+  {
+    toolId: 'pull_request_read',
+    method: 'get_review_threads',
+    args: {pull_number: 1},
+    expectedRoute: 'POST /graphql',
+  },
   {
     toolId: 'pull_request_read',
     method: 'get_reviews',
@@ -427,6 +444,12 @@ const githubOperationRouteCases = [
     runtimeInjectedProperties: ['review_id'],
     expectedRoute: 'DELETE /repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}',
   },
+  {
+    toolId: 'pull_request_review_thread_write',
+    method: 'resolve',
+    args: {thread_id: 'PRRT_kwDOExample'},
+    expectedRoute: 'POST /graphql',
+  },
   {
     toolId: 'add_comment_to_pending_review',
     args: {pull_number: 1, path: 'src/index.ts', body: 'Comment'},
@@ -661,6 +684,7 @@ describe('github agent tool catalog', () => {
       {properties: {method: {const: 'get_files'}}, required: []},
       {properties: {method: {const: 'get_commits'}}, required: []},
       {properties: {method: {const: 'get_review_comments'}}, required: []},
+      {properties: {method: {const: 'get_review_threads'}}, required: []},
       {properties: {method: {const: 'get_reviews'}}, required: []},
       {properties: {method: {const: 'get_comments'}}, required: []},
       {properties: {method: {const: 'get_check_runs'}}, required: ['ref']},
@@ -810,6 +834,7 @@ describe('github agent tool catalog', () => {
     expect(result).toEqual({
       isError: true,
       content: [{type: 'text', text: 'GitHub artifact download did not return a download URL'}],
+      structuredContent: {code: 'malformed-provider-response'},
     });
   });
 
@@ -838,6 +863,104 @@ describe('github agent tool catalog', () => {
     });
   });
 
+  it('reads pull request review threads through GraphQL', async () => {
+    const request = vi.fn();
+    const data = {
+      repository: {
+        pullRequest: {
+          reviewThreads: {
+            nodes: [
+              {
+                id: 'PRRT_kwDOExample',
+                isResolved: false,
+                comments: {
+                  nodes: [
+                    {
+                      id: 'PRRC_kwDOExample',
+                      databaseId: 7,
+                      body: 'Please handle this.',
+                      author: {login: 'reviewer'},
+                      path: 'src/index.ts',
+                      line: 42,
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        },
+      },
+    };
+    const graphql = vi.fn().mockResolvedValueOnce(data);
+    const provider = createAgentToolsProvider({request, graphql});
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [pullRequestReadTool()],
+      scope: undefined,
+    });
+
+    const result = await session.call({
+      toolId: 'pull_request_read',
+      arguments: {
+        method: 'get_review_threads',
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        cursor: 'cursor-1',
+      },
+    });
+
+    expect(request).not.toHaveBeenCalled();
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('reviewThreads(first: 100, after: $after)'),
+      {owner: 'shipfox', repo: 'platform', pullNumber: 2, after: 'cursor-1'},
+    );
+    const query = graphql.mock.calls[0]?.[0];
+    expect(query).toContain('isResolved');
+    expect(query).toContain('author');
+    expect(query).toContain('path');
+    expect(query).toContain('line');
+    expect(result).toEqual({
+      content: [{type: 'text', text: JSON.stringify(data)}],
+      structuredContent: data,
+    });
+  });
+
+  it('resolves a pull request review thread through GraphQL', async () => {
+    const request = vi.fn();
+    const data = {
+      resolveReviewThread: {
+        thread: {id: 'PRRT_kwDOExample', isResolved: true},
+      },
+    };
+    const graphql = vi.fn().mockResolvedValueOnce(data);
+    const provider = createAgentToolsProvider({request, graphql});
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [pullRequestReviewThreadWriteTool()],
+      scope: undefined,
+    });
+
+    const result = await session.call({
+      toolId: 'pull_request_review_thread_write',
+      arguments: {
+        method: 'resolve',
+        owner: 'shipfox',
+        repo: 'platform',
+        thread_id: 'PRRT_kwDOExample',
+      },
+    });
+
+    expect(request).not.toHaveBeenCalled();
+    expect(graphql).toHaveBeenCalledWith(expect.stringContaining('resolveReviewThread'), {
+      input: {threadId: 'PRRT_kwDOExample'},
+    });
+    expect(result).toEqual({
+      content: [{type: 'text', text: JSON.stringify(data)}],
+      structuredContent: data,
+    });
+  });
+
   it('projects issue comment reactions through the provider session', async () => {
     const request = vi.fn(() => Promise.resolve({data: {id: 7}}));
     const result = await callGithubToolWithRequest(
@@ -856,34 +979,22 @@ describe('github agent tool catalog', () => {
     });
   });
 
-  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',
-                },
-              ],
-            },
-          },
+  it('adds a comment to the latest caller pending review through GraphQL', async () => {
+    const request = vi.fn().mockResolvedValueOnce({
+      data: [
+        {id: 40, node_id: 'review-older', state: 'PENDING', user: githubAppReviewUser},
+        {id: 41, node_id: 'review-latest', state: 'PENDING', user: githubAppReviewUser},
+        {
+          id: 42,
+          node_id: 'another-review',
+          state: 'PENDING',
+          user: {login: 'another-user'},
         },
-      })
-      .mockResolvedValueOnce({
-        addPullRequestReviewThread: {thread: {id: 'thread-1'}},
-      });
+      ],
+    });
+    const graphql = vi.fn().mockResolvedValueOnce({
+      addPullRequestReviewThread: {thread: {id: 'thread-1'}},
+    });
     const provider = createAgentToolsProvider({request, graphql});
     const session = await provider.openSession({
       connection: connection(),
@@ -907,28 +1018,29 @@ describe('github agent tool catalog', () => {
       },
     });
 
-    expect(request).not.toHaveBeenCalled();
-    expect(graphql).toHaveBeenNthCalledWith(
-      1,
-      expect.stringContaining('reviews(last: 100, states: [PENDING])'),
-      {owner: 'shipfox', repo: 'platform', pullNumber: 2},
+    expect(request).toHaveBeenCalledWith(
+      'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
+      expect.objectContaining({
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        per_page: 100,
+        page: 1,
+      }),
     );
-    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(request.mock.calls[0]?.[1]).toHaveProperty('request.signal');
+    expect(graphql).toHaveBeenCalledWith(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: [
         {
@@ -941,23 +1053,17 @@ describe('github agent tool catalog', () => {
   });
 
   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 request = vi.fn().mockResolvedValueOnce({
+      data: [
+        {
+          id: 41,
+          node_id: 'another-review',
+          state: 'PENDING',
+          user: {login: 'another-user'},
         },
-      },
+      ],
     });
+    const graphql = vi.fn();
     const provider = createAgentToolsProvider({request, graphql});
     const session = await provider.openSession({
       connection: connection(),
@@ -976,8 +1082,8 @@ describe('github agent tool catalog', () => {
       },
     });
 
-    expect(graphql).toHaveBeenCalledTimes(1);
-    expect(request).not.toHaveBeenCalled();
+    expect(request).toHaveBeenCalledOnce();
+    expect(graphql).not.toHaveBeenCalled();
     expect(result).toEqual({
       isError: true,
       content: [
@@ -986,7 +1092,142 @@ describe('github agent tool catalog', () => {
           text: 'No pending pull request review found for the authenticated GitHub user.',
         },
       ],
+      structuredContent: {code: 'provider-rejected'},
+    });
+  });
+
+  it('returns an access-denied code when the installation lacks a required permission', async () => {
+    const provider = new GithubAgentToolsProvider({
+      getInstallationByConnectionId: vi.fn(() => Promise.resolve(installation())),
+      tokenProvider: {
+        getInstallationAccessToken: vi.fn(() =>
+          Promise.resolve({
+            token: 'installation-token',
+            expiresAt: new Date(),
+            permissions: {},
+          }),
+        ),
+      },
+    });
+    const tool = githubAgentToolCatalog.find((entry) => entry.id === 'list_issues');
+    if (!tool) throw new Error('Missing list_issues tool');
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [tool],
+      scope: undefined,
+    });
+
+    const result = await session.call({
+      toolId: 'list_issues',
+      arguments: {owner: 'shipfox', repo: 'platform'},
+    });
+
+    expect(result).toEqual({
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: 'GitHub installation token is missing permission for this operation',
+        },
+      ],
+      structuredContent: {code: 'access-denied'},
+    });
+  });
+
+  it('rejects a pending review without a GraphQL node ID', async () => {
+    const request = vi.fn().mockResolvedValueOnce({
+      data: [{id: 41, state: 'PENDING', user: githubAppReviewUser}],
+    });
+    const graphql = vi.fn();
+    const provider = createAgentToolsProvider({request, graphql});
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [pendingReviewTool()],
+      scope: undefined,
+    });
+
+    await expect(
+      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.',
+        },
+      }),
+    ).rejects.toMatchObject({
+      reason: 'malformed-provider-response',
+      message: 'GitHub pending pull request review did not include a node ID',
     });
+    expect(graphql).not.toHaveBeenCalled();
+  });
+
+  it('skips a malformed newer review for an older valid caller review', async () => {
+    const request = vi.fn().mockResolvedValueOnce({
+      data: [
+        {
+          id: 40,
+          node_id: 'review-valid',
+          state: 'PENDING',
+          user: githubAppReviewUser,
+        },
+        {id: 41, node_id: '   ', state: 'PENDING', user: githubAppReviewUser},
+      ],
+    });
+    const graphql = vi.fn().mockResolvedValueOnce({
+      addPullRequestReviewThread: {thread: {id: 'thread-1'}},
+    });
+    const provider = createAgentToolsProvider({request, graphql});
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [pendingReviewTool()],
+      scope: undefined,
+    });
+
+    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).toHaveBeenCalledWith(expect.stringContaining('addPullRequestReviewThread'), {
+      input: expect.objectContaining({pullRequestReviewId: 'review-valid'}),
+    });
+  });
+
+  it('rejects a malformed pending review list response', async () => {
+    const request = vi.fn().mockResolvedValueOnce({data: {reviews: []}});
+    const graphql = vi.fn();
+    const provider = createAgentToolsProvider({request, graphql});
+    const session = await provider.openSession({
+      connection: connection(),
+      tools: [pendingReviewTool()],
+      scope: undefined,
+    });
+
+    await expect(
+      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.',
+        },
+      }),
+    ).rejects.toMatchObject({
+      reason: 'malformed-provider-response',
+      message: 'GitHub pull request review list response was malformed',
+    });
+    expect(graphql).not.toHaveBeenCalled();
   });
 
   it('maps Octokit 4xx failures to terminal provider errors', async () => {
@@ -1040,6 +1281,7 @@ describe('github agent tool catalog', () => {
     expect(result).toEqual({
       isError: true,
       content: [{type: 'text', text: 'Missing required parameter: ref'}],
+      structuredContent: {code: 'invalid-request'},
     });
   });
 
@@ -1094,8 +1336,9 @@ describe('github agent tool catalog', () => {
       .mockResolvedValueOnce({
         data: [
           {id: 40, state: 'APPROVED'},
-          {id: 41, state: 'PENDING'},
-          {id: 42, state: 'PENDING'},
+          {id: 41, state: 'PENDING', user: githubAppReviewUser},
+          {id: 42, state: 'PENDING', user: githubAppReviewUser},
+          {id: 43, state: 'PENDING', user: {login: 'another-user'}},
         ],
       })
       .mockResolvedValueOnce({data: testCase.data});
@@ -1113,13 +1356,13 @@ describe('github agent tool catalog', () => {
     expect(request).toHaveBeenNthCalledWith(
       1,
       'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
-      {
+      expect.objectContaining({
         owner: 'shipfox',
         repo: 'platform',
         pull_number: 2,
         per_page: 100,
         page: 1,
-      },
+      }),
     );
     expect(request).toHaveBeenNthCalledWith(2, testCase.route, testCase.parameters);
   });
@@ -1128,9 +1371,17 @@ describe('github agent tool catalog', () => {
     const request = vi
       .fn()
       .mockResolvedValueOnce({
-        data: Array.from({length: 100}, (_, index) => ({id: index + 1, state: 'APPROVED'})),
+        data: [
+          ...Array.from({length: 99}, (_, index) => ({id: index + 1, state: 'APPROVED'})),
+          {id: 100, state: 'PENDING', user: githubAppReviewUser},
+        ],
+        headers: {
+          link: '<https://api.github.com/repositories/1/pulls/2/reviews?per_page=100&page=2>; rel="last"',
+        },
+      })
+      .mockResolvedValueOnce({
+        data: [{id: 101, state: 'PENDING', user: githubAppReviewUser}],
       })
-      .mockResolvedValueOnce({data: [{id: 101, state: 'PENDING'}]})
       .mockResolvedValueOnce({data: {id: 101, state: 'COMMENTED'}});
 
     const result = await callGithubToolWithRequest(
@@ -1153,24 +1404,24 @@ describe('github agent tool catalog', () => {
     expect(request).toHaveBeenNthCalledWith(
       1,
       'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
-      {
+      expect.objectContaining({
         owner: 'shipfox',
         repo: 'platform',
         pull_number: 2,
         per_page: 100,
         page: 1,
-      },
+      }),
     );
     expect(request).toHaveBeenNthCalledWith(
       2,
       'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
-      {
+      expect.objectContaining({
         owner: 'shipfox',
         repo: 'platform',
         pull_number: 2,
         per_page: 100,
         page: 2,
-      },
+      }),
     );
     expect(request).toHaveBeenNthCalledWith(
       3,
@@ -1186,6 +1437,61 @@ describe('github agent tool catalog', () => {
     );
   });
 
+  it('bounds pending review lookup to the newest review pages', async () => {
+    const request = vi.fn().mockResolvedValue({data: []});
+    request.mockResolvedValueOnce({
+      data: Array.from({length: 100}, (_, index) => ({id: index + 1, state: 'APPROVED'})),
+      headers: {
+        link: '<https://api.github.com/repositories/1/pulls/2/reviews?per_page=100&page=6>; rel="last"',
+      },
+    });
+
+    await expect(
+      callGithubToolWithRequest(
+        'pull_request_review_write',
+        {
+          method: 'submit_pending',
+          owner: 'shipfox',
+          repo: 'platform',
+          pull_number: 2,
+          body: 'Looks good.',
+          event: 'COMMENT',
+        },
+        request,
+      ),
+    ).rejects.toMatchObject({
+      reason: 'content-too-large',
+      message: 'GitHub pull request review history exceeded the pending review lookup limit',
+    });
+    expect(request).toHaveBeenCalledTimes(5);
+    expect(request.mock.calls.map((call) => call[1]?.page)).toEqual([1, 6, 5, 4, 3]);
+  });
+
+  it.each([0, -1])('rejects non-positive pending review ID %s', async (id) => {
+    const request = vi.fn().mockResolvedValueOnce({
+      data: [{id, state: 'PENDING', user: githubAppReviewUser}],
+    });
+
+    await expect(
+      callGithubToolWithRequest(
+        'pull_request_review_write',
+        {
+          method: 'submit_pending',
+          owner: 'shipfox',
+          repo: 'platform',
+          pull_number: 2,
+          body: 'Looks good.',
+          event: 'COMMENT',
+        },
+        request,
+      ),
+    ).rejects.toMatchObject({
+      reason: 'malformed-provider-response',
+      message: 'GitHub pending pull request review did not include a numeric ID',
+    });
+    expect(request).toHaveBeenCalledOnce();
+  });
+
   it.each([
     'submit_pending',
     'delete_pending',
@@ -1206,6 +1512,7 @@ describe('github agent tool catalog', () => {
           text: 'No pending pull request review found for the authenticated GitHub user.',
         },
       ],
+      structuredContent: {code: 'provider-rejected'},
     });
     expect(request).toHaveBeenCalledOnce();
   });
@@ -1359,6 +1666,20 @@ function pendingReviewTool() {
   return tool;
 }
 
+function pullRequestReadTool() {
+  const tool = githubAgentToolCatalog.find((entry) => entry.id === 'pull_request_read');
+  if (!tool) throw new Error('Missing pull_request_read tool');
+  return tool;
+}
+
+function pullRequestReviewThreadWriteTool() {
+  const tool = githubAgentToolCatalog.find(
+    (entry) => entry.id === 'pull_request_review_thread_write',
+  );
+  if (!tool) throw new Error('Missing pull_request_review_thread_write tool');
+  return tool;
+}
+
 function connection() {
   return {
     id: 'connection-1',