typeclaw 0.19.0 → 0.20.0

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

@@ -4,6 +4,7 @@ import type { InboundMessage } from '@/channels/types'
 
 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 }
 
@@ -109,6 +110,7 @@ export function classifyGithubInbound(
       user,
       selfLogin,
       comment.created_at,
+      { kind: 'issue-comment', owner: repository.owner, repo: repository.name, commentId: id },
     )
   }
 
@@ -127,6 +129,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 +147,7 @@ export function classifyGithubInbound(
       readUser(comment.user),
       selfLogin,
       comment.created_at,
+      null,
     )
   }
 
@@ -160,6 +164,7 @@ export function classifyGithubInbound(
       readUser(issue.user),
       selfLogin,
       issue.created_at,
+      { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
     )
   }
 
@@ -189,6 +194,7 @@ export function classifyGithubInbound(
       readUser(pr.user),
       selfLogin,
       pr.created_at,
+      { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
     )
   }
 
@@ -206,6 +212,7 @@ export function classifyGithubInbound(
       readUser(review.user),
       selfLogin,
       review.submitted_at,
+      null,
     )
   }
 
@@ -222,6 +229,7 @@ export function classifyGithubInbound(
       readUser(discussion.user),
       selfLogin,
       discussion.created_at,
+      null,
     )
   }
 
@@ -340,6 +348,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 +356,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 } from './reactions'
 import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
 
@@ -119,6 +120,11 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     logger,
     fetchImpl,
   })
