typeclaw 0.19.0 → 0.21.0

package/src/channels/adapters/discord-bot.ts

@@ -1,8 +1,11 @@
 import { DiscordBotClient, DiscordBotListener } from 'agent-messenger/discordbot'
 import {
   DiscordIntent,
+  type DiscordFile,
+  type DiscordGatewayEmbed,
   type DiscordGatewayInteractionEvent,
   type DiscordGatewayMessageCreateEvent,
+  type DiscordGatewayStickerItem,
 } from 'agent-messenger/discordbot'
 
 import {
@@ -29,7 +32,12 @@ import type {
 } from '@/channels/types'
 
 import { createDiscordChannelResolver } from './discord-bot-channel-resolver'
-import { classifyInbound, type InboundDropReason } from './discord-bot-classify'
+import {
+  classifyInbound,
+  describeDiscordMedia,
+  type InboundDropReason,
+  renderPlaceholder,
+} from './discord-bot-classify'
 import {
   ackInteraction,
   parseInteractionAsCommand,
@@ -148,6 +156,116 @@ type DiscordGuildPreview = {
 
 type DiscordGuildMember = {
   user?: { id?: string; bot?: boolean }
+  roles?: string[]
+}
+
+type DiscordPermissionOverwrite = {
+  id?: string
+  type?: number
+  allow?: string
+  deny?: string
+}
+
+// Discord channel `type` values that are threads. A thread's own
+// permission_overwrites are empty and its `parent_id` points at its parent
+// channel (not a category), so the normal "compute from this channel's
+// overwrites" path would treat a thread as fully public. We refuse to count
+// threads channel-scoped and fall back instead — fail-closed.
+const DISCORD_THREAD_CHANNEL_TYPES: ReadonlySet<number> = new Set([10, 11, 12])
+
+type DiscordChannelObject = {
+  type?: number
+  permission_overwrites?: DiscordPermissionOverwrite[]
+}
+
+type DiscordRole = {
+  id?: string
+  permissions?: string
+}
+
+type DiscordGuildObject = {
+  owner_id?: string
+  roles?: DiscordRole[]
+}
+
+// Discord permission bits. Discord serialises permission bitsets as decimal
+// STRINGS that can exceed Number.MAX_SAFE_INTEGER, so all bit math is done in
+// BigInt. Only the two bits this resolver needs are named.
+const DISCORD_PERMISSION_VIEW_CHANNEL = 0x400n
+const DISCORD_PERMISSION_ADMINISTRATOR = 0x8n
+
+function parsePermissionBits(raw: string | undefined): bigint {
+  if (raw === undefined || raw === '') return 0n
+  try {
+    return BigInt(raw)
+  } catch {
+    return 0n
+  }
+}
+
+// Computes whether a single member can VIEW_CHANNEL on a normal guild channel,
+// following Discord's documented resolution order:
+//   base = @everyone role perms OR all of the member's role perms
+//   → owner or ADMINISTRATOR short-circuits to visible
+//   → @everyone channel overwrite (clear deny bits, then set allow bits)
+//   → all matching role overwrites combined (OR every deny, OR every allow;
+//     apply denies then allows)
+//   → member-specific overwrite (clear deny, set allow)
+// Returns null when the data is insufficient to decide (a member references a
+// role absent from the guild role map), so the caller can fail closed rather
+// than guess.
+function memberCanViewChannel(args: {
+  guildId: string
+  ownerId: string | undefined
+  rolePermissions: ReadonlyMap<string, bigint>
+  overwrites: ReadonlyMap<string, { allow: bigint; deny: bigint }>
+  memberId: string | undefined
+  memberRoleIds: readonly string[]
+}): boolean | null {
+  const { guildId, ownerId, rolePermissions, overwrites, memberId, memberRoleIds } = args
+
+  if (memberId !== undefined && ownerId !== undefined && memberId === ownerId) return true
+
+  // Discord's `@everyone` role id always equals the guild id, so the guild id
+  // keys both the base @everyone permissions and the @everyone overwrite.
+  let base = rolePermissions.get(guildId) ?? 0n
+  for (const roleId of memberRoleIds) {
+    const perms = rolePermissions.get(roleId)
+    if (perms === undefined) return null
+    base |= perms
+  }
+
+  if ((base & DISCORD_PERMISSION_ADMINISTRATOR) !== 0n) return true
+
+  let perms = base
+
+  const everyoneOverwrite = overwrites.get(guildId)
+  if (everyoneOverwrite !== undefined) {
+    perms &= ~everyoneOverwrite.deny
+    perms |= everyoneOverwrite.allow
+  }
+
+  let roleDeny = 0n
+  let roleAllow = 0n
+  for (const roleId of memberRoleIds) {
+    const overwrite = overwrites.get(roleId)
+    if (overwrite !== undefined) {
+      roleDeny |= overwrite.deny
+      roleAllow |= overwrite.allow
+    }
+  }
+  perms &= ~roleDeny
+  perms |= roleAllow
+
+  if (memberId !== undefined) {
+    const memberOverwrite = overwrites.get(memberId)
+    if (memberOverwrite !== undefined) {
+      perms &= ~memberOverwrite.deny
+      perms |= memberOverwrite.allow
+    }
+  }
+
+  return (perms & DISCORD_PERMISSION_VIEW_CHANNEL) !== 0n
 }
 
 export function createDiscordMembershipResolver(deps: {
@@ -207,28 +325,136 @@ export function createDiscordMembershipResolver(deps: {
       return members.failure
     }
 
-    let bots = 0
-    let humans = 0
-    const humanMemberIds: string[] = []
-    let everyHumanIdentified = true
-    for (const member of members.value) {
-      if (member.user?.bot === true) {
-        bots++
-        continue
-      }
-      humans++
-      const userId = member.user?.id
-      if (userId === undefined) everyHumanIdentified = false
-      else humanMemberIds.push(userId)
+    // Guild `/members` returns the whole guild, not the channel. A bot or
+    // human that cannot VIEW_CHANNEL the target channel is not in the room and
+    // not a prompt-injection surface, so it must not be counted — otherwise a
+    // private channel of "operator + agent bot" inside a multi-bot guild reads
+    // as bots>1 and the grant_role relaxation (provesOnlyAgentBotPresent)
+    // false-refuses. Resolve channel visibility for each member; on ANY
+    // inability to decide, fall back rather than over- or under-count.
+    // `key.thread ?? key.chat` mirrors the history callback's channel-id
+    // resolution: today Discord stores a thread's own snowflake in `chat` with
+    // `thread` null, but a future caller that passes `chat=parent,
+    // thread=threadId` must scope visibility to the thread, not the parent.
+    const scoped = await scopeMembersToChannel({
+      fetchFn,
+      token: deps.token,
+      logger: deps.logger,
+      guildId: key.workspace,
+      channelId: key.thread ?? key.chat,
+      members: members.value,
+    })
+    if (scoped === 'fallback') return await fallback()
+
+    return scoped.everyHumanIdentified
+      ? {
+          humans: scoped.humans,
+          bots: scoped.bots,
+          fetchedAt: now(),
+          truncated: false,
+          humanMemberIds: scoped.humanMemberIds,
+        }
+      : { humans: scoped.humans, bots: scoped.bots, fetchedAt: now(), truncated: false }
+  }
+}
+
+type ScopedMembership = {
+  humans: number
+  bots: number
+  humanMemberIds: string[]
+  everyHumanIdentified: boolean
+}
+
+// Filters a guild member list down to those who can VIEW_CHANNEL the target
+// channel, then counts humans/bots over that visible set. Returns 'fallback'
+// when channel visibility cannot be computed completely (channel/guild fetch
+// failure, a member referencing an unknown role, or a thread channel whose
+// visibility this resolver does not model) — the caller then derives from
+// history (truncated:true), keeping every security consumer fail-closed.
+async function scopeMembersToChannel(args: {
+  fetchFn: typeof fetch
+  token: string
+  logger: DiscordBotAdapterLogger
+  guildId: string
+  channelId: string
+  members: readonly DiscordGuildMember[]
+}): Promise<ScopedMembership | 'fallback'> {
+  const { fetchFn, token, logger, guildId, channelId, members } = args
+
+  const [channel, guild] = await Promise.all([
+    fetchDiscordJson<DiscordChannelObject>(fetchFn, `${DISCORD_API_BASE}/channels/${channelId}`, token),
+    fetchDiscordJson<DiscordGuildObject>(fetchFn, `${DISCORD_API_BASE}/guilds/${guildId}`, token),
+  ])
+  if (!channel.ok) {
+    logger.warn(
+      `[discord-bot] membership channel=${channelId} fetch failed: ${channel.reason}; deriving from recent message authors`,
+    )
+    return 'fallback'
+  }
+  if (!guild.ok) {
+    logger.warn(
+      `[discord-bot] membership guild=${guildId} fetch failed: ${guild.reason}; deriving from recent message authors`,
+    )
+    return 'fallback'
+  }
+
+  if (channel.value.type !== undefined && DISCORD_THREAD_CHANNEL_TYPES.has(channel.value.type)) {
+    // A thread inherits visibility from its parent channel and (for private
+    // threads) an explicit member list; we do not model either here. Fall
+    // back rather than treat the thread as world-visible.
+    logger.warn(
+      `[discord-bot] membership channel=${channelId} is a thread; deriving from recent message authors instead of channel-scoped enumeration`,
+    )
+    return 'fallback'
+  }
+
+  const rolePermissions = new Map<string, bigint>()
+  for (const role of guild.value.roles ?? []) {
+    if (role.id !== undefined) rolePermissions.set(role.id, parsePermissionBits(role.permissions))
+  }
+
+  const overwrites = new Map<string, { allow: bigint; deny: bigint }>()
+  for (const overwrite of channel.value.permission_overwrites ?? []) {
+    if (overwrite.id === undefined) continue
+    overwrites.set(overwrite.id, {
+      allow: parsePermissionBits(overwrite.allow),
+      deny: parsePermissionBits(overwrite.deny),
+    })
+  }
+
+  let humans = 0
+  let bots = 0
+  const humanMemberIds: string[] = []
+  let everyHumanIdentified = true
+
+  for (const member of members) {
+    const visible = memberCanViewChannel({
+      guildId,
+      ownerId: guild.value.owner_id,
+      rolePermissions,
+      overwrites,
+      memberId: member.user?.id,
+      memberRoleIds: member.roles ?? [],
+    })
+    if (visible === null) {
+      logger.warn(
+        `[discord-bot] membership channel=${channelId} member references unknown role; deriving from recent message authors`,
+      )
+      return 'fallback'
     }
-    // Only attach identities when every human was identifiable; an
-    // unidentifiable human must not be silently dropped, or a consumer proving
-    // "all humans trusted" would skip an unaccounted member. Falling back to
-    // counts-only keeps that consumer fail-closed.
-    return everyHumanIdentified
-      ? { humans, bots, fetchedAt: now(), truncated: false, humanMemberIds }
-      : { humans, bots, fetchedAt: now(), truncated: false }
+    if (!visible) continue
+
+    if (member.user?.bot === true) {
+      bots++
+      continue
+    }
+    humans++
+    const userId = member.user?.id
+    if (userId === undefined) everyHumanIdentified = false
+    else humanMemberIds.push(userId)
   }
+
+  return { humans, bots, humanMemberIds, everyHumanIdentified }
 }
 
 type DiscordFetchResult<T> =
@@ -269,6 +495,9 @@ type DiscordRawHistoryMessage = {
   content: string
   timestamp: string
   message_reference?: { message_id?: string }
+  attachments?: DiscordFile[]
+  embeds?: DiscordGatewayEmbed[]
+  sticker_items?: DiscordGatewayStickerItem[]
 }
 
 // Discord treats threads as separate channels with their own snowflake ids,
@@ -333,14 +562,28 @@ export function createDiscordHistoryCallback(deps: {
 function mapDiscordMessage(msg: DiscordRawHistoryMessage, botUserId: string | null): ChannelHistoryMessage {
   const isBot = msg.author.bot === true || (botUserId !== null && msg.author.id === botUserId)
   const ts = Date.parse(msg.timestamp)
+  // The REST history fetch bypasses the inbound classifier, so attachments,
+  // embeds, and stickers on already-posted messages (e.g. an image on a thread
+  // root the agent is later @-mentioned under) must be mapped here too —
+  // otherwise they are silently dropped and look_at_channel_attachment can
+  // never resolve them. Mirror the classifier's splitInbound: bake placeholders
+  // into text and carry the structured attachments so the router can resolve ids.
+  const attachments = describeDiscordMedia(msg)
+  const text =
+    attachments.length === 0
+      ? msg.content
+      : msg.content === ''
+        ? attachments.map(renderPlaceholder).join('\n')
+        : `${msg.content}\n${attachments.map(renderPlaceholder).join('\n')}`
   return {
     externalMessageId: msg.id,
     authorId: msg.author.id,
     authorName: msg.author.global_name ?? msg.author.username ?? msg.author.id,
-    text: msg.content,
+    text,
     ts: Number.isFinite(ts) ? ts : 0,
     isBot,
     replyToBotMessageId: msg.message_reference?.message_id ?? null,
+    ...(attachments.length > 0 ? { attachments } : {}),
   }
 }
 

package/src/channels/adapters/github/decoy-reviewer.ts

@@ -0,0 +1,43 @@
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+// `absent` separates "GitHub says the reviewer is already not requested"
+// (404/422 — never on the list, already removed, or invalid for the repo) from
+// `failed` ("couldn't reach GitHub"), so callers warn only on the latter.
+export type RemoveRequestedReviewerResult =
+  | { kind: 'removed'; status: number }
+  | { kind: 'absent'; status: number; message: string }
+  | { kind: 'failed'; status?: number; reason: string }
+
+export async function removeRequestedReviewer(params: {
+  fetchImpl: typeof fetch
+  token: string
+  owner: string
+  repo: string
+  pullNumber: number
+  reviewerLogin: string
+}): Promise<RemoveRequestedReviewerResult> {
+  const url = `${GITHUB_API_BASE}/repos/${params.owner}/${params.repo}/pulls/${params.pullNumber}/requested_reviewers`
+  try {
+    const response = await params.fetchImpl(url, {
+      method: 'DELETE',
+      headers: githubJsonHeaders(params.token),
+      body: JSON.stringify({ reviewers: [params.reviewerLogin] }),
+    })
+    if (response.ok) return { kind: 'removed', status: response.status }
+    const message = await response.text().catch(() => '')
+    // 404 (PR/reviewer not found) and 422 (reviewer not currently requested,
+    // or not a valid reviewer for this repo) mean there is nothing to remove —
+    // the desired end state already holds. Everything else (401/403 auth,
+    // 429 rate, 5xx) is a real failure worth surfacing.
+    if (response.status === 404 || response.status === 422) {
+      return { kind: 'absent', status: response.status, message }
+    }
+    return {
+      kind: 'failed',
+      status: response.status,
+      reason: `GitHub API ${response.status}${message !== '' ? `: ${message}` : ''}`,
+    }
+  } catch (err) {
+    return { kind: 'failed', reason: err instanceof Error ? err.message : String(err) }
+  }
+}

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

@@ -2,8 +2,11 @@ import { createHmac, timingSafeEqual } from 'node:crypto'
 
 import type { InboundMessage } from '@/channels/types'
 
+import type { GithubAuthContext } from './auth'
+import { removeRequestedReviewer } from './decoy-reviewer'
 import type { DeliveryDedup } from './dedup'
 import { isGithubEventAllowed } from './event-allowlist'
+import { encodeGithubReactionRef, type GithubReactionTarget } from './reactions'
 
 export type GithubInboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
 
@@ -22,6 +25,13 @@ export type GithubWebhookHandlerOptions = {
   // omitted, team-reviewer requests are silently dropped (the v1 fallback
   // behavior). The adapter wires this in production; tests inject a fake.
   isBotInTeam?: (input: { org: string; slug: string; login: string }) => Promise<boolean>
+  // App-auth only: mints a repo-scoped token used to drop the decoy reviewer
+  // once the bot's own review lands. Omitted under PAT auth (no decoy exists).
+  authToken?: (context?: GithubAuthContext) => Promise<string>
+  // Schedules the decoy-drop off the webhook ACK path so the 200 stays fast.
+  // Defaults to fire-and-forget; tests inject a recorder to await the task.
+  scheduleBackgroundTask?: (task: () => Promise<void>) => void
+  fetchImpl?: typeof fetch
 }
 
 export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions): (req: Request) => Promise<Response> {
@@ -50,6 +60,7 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     const selfLogin = options.selfLogin()
     const author = readAuthor(event, payload)
     if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
+      maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
       options.logger.info(
         `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
       )
@@ -69,6 +80,65 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
   }
 }
 
+// GitHub auto-records the App as a reviewer the moment its review posts, but
+// leaves the decoy user pinned as a perpetual "review requested". When the bot
+// drops its own review (the self-authored event we're about to discard), fire a
+// background DELETE to remove the decoy. The DELETE is authenticated as the App,
+// so the resulting review_request_removed webhook has the bot actor as sender
+// and is dropped by classifyReviewRequest's self-loop guard — no fresh session.
+function maybeScheduleDecoyReviewerDrop(input: {
+  event: string
+  action: string | null
+  payload: Record<string, unknown>
+  selfLogin: string | null
+  options: GithubWebhookHandlerOptions
+}): void {
+  const { event, action, payload, selfLogin, options } = input
+  if (event !== 'pull_request_review' || action !== 'submitted') return
+  if (selfLogin === null) return
+  const authToken = options.authToken
+  if (authToken === undefined) return
+  if ((options.authType?.() ?? 'pat') !== 'app') return
+  const decoyLogin = resolveDecoyReviewerLogin(selfLogin, 'app')
+  if (decoyLogin === null) return
+
+  const repository = readRepository(payload)
+  const pr = readRecord(payload.pull_request)
+  const pullNumber = readNumber(pr, 'number')
+  if (repository === null || pullNumber === null) return
+
+  const fetchImpl = options.fetchImpl ?? fetch
+  const schedule = options.scheduleBackgroundTask ?? defaultScheduleBackgroundTask
+  const target = `${repository.owner}/${repository.name}#${pullNumber}`
+  schedule(async () => {
+    // authToken can throw (installation lookup / token mint), and a thrown
+    // failure must still warn — the default scheduler swallows rejections, so
+    // catching here is the only place the failure is observable.
+    try {
+      const token = await authToken({ repoSlug: `${repository.owner}/${repository.name}` })
+      const result = await removeRequestedReviewer({
+        fetchImpl,
+        token,
+        owner: repository.owner,
+        repo: repository.name,
+        pullNumber,
+        reviewerLogin: decoyLogin,
+      })
+      if (result.kind === 'failed') {
+        options.logger.warn(`[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${result.reason}`)
+      }
+    } catch (err) {
+      options.logger.warn(
+        `[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  })
+}
+
+function defaultScheduleBackgroundTask(task: () => Promise<void>): void {
+  void task().catch(() => {})
+}
+
 export async function verifySignature(body: string, secret: string, sigHeader: string): Promise<boolean> {
   const expected = `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`
   const a = Buffer.from(expected)
@@ -109,6 +179,7 @@ export function classifyGithubInbound(
       user,
       selfLogin,
       comment.created_at,
+      { kind: 'issue-comment', owner: repository.owner, repo: repository.name, commentId: id },
     )
   }
 
@@ -127,6 +198,7 @@ export function classifyGithubInbound(
       readUser(comment.user),
       selfLogin,
       comment.created_at,
+      { kind: 'pr-review-comment', owner: repository.owner, repo: repository.name, commentId: id },
     )
   }
 
@@ -144,6 +216,7 @@ export function classifyGithubInbound(
       readUser(comment.user),
       selfLogin,
       comment.created_at,
+      null,
     )
   }
 
@@ -160,6 +233,7 @@ export function classifyGithubInbound(
       readUser(issue.user),
       selfLogin,
       issue.created_at,
+      { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
     )
   }
 
@@ -189,6 +263,7 @@ export function classifyGithubInbound(
       readUser(pr.user),
       selfLogin,
       pr.created_at,
+      { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
     )
   }
 
@@ -206,6 +281,7 @@ export function classifyGithubInbound(
       readUser(review.user),
       selfLogin,
       review.submitted_at,
+      null,
     )
   }
 
@@ -222,6 +298,7 @@ export function classifyGithubInbound(
       readUser(discussion.user),
       selfLogin,
       discussion.created_at,
+      null,
     )
   }
 
@@ -340,6 +417,7 @@ function buildInbound(
   user: GithubUser | null,
   selfLogin: string | null,
   rawTs: unknown,
+  reactionTarget: GithubReactionTarget | null,
 ): InboundMessage | null {
   if (user === null) return null
   const text = typeof rawText === 'string' ? rawText : ''
@@ -347,6 +425,7 @@ function buildInbound(
     ...key,
     text,
     externalMessageId: String(id),
+    ...(reactionTarget !== null ? { reactionRef: encodeGithubReactionRef(reactionTarget) } : {}),
     authorId: String(user.id),
     authorName: user.login,
     authorIsBot: user.type === 'Bot',

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

@@ -19,6 +19,7 @@ import {
   buildPermissionGuidance,
   parseListHooksPermissionStatus,
 } from './permission-guidance'
+import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
 import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
 
@@ -119,6 +120,16 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     logger,
     fetchImpl,
   })
+  const reaction = createGithubReactionCallback({
+    token: authToken,
+    authType: options.secrets.auth.type,
+    fetchImpl,
+  })
+  const removeReaction = createGithubRemoveReactionCallback({
+    token: authToken,
+    authType: options.secrets.auth.type,
+    fetchImpl,
+  })
   const history = createGithubHistoryCallback({
     token: authToken,
     fetchImpl,
@@ -139,6 +150,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     selfLogin: () => selfLogin,
     authType: () => options.secrets.auth.type,
     isBotInTeam,
+    authToken,
+    fetchImpl,
     logger,
     route: (message) => {
       rememberWorkspace(message.workspace, message.chat)
@@ -161,6 +174,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       // Register all callbacks before binding the HTTP listener so the router
       // is fully wired before any webhook can arrive.
       options.router.registerOutbound('github', outbound)
+      options.router.registerReaction('github', reaction)
+      options.router.registerRemoveReaction('github', removeReaction)
       options.router.registerTyping('github', typing)
       options.router.registerHistory('github', history)
       options.router.registerMembership('github', membership)
@@ -172,6 +187,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         // Listener failed — roll back all registrations so stop() is a no-op
         // and the manager can report the failure cleanly.
         options.router.unregisterOutbound('github', outbound)
+        options.router.unregisterReaction('github', reaction)
+        options.router.unregisterRemoveReaction('github', removeReaction)
         options.router.unregisterTyping('github', typing)
         options.router.unregisterHistory('github', history)
         options.router.unregisterMembership('github', membership)
@@ -292,6 +309,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       if (!started) return
       started = false
       options.router.unregisterOutbound('github', outbound)
+      options.router.unregisterReaction('github', reaction)
+      options.router.unregisterRemoveReaction('github', removeReaction)
       options.router.unregisterTyping('github', typing)
       options.router.unregisterHistory('github', history)
       options.router.unregisterMembership('github', membership)

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

@@ -6,7 +6,12 @@ export type GithubAuthType = 'pat' | 'app'
 // 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'
+export type OutboundEndpointKind =
+  | 'issue-comment'
+  | 'pr-review-reply'
+  | 'discussion-comment'
+  | 'issue-reaction'
+  | 'pr-review-comment-reaction'
 
 // 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
@@ -127,6 +132,20 @@ const OUTBOUND_PERMISSION_FOR_KIND: Record<
     patScope: 'repo',
     patFineGrained: 'Discussions',
   },
+  // Reactions on an issue/PR body or an issue comment go through the Issues
+  // permission family; reactions on a PR review comment go through Pull requests.
+  'issue-reaction': {
+    label: 'Issues',
+    level: 'Read and write',
+    patScope: 'repo (or public_repo for public repos)',
+    patFineGrained: 'Issues',
+  },
+  'pr-review-comment-reaction': {
+    label: 'Pull requests',
+    level: 'Read and write',
+    patScope: 'repo',
+    patFineGrained: 'Pull requests',
+  },
 }
 
 // Decorate an outbound-API failure with the precise github.com permission a