typeclaw 0.19.0 → 0.21.0

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

@@ -0,0 +1,276 @@
+import type {
+  RemoveReactionCallback,
+  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 type GithubReactionRemovalTarget =
+  | { kind: 'issue'; owner: string; repo: string; issueNumber: number; reactionId: number }
+  | { kind: 'issue-comment'; owner: string; repo: string; commentId: number; reactionId: number }
+  | { kind: 'pr-review-comment'; owner: string; repo: string; commentId: number; reactionId: 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>
+  if (t.op !== undefined) return null
+  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
+}
+
+export function encodeGithubRemovalRef(target: GithubReactionRemovalTarget): ReactionRef {
+  return { adapter: 'github', value: JSON.stringify({ op: 'remove', ...target }) }
+}
+
+export function decodeGithubRemovalRef(ref: ReactionRef): GithubReactionRemovalTarget | 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 (t.op !== 'remove' || owner === null || repo === null || typeof t.reactionId !== 'number') return null
+  if (t.kind === 'issue' && typeof t.issueNumber === 'number') {
+    return { kind: 'issue', owner, repo, issueNumber: t.issueNumber, reactionId: t.reactionId }
+  }
+  if ((t.kind === 'issue-comment' || t.kind === 'pr-review-comment') && typeof t.commentId === 'number') {
+    return { kind: t.kind, owner, repo, commentId: t.commentId, reactionId: t.reactionId }
+  }
+  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,
+      target,
+      {
+        content,
+        authType: deps.authType,
+        endpointKind,
+      },
+    )
+  }
+}
+
+export function createGithubRemoveReactionCallback(deps: {
+  token: (context?: GithubAuthContext) => Promise<string>
+  authType: GithubAuthType
+  fetchImpl?: typeof fetch
+}): RemoveReactionCallback {
+  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 target = decodeGithubRemovalRef(req.reactionRef)
+    if (target === null) return { ok: false, error: 'unparseable github reaction removal ref', code: 'unsupported' }
+
+    const endpoint = removeReactionEndpoint(target)
+    const endpointKind: OutboundEndpointKind =
+      target.kind === 'pr-review-comment' ? 'pr-review-comment-reaction' : 'issue-reaction'
+    return await deleteReaction(fetchImpl, await deps.token({ repoSlug: `${target.owner}/${target.repo}` }), endpoint, {
+      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`
+  }
+}
+
+function removeReactionEndpoint(target: GithubReactionRemovalTarget): string {
+  const base = `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}`
+  switch (target.kind) {
+    case 'issue':
+      return `${base}/issues/${target.issueNumber}/reactions/${target.reactionId}`
+    case 'issue-comment':
+      return `${base}/issues/comments/${target.commentId}/reactions/${target.reactionId}`
+    case 'pr-review-comment':
+      return `${base}/pulls/comments/${target.commentId}/reactions/${target.reactionId}`
+  }
+}
+
+async function postReaction(
+  fetchImpl: typeof fetch,
+  token: string,
+  url: string,
+  target: GithubReactionTarget,
+  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) {
+    const reactionId = await readReactionId(response)
+    if (reactionId === null) return { ok: true }
+    return { ok: true, reactionRef: encodeGithubRemovalRef(removalTargetFor(target, reactionId)) }
+  }
+  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) }
+}
+
+async function deleteReaction(
+  fetchImpl: typeof fetch,
+  token: string,
+  url: string,
+  options: { authType: GithubAuthType; endpointKind: OutboundEndpointKind },
+): Promise<ReactionResult> {
+  let response: Response
+  try {
+    response = await fetchImpl(url, {
+      method: 'DELETE',
+      headers: githubJsonHeaders(token),
+    })
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+  }
+  if (response.status === 204) 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 removalTargetFor(target: GithubReactionTarget, reactionId: number): GithubReactionRemovalTarget {
+  switch (target.kind) {
+    case 'issue':
+      return { kind: 'issue', owner: target.owner, repo: target.repo, issueNumber: target.issueNumber, reactionId }
+    case 'issue-comment':
+      return { kind: 'issue-comment', owner: target.owner, repo: target.repo, commentId: target.commentId, reactionId }
+    case 'pr-review-comment':
+      return {
+        kind: 'pr-review-comment',
+        owner: target.owner,
+        repo: target.repo,
+        commentId: target.commentId,
+        reactionId,
+      }
+  }
+}
+
+async function readReactionId(response: Response): Promise<number | null> {
+  const body = await response.json().catch(() => null)
+  if (typeof body !== 'object' || body === null) return null
+  const id = (body as Record<string, unknown>).id
+  return typeof id === 'number' ? id : null
+}
+
+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/adapters/slack-bot-classify.ts

@@ -182,7 +182,7 @@ function describeSlackMedia(event: SlackInboundMessageEvent): InboundAttachment[
   return (event.files ?? []).map((file, index) => describeSlackFile(file, index + 1))
 }
 
-function describeSlackFile(file: SlackFile, id: number): InboundAttachment {
+export function describeSlackFile(file: SlackFile, id: number): InboundAttachment {
   return {
     id,
     kind: 'file',
@@ -192,7 +192,7 @@ function describeSlackFile(file: SlackFile, id: number): InboundAttachment {
   }
 }
 
-function renderPlaceholder(attachment: InboundAttachment): string {
+export function renderPlaceholder(attachment: InboundAttachment): string {
   const parts: string[] = [`Slack attachment #${attachment.id}: ${attachment.kind}`]
   if (attachment.mimetype !== undefined) parts.push(attachment.mimetype)
   if (attachment.filename !== undefined) parts.push(`name=${attachment.filename}`)

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

@@ -1,4 +1,9 @@
-import { SlackBotClient, SlackBotListener, type SlackSocketModeSlashCommandArgs } from 'agent-messenger/slackbot'
+import {
+  SlackBotClient,
+  SlackBotListener,
+  type SlackFile,
+  type SlackSocketModeSlashCommandArgs,
+} from 'agent-messenger/slackbot'
 
 import {
   MEMBERSHIP_ENUMERATION_CAP,
@@ -28,7 +33,9 @@ import { createSlackAuthorResolver } from './slack-bot-author-resolver'
 import { createSlackChannelResolver } from './slack-bot-channel-resolver'
 import {
   classifyInbound,
+  describeSlackFile,
   type InboundDropReason,
+  renderPlaceholder,
   type SlackInboundAppMentionEvent,
   type SlackInboundMessageEvent,
 } from './slack-bot-classify'
@@ -369,6 +376,7 @@ type SlackRawHistoryMessage = {
   text?: string
   thread_ts?: string
   parent_user_id?: string
+  files?: SlackFile[]
 }
 
 type SlackHistoryResponse = {
@@ -601,14 +609,29 @@ function mapSlackMessage(msg: SlackRawHistoryMessage, botUserId: string | null):
     msg.parent_user_id === botUserId
       ? msg.thread_ts
       : null
+  // The history fetch bypasses the inbound classifier, so files 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 splitInbound: bake placeholders into text and carry the structured
+  // attachments so the router can resolve ids.
+  const attachments = (msg.files ?? []).map((file, index) => describeSlackFile(file, index + 1))
+  const rawText = msg.text ?? ''
+  const text =
+    attachments.length === 0
+      ? rawText
+      : rawText === ''
+        ? attachments.map(renderPlaceholder).join('\n')
+        : `${rawText}\n${attachments.map(renderPlaceholder).join('\n')}`
   return {
     externalMessageId: msg.ts,
     authorId: msg.user ?? msg.bot_id ?? 'unknown',
     authorName: msg.user ?? msg.bot_id ?? 'unknown',
-    text: msg.text ?? '',
+    text,
     ts: slackTsToMillis(msg.ts),
     isBot,
     replyToBotMessageId,
+    ...(attachments.length > 0 ? { attachments } : {}),
   }
 }
 

package/src/channels/engagement.ts

@@ -81,25 +81,60 @@ 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) {
+  // Multi-human pre-sticky target check. In a busy group the conversational
+  // target shifts every message: the author we're mid-exchange with (and hold
+  // a sticky credit for) may, on THIS turn, structurally address a third party
+  // — "@bob what do you think?", a reply to another human's message, or a
+  // peer bot by name. Sticky below is content-blind by design (it answers "am
+  // I mid-conversation with this author?"), so without this guard it would
+  // force-engage on a message plainly aimed elsewhere and burn the credit.
+  //
+  // This stays inside the pinned content-blind philosophy: it adds NO semantic
+  // text interpretation. It reuses the SAME structural booleans the post-alias
+  // suppressors already trust (`mentionsOthers`, `replyToOtherMessageId`,
+  // `textTargetsAnyPeerBot`) — the adapter classifiers decide "addressed to
+  // someone else", not this gate. The only refinement is ordering: when those
+  // structural signals fire in a multi-human group, observe BEFORE consuming
+  // sticky, and PRESERVE the credit so the author's next untargeted follow-up
+  // still wakes us within the window. A plain follow-up (no suppressor set)
+  // is untouched: it falls through to sticky and engages exactly as before.
+  //
+  // Solo-human channels are deliberately excluded (`effectiveHumans > 1`):
+  // there the sticky-over-mentionsOthers behavior is intentional and tested.
+  // The `!matchesAnyAlias` guard preserves the ladder invariant "explicit
+  // address to us beats structural targeting of others": a message that names
+  // us by alias engages on the alias rule below even when it ALSO tags a third
+  // party (the "봉봉아 펭펭아 둘 다 봐" multi-bot case), so we must not pre-empt
+  // it here. We only step aside for a credited author whose message is aimed
+  // PURELY elsewhere.
+  if (
+    effectiveHumans > 1 &&
+    config.stickiness !== 'off' &&
+    !matchesAnyAlias(message.text, selfAliases) &&
+    targetsSomeoneElse(message, participants, botInThread)
+  ) {
+    return 'observe'
+  }
+
+  // Sticky credit force-engages 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 for plain follow-ups 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 wholesale (the prior approach) dropped genuine follow-ups outright;
+  // the pre-check above is narrower — it only steps aside when the message is
+  // STRUCTURALLY addressed elsewhere, leaving plain follow-ups engaged.
+  if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
     return 'engage'
   }
 
@@ -157,37 +192,40 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   // has rejected that design repeatedly. The right knob is `trigger`
   // (which already applies symmetrically to humans and bots) plus this
   // fallback fix.
-  if (message.mentionsOthers) return 'observe'
-  // The replyToOtherMessageId suppressor exists to keep the bot out of
-  // human-to-human side conversations in busy channels. But Slack's
-  // `parent_user_id` is the THREAD ROOT author, not the immediate parent
-  // author — so a thread the human starts by @-mentioning the bot
-  // produces `replyToOtherMessageId` on every follow-up (root author is
-  // the human, not us), which would silently drop every reply after the
-  // first. Once the bot has actually sent into this thread, subsequent
-  // replies are part of OUR conversation regardless of who started it,
-  // so the suppressor stops applying. The two-humans-in-a-thread case
-  // PR #58 fixed is preserved because the bot never sent into that
-  // thread in the first place.
-  if (message.replyToOtherMessageId !== null && !botInThread) return 'observe'
-
-  // Plain-text peer-bot addressing as a fallback suppressor. We've reached
-  // here because the message lacks a structural mention/reply/dm AND
-  // doesn't contain our own alias. If it DOES contain a known peer bot's
-  // observed display name, the solo-human fallback would still engage us
-  // — same wrong behavior the alias trigger is meant to fix, just for
-  // peers instead of self. Each bot only configures its own aliases, so
-  // the only source of peer names is `participants[]` (observed
-  // authorName once a peer has spoken at least once in this channel).
-  // First-time addressing of a never-seen peer slips through; after that
-  // peer's first message it's caught forever.
-  if (textTargetsAnyPeerBot(message.text, participants)) return 'observe'
+  if (targetsSomeoneElse(message, participants, botInThread)) return 'observe'
 
   if (effectiveHumans <= 1 && !message.authorIsBot) return 'engage'
 
   return 'observe'
 }
 
+// Structural "this message is addressed to someone other than us" test. Pure
+// over adapter-classified booleans + observed peer names — no semantic text
+// interpretation, so it is safe for the content-blind engagement gate. Shared
+// by the multi-human pre-sticky check and the post-alias fallback suppressors
+// so the two can never drift apart.
+//
+//   - `mentionsOthers` — the message tags at least one other user and none of
+//     the mentions resolve to us.
+//   - `replyToOtherMessageId !== null && !botInThread` — the message replies to
+//     a non-bot message AND we haven't sent into this thread yet. Slack's
+//     `parent_user_id` is the THREAD ROOT author, not the immediate parent, so
+//     a thread a human opens by @-mentioning us would otherwise drop every
+//     follow-up; `botInThread` is the escape hatch once we're participating.
+//   - `textTargetsAnyPeerBot` — the text names a known peer bot (observed via
+//     `participants[]`). A never-seen peer's first addressing slips through,
+//     then is caught forever once that peer has spoken once.
+function targetsSomeoneElse(
+  message: InboundMessage,
+  participants: readonly ChannelParticipant[],
+  botInThread: boolean,
+): boolean {
+  if (message.mentionsOthers) return true
+  if (message.replyToOtherMessageId !== null && !botInThread) return true
+  if (textTargetsAnyPeerBot(message.text, participants)) return true
+  return false
+}
+
 export function countEffectiveHumans(
   participants: readonly ChannelParticipant[],
   membership: MembershipCount | null,
@@ -197,12 +235,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
 }