+  const reaction = createGithubReactionCallback({
+    token: authToken,
+    authType: options.secrets.auth.type,
+    fetchImpl,
+  })
   const history = createGithubHistoryCallback({
     token: authToken,
     fetchImpl,
@@ -161,6 +167,7 @@ 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.registerTyping('github', typing)
       options.router.registerHistory('github', history)
       options.router.registerMembership('github', membership)
@@ -172,6 +179,7 @@ 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.unregisterTyping('github', typing)
         options.router.unregisterHistory('github', history)
         options.router.unregisterMembership('github', membership)
@@ -292,6 +300,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       if (!started) return
       started = false
       options.router.unregisterOutbound('github', outbound)
+      options.router.unregisterReaction('github', reaction)
       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

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

@@ -0,0 +1,142 @@
+import type { ReactionCallback, ReactionErrorCode, ReactionRef, ReactionResult } from '@/channels/types'
+
+import type { GithubAuthContext } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import {
+  buildOutboundPermissionGuidance,
+  type GithubAuthType,
+  isOutboundPermissionDenial,
+  type OutboundEndpointKind,
+} from './permission-guidance'
+
+// The reactable target, distinguished by the webhook event the inbound came
+// from. The router collapses every github inbound to the same `chat`/
+// `externalMessageId` pair, so this kind — known only at classification time —
+// is what selects the right Reactions endpoint. `issue` covers both issue and
+// PR bodies (GitHub models a PR body as an issue for reactions); `discussion`
+// is unsupported until the GraphQL `addReaction` path lands, so the classifier
+// does not stamp it today.
+export type GithubReactionTarget =
+  | { kind: 'issue'; owner: string; repo: string; issueNumber: number }
+  | { kind: 'issue-comment'; owner: string; repo: string; commentId: number }
+  | { kind: 'pr-review-comment'; owner: string; repo: string; commentId: number }
+
+export function encodeGithubReactionRef(target: GithubReactionTarget): ReactionRef {
+  return { adapter: 'github', value: JSON.stringify(target) }
+}
+
+export function decodeGithubReactionRef(ref: ReactionRef): GithubReactionTarget | null {
+  if (ref.adapter !== 'github') return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(ref.value)
+  } catch {
+    return null
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const t = parsed as Record<string, unknown>
+  const owner = typeof t.owner === 'string' ? t.owner : null
+  const repo = typeof t.repo === 'string' ? t.repo : null
+  if (owner === null || repo === null) return null
+  if (t.kind === 'issue' && typeof t.issueNumber === 'number') {
+    return { kind: 'issue', owner, repo, issueNumber: t.issueNumber }
+  }
+  if ((t.kind === 'issue-comment' || t.kind === 'pr-review-comment') && typeof t.commentId === 'number') {
+    return { kind: t.kind, owner, repo, commentId: t.commentId }
+  }
+  return null
+}
+
+// GitHub's Reactions API takes a fixed vocabulary of content strings. Map the
+// adapter-generic emoji name onto it; anything outside the set is reported as
+// `unsupported` so the model gets a clear signal rather than a silent 422.
+const REACTION_CONTENT: Record<string, string> = {
+  eyes: 'eyes',
+  '+1': '+1',
+  thumbsup: '+1',
+  '-1': '-1',
+  thumbsdown: '-1',
+  laugh: 'laugh',
+  hooray: 'hooray',
+  tada: 'hooray',
+  confused: 'confused',
+  heart: 'heart',
+  rocket: 'rocket',
+}
+
+export function createGithubReactionCallback(deps: {
+  token: (context?: GithubAuthContext) => Promise<string>
+  authType: GithubAuthType
+  fetchImpl?: typeof fetch
+}): ReactionCallback {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (req): Promise<ReactionResult> => {
+    if (req.adapter !== 'github') return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    const content = REACTION_CONTENT[req.emoji.replace(/^:|:$/g, '')]
+    if (content === undefined) {
+      return { ok: false, error: `github does not support reaction "${req.emoji}"`, code: 'unsupported' }
+    }
+    const target = decodeGithubReactionRef(req.reactionRef)
+    if (target === null) return { ok: false, error: 'unparseable github reaction ref', code: 'unsupported' }
+
+    const endpoint = reactionEndpoint(target)
+    const endpointKind: OutboundEndpointKind =
+      target.kind === 'pr-review-comment' ? 'pr-review-comment-reaction' : 'issue-reaction'
+    return await postReaction(fetchImpl, await deps.token({ repoSlug: `${target.owner}/${target.repo}` }), endpoint, {
+      content,
+      authType: deps.authType,
+      endpointKind,
+    })
+  }
+}
+
+function reactionEndpoint(target: GithubReactionTarget): string {
+  const base = `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}`
+  switch (target.kind) {
+    case 'issue':
+      return `${base}/issues/${target.issueNumber}/reactions`
+    case 'issue-comment':
+      return `${base}/issues/comments/${target.commentId}/reactions`
+    case 'pr-review-comment':
+      return `${base}/pulls/comments/${target.commentId}/reactions`
+  }
+}
+
+async function postReaction(
+  fetchImpl: typeof fetch,
+  token: string,
+  url: string,
+  options: { content: string; authType: GithubAuthType; endpointKind: OutboundEndpointKind },
+): Promise<ReactionResult> {
+  let response: Response
+  try {
+    response = await fetchImpl(url, {
+      method: 'POST',
+      headers: githubJsonHeaders(token),
+      body: JSON.stringify({ content: options.content }),
+    })
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+  }
+  // 201 = reaction created, 200 = the actor already left this same reaction.
+  // Both are success: an :eyes: that's already there is the desired end state,
+  // so a duplicate webhook delivery (or a retried engage) must not surface an error.
+  if (response.status === 200 || response.status === 201) return { ok: true }
+  const text = await response.text().catch(() => '')
+  const baseError = `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}`
+  if (isOutboundPermissionDenial(response.status, text)) {
+    return {
+      ok: false,
+      error: `${baseError}${buildOutboundPermissionGuidance({ authType: options.authType, endpointKind: options.endpointKind })}`,
+      code: 'permission-denied',
+    }
+  }
+  return { ok: false, error: baseError, code: classifyStatus(response.status) }
+}
+
+function classifyStatus(status: number): ReactionErrorCode {
+  if (status === 403) return 'permission-denied'
+  if (status === 404) return 'not-found'
+  if (status === 429) return 'rate-limited'
+  return 'transient'
+}

package/src/channels/engagement.ts

@@ -81,25 +81,23 @@ export type EngagementInput = {
 export function decideEngagement(input: EngagementInput): EngagementDecision {
   const { message, config, key, ledger, now, participants, selfAliases, botInThread } = input
 
-  // The human count drives both the sticky-credit gate (below) and the
-  // solo-human fallback (bottom). Compute it once, up front. Peer bots are
-  // excluded — a 1-human-N-bot room is still "solo" for engagement purposes.
+  // Peer bots are excluded from the count — a 1-human-N-bot room is still
+  // "solo" for the fallback at the bottom.
   const effectiveHumans = countEffectiveHumans(participants, input.membership, now)
-  const multiHumanGroup = isMultiHumanGroup(message.isDm, effectiveHumans)
 
   if (config.trigger.includes('dm') && message.isDm) return 'engage'
   if (config.trigger.includes('mention') && message.isBotMention) return 'engage'
   if (config.trigger.includes('reply') && message.replyToBotMessageId !== null) return 'engage'
 
-  // Sticky credit. ALWAYS consume when present (the credit stays one-shot,
-  // so a later membership change can't resurrect stale conversational
-  // credit), but only let it FORCE engagement outside a multi-human group.
-  // In a group, sticky alone no longer wakes the bot on every follow-up —
-  // the author must re-address us (mention/reply/alias) to re-engage. This
-  // narrows an existing permissive rule in the exact context where it's
-  // harmful; it is NOT a new bot-specific gate (peer bots and humans are
-  // treated identically, via `multiHumanGroup`). See engagement.mdx.
-  if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now) && !multiHumanGroup) {
+  // Sticky credit force-engages in EVERY context (groups included) for the
+  // full window. This gate is deliberately content-blind: it answers "am I in
+  // an active conversation with this author?", not "does THIS message need a
+  // reply?" — a boolean over membership cannot tell "where did you send it?"
+  // (reply) from "lol ok" (chatter). Selectivity is the MODEL's job: engaged
+  // group turns get a `composeTurnPrompt` nudge (keyed off `isMultiHumanGroup`)
+  // to answer real follow-ups and `NO_REPLY` chatter. Gating sticky off in
+  // groups instead (the prior approach) dropped genuine follow-ups outright.
+  if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
     return 'engage'
   }
 
@@ -197,12 +195,11 @@ export function countEffectiveHumans(
   return resolveEffectiveHumans(persistedHumans, membership, now)
 }
 
-// A multi-human group is the one place where the chatty "reply to every
-// follow-up" behavior (sticky credit, and the prompt's default eagerness) is
-// wrong. DMs — 1:1, or platform group-DMs reached via the `dm` trigger — and
-// solo-human channels keep the back-and-forth. The router reuses this to
-// decide both sticky suppression and the group-chat prompt nudge, so the two
-// stay in lockstep off one definition.
+// A multi-human group is where the prompt's default "answer everything"
+// eagerness needs tempering. The router reads this in `route()` to decide
+// whether to append the group-chat nudge that tells the model to be selective
+// (answer real follow-ups, `NO_REPLY` chatter) on its engaged turns. DMs and
+// solo-human channels skip the nudge — there, replying to everything is right.
 export function isMultiHumanGroup(isDm: boolean, effectiveHumans: number): boolean {
   return !isDm && effectiveHumans > 1
 }