@shipfox/api-integration-github 12.3.0 → 12.6.0

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

@@ -1,13 +1,19 @@
+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';
 
+const githubAppReviewUser = {login: 'shipfox-test[bot]'};
+
 const expectedCatalogRows = [
   {
     id: 'issue_read',
@@ -200,6 +206,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 +547,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 +751,406 @@ 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'}],
+      structuredContent: {code: 'malformed-provider-response'},
+    });
+  });
+
+  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 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'},
+        },
+      ],
+    });
+    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,
+    });
+
+    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).toHaveBeenCalledWith(
+      'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews',
+      expect.objectContaining({
+        owner: 'shipfox',
+        repo: 'platform',
+        pull_number: 2,
+        per_page: 100,
+        page: 1,
+      }),
+    );
+    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: [
+        {
+          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().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(),
+      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(request).toHaveBeenCalledOnce();
+    expect(graphql).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          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 () => {
+    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',
@@ -379,7 +1161,240 @@ describe('github agent tool catalog', () => {
     expect(result).toEqual({
       isError: true,
       content: [{type: 'text', text: 'Missing required parameter: ref'}],
+      structuredContent: {code: 'invalid-request'},
+    });
+  });
+
+  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', user: githubAppReviewUser},
+          {id: 42, state: 'PENDING', user: githubAppReviewUser},
+          {id: 43, state: 'PENDING', user: {login: 'another-user'}},
+        ],
+      })
+      .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',
+      expect.objectContaining({
+        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: 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: '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',
+      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,
+      '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('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',
+  ] 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.',
+        },
+      ],
+      structuredContent: {code: 'provider-rejected'},
     });
+    expect(request).toHaveBeenCalledOnce();
   });
 
   it.each([
@@ -479,10 +1494,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 +1536,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 +1612,7 @@ function inputSchemaFor(id: (typeof githubAgentToolCatalog)[number]['id']) {
     oneOf?: unknown[] | undefined;
   };
 }
+
+function operationKey(toolId: GithubAgentToolId, method?: string) {
+  return `${toolId}.${method ?? ''}`;
+}