typeclaw 0.17.0 → 0.19.0

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

@@ -35,12 +35,11 @@ import {
 import { createSlackDedupe } from './slack-bot-dedupe'
 import {
   buildSlashAckPayload,
+  commandResultReply,
   parseSlashCommand,
-  SLACK_SLASH_REPLY_ABORTED,
-  SLACK_SLASH_REPLY_AMBIGUOUS,
+  parseThreadCommand,
   SLACK_SLASH_REPLY_FAILED,
-  SLACK_SLASH_REPLY_NO_LIVE_SESSION,
-  SLACK_SLASH_REPLY_PERMISSION_DENIED,
+  type ThreadCommandInput,
 } from './slack-bot-slash-commands'
 import { slackTsToMillis } from './slack-bot-time'
 
@@ -52,7 +51,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(['stop'])
+export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['help', 'stop'])
 
 // 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
@@ -124,16 +123,7 @@ export function createSlashCommandHandler(
       return
     }
 
-    const replyContent =
-      result.kind === 'handled'
-        ? SLACK_SLASH_REPLY_ABORTED
-        : result.kind === 'no-live-session'
-          ? SLACK_SLASH_REPLY_NO_LIVE_SESSION
-          : result.kind === 'permission-denied'
-            ? SLACK_SLASH_REPLY_PERMISSION_DENIED
-            : result.kind === 'ambiguous'
-              ? SLACK_SLASH_REPLY_AMBIGUOUS
-              : SLACK_SLASH_REPLY_FAILED
+    const replyContent = commandResultReply(result)
 
     // Final ack on the happy path: own try/catch so a thrown ack here does
     // NOT cascade into the error-path ack above (which would violate the
@@ -158,6 +148,67 @@ export function createSlashCommandHandler(
   }
 }
 
+export type ThreadCommandReplyPoster = (args: { chat: string; thread: string | null; text: string }) => Promise<void>
+
+export type ThreadCommandHandlerDeps = {
+  router: Pick<ChannelRouter, 'executeCommand'>
+  knownCommandNames: ReadonlySet<string>
+  postReply: ThreadCommandReplyPoster
+  logger: SlackBotAdapterLoggerLike
+}
+
+export type ThreadCommandOutcome = { kind: 'not-a-command' } | { kind: 'duplicate' } | { kind: 'executed' }
+
+// Synchronous reservation: the adapter marks the dedupe ring inside this hook,
+// which the handler calls before its first `await`. Two duplicate Slack
+// deliveries can both clear `dedupe.check()` on the same JS tick; whichever
+// reserves first wins and returns `true`, the loser returns `false` and aborts
+// — so a control command never runs twice across the check→execute window.
+export type ThreadCommandReserve = () => boolean
+
+// Routes a `!cmd` thread message through the SAME router.executeCommand path as
+// native slashes, then posts the outcome back into the thread. Returns
+// 'not-a-command' (caller proceeds with normal classify/route), 'duplicate'
+// (a racing delivery already reserved this event — caller stops silently), or
+// 'executed' (command handled — caller stops; it is not agent input).
+export function createThreadCommandHandler(
+  deps: ThreadCommandHandlerDeps,
+): (input: ThreadCommandInput, reserve: ThreadCommandReserve) => Promise<ThreadCommandOutcome> {
+  return async (input, reserve) => {
+    const parsed = parseThreadCommand(input, deps.knownCommandNames)
+    if (parsed.kind === 'ignore') {
+      return { kind: 'not-a-command' }
+    }
+    // Reserve synchronously, before any await, to close the check→execute race.
+    if (!reserve()) {
+      return { kind: 'duplicate' }
+    }
+    const { command } = parsed
+    deps.logger.info(
+      `[slack-bot] thread-command !${command.name} invoker=${command.invokerId} team=${command.key.workspace} channel=${command.key.chat} thread=${command.key.thread ?? '(none)'}`,
+    )
+
+    let reply: string
+    try {
+      const result = await deps.router.executeCommand(command.key, command.name, {
+        invokerId: command.invokerId,
+      })
+      reply = commandResultReply(result)
+      deps.logger.info(`[slack-bot] thread-command !${command.name} result=${result.kind}`)
+    } catch (err) {
+      deps.logger.error(`[slack-bot] thread-command !${command.name} failed: ${describe(err)}`)
+      reply = SLACK_SLASH_REPLY_FAILED
+    }
+
+    try {
+      await deps.postReply({ chat: input.channel, thread: input.threadTs, text: reply })
+    } catch (err) {
+      deps.logger.warn(`[slack-bot] thread-command reply post failed: ${describe(err)}`)
+    }
+    return { kind: 'executed' }
+  }
+}
+
 // app_mention payloads omit channel_type and never carry a subtype, so we
 // promote them to a message-shaped event for the shared classifier. The
 // promoted event is classified as a regular channel message; the
