typeclaw 0.9.2 → 0.11.0

package/src/channels/adapters/github/outbound.ts

@@ -1,11 +1,18 @@
 import type { OutboundCallback, OutboundMessage, SendResult } from '@/channels/types'
 
 import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import {
+  buildOutboundPermissionGuidance,
+  type GithubAuthType,
+  isOutboundPermissionDenial,
+  type OutboundEndpointKind,
+} from './permission-guidance'
 
 export type GithubOutboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
 
 export function createGithubOutboundCallback(deps: {
   token: () => Promise<string>
+  authType: GithubAuthType
   logger: GithubOutboundLogger
   fetchImpl?: typeof fetch
 }): OutboundCallback {
@@ -22,19 +29,35 @@ export function createGithubOutboundCallback(deps: {
     if (target === null) return { ok: false, error: `invalid GitHub chat: ${msg.chat}` }
 
     if (target.kind === 'discussion') {
-      return await postDiscussionComment({ ...deps, fetchImpl, repo, discussionNumber: target.number, body })
+      return await postDiscussionComment({
+        ...deps,
+        fetchImpl,
+        repo,
+        discussionNumber: target.number,
+        body,
+      })
     }
 
-    const endpoint =
-      target.kind === 'pr' && msg.thread !== null && msg.thread !== undefined && msg.thread !== ''
-        ? `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/pulls/${target.number}/comments/${encodeURIComponent(msg.thread)}/replies`
-        : `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/issues/${target.number}/comments`
-    return await postJson(fetchImpl, await deps.token(), endpoint, { body })
+    const isPrReviewReply = target.kind === 'pr' && msg.thread !== null && msg.thread !== undefined && msg.thread !== ''
+    const endpoint = isPrReviewReply
+      ? `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/pulls/${target.number}/comments/${encodeURIComponent(msg.thread ?? '')}/replies`
+      : `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/issues/${target.number}/comments`
+    return await postJson(
+      fetchImpl,
+      await deps.token(),
+      endpoint,
+      { body },
+      {
+        authType: deps.authType,
+        endpointKind: isPrReviewReply ? 'pr-review-reply' : 'issue-comment',
+      },
+    )
   }
 }
 
 async function postDiscussionComment(options: {
   token: () => Promise<string>
+  authType: GithubAuthType
   fetchImpl: typeof fetch
   repo: RepoRef
   discussionNumber: number
@@ -43,14 +66,21 @@ async function postDiscussionComment(options: {
   const discussionId = await fetchDiscussionId(options)
   if (!discussionId.ok) return discussionId
   const mutation = `mutation($discussionId:ID!,$body:String!){addDiscussionComment(input:{discussionId:$discussionId,body:$body}){comment{id}}}`
-  return await postGraphql(options.fetchImpl, await options.token(), mutation, {
-    discussionId: discussionId.id,
-    body: options.body,
-  })
+  return await postGraphql(
+    options.fetchImpl,
+    await options.token(),
+    mutation,
+    {
+      discussionId: discussionId.id,
+      body: options.body,
+    },
+    { authType: options.authType, endpointKind: 'discussion-comment' },
+  )
 }
 
 async function fetchDiscussionId(options: {
   token: () => Promise<string>
+  authType: GithubAuthType
   fetchImpl: typeof fetch
   repo: RepoRef
   discussionNumber: number
@@ -65,6 +95,7 @@ async function fetchDiscussionId(options: {
       name: options.repo.name,
       number: options.discussionNumber,
     },
+    { authType: options.authType, endpointKind: 'discussion-comment' },
   )
   if (!result.ok) return result
   const id = result.data.repository?.discussion?.id
@@ -76,8 +107,9 @@ async function postGraphql(
   token: string,
   query: string,
   variables: Record<string, unknown>,
+  guidance: { authType: GithubAuthType; endpointKind: OutboundEndpointKind },
 ): Promise<SendResult> {
-  const result = await graphql(fetchImpl, token, query, variables)
+  const result = await graphql(fetchImpl, token, query, variables, guidance)
   return result.ok ? { ok: true } : { ok: false, error: result.error }
 }
 
@@ -86,6 +118,7 @@ async function graphql<T>(
   token: string,
   query: string,
   variables: Record<string, unknown>,
+  guidance: { authType: GithubAuthType; endpointKind: OutboundEndpointKind },
 ): Promise<{ ok: true; data: T } | { ok: false; error: string }> {
   try {
     const response = await fetchImpl(`${GITHUB_API_BASE}/graphql`, {
@@ -95,10 +128,15 @@ async function graphql<T>(
     })
     const raw = (await response.json()) as { data?: T; errors?: Array<{ message?: string }> }
     if (!response.ok || raw.errors !== undefined) {
-      return {
-        ok: false,
-        error: raw.errors?.map((e) => e.message ?? 'unknown').join('; ') ?? `HTTP ${response.status}`,
-      }
+      // GraphQL errors carry a permission-denial in their `errors[].type` =
+      // 'FORBIDDEN' or message text. Match on either the HTTP 403 (rare for
+      // GraphQL) or the literal denial string in any error message.
+      const message = raw.errors?.map((e) => e.message ?? 'unknown').join('; ') ?? `HTTP ${response.status}`
+      const baseError = response.ok ? message : `GitHub API ${response.status}: ${message}`
+      const decorated = isOutboundPermissionDenial(response.ok ? 403 : response.status, message)
+        ? `${baseError}${buildOutboundPermissionGuidance(guidance)}`
+        : baseError
+      return { ok: false, error: decorated }
     }
     if (raw.data === undefined) return { ok: false, error: 'GraphQL response missing data' }
     return { ok: true, data: raw.data }
@@ -107,7 +145,13 @@ async function graphql<T>(
   }
 }
 
-async function postJson(fetchImpl: typeof fetch, token: string, url: string, payload: unknown): Promise<SendResult> {
+async function postJson(
+  fetchImpl: typeof fetch,
+  token: string,
+  url: string,
+  payload: unknown,
+  guidance: { authType: GithubAuthType; endpointKind: OutboundEndpointKind },
+): Promise<SendResult> {
   try {
     const response = await fetchImpl(url, {
       method: 'POST',
@@ -116,7 +160,11 @@ async function postJson(fetchImpl: typeof fetch, token: string, url: string, pay
     })
     if (response.ok) return { ok: true }
     const text = await response.text().catch(() => '')
-    return { ok: false, error: `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}` }
+    const baseError = `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}`
+    const decorated = isOutboundPermissionDenial(response.status, text)
+      ? `${baseError}${buildOutboundPermissionGuidance(guidance)}`
+      : baseError
+    return { ok: false, error: decorated }
   } catch (err) {
     return { ok: false, error: describe(err) }
   }

package/src/channels/adapters/github/permission-guidance.ts

@@ -0,0 +1,169 @@
+import type { PermissionGap } from './event-permissions'
+
+export type GithubAuthType = 'pat' | 'app'
+
+// What kind of outbound API the adapter was trying to call when it got a
+// permission-failure response. Each value maps to a distinct GitHub App
+// permission family (and, for PATs, a distinct scope), so each surfaces a
+// different remediation message.
+export type OutboundEndpointKind = 'issue-comment' | 'pr-review-reply' | 'discussion-comment'
+
+// Parses webhook-register errors of the shape `list hooks failed: <status> <body>`.
+// Returns the status code when it matches the two shapes GitHub emits for
+// missing access on the list-hooks endpoint:
+//   - 404 Not Found: the token cannot see the repo at all (private repo
+//     gated behind missing repository access — GitHub returns 404 instead of
+//     403 to avoid leaking the existence of private repos).
+//   - 403 Forbidden: the token sees the repo but lacks webhook-management
+//     permission, OR is blocked by an org SSO/SAML authorization gate.
+// Returns null for any other error (network, malformed slug, create-hook
+// failures, etc.) so the guidance only fires on the actual symptom.
+export function parseListHooksPermissionStatus(error: string): number | null {
+  const match = error.match(/^list hooks failed: (404|403)\b/)
+  if (match === null) return null
+  return Number(match[1])
+}
+
+// The labels below intentionally mirror github.com's current UI verbatim so a
+// user can grep their settings page for the exact string. If GitHub renames
+// any of these in a future redesign, update both here and the
+// `permissionGuidance` tests in lifecycle.test.ts.
+//
+//   Fine-grained PAT:
+//     Settings → Developer settings → Personal access tokens → Fine-grained tokens
+//     "Resource owner", "Repository access", "Repository permissions" → "Webhooks" → "Read and write", "Metadata" → "Read-only"
+//   GitHub App:
+//     Settings → Developer settings → GitHub Apps → <app> → Permissions & events
+//     "Repository permissions" → "Webhooks" → "Read and write"
+//     Install/configure on the org: <app settings> → Install App / Configure → "Repository access"
+//   Classic PAT (legacy, still supported by GitHub but we don't surface it in
+//     channel-add prompts):
+//     Settings → Developer settings → Personal access tokens (classic)
+//     Scope: "admin:repo_hook" (or full "repo" for private repositories)
+export function buildPermissionGuidance(
+  authType: GithubAuthType,
+  failures: ReadonlyArray<{ repo: string; status: number }>,
+): string {
+  const repoList = failures.map((f) => `${f.repo} (${f.status})`).join(', ')
+  const lines: string[] = [
+    `[github] webhook setup needs more access for: ${repoList}.`,
+    '  - 404 from GitHub means the token cannot see the repo (GitHub hides private repos behind 404 instead of 403).',
+    '  - 403 means the token sees the repo but lacks webhook permission, or is blocked by org SAML/SSO.',
+    '',
+  ]
+  if (authType === 'pat') {
+    lines.push(
+      '  Fix (fine-grained personal access token):',
+      '    1. Open https://github.com/settings/personal-access-tokens and edit the token TypeClaw is using.',
+      '    2. Under "Resource owner", select the org that owns the failing repos (e.g. the org in the slug above).',
+      '    3. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
+      '    4. Under "Repository permissions", set "Webhooks" to "Read and write" and "Metadata" to "Read-only".',
+      '    5. Save. If the org enforces SAML SSO, click "Configure SSO" next to the token and authorize the org.',
+      '',
+      '  Or (classic personal access token): grant the "admin:repo_hook" scope (or "repo" for private repos),',
+      '  and on a SAML-protected org click "Authorize" next to the token.',
+    )
+  } else {
+    lines.push(
+      '  Fix (GitHub App):',
+      '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
+      '    2. Under "Permissions & events" → "Repository permissions", set "Webhooks" to "Read and write". Save.',
+      '    3. From the app page, click "Install App" (or "Configure" if already installed) and select the org that owns the failing repos.',
+      '    4. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
+      '    5. If the app permissions changed in step 2, install owners must accept the updated permissions from the install page before the new access takes effect.',
+    )
+  }
+  return lines.join('\n')
+}
+
+// Always GitHub App: PATs don't have per-installation permission grants
+// (their access is gated by token scopes, surfaced by the existing 404/403
+// flow in webhook-register).
+export function buildAppPermissionPreflightGuidance(gaps: ReadonlyArray<PermissionGap>): string {
+  const lines = [
+    `[github] GitHub App installation is missing permissions for ${gaps.length} configured event ${gaps.length === 1 ? 'family' : 'families'}:`,
+  ]
+  for (const gap of gaps) {
+    const eventList = gap.events.join(', ')
+    const grantedLabel = gap.granted === null ? 'none' : gap.granted
+    const needLabel = gap.needsWrite ? 'Read and write' : 'Read-only'
+    lines.push(`  - ${gap.uiLabel}: granted=${grantedLabel}, need=${needLabel} (covers: ${eventList})`)
+  }
+  lines.push(
+    '',
+    '  Fix:',
+    '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
+    '    2. Under "Permissions & events" → "Repository permissions", set each missing permission above to the listed level. Save.',
+    '    3. Open the install page (Install App / Configure for the org) and accept the updated permissions request — the new access only takes effect after the install owner accepts.',
+    '    4. If the org enforces SAML SSO, ensure the App is authorized for the org from the org settings → Third-party Apps page.',
+    '',
+    '  Webhooks already received will continue to deliver, but payload fields and reply attempts that require the missing permission will fail with 403 ("Resource not accessible by integration") until the install is reaccepted.',
+  )
+  return lines.join('\n')
+}
+
+// The label and (for App auth) the level appear verbatim on github.com so
+// users can grep their settings page for the exact strings. The PAT scope
+// names are GitHub's canonical token-scope identifiers, also verbatim.
+const OUTBOUND_PERMISSION_FOR_KIND: Record<
+  OutboundEndpointKind,
+  { label: string; level: 'Read and write'; patScope: string; patFineGrained: string }
+> = {
+  'issue-comment': {
+    label: 'Issues',
+    level: 'Read and write',
+    patScope: 'repo (or public_repo for public repos)',
+    patFineGrained: 'Issues',
+  },
+  'pr-review-reply': {
+    label: 'Pull requests',
+    level: 'Read and write',
+    patScope: 'repo',
+    patFineGrained: 'Pull requests',
+  },
+  'discussion-comment': {
+    label: 'Discussions',
+    level: 'Read and write',
+    patScope: 'repo',
+    patFineGrained: 'Discussions',
+  },
+}
+
+// Decorate an outbound-API failure with the precise github.com permission a
+// user needs to enable. Called only on the 403 + "Resource not accessible by
+// integration" combination — other 403s (org SSO, suspended install) need
+// different remediation and would be mis-described here.
+export function buildOutboundPermissionGuidance(options: {
+  authType: GithubAuthType
+  endpointKind: OutboundEndpointKind
+}): string {
+  const perm = OUTBOUND_PERMISSION_FOR_KIND[options.endpointKind]
+  if (options.authType === 'app') {
+    return [
+      '',
+      `  Fix (GitHub App): the App needs "${perm.label}" → "${perm.level}".`,
+      '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
+      `    2. Under "Permissions & events" → "Repository permissions", set "${perm.label}" to "${perm.level}". Save.`,
+      '    3. Open the install page (Install App / Configure for the org) and accept the updated permissions request — the new access only takes effect after the install owner accepts.',
+    ].join('\n')
+  }
+  return [
+    '',
+    `  Fix (fine-grained personal access token): grant "${perm.patFineGrained}" → "Read and write" on the failing repo.`,
+    '    1. Open https://github.com/settings/personal-access-tokens and edit the token TypeClaw is using.',
+    `    2. Under "Repository permissions", set "${perm.patFineGrained}" to "Read and write". Save.`,
+    `    3. If the org enforces SAML SSO, click "Configure SSO" next to the token and authorize the org.`,
+    '',
+    `  Or (classic personal access token): grant the "${perm.patScope}" scope; SAML-protected orgs additionally need "Authorize" next to the token.`,
+  ].join('\n')
+}
+
+// 403 with this exact body is GitHub's signal that the call would succeed
+// with the right permissions. Other 403 bodies (e.g. "OAuth token… needs to
+// be authorized for this organization", suspended installation) need
+// different remediation, so the decoration matcher is intentionally narrow.
+const INTEGRATION_PERMISSION_DENIAL = 'Resource not accessible by integration'
+
+export function isOutboundPermissionDenial(status: number, body: string): boolean {
+  return status === 403 && body.includes(INTEGRATION_PERMISSION_DENIAL)
+}

package/src/channels/adapters/github/team-membership.ts

@@ -0,0 +1,56 @@
+// Best-effort "is the bot a member of this team?" lookup, used to gate
+// `pull_request.review_requested` inbounds when GitHub assigns a *team*
+// rather than a user as the reviewer.
+//
+// Cached per (org, slug, login) for the adapter's lifetime: team membership
+// changes rarely, and a stale cache costs us one missed review (the next
+// request rebuilds it). Errors fall closed (return false): we'd rather drop
+// a real review request than wake the agent on a team the bot isn't in.
+
+const ACTIVE_MEMBERSHIP_STATE = 'active'
+
+export type TeamMembershipChecker = (input: { org: string; slug: string; login: string }) => Promise<boolean>
+
+export function createTeamMembershipChecker(options: {
+  token: () => Promise<string>
+  fetchImpl?: typeof fetch
+}): TeamMembershipChecker {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const cache = new Map<string, boolean>()
+
+  return async ({ org, slug, login }) => {
+    const key = `${org}/${slug}#${login}`
+    const cached = cache.get(key)
+    if (cached !== undefined) return cached
+
+    const result = await lookup(fetchImpl, await options.token(), org, slug, login)
+    cache.set(key, result)
+    return result
+  }
+}
+
+async function lookup(
+  fetchImpl: typeof fetch,
+  token: string,
+  org: string,
+  slug: string,
+  login: string,
+): Promise<boolean> {
+  const url = `https://api.github.com/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(slug)}/memberships/${encodeURIComponent(login)}`
+  let res: Response
+  try {
+    res = await fetchImpl(url, {
+      headers: {
+        accept: 'application/vnd.github+json',
+        authorization: `Bearer ${token}`,
+        'x-github-api-version': '2022-11-28',
+      },
+    })
+  } catch {
+    return false
+  }
+  if (res.status === 404) return false
+  if (!res.ok) return false
+  const body = (await res.json().catch(() => null)) as { state?: unknown } | null
+  return typeof body?.state === 'string' && body.state === ACTIVE_MEMBERSHIP_STATE
+}