@shipfox/api-integration-github 12.3.0 → 12.6.0

package/dist/api/shared-installation-token-cache.js

@@ -55,7 +55,7 @@ export class SharedInstallationTokenCache {
                 return tokenFromEnvelope(envelope);
             }
             recordInstallationTokenLookup('backoff');
-            throw providerErrorFromBackoff(envelope?.backoffReason ?? 'provider-unavailable', (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime());
+            throw providerErrorFromBackoff(envelope?.backoffReason ?? 'provider-unavailable', (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(), envelope?.backoffError);
         }
         let token;
         try {
@@ -73,7 +73,13 @@ export class SharedInstallationTokenCache {
                 expiresAt: envelope?.expiresAt,
                 permissions: envelope?.permissions,
                 backoffUntil: until,
-                backoffReason: classified.reason
+                backoffReason: classified.reason,
+                backoffError: {
+                    message: providerError.message,
+                    ...providerError.status === undefined ? {} : {
+                        status: providerError.status
+                    }
+                }
             }).catch((writeError)=>{
                 logger().warn({
                     installationId: params.installationId,
@@ -142,7 +148,7 @@ export class SharedInstallationTokenCache {
         }
         if (activeBackoff(params.envelope, initialNow)) {
             recordInstallationTokenLookup('backoff');
-            throw providerErrorFromBackoff(params.envelope.backoffReason, params.envelope.backoffUntil.getTime() - initialNow.getTime());
+            throw providerErrorFromBackoff(params.envelope.backoffReason, params.envelope.backoffUntil.getTime() - initialNow.getTime(), params.envelope.backoffError);
         }
         for (const delayMs of this.pollDelaysMs){
             await this.sleep(delayMs);
@@ -154,7 +160,7 @@ export class SharedInstallationTokenCache {
             }
             if (backoffActive(envelope, now)) {
                 recordInstallationTokenLookup('backoff');
-                throw providerErrorFromBackoff(envelope?.backoffReason ?? 'provider-unavailable', (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime());
+                throw providerErrorFromBackoff(envelope?.backoffReason ?? 'provider-unavailable', (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(), envelope?.backoffError);
             }
         }
         throw new GithubIntegrationProviderError('provider-unavailable', 'GitHub installation token mint is still in progress', 1);

package/dist/api/shared-installation-token-cache.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/api/shared-installation-token-cache.ts"],"sourcesContent":["import {setTimeout as sleepTimeout} from 'node:timers/promises';\nimport {reportError} from '@shipfox/node-error-monitoring';\nimport {logger} from '@shipfox/node-opentelemetry';\nimport {GithubIntegrationProviderError} from '#core/errors.js';\nimport {\n  recordInstallationTokenBackoff,\n  recordInstallationTokenLookup,\n  recordInstallationTokenMint,\n} from '#metrics/index.js';\nimport type {GithubInstallationAccessToken} from './client.js';\nimport {\n  backoffActive,\n  backoffMs,\n  classifyMintError,\n  type InstallationTokenEnvelope,\n  mintErrorClassForReason,\n  parseInstallationTokenEnvelope,\n  providerErrorFromBackoff,\n  stillValid,\n  toProviderError,\n  usable,\n} from './installation-token-envelope.js';\n\nexport interface InstallationTokenCache {\n  getOrMint(\n    installationId: number,\n    mint: () => Promise<GithubInstallationAccessToken>,\n  ): Promise<GithubInstallationAccessToken>;\n}\n\nexport type InstallationTokenLockResult<T> = {acquired: true; value: T} | {acquired: false};\n\nexport interface InstallationTokenSecretStore {\n  read(workspaceId: string, installationId: number): Promise<string | null>;\n  write(\n    workspaceId: string,\n    installationId: number,\n    envelope: InstallationTokenEnvelope,\n  ): Promise<void>;\n}\n\nexport interface SharedInstallationTokenCacheOptions {\n  secretStore: InstallationTokenSecretStore;\n  withLock: <T>(\n    installationId: number,\n    fn: () => Promise<T>,\n  ) => Promise<InstallationTokenLockResult<T>>;\n  resolveWorkspaceId: (installationId: number) => Promise<string>;\n  now?: (() => Date) | undefined;\n  sleep?: ((ms: number) => Promise<void>) | undefined;\n  pollDelaysMs?: number[] | undefined;\n  workspaceCacheTtlMs?: number | undefined;\n  mintTimeoutMs?: number | undefined;\n}\n\nconst DEFAULT_POLL_DELAYS_MS = [100, 200, 400, 500, 800];\nconst DEFAULT_WORKSPACE_CACHE_TTL_MS = 10 * 60 * 1000;\nconst DEFAULT_MINT_TIMEOUT_MS = 30 * 1000;\n\nexport class SharedInstallationTokenCache implements InstallationTokenCache {\n  private readonly workspaceIds = new Map<number, {workspaceId: string; expiresAtMs: number}>();\n  private readonly now: () => Date;\n  private readonly sleep: (ms: number) => Promise<void>;\n  private readonly pollDelaysMs: number[];\n  private readonly workspaceCacheTtlMs: number;\n  private readonly mintTimeoutMs: number;\n\n  constructor(private readonly options: SharedInstallationTokenCacheOptions) {\n    this.now = options.now ?? (() => new Date());\n    this.sleep = options.sleep ?? ((ms) => sleepTimeout(ms).then(() => undefined));\n    this.pollDelaysMs = options.pollDelaysMs ?? DEFAULT_POLL_DELAYS_MS;\n    this.workspaceCacheTtlMs = options.workspaceCacheTtlMs ?? DEFAULT_WORKSPACE_CACHE_TTL_MS;\n    this.mintTimeoutMs = options.mintTimeoutMs ?? DEFAULT_MINT_TIMEOUT_MS;\n  }\n\n  async getOrMint(\n    installationId: number,\n    mint: () => Promise<GithubInstallationAccessToken>,\n  ): Promise<GithubInstallationAccessToken> {\n    const workspaceId = await this.resolveWorkspaceId(installationId);\n    const envelope = await this.readEnvelope(workspaceId, installationId);\n    if (usable(envelope, this.now())) {\n      recordInstallationTokenLookup('db-hit');\n      return tokenFromEnvelope(envelope);\n    }\n\n    const result = await this.options.withLock(installationId, () =>\n      this.mintUnderLock({workspaceId, installationId, mint}),\n    );\n    if (result.acquired) return result.value;\n\n    return await this.serveStaleOrPoll({workspaceId, installationId, envelope});\n  }\n\n  private async mintUnderLock(params: {\n    workspaceId: string;\n    installationId: number;\n    mint: () => Promise<GithubInstallationAccessToken>;\n  }): Promise<GithubInstallationAccessToken> {\n    const envelope = await this.readEnvelope(params.workspaceId, params.installationId);\n    const now = this.now();\n    if (usable(envelope, now)) {\n      recordInstallationTokenLookup('db-hit');\n      return tokenFromEnvelope(envelope);\n    }\n\n    if (activeBackoff(envelope, now)) {\n      if (canServeStale(envelope, now)) {\n        recordInstallationTokenLookup('served-stale');\n        return tokenFromEnvelope(envelope);\n      }\n      recordInstallationTokenLookup('backoff');\n      throw providerErrorFromBackoff(\n        envelope?.backoffReason ?? 'provider-unavailable',\n        (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(),\n      );\n    }\n\n    let token: GithubInstallationAccessToken;\n    try {\n      token = await this.recordMint(params.mint);\n    } catch (error) {\n      const providerError = toProviderError(error);\n      const classified = classifyMintError(providerError);\n      const until = new Date(this.now().getTime() + backoffMs(classified));\n      recordInstallationTokenBackoff({reason: classified.reason, class: classified.class});\n\n      await this.writeEnvelope(params.workspaceId, params.installationId, {\n        token: envelope?.token,\n        expiresAt: envelope?.expiresAt,\n        permissions: envelope?.permissions,\n        backoffUntil: until,\n        backoffReason: classified.reason,\n      }).catch((writeError) => {\n        logger().warn(\n          {installationId: params.installationId, reason: classified.reason, error: writeError},\n          'github installation token backoff write failed',\n        );\n        reportError(writeError, {\n          boundary: 'integration.cache',\n          operation: 'write-backoff-envelope',\n          extra: {installationId: params.installationId},\n        });\n      });\n\n      if (\n        classified.class === 'transient' &&\n        envelope?.token &&\n        stillValid(envelope.expiresAt, this.now())\n      ) {\n        logger().warn(\n          {\n            installationId: params.installationId,\n            expiresAt: envelope.expiresAt?.toISOString(),\n            reason: classified.reason,\n            backoffUntil: until.toISOString(),\n          },\n          'github installation token mint failed; serving stale token',\n        );\n        recordInstallationTokenLookup('served-stale');\n        return tokenFromEnvelope(envelope);\n      }\n\n      logger().warn(\n        {\n          installationId: params.installationId,\n          reason: classified.reason,\n          backoffUntil: until.toISOString(),\n          error: providerError,\n        },\n        'github installation token mint failed; backoff recorded',\n      );\n      recordInstallationTokenLookup('backoff');\n      throw providerError;\n    }\n\n    try {\n      await this.writeEnvelope(params.workspaceId, params.installationId, {\n        token: token.token,\n        expiresAt: token.expiresAt,\n        permissions: token.permissions,\n      });\n    } catch (error) {\n      logger().warn(\n        {installationId: params.installationId, expiresAt: token.expiresAt.toISOString(), error},\n        'github installation token cache write failed after mint',\n      );\n      reportError(error, {\n        boundary: 'integration.cache',\n        operation: 'write-minted-token',\n        extra: {installationId: params.installationId},\n      });\n    }\n\n    logger().info(\n      {installationId: params.installationId, expiresAt: token.expiresAt.toISOString()},\n      'github installation token minted',\n    );\n    recordInstallationTokenLookup('minted');\n    return token;\n  }\n\n  private async serveStaleOrPoll(params: {\n    workspaceId: string;\n    installationId: number;\n    envelope: InstallationTokenEnvelope | undefined;\n  }): Promise<GithubInstallationAccessToken> {\n    const initialNow = this.now();\n    if (canServeStale(params.envelope, initialNow)) {\n      recordInstallationTokenLookup('served-stale');\n      return tokenFromEnvelope(params.envelope);\n    }\n    if (activeBackoff(params.envelope, initialNow)) {\n      recordInstallationTokenLookup('backoff');\n      throw providerErrorFromBackoff(\n        params.envelope.backoffReason,\n        params.envelope.backoffUntil.getTime() - initialNow.getTime(),\n      );\n    }\n\n    for (const delayMs of this.pollDelaysMs) {\n      await this.sleep(delayMs);\n      const envelope = await this.readEnvelope(params.workspaceId, params.installationId);\n      const now = this.now();\n      if (usable(envelope, now)) {\n        recordInstallationTokenLookup('contended-poll');\n        return tokenFromEnvelope(envelope);\n      }\n      if (backoffActive(envelope, now)) {\n        recordInstallationTokenLookup('backoff');\n        throw providerErrorFromBackoff(\n          envelope?.backoffReason ?? 'provider-unavailable',\n          (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(),\n        );\n      }\n    }\n\n    throw new GithubIntegrationProviderError(\n      'provider-unavailable',\n      'GitHub installation token mint is still in progress',\n      1,\n    );\n  }\n\n  private async recordMint(\n    mint: () => Promise<GithubInstallationAccessToken>,\n  ): Promise<GithubInstallationAccessToken> {\n    const startedAt = Date.now();\n    try {\n      const token = await withTimeout(mint(), this.mintTimeoutMs);\n      recordInstallationTokenMint({outcome: 'success', durationMs: Date.now() - startedAt});\n      return token;\n    } catch (error) {\n      recordInstallationTokenMint({outcome: 'failure', durationMs: Date.now() - startedAt});\n      throw error;\n    }\n  }\n\n  private async readEnvelope(\n    workspaceId: string,\n    installationId: number,\n  ): Promise<InstallationTokenEnvelope | undefined> {\n    const raw = await this.options.secretStore.read(workspaceId, installationId);\n    if (raw === null) return undefined;\n\n    const envelope = parseInstallationTokenEnvelope(raw);\n    if (envelope === undefined) {\n      logger().warn({installationId}, 'github installation token cache envelope failed to decode');\n    }\n    return envelope;\n  }\n\n  private async writeEnvelope(\n    workspaceId: string,\n    installationId: number,\n    envelope: InstallationTokenEnvelope,\n  ): Promise<void> {\n    await this.options.secretStore.write(workspaceId, installationId, envelope);\n  }\n\n  private async resolveWorkspaceId(installationId: number): Promise<string> {\n    const nowMs = this.now().getTime();\n    const cached = this.workspaceIds.get(installationId);\n    if (cached && cached.expiresAtMs > nowMs) return cached.workspaceId;\n\n    const workspaceId = await this.options.resolveWorkspaceId(installationId);\n    this.workspaceIds.set(installationId, {\n      workspaceId,\n      expiresAtMs: nowMs + this.workspaceCacheTtlMs,\n    });\n    return workspaceId;\n  }\n}\n\ntype ActiveBackoffEnvelope = InstallationTokenEnvelope & {\n  backoffUntil: Date;\n  backoffReason: NonNullable<InstallationTokenEnvelope['backoffReason']>;\n};\n\ntype TokenEnvelope = InstallationTokenEnvelope & {token: string; expiresAt: Date};\n\nfunction activeBackoff(\n  envelope: InstallationTokenEnvelope | undefined,\n  now: Date,\n): envelope is ActiveBackoffEnvelope {\n  return (\n    backoffActive(envelope, now) &&\n    envelope?.backoffUntil !== undefined &&\n    envelope.backoffReason !== undefined\n  );\n}\n\nfunction canServeStale(\n  envelope: InstallationTokenEnvelope | undefined,\n  now: Date,\n): envelope is TokenEnvelope {\n  const terminalBackoff =\n    activeBackoff(envelope, now) && mintErrorClassForReason(envelope.backoffReason) === 'terminal';\n  return (\n    envelope?.token !== undefined &&\n    envelope.expiresAt !== undefined &&\n    stillValid(envelope.expiresAt, now) &&\n    !terminalBackoff\n  );\n}\n\nfunction tokenFromEnvelope(envelope: InstallationTokenEnvelope): GithubInstallationAccessToken {\n  if (!envelope.token || !envelope.expiresAt) {\n    throw new GithubIntegrationProviderError(\n      'malformed-provider-response',\n      'GitHub installation token cache envelope is missing a token or expiry',\n    );\n  }\n  return {\n    token: envelope.token,\n    expiresAt: envelope.expiresAt,\n    ...(envelope.permissions === undefined ? {} : {permissions: envelope.permissions}),\n  };\n}\n\nfunction withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {\n  let timer: NodeJS.Timeout | undefined;\n  const timeout = new Promise<T>((_, reject) => {\n    timer = setTimeout(() => {\n      reject(\n        new GithubIntegrationProviderError(\n          'timeout',\n          'Timed out minting GitHub installation access token',\n        ),\n      );\n    }, timeoutMs);\n  });\n\n  return Promise.race([promise, timeout]).finally(() => {\n    if (timer) clearTimeout(timer);\n  });\n}\n"],"names":["setTimeout","sleepTimeout","reportError","logger","GithubIntegrationProviderError","recordInstallationTokenBackoff","recordInstallationTokenLookup","recordInstallationTokenMint","backoffActive","backoffMs","classifyMintError","mintErrorClassForReason","parseInstallationTokenEnvelope","providerErrorFromBackoff","stillValid","toProviderError","usable","DEFAULT_POLL_DELAYS_MS","DEFAULT_WORKSPACE_CACHE_TTL_MS","DEFAULT_MINT_TIMEOUT_MS","SharedInstallationTokenCache","options","workspaceIds","Map","now","Date","sleep","ms","then","undefined","pollDelaysMs","workspaceCacheTtlMs","mintTimeoutMs","getOrMint","installationId","mint","workspaceId","resolveWorkspaceId","envelope","readEnvelope","tokenFromEnvelope","result","withLock","mintUnderLock","acquired","value","serveStaleOrPoll","params","activeBackoff","canServeStale","backoffReason","backoffUntil","getTime","token","recordMint","error","providerError","classified","until","reason","class","writeEnvelope","expiresAt","permissions","catch","writeError","warn","boundary","operation","extra","toISOString","info","initialNow","delayMs","startedAt","withTimeout","outcome","durationMs","raw","secretStore","read","write","nowMs","cached","get","expiresAtMs","set","terminalBackoff","promise","timeoutMs","timer","timeout","Promise","_","reject","race","finally","clearTimeout"],"mappings":"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"}
+{"version":3,"sources":["../../src/api/shared-installation-token-cache.ts"],"sourcesContent":["import {setTimeout as sleepTimeout} from 'node:timers/promises';\nimport {reportError} from '@shipfox/node-error-monitoring';\nimport {logger} from '@shipfox/node-opentelemetry';\nimport {GithubIntegrationProviderError} from '#core/errors.js';\nimport {\n  recordInstallationTokenBackoff,\n  recordInstallationTokenLookup,\n  recordInstallationTokenMint,\n} from '#metrics/index.js';\nimport type {GithubInstallationAccessToken} from './client.js';\nimport {\n  backoffActive,\n  backoffMs,\n  classifyMintError,\n  type InstallationTokenEnvelope,\n  mintErrorClassForReason,\n  parseInstallationTokenEnvelope,\n  providerErrorFromBackoff,\n  stillValid,\n  toProviderError,\n  usable,\n} from './installation-token-envelope.js';\n\nexport interface InstallationTokenCache {\n  getOrMint(\n    installationId: number,\n    mint: () => Promise<GithubInstallationAccessToken>,\n  ): Promise<GithubInstallationAccessToken>;\n}\n\nexport type InstallationTokenLockResult<T> = {acquired: true; value: T} | {acquired: false};\n\nexport interface InstallationTokenSecretStore {\n  read(workspaceId: string, installationId: number): Promise<string | null>;\n  write(\n    workspaceId: string,\n    installationId: number,\n    envelope: InstallationTokenEnvelope,\n  ): Promise<void>;\n}\n\nexport interface SharedInstallationTokenCacheOptions {\n  secretStore: InstallationTokenSecretStore;\n  withLock: <T>(\n    installationId: number,\n    fn: () => Promise<T>,\n  ) => Promise<InstallationTokenLockResult<T>>;\n  resolveWorkspaceId: (installationId: number) => Promise<string>;\n  now?: (() => Date) | undefined;\n  sleep?: ((ms: number) => Promise<void>) | undefined;\n  pollDelaysMs?: number[] | undefined;\n  workspaceCacheTtlMs?: number | undefined;\n  mintTimeoutMs?: number | undefined;\n}\n\nconst DEFAULT_POLL_DELAYS_MS = [100, 200, 400, 500, 800];\nconst DEFAULT_WORKSPACE_CACHE_TTL_MS = 10 * 60 * 1000;\nconst DEFAULT_MINT_TIMEOUT_MS = 30 * 1000;\n\nexport class SharedInstallationTokenCache implements InstallationTokenCache {\n  private readonly workspaceIds = new Map<number, {workspaceId: string; expiresAtMs: number}>();\n  private readonly now: () => Date;\n  private readonly sleep: (ms: number) => Promise<void>;\n  private readonly pollDelaysMs: number[];\n  private readonly workspaceCacheTtlMs: number;\n  private readonly mintTimeoutMs: number;\n\n  constructor(private readonly options: SharedInstallationTokenCacheOptions) {\n    this.now = options.now ?? (() => new Date());\n    this.sleep = options.sleep ?? ((ms) => sleepTimeout(ms).then(() => undefined));\n    this.pollDelaysMs = options.pollDelaysMs ?? DEFAULT_POLL_DELAYS_MS;\n    this.workspaceCacheTtlMs = options.workspaceCacheTtlMs ?? DEFAULT_WORKSPACE_CACHE_TTL_MS;\n    this.mintTimeoutMs = options.mintTimeoutMs ?? DEFAULT_MINT_TIMEOUT_MS;\n  }\n\n  async getOrMint(\n    installationId: number,\n    mint: () => Promise<GithubInstallationAccessToken>,\n  ): Promise<GithubInstallationAccessToken> {\n    const workspaceId = await this.resolveWorkspaceId(installationId);\n    const envelope = await this.readEnvelope(workspaceId, installationId);\n    if (usable(envelope, this.now())) {\n      recordInstallationTokenLookup('db-hit');\n      return tokenFromEnvelope(envelope);\n    }\n\n    const result = await this.options.withLock(installationId, () =>\n      this.mintUnderLock({workspaceId, installationId, mint}),\n    );\n    if (result.acquired) return result.value;\n\n    return await this.serveStaleOrPoll({workspaceId, installationId, envelope});\n  }\n\n  private async mintUnderLock(params: {\n    workspaceId: string;\n    installationId: number;\n    mint: () => Promise<GithubInstallationAccessToken>;\n  }): Promise<GithubInstallationAccessToken> {\n    const envelope = await this.readEnvelope(params.workspaceId, params.installationId);\n    const now = this.now();\n    if (usable(envelope, now)) {\n      recordInstallationTokenLookup('db-hit');\n      return tokenFromEnvelope(envelope);\n    }\n\n    if (activeBackoff(envelope, now)) {\n      if (canServeStale(envelope, now)) {\n        recordInstallationTokenLookup('served-stale');\n        return tokenFromEnvelope(envelope);\n      }\n      recordInstallationTokenLookup('backoff');\n      throw providerErrorFromBackoff(\n        envelope?.backoffReason ?? 'provider-unavailable',\n        (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(),\n        envelope?.backoffError,\n      );\n    }\n\n    let token: GithubInstallationAccessToken;\n    try {\n      token = await this.recordMint(params.mint);\n    } catch (error) {\n      const providerError = toProviderError(error);\n      const classified = classifyMintError(providerError);\n      const until = new Date(this.now().getTime() + backoffMs(classified));\n      recordInstallationTokenBackoff({reason: classified.reason, class: classified.class});\n\n      await this.writeEnvelope(params.workspaceId, params.installationId, {\n        token: envelope?.token,\n        expiresAt: envelope?.expiresAt,\n        permissions: envelope?.permissions,\n        backoffUntil: until,\n        backoffReason: classified.reason,\n        backoffError: {\n          message: providerError.message,\n          ...(providerError.status === undefined ? {} : {status: providerError.status}),\n        },\n      }).catch((writeError) => {\n        logger().warn(\n          {installationId: params.installationId, reason: classified.reason, error: writeError},\n          'github installation token backoff write failed',\n        );\n        reportError(writeError, {\n          boundary: 'integration.cache',\n          operation: 'write-backoff-envelope',\n          extra: {installationId: params.installationId},\n        });\n      });\n\n      if (\n        classified.class === 'transient' &&\n        envelope?.token &&\n        stillValid(envelope.expiresAt, this.now())\n      ) {\n        logger().warn(\n          {\n            installationId: params.installationId,\n            expiresAt: envelope.expiresAt?.toISOString(),\n            reason: classified.reason,\n            backoffUntil: until.toISOString(),\n          },\n          'github installation token mint failed; serving stale token',\n        );\n        recordInstallationTokenLookup('served-stale');\n        return tokenFromEnvelope(envelope);\n      }\n\n      logger().warn(\n        {\n          installationId: params.installationId,\n          reason: classified.reason,\n          backoffUntil: until.toISOString(),\n          error: providerError,\n        },\n        'github installation token mint failed; backoff recorded',\n      );\n      recordInstallationTokenLookup('backoff');\n      throw providerError;\n    }\n\n    try {\n      await this.writeEnvelope(params.workspaceId, params.installationId, {\n        token: token.token,\n        expiresAt: token.expiresAt,\n        permissions: token.permissions,\n      });\n    } catch (error) {\n      logger().warn(\n        {installationId: params.installationId, expiresAt: token.expiresAt.toISOString(), error},\n        'github installation token cache write failed after mint',\n      );\n      reportError(error, {\n        boundary: 'integration.cache',\n        operation: 'write-minted-token',\n        extra: {installationId: params.installationId},\n      });\n    }\n\n    logger().info(\n      {installationId: params.installationId, expiresAt: token.expiresAt.toISOString()},\n      'github installation token minted',\n    );\n    recordInstallationTokenLookup('minted');\n    return token;\n  }\n\n  private async serveStaleOrPoll(params: {\n    workspaceId: string;\n    installationId: number;\n    envelope: InstallationTokenEnvelope | undefined;\n  }): Promise<GithubInstallationAccessToken> {\n    const initialNow = this.now();\n    if (canServeStale(params.envelope, initialNow)) {\n      recordInstallationTokenLookup('served-stale');\n      return tokenFromEnvelope(params.envelope);\n    }\n    if (activeBackoff(params.envelope, initialNow)) {\n      recordInstallationTokenLookup('backoff');\n      throw providerErrorFromBackoff(\n        params.envelope.backoffReason,\n        params.envelope.backoffUntil.getTime() - initialNow.getTime(),\n        params.envelope.backoffError,\n      );\n    }\n\n    for (const delayMs of this.pollDelaysMs) {\n      await this.sleep(delayMs);\n      const envelope = await this.readEnvelope(params.workspaceId, params.installationId);\n      const now = this.now();\n      if (usable(envelope, now)) {\n        recordInstallationTokenLookup('contended-poll');\n        return tokenFromEnvelope(envelope);\n      }\n      if (backoffActive(envelope, now)) {\n        recordInstallationTokenLookup('backoff');\n        throw providerErrorFromBackoff(\n          envelope?.backoffReason ?? 'provider-unavailable',\n          (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(),\n          envelope?.backoffError,\n        );\n      }\n    }\n\n    throw new GithubIntegrationProviderError(\n      'provider-unavailable',\n      'GitHub installation token mint is still in progress',\n      1,\n    );\n  }\n\n  private async recordMint(\n    mint: () => Promise<GithubInstallationAccessToken>,\n  ): Promise<GithubInstallationAccessToken> {\n    const startedAt = Date.now();\n    try {\n      const token = await withTimeout(mint(), this.mintTimeoutMs);\n      recordInstallationTokenMint({outcome: 'success', durationMs: Date.now() - startedAt});\n      return token;\n    } catch (error) {\n      recordInstallationTokenMint({outcome: 'failure', durationMs: Date.now() - startedAt});\n      throw error;\n    }\n  }\n\n  private async readEnvelope(\n    workspaceId: string,\n    installationId: number,\n  ): Promise<InstallationTokenEnvelope | undefined> {\n    const raw = await this.options.secretStore.read(workspaceId, installationId);\n    if (raw === null) return undefined;\n\n    const envelope = parseInstallationTokenEnvelope(raw);\n    if (envelope === undefined) {\n      logger().warn({installationId}, 'github installation token cache envelope failed to decode');\n    }\n    return envelope;\n  }\n\n  private async writeEnvelope(\n    workspaceId: string,\n    installationId: number,\n    envelope: InstallationTokenEnvelope,\n  ): Promise<void> {\n    await this.options.secretStore.write(workspaceId, installationId, envelope);\n  }\n\n  private async resolveWorkspaceId(installationId: number): Promise<string> {\n    const nowMs = this.now().getTime();\n    const cached = this.workspaceIds.get(installationId);\n    if (cached && cached.expiresAtMs > nowMs) return cached.workspaceId;\n\n    const workspaceId = await this.options.resolveWorkspaceId(installationId);\n    this.workspaceIds.set(installationId, {\n      workspaceId,\n      expiresAtMs: nowMs + this.workspaceCacheTtlMs,\n    });\n    return workspaceId;\n  }\n}\n\ntype ActiveBackoffEnvelope = InstallationTokenEnvelope & {\n  backoffUntil: Date;\n  backoffReason: NonNullable<InstallationTokenEnvelope['backoffReason']>;\n};\n\ntype TokenEnvelope = InstallationTokenEnvelope & {token: string; expiresAt: Date};\n\nfunction activeBackoff(\n  envelope: InstallationTokenEnvelope | undefined,\n  now: Date,\n): envelope is ActiveBackoffEnvelope {\n  return (\n    backoffActive(envelope, now) &&\n    envelope?.backoffUntil !== undefined &&\n    envelope.backoffReason !== undefined\n  );\n}\n\nfunction canServeStale(\n  envelope: InstallationTokenEnvelope | undefined,\n  now: Date,\n): envelope is TokenEnvelope {\n  const terminalBackoff =\n    activeBackoff(envelope, now) && mintErrorClassForReason(envelope.backoffReason) === 'terminal';\n  return (\n    envelope?.token !== undefined &&\n    envelope.expiresAt !== undefined &&\n    stillValid(envelope.expiresAt, now) &&\n    !terminalBackoff\n  );\n}\n\nfunction tokenFromEnvelope(envelope: InstallationTokenEnvelope): GithubInstallationAccessToken {\n  if (!envelope.token || !envelope.expiresAt) {\n    throw new GithubIntegrationProviderError(\n      'malformed-provider-response',\n      'GitHub installation token cache envelope is missing a token or expiry',\n    );\n  }\n  return {\n    token: envelope.token,\n    expiresAt: envelope.expiresAt,\n    ...(envelope.permissions === undefined ? {} : {permissions: envelope.permissions}),\n  };\n}\n\nfunction withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {\n  let timer: NodeJS.Timeout | undefined;\n  const timeout = new Promise<T>((_, reject) => {\n    timer = setTimeout(() => {\n      reject(\n        new GithubIntegrationProviderError(\n          'timeout',\n          'Timed out minting GitHub installation access token',\n        ),\n      );\n    }, timeoutMs);\n  });\n\n  return Promise.race([promise, timeout]).finally(() => {\n    if (timer) clearTimeout(timer);\n  });\n}\n"],"names":["setTimeout","sleepTimeout","reportError","logger","GithubIntegrationProviderError","recordInstallationTokenBackoff","recordInstallationTokenLookup","recordInstallationTokenMint","backoffActive","backoffMs","classifyMintError","mintErrorClassForReason","parseInstallationTokenEnvelope","providerErrorFromBackoff","stillValid","toProviderError","usable","DEFAULT_POLL_DELAYS_MS","DEFAULT_WORKSPACE_CACHE_TTL_MS","DEFAULT_MINT_TIMEOUT_MS","SharedInstallationTokenCache","options","workspaceIds","Map","now","Date","sleep","ms","then","undefined","pollDelaysMs","workspaceCacheTtlMs","mintTimeoutMs","getOrMint","installationId","mint","workspaceId","resolveWorkspaceId","envelope","readEnvelope","tokenFromEnvelope","result","withLock","mintUnderLock","acquired","value","serveStaleOrPoll","params","activeBackoff","canServeStale","backoffReason","backoffUntil","getTime","backoffError","token","recordMint","error","providerError","classified","until","reason","class","writeEnvelope","expiresAt","permissions","message","status","catch","writeError","warn","boundary","operation","extra","toISOString","info","initialNow","delayMs","startedAt","withTimeout","outcome","durationMs","raw","secretStore","read","write","nowMs","cached","get","expiresAtMs","set","terminalBackoff","promise","timeoutMs","timer","timeout","Promise","_","reject","race","finally","clearTimeout"],"mappings":"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"}

package/dist/config.d.ts

@@ -7,6 +7,7 @@ export declare const config: Readonly<{
     GITHUB_APP_SLUG: string;
     GITHUB_APP_USERNAME: string | undefined;
     GITHUB_API_BASE_URL: string;
+    GITHUB_INSTALLATION_TOKEN_FORMAT_OVERRIDE: "disabled" | "enabled" | undefined;
     GITHUB_INSTALL_STATE_SECRET: string;
 } & import("@shipfox/config").CleanedEnvAccessors>;
 export declare function normalizedGithubPrivateKey(): string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,MAAM;;;;;;;;;;kDA8BjB,CAAC;AAEH,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,MAAM;;;;;;;;;;;kDAmCjB,CAAC;AAEH,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD"}

package/dist/config.js

@@ -27,6 +27,14 @@ export const config = createConfig({
         desc: 'Base URL used for GitHub REST API requests. Set this only for GitHub Enterprise Server or a compatible test server.',
         default: 'https://api.github.com'
     }),
+    GITHUB_INSTALLATION_TOKEN_FORMAT_OVERRIDE: str({
+        desc: 'Temporary GitHub installation token format override. Set this to enabled to request stateless tokens, disabled to request stateful tokens, or leave it unset to follow the GitHub rollout.',
+        choices: [
+            'enabled',
+            'disabled'
+        ],
+        default: undefined
+    }),
     GITHUB_INSTALL_STATE_SECRET: str({
         desc: 'Secret used to sign the state token that protects the GitHub App install flow. Required.'
     })

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/config.ts"],"sourcesContent":["import {createConfig, str, url} from '@shipfox/config';\n\nconst trailingSlashesPattern = /\\/+$/u;\n\nexport const config = createConfig({\n  GITHUB_APP_ID: str({\n    desc: \"Numeric ID of the GitHub App, found on the app's settings page. Required.\",\n  }),\n  GITHUB_APP_PRIVATE_KEY: str({\n    desc: 'Private key of the GitHub App in PEM format, used to sign API requests. Newlines may be written as \\\\n and are restored at runtime. Required.',\n  }),\n  GITHUB_APP_CLIENT_ID: str({\n    desc: 'OAuth client ID of the GitHub App, used for user sign-in. Required.',\n  }),\n  GITHUB_APP_CLIENT_SECRET: str({\n    desc: 'OAuth client secret of the GitHub App. Required.',\n  }),\n  GITHUB_APP_WEBHOOK_SECRET: str({\n    desc: 'Secret used to verify the signature of incoming GitHub webhooks. Must match the value set on the GitHub App. Required.',\n  }),\n  GITHUB_APP_SLUG: str({\n    desc: 'URL slug of the GitHub App, used to build install and callback links. Required.',\n  }),\n  GITHUB_APP_USERNAME: str({\n    desc: 'GitHub App username used as the Git commit author when checkout credentials are persisted. Set this to the app username, such as my-app. The [bot] suffix is added automatically. Leave unset to keep Git author identity unset.',\n    default: undefined,\n  }),\n  GITHUB_API_BASE_URL: url({\n    desc: 'Base URL used for GitHub REST API requests. Set this only for GitHub Enterprise Server or a compatible test server.',\n    default: 'https://api.github.com',\n  }),\n  GITHUB_INSTALL_STATE_SECRET: str({\n    desc: 'Secret used to sign the state token that protects the GitHub App install flow. Required.',\n  }),\n});\n\nexport function normalizedGithubPrivateKey(): string {\n  return config.GITHUB_APP_PRIVATE_KEY.replaceAll('\\\\n', '\\n');\n}\n\nexport function normalizeGithubApiBaseUrl(baseUrl: string): string {\n  return baseUrl.replace(trailingSlashesPattern, '');\n}\n\nexport function normalizedGithubApiBaseUrl(): string {\n  return normalizeGithubApiBaseUrl(config.GITHUB_API_BASE_URL);\n}\n"],"names":["createConfig","str","url","trailingSlashesPattern","config","GITHUB_APP_ID","desc","GITHUB_APP_PRIVATE_KEY","GITHUB_APP_CLIENT_ID","GITHUB_APP_CLIENT_SECRET","GITHUB_APP_WEBHOOK_SECRET","GITHUB_APP_SLUG","GITHUB_APP_USERNAME","default","undefined","GITHUB_API_BASE_URL","GITHUB_INSTALL_STATE_SECRET","normalizedGithubPrivateKey","replaceAll","normalizeGithubApiBaseUrl","baseUrl","replace","normalizedGithubApiBaseUrl"],"mappings":"AAAA,SAAQA,YAAY,EAAEC,GAAG,EAAEC,GAAG,QAAO,kBAAkB;AAEvD,MAAMC,yBAAyB;AAE/B,OAAO,MAAMC,SAASJ,aAAa;IACjCK,eAAeJ,IAAI;QACjBK,MAAM;IACR;IACAC,wBAAwBN,IAAI;QAC1BK,MAAM;IACR;IACAE,sBAAsBP,IAAI;QACxBK,MAAM;IACR;IACAG,0BAA0BR,IAAI;QAC5BK,MAAM;IACR;IACAI,2BAA2BT,IAAI;QAC7BK,MAAM;IACR;IACAK,iBAAiBV,IAAI;QACnBK,MAAM;IACR;IACAM,qBAAqBX,IAAI;QACvBK,MAAM;QACNO,SAASC;IACX;IACAC,qBAAqBb,IAAI;QACvBI,MAAM;QACNO,SAAS;IACX;IACAG,6BAA6Bf,IAAI;QAC/BK,MAAM;IACR;AACF,GAAG;AAEH,OAAO,SAASW;IACd,OAAOb,OAAOG,sBAAsB,CAACW,UAAU,CAAC,OAAO;AACzD;AAEA,OAAO,SAASC,0BAA0BC,OAAe;IACvD,OAAOA,QAAQC,OAAO,CAAClB,wBAAwB;AACjD;AAEA,OAAO,SAASmB;IACd,OAAOH,0BAA0Bf,OAAOW,mBAAmB;AAC7D"}
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["import {createConfig, str, url} from '@shipfox/config';\n\nconst trailingSlashesPattern = /\\/+$/u;\n\nexport const config = createConfig({\n  GITHUB_APP_ID: str({\n    desc: \"Numeric ID of the GitHub App, found on the app's settings page. Required.\",\n  }),\n  GITHUB_APP_PRIVATE_KEY: str({\n    desc: 'Private key of the GitHub App in PEM format, used to sign API requests. Newlines may be written as \\\\n and are restored at runtime. Required.',\n  }),\n  GITHUB_APP_CLIENT_ID: str({\n    desc: 'OAuth client ID of the GitHub App, used for user sign-in. Required.',\n  }),\n  GITHUB_APP_CLIENT_SECRET: str({\n    desc: 'OAuth client secret of the GitHub App. Required.',\n  }),\n  GITHUB_APP_WEBHOOK_SECRET: str({\n    desc: 'Secret used to verify the signature of incoming GitHub webhooks. Must match the value set on the GitHub App. Required.',\n  }),\n  GITHUB_APP_SLUG: str({\n    desc: 'URL slug of the GitHub App, used to build install and callback links. Required.',\n  }),\n  GITHUB_APP_USERNAME: str({\n    desc: 'GitHub App username used as the Git commit author when checkout credentials are persisted. Set this to the app username, such as my-app. The [bot] suffix is added automatically. Leave unset to keep Git author identity unset.',\n    default: undefined,\n  }),\n  GITHUB_API_BASE_URL: url({\n    desc: 'Base URL used for GitHub REST API requests. Set this only for GitHub Enterprise Server or a compatible test server.',\n    default: 'https://api.github.com',\n  }),\n  GITHUB_INSTALLATION_TOKEN_FORMAT_OVERRIDE: str({\n    desc: 'Temporary GitHub installation token format override. Set this to enabled to request stateless tokens, disabled to request stateful tokens, or leave it unset to follow the GitHub rollout.',\n    choices: ['enabled', 'disabled'] as const,\n    default: undefined,\n  }),\n  GITHUB_INSTALL_STATE_SECRET: str({\n    desc: 'Secret used to sign the state token that protects the GitHub App install flow. Required.',\n  }),\n});\n\nexport function normalizedGithubPrivateKey(): string {\n  return config.GITHUB_APP_PRIVATE_KEY.replaceAll('\\\\n', '\\n');\n}\n\nexport function normalizeGithubApiBaseUrl(baseUrl: string): string {\n  return baseUrl.replace(trailingSlashesPattern, '');\n}\n\nexport function normalizedGithubApiBaseUrl(): string {\n  return normalizeGithubApiBaseUrl(config.GITHUB_API_BASE_URL);\n}\n"],"names":["createConfig","str","url","trailingSlashesPattern","config","GITHUB_APP_ID","desc","GITHUB_APP_PRIVATE_KEY","GITHUB_APP_CLIENT_ID","GITHUB_APP_CLIENT_SECRET","GITHUB_APP_WEBHOOK_SECRET","GITHUB_APP_SLUG","GITHUB_APP_USERNAME","default","undefined","GITHUB_API_BASE_URL","GITHUB_INSTALLATION_TOKEN_FORMAT_OVERRIDE","choices","GITHUB_INSTALL_STATE_SECRET","normalizedGithubPrivateKey","replaceAll","normalizeGithubApiBaseUrl","baseUrl","replace","normalizedGithubApiBaseUrl"],"mappings":"AAAA,SAAQA,YAAY,EAAEC,GAAG,EAAEC,GAAG,QAAO,kBAAkB;AAEvD,MAAMC,yBAAyB;AAE/B,OAAO,MAAMC,SAASJ,aAAa;IACjCK,eAAeJ,IAAI;QACjBK,MAAM;IACR;IACAC,wBAAwBN,IAAI;QAC1BK,MAAM;IACR;IACAE,sBAAsBP,IAAI;QACxBK,MAAM;IACR;IACAG,0BAA0BR,IAAI;QAC5BK,MAAM;IACR;IACAI,2BAA2BT,IAAI;QAC7BK,MAAM;IACR;IACAK,iBAAiBV,IAAI;QACnBK,MAAM;IACR;IACAM,qBAAqBX,IAAI;QACvBK,MAAM;QACNO,SAASC;IACX;IACAC,qBAAqBb,IAAI;QACvBI,MAAM;QACNO,SAAS;IACX;IACAG,2CAA2Cf,IAAI;QAC7CK,MAAM;QACNW,SAAS;YAAC;YAAW;SAAW;QAChCJ,SAASC;IACX;IACAI,6BAA6BjB,IAAI;QAC/BK,MAAM;IACR;AACF,GAAG;AAEH,OAAO,SAASa;IACd,OAAOf,OAAOG,sBAAsB,CAACa,UAAU,CAAC,OAAO;AACzD;AAEA,OAAO,SAASC,0BAA0BC,OAAe;IACvD,OAAOA,QAAQC,OAAO,CAACpB,wBAAwB;AACjD;AAEA,OAAO,SAASqB;IACd,OAAOH,0BAA0BjB,OAAOW,mBAAmB;AAC7D"}

package/dist/core/agent-tools.d.ts

@@ -1,7 +1,7 @@
 import type { AgentToolSelectionCatalog, AgentToolSession, AgentToolsProvider, IntegrationConnection, OpenAgentToolsSessionInput } from '@shipfox/api-integration-spi';
 import { type GithubInstallationTokenProvider } from '#api/installation-token-provider.js';
 import type { GithubInstallation } from '#db/installations.js';
-import { type GithubAgentToolCatalogEntry, type GithubAgentToolRequiredScope } from './github-agent-tool-catalog.js';
+import { type GithubAgentToolCatalogEntry, type GithubAgentToolId, type GithubAgentToolRequiredScope } from './github-agent-tool-catalog.js';
 export type { GithubAgentToolCatalogEntry, GithubAgentToolCategory, GithubAgentToolId, GithubAgentToolPermission, GithubAgentToolPermissionAccess, GithubAgentToolRequiredPermission, GithubAgentToolRequiredScope, GithubAgentToolSensitivity, } from './github-agent-tool-catalog.js';
 export { buildGithubAgentToolSelectionCatalog, DEFAULT_JOB_LOG_TAIL_LINES, githubAgentToolCatalog, githubAgentToolSelectionCatalog, } from './github-agent-tool-catalog.js';
 type GithubIntegrationConnection = IntegrationConnection<'github'>;
@@ -26,10 +26,17 @@ export interface GithubAgentToolsProviderOptions {
     tokenProvider?: GithubInstallationTokenProvider | undefined;
     createClient?: GithubToolClientFactory | undefined;
 }
+export interface GithubToolResponse {
+    data: unknown;
+    headers?: Record<string, string | number | undefined> | undefined;
+    status?: number | undefined;
+    url?: string | undefined;
+}
 export interface GithubToolClient {
-    request(route: string, parameters: Record<string, unknown>): Promise<{
-        data: unknown;
-    }>;
+    request(route: string, parameters: Record<string, unknown>): Promise<GithubToolResponse>;
+    graphql?: ((query: string, variables: Record<string, unknown>) => Promise<unknown>) | undefined;
 }
 export type GithubToolClientFactory = (token: string) => GithubToolClient;
+export declare function githubOperationRoute(toolId: GithubAgentToolId, method: string | undefined, args: Record<string, unknown>): string | undefined;
+export declare function projectGithubOperationParameters(toolId: GithubAgentToolId, method: string | undefined, args: Record<string, unknown>): Record<string, unknown>;
 //# sourceMappingURL=agent-tools.d.ts.map

package/dist/core/agent-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-tools.d.ts","sourceRoot":"","sources":["../../src/core/agent-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,yBAAyB,EACzB,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EACL,KAAK,2BAA2B,EAEhC,KAAK,4BAA4B,EAGlC,MAAM,gCAAgC,CAAC;AAExC,YAAY,EACV,2BAA2B,EAC3B,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EACzB,+BAA+B,EAC/B,iCAAiC,EACjC,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,oCAAoC,EACpC,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,gCAAgC,CAAC;AAExC,KAAK,2BAA2B,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;AAEnE,KAAK,oBAAoB,GAAG;IAC1B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,SAAS;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACzD,CAAC;AAEF,qBAAa,wBACX,YACE,kBAAkB,CAChB,2BAA2B,EAC3B,4BAA4B,EAC5B,OAAO,EACP,oBAAoB,CACrB;IAIS,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAEhE,YAA6B,OAAO,GAAE,+BAAoC,EAEzE;IAED,OAAO,IAAI,SAAS,2BAA2B,EAAE,CAEhD;IAED,gBAAgB,IAAI,yBAAyB,CAE5C;IAEK,WAAW,CACf,KAAK,EAAE,0BAA0B,CAAC,2BAA2B,EAAE,4BAA4B,CAAC,GAC3F,OAAO,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,CAAC,CA8CjD;CACF;AAED,MAAM,WAAW,+BAA+B;IAC9C,6BAA6B,CAAC,EAC1B,CAAC,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC,GACnE,SAAS,CAAC;IACd,aAAa,CAAC,EAAE,+BAA+B,GAAG,SAAS,CAAC;IAC5D,YAAY,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC;CACpD;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC,CAAC,CAAC;CACvF;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,gBAAgB,CAAC"}
+{"version":3,"file":"agent-tools.d.ts","sourceRoot":"","sources":["../../src/core/agent-tools.ts"],"names":[],"mappings":"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"}

package/dist/core/agent-tools.js

@@ -1,9 +1,30 @@
 import { Octokit } from 'octokit';
+import { mapGithubError } from '#api/client.js';
 import { createGithubInstallationTokenProvider } from '#api/installation-token-provider.js';
-import { normalizedGithubApiBaseUrl } from '#config.js';
+import { config, normalizedGithubApiBaseUrl } from '#config.js';
 import { GithubIntegrationProviderError } from './errors.js';
 import { githubAgentToolCatalog, githubAgentToolSelectionCatalog } from './github-agent-tool-catalog.js';
 export { buildGithubAgentToolSelectionCatalog, DEFAULT_JOB_LOG_TAIL_LINES, githubAgentToolCatalog, githubAgentToolSelectionCatalog } from './github-agent-tool-catalog.js';
+const GITHUB_GRAPHQL_ROUTE = 'POST /graphql';
+const GITHUB_ARTIFACT_ARCHIVE_FORMAT = 'zip';
+const GITHUB_ARTIFACT_DOWNLOAD_ROUTE = `GET /repos/{owner}/{repo}/actions/artifacts/{resource_id}/${GITHUB_ARTIFACT_ARCHIVE_FORMAT}`;
+const GITHUB_ARTIFACT_DOWNLOAD_TIMEOUT_MS = 30_000;
+const GITHUB_APP_BOT_SUFFIX = '[bot]';
+const PENDING_REVIEW_PAGE_SIZE = 100;
+const PENDING_REVIEW_MAX_PAGE_REQUESTS = 5;
+const PENDING_REVIEW_LOOKUP_TIMEOUT_MS = 15_000;
+const PENDING_REVIEW_PAGE_TIMEOUT_MS = 5_000;
+const PENDING_REVIEW_PAGE_PATTERN = /[?&]page=(\d+)/u;
+const NO_PENDING_REVIEW_MESSAGE = 'No pending pull request review found for the authenticated GitHub user.';
+const ADD_PENDING_REVIEW_COMMENT_MUTATION = `
+  mutation AddCommentToPendingReview($input: AddPullRequestReviewThreadInput!) {
+    addPullRequestReviewThread(input: $input) {
+      thread {
+        id
+      }
+    }
+  }
+`;
 export class GithubAgentToolsProvider {
     constructor(options = {}){
         this.options = options;
@@ -28,24 +49,28 @@ export class GithubAgentToolsProvider {
         return {
             call: async (call)=>{
                 const tool = input.tools.find((candidate)=>candidate.id === call.toolId);
-                if (!tool) return githubToolError(`Unknown GitHub tool: ${call.toolId}`);
+                if (!tool) return githubToolError(`Unknown GitHub tool: ${call.toolId}`, 'invalid-request');
                 const operation = resolveGithubOperation(tool, call);
-                if (operation === undefined) return githubToolError('Unknown GitHub tool operation');
+                if (operation === undefined) return githubToolError('Unknown GitHub tool operation', 'invalid-request');
                 const validationError = validateGithubToolArguments(tool, call.arguments);
-                if (validationError) return githubToolError(validationError);
+                if (validationError) return githubToolError(validationError, 'invalid-request');
                 tokenPromise ??= this.tokenProvider.getInstallationAccessToken(installationId);
                 const token = await tokenPromise;
                 if (!hasGrantedPermissions(token.permissions ?? {}, tool, call)) {
-                    return githubToolError('GitHub installation token is missing permission for this operation');
+                    return githubToolError('GitHub installation token is missing permission for this operation', 'access-denied');
                 }
                 const client = (this.options.createClient ?? createOctokitClient)(token.token);
-                try {
-                    const response = await client.request(operation.route, operation.parameters);
-                    return githubToolResult(tool.id, response.data);
-                } catch (error) {
-                    if (error instanceof GithubIntegrationProviderError) return githubToolError(error.message);
-                    throw error;
+                const method = typeof call.arguments.method === 'string' ? call.arguments.method : undefined;
+                if (operation.kind === 'graphql') {
+                    const data = await mapGithubError(()=>addCommentToPendingReview(client, operation.parameters));
+                    return data === undefined ? githubToolError(NO_PENDING_REVIEW_MESSAGE, 'provider-rejected') : githubToolResult(tool.id, data);
+                }
+                const operationParameters = await mapGithubError(()=>resolvePendingReviewParameters(client, operation.parameters, tool.id, method));
+                if (operationParameters === undefined) {
+                    return githubToolError(NO_PENDING_REVIEW_MESSAGE, 'provider-rejected');
                 }
+                const response = await mapGithubError(()=>client.request(operation.route, operationParameters));
+                return githubToolResult(tool.id, response.data, response, operationParameters, operation.route);
             }
         };
     }
@@ -59,7 +84,26 @@ function createOctokitClient(token) {
         }
     });
     return {
-        request: async (route, parameters)=>await octokit.request(route, parameters)
+        request: async (route, parameters)=>{
+            if (route !== GITHUB_ARTIFACT_DOWNLOAD_ROUTE) {
+                return await octokit.request(route, parameters);
+            }
+            const abortController = new AbortController();
+            const timeout = setTimeout(()=>abortController.abort(), GITHUB_ARTIFACT_DOWNLOAD_TIMEOUT_MS);
+            try {
+                return await octokit.request(route, {
+                    ...parameters,
+                    request: {
+                        redirect: 'manual',
+                        parseSuccessResponseBody: false,
+                        signal: abortController.signal
+                    }
+                });
+            } finally{
+                clearTimeout(timeout);
+            }
+        },
+        graphql: async (query, variables)=>await octokit.graphql(query, variables)
     };
 }
 function resolveGithubOperation(tool, call) {
@@ -74,10 +118,11 @@ function resolveGithubOperation(tool, call) {
     const route = githubOperationRoute(toolId, method, params);
     return route === undefined ? undefined : {
         route,
-        parameters: projectGithubOperationParameters(toolId, method, params)
+        parameters: projectGithubOperationParameters(toolId, method, params),
+        kind: route === GITHUB_GRAPHQL_ROUTE ? 'graphql' : 'rest'
     };
 }
-function githubOperationRoute(toolId, method, args) {
+export function githubOperationRoute(toolId, method, args) {
     const owner = '{owner}';
     const repo = '{repo}';
     const issue = '{issue_number}';
@@ -114,7 +159,7 @@ function githubOperationRoute(toolId, method, args) {
         case 'sub_issue_write.remove':
             return `DELETE ${repoPath}/issues/${issue}/sub_issues/{sub_issue_id}`;
         case 'sub_issue_write.reprioritize':
-            return `PATCH ${repoPath}/issues/${issue}/sub_issues/{sub_issue_id}`;
+            return `PATCH ${repoPath}/issues/${issue}/sub_issues/priority`;
         case 'pull_request_read.get':
             return `GET ${repoPath}/pulls/${pull}`;
         case 'pull_request_read.get_diff':
@@ -142,7 +187,7 @@ function githubOperationRoute(toolId, method, args) {
         case 'update_pull_request.':
             return `PATCH ${repoPath}/pulls/${pull}`;
         case 'add_reply_to_pull_request_comment.':
-            return `POST ${repoPath}/pulls/{comment_id}/replies`;
+            return args.reaction !== undefined && args.body === undefined ? `POST ${repoPath}/pulls/comments/{comment_id}/reactions` : `POST ${repoPath}/pulls/${pull}/comments/{comment_id}/replies`;
         case 'merge_pull_request.':
             return `PUT ${repoPath}/pulls/${pull}/merge`;
         case 'update_pull_request_branch.':
@@ -154,7 +199,7 @@ function githubOperationRoute(toolId, method, args) {
         case 'pull_request_review_write.delete_pending':
             return `DELETE ${repoPath}/pulls/${pull}/reviews/{review_id}`;
         case 'add_comment_to_pending_review.':
-            return `POST ${repoPath}/pulls/${pull}/comments`;
+            return GITHUB_GRAPHQL_ROUTE;
         case 'actions_list.list_workflows':
             return `GET ${repoPath}/actions/workflows`;
         case 'actions_list.list_workflow_runs':
@@ -170,7 +215,7 @@ function githubOperationRoute(toolId, method, args) {
         case 'actions_get.get_workflow_job':
             return `GET ${repoPath}/actions/jobs/${resource}`;
         case 'actions_get.download_workflow_run_artifact':
-            return `GET ${repoPath}/actions/artifacts/${resource}/{archive_format}`;
+            return GITHUB_ARTIFACT_DOWNLOAD_ROUTE;
         case 'actions_get.get_workflow_run_usage':
             return `GET ${repoPath}/actions/runs/${resource}/timing`;
         case 'actions_get.get_workflow_run_logs_url':
@@ -191,7 +236,30 @@ function githubOperationRoute(toolId, method, args) {
             return undefined;
     }
 }
-function projectGithubOperationParameters(toolId, method, args) {
+async function addCommentToPendingReview(client, args) {
+    if (client.graphql === undefined) {
+        throw new GithubIntegrationProviderError('malformed-provider-response', 'GitHub client does not support GraphQL operations');
+    }
+    const review = await latestPendingReview(client, args, 'nodeId');
+    if (review === undefined) return undefined;
+    if (review.nodeId === undefined) {
+        throw new GithubIntegrationProviderError('malformed-provider-response', 'GitHub pending pull request review did not include a node ID');
+    }
+    const input = {
+        pullRequestReviewId: review.nodeId,
+        path: args.path,
+        body: args.body,
+        subjectType: args.subject_type
+    };
+    if (args.line !== undefined) input.line = args.line;
+    if (args.side !== undefined) input.side = args.side;
+    if (args.start_line !== undefined) input.startLine = args.start_line;
+    if (args.start_side !== undefined) input.startSide = args.start_side;
+    return await client.graphql(ADD_PENDING_REVIEW_COMMENT_MUTATION, {
+        input
+    });
+}
+export function projectGithubOperationParameters(toolId, method, args) {
     const parameters = {
         ...args
     };
@@ -207,8 +275,129 @@ function projectGithubOperationParameters(toolId, method, args) {
     }
     return parameters;
 }
-function githubToolResult(toolId, data) {
-    const structuredContent = projectGithubToolOutput(toolId, data);
+async function resolvePendingReviewParameters(client, parameters, toolId, method) {
+    if (!isPendingReviewOperation(toolId, method)) return parameters;
+    const review = await latestPendingReview(client, parameters, 'id');
+    if (review === undefined) return undefined;
+    if (review.id === undefined) {
+        throw new GithubIntegrationProviderError('malformed-provider-response', 'GitHub pending pull request review did not include a numeric ID');
+    }
+    return {
+        ...parameters,
+        review_id: review.id
+    };
+}
+function isPendingReviewOperation(toolId, method) {
+    return toolId === 'pull_request_review_write' && (method === 'submit_pending' || method === 'delete_pending');
+}
+async function latestPendingReview(client, parameters, requiredIdentifier) {
+    const lookupController = new AbortController();
+    const lookupTimeout = setTimeout(()=>lookupController.abort(), PENDING_REVIEW_LOOKUP_TIMEOUT_MS);
+    try {
+        return await latestPendingReviewBeforeDeadline(client, parameters, requiredIdentifier, lookupController.signal);
+    } finally{
+        clearTimeout(lookupTimeout);
+    }
+}
+async function latestPendingReviewBeforeDeadline(client, parameters, requiredIdentifier, lookupSignal) {
+    const firstPage = await requestPendingReviewPage(client, parameters, 1, lookupSignal);
+    const lastPage = pendingReviewLastPage(firstPage.headers);
+    let requests = 1;
+    let malformed = false;
+    for(let page = lastPage; page >= 1; page -= 1){
+        let response = firstPage;
+        if (page !== 1) {
+            if (requests >= PENDING_REVIEW_MAX_PAGE_REQUESTS) {
+                throw new GithubIntegrationProviderError('content-too-large', 'GitHub pull request review history exceeded the pending review lookup limit');
+            }
+            response = await requestPendingReviewPage(client, parameters, page, lookupSignal);
+            requests += 1;
+        }
+        if (!Array.isArray(response.data)) {
+            throw new GithubIntegrationProviderError('malformed-provider-response', 'GitHub pull request review list response was malformed');
+        }
+        const result = latestPendingReviewOnPage(response.data, requiredIdentifier);
+        if (result.review !== undefined) return result.review;
+        malformed ||= result.malformed;
+    }
+    if (malformed) {
+        throw new GithubIntegrationProviderError('malformed-provider-response', requiredIdentifier === 'nodeId' ? 'GitHub pending pull request review did not include a node ID' : 'GitHub pending pull request review did not include a numeric ID');
+    }
+    return undefined;
+}
+async function requestPendingReviewPage(client, parameters, page, lookupSignal) {
+    const pageController = new AbortController();
+    const abortPage = ()=>pageController.abort();
+    if (lookupSignal.aborted) abortPage();
+    else lookupSignal.addEventListener('abort', abortPage, {
+        once: true
+    });
+    const pageTimeout = setTimeout(abortPage, PENDING_REVIEW_PAGE_TIMEOUT_MS);
+    try {
+        return await client.request('GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews', {
+            owner: parameters.owner,
+            repo: parameters.repo,
+            pull_number: parameters.pull_number,
+            per_page: PENDING_REVIEW_PAGE_SIZE,
+            page,
+            request: {
+                signal: pageController.signal
+            }
+        });
+    } finally{
+        clearTimeout(pageTimeout);
+        lookupSignal.removeEventListener('abort', abortPage);
+    }
+}
+function pendingReviewLastPage(headers) {
+    const link = headers?.link;
+    if (typeof link !== 'string') return 1;
+    const lastLink = link.split(',').find((part)=>part.includes('rel="last"'));
+    if (lastLink === undefined) return 1;
+    const match = PENDING_REVIEW_PAGE_PATTERN.exec(lastLink);
+    const page = match?.[1] === undefined ? Number.NaN : Number.parseInt(match[1], 10);
+    if (!Number.isSafeInteger(page) || page < 1) {
+        throw new GithubIntegrationProviderError('malformed-provider-response', 'GitHub pull request review pagination response was malformed');
+    }
+    return page;
+}
+function latestPendingReviewOnPage(data, requiredIdentifier) {
+    let malformed = false;
+    const appLogin = githubAppBotLogin().toLowerCase();
+    for(let index = data.length - 1; index >= 0; index -= 1){
+        const review = data[index];
+        if (!isRecord(review) || review.state !== 'PENDING') continue;
+        const userLogin = isRecord(review.user) ? review.user.login : undefined;
+        if (typeof userLogin !== 'string' || userLogin.trim().length === 0) {
+            malformed = true;
+            continue;
+        }
+        if (userLogin.trim().toLowerCase() !== appLogin) continue;
+        const id = typeof review.id === 'number' && Number.isSafeInteger(review.id) && review.id > 0 ? review.id : undefined;
+        const nodeId = typeof review.node_id === 'string' && review.node_id.trim().length > 0 ? review.node_id.trim() : undefined;
+        const reference = {
+            id,
+            nodeId
+        };
+        if (reference[requiredIdentifier] !== undefined) return {
+            malformed,
+            review: reference
+        };
+        malformed = true;
+    }
+    return {
+        malformed
+    };
+}
+function githubAppBotLogin() {
+    const configuredUsername = config.GITHUB_APP_USERNAME?.trim() || config.GITHUB_APP_SLUG.trim();
+    return configuredUsername.toLowerCase().endsWith(GITHUB_APP_BOT_SUFFIX) ? configuredUsername : `${configuredUsername}${GITHUB_APP_BOT_SUFFIX}`;
+}
+function githubToolResult(toolId, data, response, parameters, route) {
+    const structuredContent = projectGithubToolOutput(toolId, data, response, parameters, route);
+    if (structuredContent === undefined) {
+        return githubToolError('GitHub artifact download did not return a download URL', 'malformed-provider-response');
+    }
     return {
         content: [
             {
@@ -219,7 +408,10 @@ function githubToolResult(toolId, data) {
         structuredContent
     };
 }
-function projectGithubToolOutput(toolId, data) {
+function projectGithubToolOutput(toolId, data, response, parameters, route) {
+    if (route === GITHUB_ARTIFACT_DOWNLOAD_ROUTE) {
+        return projectGithubArtifactDownloadOutput(response, parameters);
+    }
     switch(toolId){
         case 'list_issue_types':
             return {
@@ -256,10 +448,26 @@ function projectGithubToolOutput(toolId, data) {
             };
     }
 }
+function projectGithubArtifactDownloadOutput(response, parameters) {
+    if (response === undefined) return undefined;
+    const downloadUrl = response.headers?.location;
+    if (typeof downloadUrl !== 'string' || downloadUrl.length === 0) return undefined;
+    const output = {
+        archive_format: GITHUB_ARTIFACT_ARCHIVE_FORMAT,
+        download_url: downloadUrl
+    };
+    if (typeof parameters?.resource_id === 'string') output.artifact_id = parameters.resource_id;
+    const contentType = response.headers?.['content-type'];
+    if (typeof contentType === 'string') output.content_type = contentType;
+    const contentLength = response.headers?.['content-length'];
+    const sizeBytes = typeof contentLength === 'number' ? contentLength : Number(contentLength);
+    if (Number.isSafeInteger(sizeBytes) && sizeBytes >= 0) output.size_bytes = sizeBytes;
+    return output;
+}
 function githubSearchItems(data) {
     return isRecord(data) ? data.items : data;
 }
-function githubToolError(message) {
+function githubToolError(message, code) {
     return {
         isError: true,
         content: [
@@ -267,7 +475,10 @@ function githubToolError(message) {
                 type: 'text',
                 text: message
             }
-        ]
+        ],
+        structuredContent: {
+            code
+        }
     };
 }
 function isRecord(value) {