typeclaw 0.20.0 → 0.22.0

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

@@ -1,6 +1,13 @@
-import { SlackBotClient, SlackBotListener, type SlackSocketModeSlashCommandArgs } from 'agent-messenger/slackbot'
+import {
+  SlackBotClient,
+  SlackBotListener,
+  type SlackFile,
+  type SlackSocketModeSlashCommandArgs,
+} from 'agent-messenger/slackbot'
 
 import {
+  MEMBERSHIP_CACHE_TRANSIENT_TTL_MS,
+  MEMBERSHIP_CACHE_TTL_MS,
   MEMBERSHIP_ENUMERATION_CAP,
   type MembershipResolver,
   type MembershipResolverFailure,
@@ -28,7 +35,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'
@@ -51,7 +60,7 @@ import { slackTsToMillis } from './slack-bot-time'
 // slash_commands events we route vs drop. The ui.test.ts manifest-drift
 // test asserts equality between this set and SLACK_APP_MANIFEST.features.
 // slash_commands so the two can never silently diverge.
-export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['help', 'stop'])
+export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['help', 'stop', 'reload', 'restart'])
 
 // Resolvers fall back to the raw id on failure, so a name equal to the id
 // means resolution failed; we render the bare id rather than `id(id)`. The
@@ -369,6 +378,7 @@ type SlackRawHistoryMessage = {
   text?: string
   thread_ts?: string
   parent_user_id?: string
+  files?: SlackFile[]
 }
 
 type SlackHistoryResponse = {
@@ -396,6 +406,16 @@ type SlackUserInfoResponse = {
   user?: { is_bot?: boolean; deleted?: boolean }
 }
 
+type SlackUsersListResponse = {
+  ok: boolean
+  error?: string
+  members?: Array<{ id?: string; is_bot?: boolean }>
+  response_metadata?: { next_cursor?: string }
+}
+
+const USERS_LIST_PAGE_LIMIT = 200
+const USERS_LIST_MAX_PAGES = 50
+
 export function createSlackMembershipResolver(deps: {
   token: string
   logger: SlackBotAdapterLogger
@@ -406,6 +426,43 @@ export function createSlackMembershipResolver(deps: {
   const fetchFn = deps.fetchImpl ?? fetch
   const now = deps.now ?? Date.now
   const userBotCache = new Map<string, boolean>()
+
+  // Keyed by workspace. One resolver instance is bound to a single token/team
+  // today, but the router dispatches by adapter (not by adapter+workspace), so
+  // scoping the warm set by `key.workspace` keeps a set built for one workspace
+  // from ever classifying another's members if a multi-workspace mode is added.
+  const botSetCache = new Map<string, { ids: ReadonlySet<string>; fetchedAt: number }>()
+  const botSetFailedAt = new Map<string, number>()
+  const botSetInFlight = new Map<string, Promise<ReadonlySet<string> | null>>()
+
+  const warmBotSet = async (workspace: string): Promise<ReadonlySet<string> | null> => {
+    const cached = botSetCache.get(workspace)
+    if (cached !== undefined && now() - cached.fetchedAt < MEMBERSHIP_CACHE_TTL_MS) return cached.ids
+    // Negative-cache a failed warm so a rate-limited workspace doesn't re-run
+    // the full paginated `users.list` crawl on every membership read — that
+    // would keep the hot path expensive under the exact failure this PR fixes.
+    // Members fall back to per-id `users.info` during the cooldown.
+    const failedAt = botSetFailedAt.get(workspace)
+    if (failedAt !== undefined && now() - failedAt < MEMBERSHIP_CACHE_TRANSIENT_TTL_MS) return null
+    const inFlight = botSetInFlight.get(workspace)
+    if (inFlight !== undefined) return await inFlight
+    const promise = fetchWorkspaceBotIds(fetchFn, deps.token, deps.logger)
+      .then((ids) => {
+        if (ids !== null) {
+          botSetCache.set(workspace, { ids, fetchedAt: now() })
+          botSetFailedAt.delete(workspace)
+        } else {
+          botSetFailedAt.set(workspace, now())
+        }
+        return ids
+      })
+      .finally(() => {
+        botSetInFlight.delete(workspace)
+      })
+    botSetInFlight.set(workspace, promise)
+    return await promise
+  }
+
   return async (key): Promise<MembershipResolverResult> => {
     if (key.workspace === '@dm') return { humans: 1, bots: 1, fetchedAt: now(), truncated: false }
 
@@ -458,11 +515,22 @@ export function createSlackMembershipResolver(deps: {
       return members.failure
     }
 
+    // Reached only for channels at or under the cap (larger ones returned
+    // `truncated` above). `conversations.members` gives ids with no bot/human
+    // flag and Slack has no bulk-classify-ids call, so per-member `users.info`
+    // is an N+1 that exceeds the router cold-fetch timeout near the cap; the
+    // read then returns null and engagement misreads the busy channel as solo.
+    // Classify against a workspace bot-id set from one paginated `users.list`
+    // (bots are a small set, shared across channels). `users.info` stays as a
+    // per-id fallback for ids minted after the last warm, keeping `bots` and
+    // `humanMemberIds` exact for `grant_role`'s "no peer bot present" proof.
+    const memberIds = members.value.members ?? []
+    const botSet = await warmBotSet(key.workspace)
     let bots = 0
     const humanMemberIds: string[] = []
-    for (const userId of members.value.members ?? []) {
-      const cached = userBotCache.get(userId)
-      const isBot = cached ?? (await resolveSlackUserIsBot(fetchFn, deps.token, userId, deps.logger, userBotCache))
+    for (const userId of memberIds) {
+      const isBot =
+        botSet?.has(userId) ?? (await resolveSlackUserIsBot(fetchFn, deps.token, userId, deps.logger, userBotCache))
       if (isBot) bots++
       else humanMemberIds.push(userId)
     }
@@ -504,10 +572,17 @@ async function resolveSlackUserIsBot(
   logger: SlackBotAdapterLogger,
   cache: Map<string, boolean>,
 ): Promise<boolean> {
+  const cached = cache.get(userId)
+  if (cached !== undefined) return cached
   const info = await slackApi<SlackUserInfoResponse>(fetchFn, token, 'users.info', { user: userId })
   if (!info.ok) {
     logger.warn(`[slack-bot] membership users.info user=${userId} failed: ${info.reason}`)
-    cache.set(userId, false)
+    // Only a definitive answer is cached. A transient failure (429/network)
+    // must not be memoized as "human" — that would poison classification until
+    // restart and let a peer bot read as human, skewing engagement and
+    // `grant_role`'s "no peer bot" proof. Default this read to human (the
+    // safe, count-conservative direction) but let the next read retry.
+    if (info.failure.kind === 'permanent') cache.set(userId, false)
     return false
   }
   const isBot = info.value.user?.is_bot === true
@@ -515,6 +590,38 @@ async function resolveSlackUserIsBot(
   return isBot
 }
 
+// Enumerates the workspace and returns the set of bot user ids. Slack has no
+// server-side `is_bot` filter, so we page the full `users.list` and keep only
+// bots — a complete pass is required so silent lurking bots (never seen in
+// history) are still counted, which `grant_role`'s "no peer bot" proof relies
+// on. Returns null on any failure so the caller can fall back to per-id
+// `users.info` rather than trusting an incomplete set. Page count is bounded so
+// a pathologically large workspace cannot stall the read indefinitely.
+async function fetchWorkspaceBotIds(
+  fetchFn: typeof fetch,
+  token: string,
+  logger: SlackBotAdapterLogger,
+): Promise<ReadonlySet<string> | null> {
+  const botIds = new Set<string>()
+  let cursor: string | undefined
+  for (let page = 0; page < USERS_LIST_MAX_PAGES; page++) {
+    const fields: Record<string, string> = { limit: String(USERS_LIST_PAGE_LIMIT) }
+    if (cursor !== undefined && cursor !== '') fields.cursor = cursor
+    const res = await slackApi<SlackUsersListResponse>(fetchFn, token, 'users.list', fields)
+    if (!res.ok) {
+      logger.warn(`[slack-bot] users.list failed: ${res.reason}; falling back to per-member classification`)
+      return null
+    }
+    for (const member of res.value.members ?? []) {
+      if (member.is_bot === true && typeof member.id === 'string') botIds.add(member.id)
+    }
+    cursor = res.value.response_metadata?.next_cursor
+    if (cursor === undefined || cursor === '') return botIds
+  }
+  logger.warn(`[slack-bot] users.list exceeded ${USERS_LIST_MAX_PAGES} pages; bot set may be incomplete`)
+  return null
+}
+
 function slackFailureForError(error: string): MembershipResolverFailure {
   if (['invalid_auth', 'not_authed', 'not_in_channel', 'channel_not_found', 'missing_scope'].includes(error)) {
     return { kind: 'permanent' }
@@ -601,14 +708,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

@@ -89,14 +89,51 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   if (config.trigger.includes('mention') && message.isBotMention) return 'engage'
   if (config.trigger.includes('reply') && message.replyToBotMessageId !== null) return 'engage'
 
-  // 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
+  // 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 instead (the prior approach) dropped genuine follow-ups outright.
+  // 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'
   }
@@ -155,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,

package/src/channels/manager.ts

@@ -89,6 +89,12 @@ export type ChannelManagerOptions = {
   // per-repo App token minter here on start (App auth only) so plugin hooks
   // can resolve a token for ad-hoc `gh` commands. Tests omit it.
   githubTokenBridge?: GithubTokenBridge
+  // Forwarded to the router as the /reload and /restart command handlers.
+  // Production wiring (src/run/index.ts) supplies the reload-registry and
+  // container-restart bindings; tests omit them so the commands stay
+  // unregistered. See CreateChannelRouterOptions.onReload/onRestart.
+  onReload?: () => Promise<string>
+  onRestart?: () => Promise<string>
 }
 
 export type ChannelManager = {
@@ -125,6 +131,8 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
     ...(options.permissions ? { permissions: options.permissions } : {}),
     ...(options.claimHandler ? { claimHandler: options.claimHandler } : {}),
     ...(options.stream ? { stream: options.stream } : {}),
+    ...(options.onReload ? { onReload: options.onReload } : {}),
+    ...(options.onRestart ? { onRestart: options.onRestart } : {}),
   })
   const createDiscordAdapter = options.createDiscordAdapter ?? createDiscordBotAdapter
   const createGithub = options.createGithubAdapter ?? createGithubAdapter