typeclaw 0.1.0

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

@@ -0,0 +1,84 @@
+import type { ChannelKey, ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
+
+const SLACK_API_BASE = 'https://slack.com/api'
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
+
+export type SlackChannelResolverOptions = {
+  token: string
+  now?: () => number
+  ttlMs?: number
+}
+
+type CacheEntry<T> = { value: T; expiresAt: number }
+
+type SlackConversationsInfoResponse = {
+  ok: boolean
+  channel?: { id?: string; name?: string }
+}
+
+type SlackTeamInfoResponse = {
+  ok: boolean
+  team?: { id?: string; name?: string }
+}
+
+export function createSlackChannelResolver(options: SlackChannelResolverOptions): ChannelNameResolver {
+  const now = options.now ?? Date.now
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
+
+  const chatCache = new Map<string, CacheEntry<string>>()
+  const teamCache = new Map<string, CacheEntry<string>>()
+
+  const fetchCached = async <T>(
+    cache: Map<string, CacheEntry<T>>,
+    key: string,
+    fetcher: () => Promise<T | null>,
+  ): Promise<T | null> => {
+    const cached = cache.get(key)
+    if (cached && cached.expiresAt > now()) return cached.value
+    const value = await fetcher()
+    if (value !== null) cache.set(key, { value, expiresAt: now() + ttlMs })
+    return value
+  }
+
+  return async (key: ChannelKey): Promise<ResolvedChannelNames> => {
+    if (key.workspace === '@dm') return {}
+
+    const [chatName, workspaceName] = await Promise.all([
+      fetchCached(chatCache, key.chat, () => fetchChannelName(key.chat, options.token)),
+      fetchCached(teamCache, key.workspace, () => fetchTeamName(key.workspace, options.token)),
+    ])
+
+    const result: ResolvedChannelNames = {}
+    if (chatName !== null) result.chatName = chatName
+    if (workspaceName !== null) result.workspaceName = workspaceName
+    return result
+  }
+}
+
+async function fetchChannelName(channelId: string, token: string): Promise<string | null> {
+  try {
+    const response = await fetch(`${SLACK_API_BASE}/conversations.info?channel=${encodeURIComponent(channelId)}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+    if (!response.ok) return null
+    const body = (await response.json()) as SlackConversationsInfoResponse
+    if (!body.ok || !body.channel?.name) return null
+    return body.channel.name
+  } catch {
+    return null
+  }
+}
+
+async function fetchTeamName(teamId: string, token: string): Promise<string | null> {
+  try {
+    const response = await fetch(`${SLACK_API_BASE}/team.info?team=${encodeURIComponent(teamId)}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+    if (!response.ok) return null
+    const body = (await response.json()) as SlackTeamInfoResponse
+    if (!body.ok || !body.team?.name) return null
+    return body.team.name
+  } catch {
+    return null
+  }
+}

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

@@ -0,0 +1,213 @@
+import type { SlackFile, SlackSocketModeAppMentionEvent, SlackSocketModeMessageEvent } from 'agent-messenger/slackbot'
+
+import { matchesAnyAlias } from '@/channels/engagement'
+import { isAllowed, type ChannelAdapterConfig } from '@/channels/schema'
+import type { InboundMessage } from '@/channels/types'
+
+import { slackTsToMillis } from './slack-bot-time'
+
+// Upstream's `SlackSocketModeMessageEvent` carries `[key: string]: unknown`
+// for fields it does not type explicitly. Three of those untyped fields are
+// load-bearing for this adapter:
+//   - `parent_user_id`: set on every reply within a thread; identifies the
+//     author of the message the thread is rooted at. Used to decide whether
+//     a reply targets the bot, another human, or an unknown parent.
+//   - `client_msg_id`: client-generated UUID on user-authored messages,
+//     stable across Slack-side resends of the same gesture. Primary dedupe
+//     key for the "one user action surfaces as two events" case.
+//   - `files`: attachments delivered inline on the same message event (Slack
+//     does not fire a separate file_share for messages we receive).
+// Typing them here (rather than reading them via `as` casts at every call
+// site) keeps the classifier readable and makes it the single source of
+// truth for "what Slack actually sends" — anything else reading these
+// fields imports `SlackInboundMessageEvent` from this module.
+export type SlackInboundMessageEvent = SlackSocketModeMessageEvent & {
+  parent_user_id?: string
+  client_msg_id?: string
+  files?: SlackFile[]
+}
+
+// `app_mention` envelopes do not always carry `client_msg_id`, but typing
+// it keeps the promotion to a message-shaped event lossless if Slack
+// starts sending it. Same reasoning as `SlackInboundMessageEvent` above.
+export type SlackInboundAppMentionEvent = SlackSocketModeAppMentionEvent & {
+  client_msg_id?: string
+}
+
+export type InboundDropReason =
+  | 'self_author' // event.user === botUserId; we never route our own messages back to ourselves
+  | 'no_user' // event has no `user` field (e.g. system messages: channel_join, message_changed)
+  | 'empty_text' // event has neither text nor files — nothing for the agent to act on
+  | 'not_in_allow_list' // workspace/channel not admitted by typeclaw.json `channels.slack-bot.allow`
+  | 'pre_connect' // bot identity is not known yet, so mention/self/reply classification cannot be trusted
+
+export type InboundClassification =
+  | { kind: 'drop'; reason: InboundDropReason }
+  | { kind: 'route'; payload: InboundMessage }
+
+export type SlackInboundContext = {
+  teamId: string
+  botUserId: string | null
+  // Lowered self-aliases (`alias` from typeclaw.json plus the implicit
+  // basename(agentDir)). When a top-level message contains one of these
+  // but no `<@bot>` mention, the classifier still anchors `thread` on
+  // `event.ts` so the bot's reply lands in a thread under the user's
+  // message instead of as a fragmented top-level post. Optional for
+  // backward compatibility — omitted means "behave like before, no
+  // alias-driven thread anchoring". The router's `computeSelfAliases`
+  // is the source of truth; the adapter just forwards it.
+  selfAliases?: readonly string[]
+}
+
+// All decision logic for "should this Socket Mode message event be routed to
+// the agent?" lives here so it can be unit-tested in isolation. The adapter
+// is left as a thin shell that handles SDK lifecycle and translates this
+// verdict into log lines + router calls. Adding a new drop reason MUST extend
+// InboundDropReason — there is no `default` log path, so the type system
+// forces logging to stay exhaustive.
+export function classifyInbound(
+  event: SlackInboundMessageEvent,
+  config: ChannelAdapterConfig,
+  context: SlackInboundContext,
+): InboundClassification {
+  // Self-drop is the hard floor: never route our own messages back to
+  // ourselves. The check requires `botUserId` (post-auth.test); before that,
+  // fail closed below because mention, reply, and self classification all
+  // depend on the bot identity.
+  if (context.botUserId !== null && event.user === context.botUserId) {
+    return { kind: 'drop', reason: 'self_author' }
+  }
+  if (event.user === undefined || event.user === '') {
+    // System events (channel_join, message_changed, …) have no `user`;
+    // they were also the ONLY way previously to flag bot_message subtype
+    // events with no user. Now that we accept peer bots, a `bot_message`
+    // subtype WITH a user (rare, but happens for legacy integrations) is
+    // routed; subtype + no user still drops as `no_user`.
+    return { kind: 'drop', reason: 'no_user' }
+  }
+
+  const rawText = event.text ?? ''
+  const text = inboundText(event)
+  if (text === '') return { kind: 'drop', reason: 'empty_text' }
+
+  const isDm = event.channel_type === 'im'
+  const workspace = isDm ? '@dm' : context.teamId
+  if (!isAllowed(config.allow, workspace, event.channel)) {
+    return { kind: 'drop', reason: 'not_in_allow_list' }
+  }
+
+  if (context.botUserId === null) {
+    return { kind: 'drop', reason: 'pre_connect' }
+  }
+
+  // Mention parsing runs against the raw user-typed text only — the
+  // appended `[Slack message with attachment: ...]` summary contains URLs
+  // and ids that must not be misread as mentions or group broadcasts.
+  // Group mentions (`<!here>`, `<!channel>`, `<!everyone>`) are coerced to
+  // direct mentions: the user fired a broadcast that explicitly includes the
+  // bot, and from the engagement layer's perspective there is no meaningful
+  // difference between "@bot, look at this" and "@channel, look at this" —
+  // both are an invitation to participate. Treating them identically also
+  // means the existing 'mention' trigger in typeclaw.json catches both
+  // without any new config surface.
+  const hasGroupMention = GROUP_MENTION_PATTERN.test(rawText)
+  const isBotMention = hasGroupMention || rawText.includes(`<@${context.botUserId}>`)
+  // Top-level alias addressing (e.g. "윙키야") is engagement-equivalent
+  // to a `<@bot>` mention (see engagement.ts: alias is unconditional and
+  // ranks alongside explicit triggers). Anchor `thread` on the inbound
+  // ts in that case too, so the bot's reply threads under the user's
+  // message rather than landing as a sibling top-level post. Mention
+  // wins the OR short-circuit; alias matching only runs when no @ was
+  // found, keeping the cost negligible in mention-heavy channels.
+  const aliasMatched = !isBotMention && matchesAnyAlias(rawText, context.selfAliases ?? [])
+  const thread = event.thread_ts ?? (!isDm && (isBotMention || aliasMatched) ? event.ts : null)
+
+  // A reply is "to the bot" only when the thread parent was authored by the
+  // bot. Slack surfaces the parent author via `parent_user_id` on every
+  // reply event; without that match we don't know who authored the parent
+  // and MUST NOT engage on the `reply` trigger — otherwise every threaded
+  // reply between two humans (or two peer bots) wakes us up. The thread
+  // root itself shares its ts with thread_ts and carries no parent_user_id.
+  const isReply = event.thread_ts !== undefined && event.thread_ts !== event.ts
+  const replyToBotMessageId =
+    isReply && context.botUserId !== null && event.parent_user_id === context.botUserId ? event.thread_ts! : null
+
+  const mentionedUserIds = extractMentionedUserIds(rawText)
+  const mentionsOthers = mentionedUserIds.length > 0 && !mentionedUserIds.includes(context.botUserId)
+
+  // Symmetric to `replyToBotMessageId` above: a reply whose parent author
+  // is identifiable AND is not the bot is a reply-to-other. The engagement
+  // layer uses this to suppress the solo-human fallback so the bot stays
+  // quiet when two humans (or a peer bot and a human) hold a thread side-
+  // conversation in a busy channel — the exact incident this fix addresses.
+  const replyToOtherMessageId =
+    isReply &&
+    event.parent_user_id !== undefined &&
+    event.parent_user_id !== '' &&
+    event.parent_user_id !== context.botUserId
+      ? event.thread_ts!
+      : null
+
+  // Slack signals "this message was authored by a bot" via either a non-empty
+  // bot_id or subtype === 'bot_message'. Either is sufficient.
+  const authorIsBot = (event.bot_id !== undefined && event.bot_id !== '') || event.subtype === 'bot_message'
+
+  return {
+    kind: 'route',
+    payload: {
+      adapter: 'slack-bot',
+      workspace,
+      chat: event.channel,
+      thread,
+      text,
+      externalMessageId: event.ts,
+      authorId: event.user,
+      authorName: event.user,
+      authorIsBot,
+      isBotMention,
+      replyToBotMessageId,
+      mentionsOthers,
+      replyToOtherMessageId,
+      isDm,
+      ts: slackTsToMillis(event.ts),
+    },
+  }
+}
+
+// Slack encodes user mentions inline as `<@U…>` (or `<@W…>` for some org
+// accounts, and `<@U…|fallback>` when the client supplied a label). Pull
+// every distinct id out of the text — duplicates collapse so the caller
+// can do a clean `includes()` check against the bot's own id.
+const MENTION_PATTERN = /<@([UW][A-Z0-9]+)(?:\|[^>]*)?>/g
+
+// Slack's group mention markup uses `!` (not `@`) and may carry an optional
+// `|label` suffix, same as user mentions. We deliberately exclude the
+// `<!subteam^ID>` form — engaging on every user-group ping would require
+// knowing which subteams the bot is a member of, which is outside what
+// Socket Mode events surface to us.
+const GROUP_MENTION_PATTERN = /<!(?:here|channel|everyone)(?:\|[^>]*)?>/
+
+function extractMentionedUserIds(text: string): string[] {
+  const seen = new Set<string>()
+  for (const match of text.matchAll(MENTION_PATTERN)) {
+    seen.add(match[1]!)
+  }
+  return Array.from(seen)
+}
+
+function inboundText(event: SlackInboundMessageEvent): string {
+  const rawText = event.text ?? ''
+  const mediaSummary = summarizeSlackMedia(event)
+  if (mediaSummary.length === 0) return rawText
+  const summary = `[Slack message with ${mediaSummary.join('; ')}]`
+  return rawText === '' ? summary : `${rawText}\n${summary}`
+}
+
+function summarizeSlackMedia(event: SlackInboundMessageEvent): string[] {
+  return (event.files ?? []).map(summarizeSlackFile)
+}
+
+function summarizeSlackFile(file: SlackFile): string {
+  const parts: string[] = [`attachment: ${file.name}`, `(${file.mimetype})`, `id=${file.id}`]
+  return parts.join(' ')
+}

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

@@ -0,0 +1,51 @@
+import type { SlackInboundMessageEvent } from './slack-bot-classify'
+
+export const SLACK_DEDUPE_CAPACITY = 256
+
+export type SlackDedupeMatch = 'client_msg_id' | 'channel_ts'
+
+export type SlackDedupeKeys = {
+  channelTs: string
+  clientMsgId: string | null
+}
+
+export type SlackDedupe = {
+  check: (event: Pick<SlackInboundMessageEvent, 'channel' | 'ts' | 'client_msg_id'>) => SlackDedupeMatch | null
+  mark: (event: Pick<SlackInboundMessageEvent, 'channel' | 'ts' | 'client_msg_id'>) => void
+}
+
+// Two parallel insertion-ordered Sets. `client_msg_id` is the primary key
+// because it is stable across Slack-side resends of the same user gesture
+// (observed in the wild: a single Slack mention surfaced as two `message`
+// events ~21s apart with different `ts` values, identical text, and — per
+// Slack's API contract — identical `client_msg_id`). `channel:ts` is the
+// fallback because it is the only key available for events Slack does not
+// stamp with `client_msg_id` (bot messages, system messages, and historically
+// `app_mention` envelopes).
+export function createSlackDedupe(capacity: number = SLACK_DEDUPE_CAPACITY): SlackDedupe {
+  const tsRing = new Set<string>()
+  const clientMsgIdRing = new Set<string>()
+
+  const remember = (ring: Set<string>, key: string): void => {
+    if (ring.has(key)) return
+    if (ring.size >= capacity) {
+      const oldest = ring.values().next().value
+      if (oldest !== undefined) ring.delete(oldest)
+    }
+    ring.add(key)
+  }
+
+  return {
+    check: (event) => {
+      const cmid = event.client_msg_id
+      if (cmid !== undefined && cmid !== '' && clientMsgIdRing.has(cmid)) return 'client_msg_id'
+      if (tsRing.has(`${event.channel}:${event.ts}`)) return 'channel_ts'
+      return null
+    },
+    mark: (event) => {
+      remember(tsRing, `${event.channel}:${event.ts}`)
+      const cmid = event.client_msg_id
+      if (cmid !== undefined && cmid !== '') remember(clientMsgIdRing, cmid)
+    },
+  }
+}

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

@@ -0,0 +1,10 @@
+// Slack timestamps are "<seconds>.<microseconds>" strings. Convert to ms
+// so callers can sort/render chronologically without re-parsing. Lives in
+// its own file to break the import cycle between slack-bot.ts (which
+// imports the classifier) and slack-bot-classify.ts (which needs to stamp
+// inbound `ts` at classify time).
+export function slackTsToMillis(ts: string): number {
+  const parsed = Number.parseFloat(ts)
+  if (!Number.isFinite(parsed)) return 0
+  return Math.round(parsed * 1000)
+}