@shipfox/api-integration-github 12.6.0 → 13.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-github",
   "license": "MIT",
-  "version": "12.6.0",
+  "version": "13.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/api/client.test.ts

@@ -7,37 +7,211 @@ import {createGithubApiClient, mapGithubError} from './client.js';
 
 const GITHUB_INSTALLATION_TOKEN_PATTERN = /^ghs_[A-Za-z0-9._-]{36,}$/u;
 
-const {createInstallationAccessTokenMock, RequestErrorMock} = vi.hoisted(() => {
-  class RequestErrorMock extends Error {
-    constructor(
-      message: string,
-      public readonly status: number,
-    ) {
-      super(message);
-      this.name = 'HttpError';
+const {createInstallationAccessTokenMock, getByUsernameMock, octokitOptionsMock, RequestErrorMock} =
+  vi.hoisted(() => {
+    class RequestErrorMock extends Error {
+      constructor(
+        message: string,
+        public readonly status: number,
+      ) {
+        super(message);
+        this.name = 'HttpError';
+      }
     }
-  }
 
-  return {createInstallationAccessTokenMock: vi.fn(), RequestErrorMock};
-});
+    return {
+      createInstallationAccessTokenMock: vi.fn(),
+      getByUsernameMock: vi.fn(),
+      octokitOptionsMock: vi.fn(),
+      RequestErrorMock,
+    };
+  });
 
 vi.mock('octokit', () => ({
   App: class App {
     octokit = {
-      rest: {apps: {createInstallationAccessToken: createInstallationAccessTokenMock}},
+      rest: {
+        apps: {createInstallationAccessToken: createInstallationAccessTokenMock},
+        users: {getByUsername: getByUsernameMock},
+      },
     };
   },
-  Octokit: {
-    plugin() {
-      return this;
-    },
-    defaults(options: unknown) {
+  Octokit: class Octokit {
+    rest = {users: {getByUsername: getByUsernameMock}};
+
+    constructor(options: unknown) {
+      octokitOptionsMock(options);
+    }
+
+    static plugin() {
+      return Octokit;
+    }
+
+    static defaults(options: unknown) {
       return {defaults: options};
-    },
+    }
   },
   RequestError: RequestErrorMock,
 }));
 
+describe('OctokitGithubApiClient.getBotUser', () => {
+  beforeEach(() => {
+    getByUsernameMock.mockReset();
+    octokitOptionsMock.mockReset();
+  });
+
+  it('shares one lookup for concurrent requests with the same token and caches the bot', async () => {
+    getByUsernameMock.mockResolvedValue({
+      data: {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'Bot'},
+    });
+    const client = createGithubApiClient();
+
+    const firstLookup = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_first',
+    });
+    const secondLookup = client.getBotUser({
+      username: 'SHIPFOX-AI[BOT]',
+      installationAccessToken: 'ghs_first',
+    });
+    const [first, second] = await Promise.all([firstLookup, secondLookup]);
+    const cached = await client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_third',
+    });
+
+    expect(first).toEqual({id: 307_629_549, login: 'shipfox-ai[bot]'});
+    expect(second).toEqual(first);
+    expect(cached).toEqual(first);
+    expect(getByUsernameMock).toHaveBeenCalledTimes(1);
+    expect(getByUsernameMock).toHaveBeenCalledWith({
+      username: 'shipfox-ai[bot]',
+      request: {signal: expect.any(AbortSignal)},
+    });
+    expect(octokitOptionsMock).toHaveBeenCalledWith({
+      auth: 'ghs_first',
+      baseUrl: 'https://api.github.com',
+    });
+  });
+
+  it('does not share an in-flight lookup across installation tokens', async () => {
+    getByUsernameMock.mockResolvedValue({
+      data: {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'Bot'},
+    });
+    const client = createGithubApiClient();
+
+    const firstLookup = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_first',
+    });
+    const secondLookup = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_second',
+    });
+
+    await expect(Promise.all([firstLookup, secondLookup])).resolves.toEqual([
+      {id: 307_629_549, login: 'shipfox-ai[bot]'},
+      {id: 307_629_549, login: 'shipfox-ai[bot]'},
+    ]);
+    expect(getByUsernameMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('evicts a failed lookup so a later request can retry', async () => {
+    getByUsernameMock
+      .mockRejectedValueOnce(new RequestErrorMock('GitHub unavailable', 503))
+      .mockResolvedValueOnce({
+        data: {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'Bot'},
+      });
+    const client = createGithubApiClient();
+
+    const failed = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_first',
+    });
+    await expect(failed).rejects.toMatchObject({reason: 'provider-unavailable'});
+    const retried = await client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_second',
+    });
+
+    expect(retried).toEqual({id: 307_629_549, login: 'shipfox-ai[bot]'});
+    expect(getByUsernameMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('maps a missing configured bot and retries after the username becomes available', async () => {
+    getByUsernameMock
+      .mockRejectedValueOnce(new RequestErrorMock('Not Found', 404))
+      .mockResolvedValueOnce({
+        data: {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'Bot'},
+      });
+    const client = createGithubApiClient();
+
+    const missing = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_installationtoken',
+    });
+    await expect(missing).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: 'Configured GitHub bot user shipfox-ai[bot] was not found',
+      status: 404,
+    });
+    const corrected = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_installationtoken',
+    });
+
+    await expect(corrected).resolves.toEqual({
+      id: 307_629_549,
+      login: 'shipfox-ai[bot]',
+    });
+    expect(getByUsernameMock).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([
+    ['a null body', null, 'GitHub bot user response is missing required fields'],
+    [
+      'an empty login',
+      {id: 307_629_549, login: '', type: 'Bot'},
+      'GitHub bot user response is missing required fields',
+    ],
+    [
+      'a zero id',
+      {id: 0, login: 'shipfox-ai[bot]', type: 'Bot'},
+      'GitHub bot user response is missing required fields',
+    ],
+    [
+      'a negative id',
+      {id: -1, login: 'shipfox-ai[bot]', type: 'Bot'},
+      'GitHub bot user response is missing required fields',
+    ],
+    [
+      'a fractional id',
+      {id: 1.5, login: 'shipfox-ai[bot]', type: 'Bot'},
+      'GitHub bot user response is missing required fields',
+    ],
+    [
+      'a non-bot account',
+      {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'User'},
+      'Configured GitHub username is not a bot account',
+    ],
+    [
+      'a different bot account',
+      {id: 307_629_549, login: 'another-app[bot]', type: 'Bot'},
+      'GitHub bot user response did not match the configured username',
+    ],
+  ])('rejects %s', async (_label, data, message) => {
+    getByUsernameMock.mockResolvedValue({data});
+    const client = createGithubApiClient();
+
+    const result = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_installationtoken',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'malformed-provider-response', message});
+  });
+});
+
 describe('mapGithubError', () => {
   it.each([400, 409, 422])('maps HTTP %i to a terminal provider rejection', async (status) => {
     const error = new RequestErrorMock(`GitHub rejected request with HTTP ${status}`, status);
@@ -62,6 +236,20 @@ describe('mapGithubError', () => {
       status: 503,
     });
   });
+
+  it('maps a request timeout cause to timeout', async () => {
+    const timeout = new Error('The operation was aborted due to timeout');
+    timeout.name = 'TimeoutError';
+    const error = new RequestErrorMock('fetch failed', 500);
+    error.cause = timeout;
+
+    const result = mapGithubError(() => Promise.reject(error));
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'timeout',
+      message: 'GitHub request timed out',
+    });
+  });
 });
 
 describe('OctokitGithubApiClient.createInstallationAccessToken', () => {

package/src/api/client.ts

@@ -1,5 +1,6 @@
 import {Buffer} from 'node:buffer';
-import {MAX_REPOSITORY_FILE_BYTES} from '@shipfox/api-integration-spi';
+import {isRecord, MAX_REPOSITORY_FILE_BYTES} from '@shipfox/api-integration-spi';
+import {logger} from '@shipfox/node-opentelemetry';
 import ky, {HTTPError, TimeoutError} from 'ky';
 import {App, Octokit, RequestError} from 'octokit';
 import {config, normalizedGithubApiBaseUrl, normalizedGithubPrivateKey} from '#config.js';
@@ -13,6 +14,7 @@ import {
 const NEXT_PAGE_RE = /[?&]page=(\d+)/;
 const TRAILING_SLASHES_RE = /\/+$/;
 const MAX_TREE_WALK_DEPTH = 10;
+const GITHUB_API_TIMEOUT_MS = 10_000;
 
 export interface GithubAccount {
   login: string;
@@ -66,7 +68,16 @@ export interface GithubUserInstallationPage {
   nextCursor: string | null;
 }
 
-export interface GithubApiClient {
+export interface GithubBotUser {
+  id: number;
+  login: string;
+}
+
+export interface GithubBotUserClient {
+  getBotUser(input: {username: string; installationAccessToken: string}): Promise<GithubBotUser>;
+}
+
+export interface GithubApiClient extends Partial<GithubBotUserClient> {
   exchangeOAuthCode(code: string): Promise<string>;
   listUserInstallations(input: {
     userAccessToken: string;
@@ -106,12 +117,17 @@ export interface GithubInstallationAccessToken {
   permissions?: Record<string, 'read' | 'write' | 'admin'> | undefined;
 }
 
-export function createGithubApiClient(): GithubApiClient {
+export function createGithubApiClient(): GithubApiClient & GithubBotUserClient {
   return new OctokitGithubApiClient();
 }
 
-class OctokitGithubApiClient implements GithubApiClient {
+class OctokitGithubApiClient implements GithubApiClient, GithubBotUserClient {
   private app: App | undefined;
+  private readonly botUsers = new Map<string, GithubBotUser>();
+  private readonly botUserLookups = new Map<
+    string,
+    {installationAccessToken: string; promise: Promise<GithubBotUser>}
+  >();
 
   async exchangeOAuthCode(code: string): Promise<string> {
     const body = await mapGithubOAuthError(() =>
@@ -136,6 +152,39 @@ class OctokitGithubApiClient implements GithubApiClient {
     return body.access_token;
   }
 
+  getBotUser(input: {username: string; installationAccessToken: string}): Promise<GithubBotUser> {
+    const cacheKey = input.username.trim().toLowerCase();
+    const cached = this.botUsers.get(cacheKey);
+    if (cached) return Promise.resolve(cached);
+
+    const pending = this.botUserLookups.get(cacheKey);
+    if (pending?.installationAccessToken === input.installationAccessToken) {
+      return pending.promise;
+    }
+
+    const lookup = this.fetchBotUser(input).then((botUser) => {
+      const resolved = this.botUsers.get(cacheKey);
+      if (resolved) return resolved;
+
+      this.botUsers.set(cacheKey, botUser);
+      logger().info(
+        {githubAppBotLogin: botUser.login, githubAppBotUserId: botUser.id},
+        'Resolved GitHub App bot identity',
+      );
+      return botUser;
+    });
+    const trackedLookup = lookup.finally(() => {
+      if (this.botUserLookups.get(cacheKey)?.promise === trackedLookup) {
+        this.botUserLookups.delete(cacheKey);
+      }
+    });
+    this.botUserLookups.set(cacheKey, {
+      installationAccessToken: input.installationAccessToken,
+      promise: trackedLookup,
+    });
+    return trackedLookup;
+  }
+
   async listUserInstallations(input: {
     userAccessToken: string;
     cursor?: string | undefined;
@@ -405,6 +454,72 @@ class OctokitGithubApiClient implements GithubApiClient {
     }
     return this.app;
   }
+
+  private async fetchBotUser(input: {
+    username: string;
+    installationAccessToken: string;
+  }): Promise<GithubBotUser> {
+    const octokit = new Octokit({
+      auth: input.installationAccessToken,
+      baseUrl: normalizedGithubApiBaseUrl(),
+    });
+    let response: Awaited<ReturnType<typeof octokit.rest.users.getByUsername>>;
+    try {
+      response = await mapGithubError(
+        () =>
+          octokit.rest.users.getByUsername({
+            username: input.username,
+            request: {signal: AbortSignal.timeout(GITHUB_API_TIMEOUT_MS)},
+          }),
+        'provider-rejected',
+      );
+    } catch (error) {
+      if (error instanceof GithubIntegrationProviderError && error.status === 404) {
+        throw new GithubIntegrationProviderError(
+          'provider-rejected',
+          `Configured GitHub bot user ${input.username} was not found`,
+          undefined,
+          error.status,
+        );
+      }
+      throw error;
+    }
+
+    const data: unknown = response.data;
+    if (!isRecord(data)) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub bot user response is missing required fields',
+      );
+    }
+    const {id, login, type} = data;
+    if (
+      typeof id !== 'number' ||
+      !Number.isSafeInteger(id) ||
+      id <= 0 ||
+      typeof login !== 'string' ||
+      login.trim().length === 0
+    ) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub bot user response is missing required fields',
+      );
+    }
+    if (type !== 'Bot') {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'Configured GitHub username is not a bot account',
+      );
+    }
+    const canonicalLogin = login.trim();
+    if (canonicalLogin.toLowerCase() !== input.username.trim().toLowerCase()) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub bot user response did not match the configured username',
+      );
+    }
+    return {id, login: canonicalLogin};
+  }
 }
 
 async function mapGithubOAuthError<T>(operation: () => Promise<T>): Promise<T> {
@@ -442,12 +557,16 @@ export async function mapGithubError<T>(
   notFoundReason:
     | 'repository-not-found'
     | 'installation-not-found'
-    | 'file-not-found' = 'repository-not-found',
+    | 'file-not-found'
+    | 'provider-rejected' = 'repository-not-found',
 ): Promise<T> {
   try {
     return await operation();
   } catch (error) {
     if (error instanceof GithubIntegrationProviderError) throw error;
+    if (isGithubTimeoutError(error)) {
+      throw new GithubIntegrationProviderError('timeout', 'GitHub request timed out');
+    }
     if (error instanceof RequestError) {
       if (error.status === 404) {
         throw new GithubIntegrationProviderError(
@@ -490,13 +609,16 @@ export async function mapGithubError<T>(
         );
       }
     }
-    if (error instanceof Error && error.name === 'AbortError') {
-      throw new GithubIntegrationProviderError('timeout', 'GitHub request timed out');
-    }
     throw error;
   }
 }
 
+function isGithubTimeoutError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.name === 'AbortError' || error.name === 'TimeoutError') return true;
+  return error.cause instanceof Error && isGithubTimeoutError(error.cause);
+}
+
 function isGithubRateLimitError(error: RequestError): boolean {
   return error.status === 403 && error.response?.headers['x-ratelimit-remaining'] === '0';
 }

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

@@ -83,6 +83,7 @@ const expectedCatalogRows = [
       'get_files',
       'get_commits',
       'get_review_comments',
+      'get_review_threads',
       'get_reviews',
       'get_comments',
       'get_check_runs',
@@ -148,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',
@@ -351,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',
@@ -429,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'},
@@ -663,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']},
@@ -841,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(
@@ -1546,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',