@@ -408,14 +459,14 @@ export function createSlackMembershipResolver(deps: {
     }
 
     let bots = 0
-    let humans = 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))
       if (isBot) bots++
-      else humans++
+      else humanMemberIds.push(userId)
     }
-    return { humans, bots, fetchedAt: now(), truncated: false }
+    return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated: false, humanMemberIds }
   }
 }
 
@@ -783,6 +834,24 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
     formatChannelTag,
   })
 
+  const handleThreadCommand = createThreadCommandHandler({
+    router: options.router,
+    knownCommandNames: SLACK_SLASH_COMMAND_NAMES,
+    logger,
+    postReply: async ({ chat, thread, text }) => {
+      const result = await outboundCallback({
+        adapter: 'slack-bot',
+        workspace: teamId ?? 'unknown',
+        chat,
+        ...(thread !== null ? { thread } : {}),
+        text,
+      })
+      if (!result.ok) {
+        throw new Error(result.error)
+      }
+    },
+  })
+
   const handleMessageEvent = async (
     event: SlackInboundMessageEvent,
     source: 'message' | 'app_mention',
@@ -813,6 +882,38 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
         return
       }
 
+      // Intercept `!cmd` thread-message commands BEFORE classifyInbound. A
+      // command is control traffic — neither dropped nor routed to the agent —
+      // so it must short-circuit here. Bypassing classifyInbound also bypasses
+      // its self_author / no_user drops, so we replicate those guards: never
+      // execute a command from our own message (echo loop) or a userless
+      // system event. The `reserve` closure marks dedupe synchronously the
+      // instant the command is recognised (before the router await), closing
+      // the check→execute race for duplicate deliveries.
+      if (event.user !== undefined && event.user !== '' && (botUserId === null || event.user !== botUserId)) {
+        const reserve = (): boolean => {
+          if (dedupe.check(event) !== null) return false
+          dedupe.mark(event)
+          return true
+        }
+        const outcome = await handleThreadCommand(
+          {
+            text: event.text ?? '',
+            channel: event.channel,
+            threadTs: event.thread_ts ?? null,
+            isDm: event.channel_type === 'im',
+            teamId,
+            invokerId: event.user,
+          },
+          reserve,
+        )
+        if (outcome.kind === 'executed') return
+        if (outcome.kind === 'duplicate') {
+          logger.info(`[slack-bot] dropped ts=${event.ts} reason=duplicate_delivery (thread-command race)`)
+          return
+        }
+      }
+
       const verdict = classifyInbound(event, options.configRef(), {
         teamId,
         botUserId,

package/src/channels/commands.ts

@@ -0,0 +1,10 @@
+import type { CommandInfo } from '@/commands'
+
+// Generated from registry metadata so the listing can never drift from the
+// actual command set. The `/` prefix is canonical across every surface; Slack
+// threads accept the `!` alias for the same names.
+export function formatChannelCommandHelp(commands: readonly CommandInfo[]): string {
+  if (commands.length === 0) return 'No commands are available.'
+  const lines = commands.map((command) => `/${command.name} — ${command.description}`)
+  return ['Available commands:', ...lines].join('\n')
+}

package/src/channels/engagement.ts

@@ -81,11 +81,25 @@ 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.
+  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'
 
-  if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
+  // 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) {
     return 'engage'
   }
 
@@ -169,13 +183,30 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   // peer's first message it's caught forever.
   if (textTargetsAnyPeerBot(message.text, participants)) return 'observe'
 
-  const persistedHumans = participants.filter((p) => p.isBot !== true).length
-  const effectiveHumans = resolveEffectiveHumans(persistedHumans, input.membership, now)
   if (effectiveHumans <= 1 && !message.authorIsBot) return 'engage'
 
   return 'observe'
 }
 
+export function countEffectiveHumans(
+  participants: readonly ChannelParticipant[],
+  membership: MembershipCount | null,
+  now: number,
+): number {
+  const persistedHumans = participants.filter((p) => p.isBot !== true).length
+  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.
+export function isMultiHumanGroup(isDm: boolean, effectiveHumans: number): boolean {
+  return !isDm && effectiveHumans > 1
+}
+
 function textTargetsAnyPeerBot(text: string, participants: readonly ChannelParticipant[]): boolean {
   const haystack = text.toLocaleLowerCase()
   for (const p of participants) {

package/src/channels/github-token-bridge.ts

@@ -0,0 +1,42 @@
+// Decoupled from ChannelRouter on purpose: minting a token for an arbitrary
+// bash `gh` command is adjacent to channels but is not routing, and a global
+// singleton would leak resolver state across tests. One instance is created in
+// run/index.ts and threaded to both the plugin loader and the channel manager.
+
+export type GithubTokenResolveResult = { kind: 'token'; token: string } | { kind: 'unavailable'; reason: string }
+
+export type ResolveGithubTokenForRepo = (repoSlug: string) => Promise<GithubTokenResolveResult>
+
+export type GithubTokenBridge = {
+  resolveTokenForRepo: ResolveGithubTokenForRepo
+  registerResolver: (resolver: (repoSlug: string) => Promise<string>) => () => void
+}
+
+const NO_RESOLVER_REASON =
+  'GitHub App token unavailable; the GitHub channel adapter is not running or failed to start. ' +
+  'Check `typeclaw logs` and `secrets.json#channels.github`.'
+
+export function createGithubTokenBridge(): GithubTokenBridge {
+  let current: ((repoSlug: string) => Promise<string>) | null = null
+
+  return {
+    resolveTokenForRepo: async (repoSlug) => {
+      const resolver = current
+      if (resolver === null) return { kind: 'unavailable', reason: NO_RESOLVER_REASON }
+      try {
+        const token = await resolver(repoSlug)
+        return { kind: 'token', token }
+      } catch (err) {
+        return { kind: 'unavailable', reason: err instanceof Error ? err.message : String(err) }
+      }
+    },
+    registerResolver: (resolver) => {
+      current = resolver
+      return () => {
+        // Only clear if still the active resolver: a stop() racing a newer
+        // start() must not wipe the newer registration.
+        if (current === resolver) current = null
+      }
+    },
+  }
+}

package/src/channels/index.ts

@@ -1,4 +1,10 @@
 export { createChannelManager, type ChannelManager, type ChannelManagerOptions } from './manager'
+export {
+  createGithubTokenBridge,
+  type GithubTokenBridge,
+  type GithubTokenResolveResult,
+  type ResolveGithubTokenForRepo,
+} from './github-token-bridge'
 export {
   createChannelRouter,
   type ChannelRouter,

package/src/channels/manager.ts

@@ -12,6 +12,7 @@ import { createGithubAdapter, type GithubAdapter } from './adapters/github'
 import { createKakaotalkAdapter, type KakaotalkAdapter } from './adapters/kakaotalk'
 import { createSlackBotAdapter, type SlackBotAdapter } from './adapters/slack-bot'
 import { createTelegramBotAdapter, type TelegramBotAdapter } from './adapters/telegram-bot'
+import type { GithubTokenBridge } from './github-token-bridge'
 import { createChannelRouter, type ChannelRouter, type ClaimHandler, type CreateSessionForChannel } from './router'
 import {
   ADAPTER_IDS,
@@ -84,6 +85,10 @@ export type ChannelManagerOptions = {
   // Production wiring (`src/run/index.ts`) always passes the agent's
   // Stream; tests typically omit it.
   stream?: Stream
+  // Write-side of the GithubTokenBridge. The github adapter publishes its
+  // 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
 }
 
 export type ChannelManager = {
@@ -199,6 +204,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
         logger,
         tunnelUrl: () => options.tunnelUrlForChannel?.('github') ?? null,
         tunnelConfiguredForChannel: () => options.tunnelConfiguredForChannel?.('github') ?? false,
+        ...(options.githubTokenBridge !== undefined ? { githubTokenBridge: options.githubTokenBridge } : {}),
       })
     }
     if (name === 'telegram-bot') {

package/src/channels/membership.ts

@@ -21,6 +21,15 @@ export type MembershipCount = {
   bots: number
   fetchedAt: number
   truncated: boolean
+  // Identities of the human members, present ONLY when the adapter enumerated
+  // the COMPLETE current membership and classified every listed member in the
+  // same pass that produced `humans`. When set, `humanMemberIds.length` equals
+  // `humans` by construction, so a consumer can prove "every human in the room
+  // is X" by resolving each id — something the bare `humans` count cannot do.
+  // Left undefined by approximate/truncated/history-derived reads and by
+  // adapters that cannot enumerate members (Telegram, KakaoTalk); consumers
+  // that need a completeness proof must fail closed when it is absent.
+  humanMemberIds?: readonly string[]
 }
 
 export type MembershipResolverFailure = { kind: 'transient' } | { kind: 'permanent' }