typeclaw 0.7.0 → 0.8.0

package/src/channels/adapters/discord-bot-slash-commands.ts

@@ -0,0 +1,186 @@
+import type { DiscordGatewayInteractionEvent } from 'agent-messenger/discordbot'
+
+import type { ChannelKey } from '@/channels/types'
+
+const DISCORD_API_BASE = 'https://discord.com/api/v10'
+
+// CHAT_INPUT is the only Discord application-command type that maps to the
+// existing text-prefix command registry. USER (2) and MESSAGE (3) are
+// right-click context-menu surfaces with no /name args equivalent — we don't
+// register them and we drop their interactions.
+const APPLICATION_COMMAND_TYPE_CHAT_INPUT = 1
+
+// type 4 = CHANNEL_MESSAGE_WITH_SOURCE; flag 64 = EPHEMERAL (only the invoker
+// sees it). Ephemeral keeps /stop replies out of the channel transcript.
+// Discord drops the interaction with "This interaction failed" if we don't
+// ack within ~3 seconds.
+const INTERACTION_CALLBACK_TYPE_CHANNEL_MESSAGE_WITH_SOURCE = 4
+const INTERACTION_MESSAGE_FLAG_EPHEMERAL = 64
+export const DISCORD_INTERACTION_ACK_BUDGET_MS = 3000
+
+export type DiscordCommandDeclaration = {
+  name: string
+  description: string
+}
+
+export type RegisterCommandsArgs = {
+  token: string
+  applicationId: string
+  commands: readonly DiscordCommandDeclaration[]
+  fetchImpl?: typeof fetch
+}
+
+export type RegisterCommandsResult = { ok: true } | { ok: false; error: string }
+
+// Bulk-overwrite is idempotent — Discord replaces the entire registered set
+// with whatever the body declares, so re-running `typeclaw start` with the
+// same commands is a no-op server-side. Global (vs. per-guild) registration
+// avoids the bot-needs-to-know-its-guilds bootstrap, at the cost of
+// Discord's documented up-to-1-hour propagation for new commands. Text-
+// prefix /stop continues to work the entire time, so the propagation
+// window doesn't regress existing behavior.
+//
+// CAUTION: this PUT replaces ALL global commands on the application with the
+// declared list. Sharing the bot application with another integration that
+// also registers global commands would delete those commands. Don't share
+// the application; TypeClaw owns the application's command set.
+export async function registerCommands(args: RegisterCommandsArgs): Promise<RegisterCommandsResult> {
+  const fetchImpl = args.fetchImpl ?? fetch
+  const body = args.commands.map((cmd) => ({
+    name: cmd.name,
+    description: cmd.description,
+    type: APPLICATION_COMMAND_TYPE_CHAT_INPUT,
+  }))
+  try {
+    const res = await fetchImpl(`${DISCORD_API_BASE}/applications/${encodeURIComponent(args.applicationId)}/commands`, {
+      method: 'PUT',
+      headers: { Authorization: `Bot ${args.token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      return { ok: false, error: `http ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}` }
+    }
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+export type ParsedSlashCommand = {
+  name: string
+  key: ChannelKey
+  invokerId: string
+  interactionId: string
+  interactionToken: string
+}
+
+export type ParseInteractionResult =
+  | { kind: 'parsed'; command: ParsedSlashCommand }
+  | { kind: 'ignore'; reason: 'not-application-command' | 'unknown-command' | 'no-invoker' | 'no-channel' }
+
+export function parseInteractionAsCommand(
+  event: DiscordGatewayInteractionEvent,
+  knownCommands: ReadonlySet<string>,
+): ParseInteractionResult {
+  const data = event.data as { name?: string; type?: number } | undefined
+  if (!data || data.type !== APPLICATION_COMMAND_TYPE_CHAT_INPUT) {
+    return { kind: 'ignore', reason: 'not-application-command' }
+  }
+  const name = typeof data.name === 'string' ? data.name.toLowerCase() : ''
+  if (name === '' || !knownCommands.has(name)) {
+    return { kind: 'ignore', reason: 'unknown-command' }
+  }
+  // Guild interactions carry the invoker in member.user.id; DM interactions
+  // carry it in user.id. Exactly one is present.
+  const member = event.member as { user?: { id?: string } } | undefined
+  const invokerId = member?.user?.id ?? event.user?.id ?? ''
+  if (invokerId === '') {
+    return { kind: 'ignore', reason: 'no-invoker' }
+  }
+  if (typeof event.channel_id !== 'string' || event.channel_id === '') {
+    return { kind: 'ignore', reason: 'no-channel' }
+  }
+  // Mirror discord-bot-classify: DM workspace is '@dm', threads are stored
+  // as their channel id in `chat` with `thread: null` (Discord treats threads
+  // as channels; interaction.channel_id is the thread id when the user
+  // invoked from a thread).
+  const workspace = typeof event.guild_id === 'string' && event.guild_id !== '' ? event.guild_id : '@dm'
+  return {
+    kind: 'parsed',
+    command: {
+      name,
+      key: { adapter: 'discord-bot', workspace, chat: event.channel_id, thread: null },
+      invokerId,
+      interactionId: event.id,
+      interactionToken: event.token,
+    },
+  }
+}
+
+// Content is required even when there's nothing to stop, because Discord
+// rejects empty CHANNEL_MESSAGE_WITH_SOURCE responses.
+export function buildInteractionAck(content: string): {
+  type: number
+  data: { content: string; flags: number }
+} {
+  return {
+    type: INTERACTION_CALLBACK_TYPE_CHANNEL_MESSAGE_WITH_SOURCE,
+    data: { content, flags: INTERACTION_MESSAGE_FLAG_EPHEMERAL },
+  }
+}
+
+export type AckInteractionArgs = {
+  interactionId: string
+  interactionToken: string
+  content: string
+  fetchImpl?: typeof fetch
+}
+
+export type AckInteractionResult = { ok: true } | { ok: false; error: string }
+
+// Interaction acks must NOT carry the bot token — the interaction token in
+// the URL is the only credential Discord expects on this endpoint, and
+// adding Authorization sometimes triggers a 401.
+//
+// Errors are scrubbed before being returned: a thrown network error from
+// fetch may include the full request URL (including the interaction token,
+// which is a short-lived credential) in its message string depending on
+// the runtime. We surface only the error class to avoid leaking the token
+// into logs.
+export async function ackInteraction(args: AckInteractionArgs): Promise<AckInteractionResult> {
+  const fetchImpl = args.fetchImpl ?? fetch
+  const body = buildInteractionAck(args.content)
+  try {
+    const res = await fetchImpl(
+      `${DISCORD_API_BASE}/interactions/${encodeURIComponent(args.interactionId)}/${encodeURIComponent(args.interactionToken)}/callback`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      },
+    )
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      return { ok: false, error: `http ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}` }
+    }
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, error: `network error: ${sanitizeErrorName(err)}` }
+  }
+}
+
+// Returns the error class name without the message, so callers can log the
+// failure mode without leaking URLs/tokens that some runtimes embed in
+// error.message (e.g. Node's "fetch failed: TypeError: fetch failed,
+// cause: Error: ... https://discord.com/api/v10/interactions/123/<token>/callback").
+function sanitizeErrorName(err: unknown): string {
+  if (err instanceof Error) return err.name
+  return typeof err === 'string' ? 'string error' : 'unknown error'
+}
+
+export function synthesizeCommandText(name: string): string {
+  return `/${name}`
+}
+
+export const DISCORD_SLASH_COMMAND_TYPE_CHAT_INPUT = APPLICATION_COMMAND_TYPE_CHAT_INPUT

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

@@ -1,5 +1,9 @@
 import { DiscordBotClient, DiscordBotListener } from 'agent-messenger/discordbot'
-import { DiscordIntent, type DiscordGatewayMessageCreateEvent } from 'agent-messenger/discordbot'
+import {
+  DiscordIntent,
+  type DiscordGatewayInteractionEvent,
+  type DiscordGatewayMessageCreateEvent,
+} from 'agent-messenger/discordbot'
 
 import {
   MEMBERSHIP_ENUMERATION_CAP,
@@ -26,6 +30,26 @@ import type {
 
 import { createDiscordChannelResolver } from './discord-bot-channel-resolver'
 import { classifyInbound, type InboundDropReason } from './discord-bot-classify'
+import {
+  ackInteraction,
+  parseInteractionAsCommand,
+  registerCommands,
+  type DiscordCommandDeclaration,
+} from './discord-bot-slash-commands'
+
+// One declared slash command per logical agent gesture. /stop maps to the
+// existing channel-command of the same name in the router. Adding new
+// commands here is the documented extension point: declare the entry here,
+// then add the matching handler in createChannelRouter's command registry.
+const SLASH_COMMANDS: readonly DiscordCommandDeclaration[] = [
+  { name: 'stop', description: 'Abort the current turn in this channel' },
+]
+const SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(SLASH_COMMANDS.map((c) => c.name))
+
+const STOP_REPLY_ABORTED = 'Stopped the current turn.'
+const STOP_REPLY_NO_LIVE_SESSION = 'Nothing to stop — no active turn in this channel.'
+const STOP_REPLY_FAILED = 'Could not stop the current turn (internal error).'
+const STOP_REPLY_PERMISSION_DENIED = 'You do not have permission to stop the current turn in this channel.'
 
 const DISCORD_API_BASE = 'https://discord.com/api/v10'
 
@@ -66,6 +90,10 @@ export type DiscordBotAdapterOptions = {
   configRef: () => ChannelAdapterConfig
   token: string
   logger?: DiscordBotAdapterLogger
+  // Injectable for tests so adapter integration tests can assert on the
+  // exact REST calls without monkey-patching globalThis.fetch. Production
+  // callers leave it undefined to use the global fetch.
+  fetchImpl?: typeof fetch
 }
 
 export type DiscordBotAdapter = {
@@ -433,9 +461,91 @@ export function createFetchAttachmentCallback(deps: {
   }
 }
 
+export type InteractionHandlerDeps = {
+  router: Pick<ChannelRouter, 'executeCommand'>
+  knownCommandNames: ReadonlySet<string>
+  logger: DiscordBotAdapterLogger
+  formatChannelTag: (workspace: string, chat: string) => Promise<string>
+  fetchImpl?: typeof fetch
+}
+
+export function createInteractionHandler(
+  deps: InteractionHandlerDeps,
+): (event: DiscordGatewayInteractionEvent) => Promise<void> {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (event) => {
+    try {
+      const parsed = parseInteractionAsCommand(event, deps.knownCommandNames)
+      if (parsed.kind === 'ignore') {
+        // 'not-application-command' is the common case (buttons, modals,
+        // autocomplete); emit at warn only when we dropped something we
+        // ostensibly handle.
+        if (parsed.reason !== 'not-application-command') {
+          deps.logger.warn(`[discord-bot] interaction id=${event.id} dropped reason=${parsed.reason}`)
+        }
+        return
+      }
+      const { command } = parsed
+
+      // Pre-ACK: emit ONE line with bare ids only (no formatChannelTag).
+      // Discord's 3s ack budget covers everything until the callback POST
+      // returns 2xx; name resolution involves two Discord REST calls that
+      // can blow the budget on a slow API minute. Decorative logging with
+      // resolved names happens AFTER the ack.
+      deps.logger.info(
+        `[discord-bot] interaction /${command.name} id=${event.id} invoker=${command.invokerId} guild=${command.key.workspace} channel=${command.key.chat}`,
+      )
+
+      const result = await deps.router.executeCommand(command.key, command.name, {
+        invokerId: command.invokerId,
+      })
+      const replyContent =
+        result.kind === 'handled'
+          ? STOP_REPLY_ABORTED
+          : result.kind === 'no-live-session'
+            ? STOP_REPLY_NO_LIVE_SESSION
+            : result.kind === 'permission-denied'
+              ? STOP_REPLY_PERMISSION_DENIED
+              : STOP_REPLY_FAILED
+
+      const ack = await ackInteraction({
+        interactionId: command.interactionId,
+        interactionToken: command.interactionToken,
+        content: replyContent,
+        fetchImpl,
+      })
+      if (!ack.ok) {
+        // Discord's interaction token is single-use per callback type and
+        // ~15min total; once we miss the 3s ack window the user sees
+        // "This interaction failed" in the UI. The abort still happened
+        // server-side — only the user-visible confirmation is lost.
+        deps.logger.warn(`[discord-bot] interaction /${command.name} ack failed: ${ack.error}`)
+      }
+
+      // Decorative post-ack logging: resolve channel/guild names now that
+      // the 3s budget is no longer a concern. Best-effort — if name
+      // resolution fails we already logged bare ids above.
+      try {
+        const inboundTag = await deps.formatChannelTag(command.key.workspace, command.key.chat)
+        deps.logger.info(`[discord-bot] interaction /${command.name} result=${result.kind} ${inboundTag}`)
+      } catch (err) {
+        deps.logger.info(
+          `[discord-bot] interaction /${command.name} result=${result.kind} (channel-tag resolution failed: ${describe(err)})`,
+        )
+      }
+    } catch (err) {
+      deps.logger.error(`[discord-bot] handleInteraction failed: ${describe(err)}`)
+    }
+  }
+}
+
+export const DISCORD_SLASH_COMMANDS = SLASH_COMMANDS
+export const DISCORD_SLASH_COMMAND_NAMES = SLASH_COMMAND_NAMES
+
 export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): DiscordBotAdapter {
   const logger = options.logger ?? consoleLogger
   const client = new DiscordBotClient()
+  const fetchImpl = options.fetchImpl ?? fetch
   let listener: DiscordBotListener | null = null
   let botUserId: string | null = null
   let started = false
@@ -479,6 +589,28 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
 
   const fetchAttachmentCallback = createFetchAttachmentCallback({ token: options.token, logger })
 
+  const interactionHandler = createInteractionHandler({
+    router: options.router,
+    knownCommandNames: SLASH_COMMAND_NAMES,
+    logger,
+    formatChannelTag,
+    fetchImpl,
+  })
+
+  const handleInteractionCreate = async (event: DiscordGatewayInteractionEvent): Promise<void> => {
+    inflightInbounds++
+    try {
+      await interactionHandler(event)
+    } finally {
+      inflightInbounds--
+      if (inflightInbounds === 0 && stopWaiters.length > 0) {
+        const waiters = stopWaiters
+        stopWaiters = []
+        for (const w of waiters) w()
+      }
+    }
+  }
+
   const handleMessageCreate = async (event: DiscordGatewayMessageCreateEvent): Promise<void> => {
     inflightInbounds++
     try {
@@ -530,6 +662,33 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
       listener.on('connected', (info) => {
         botUserId = info.user.id
         logger.info(`[discord-bot] connected as ${info.user.username} (${info.user.id})`)
+        // For bots, the gateway's user.id IS the application id — the same
+        // value is required for both /me lookups and /applications/{id}/
+        // commands. Fire-and-forget registration so a slow Discord API
+        // call (or a 403 from missing applications.commands scope) doesn't
+        // block the listener from receiving messages. Text-prefix /stop
+        // keeps working regardless.
+        void registerCommands({
+          token: options.token,
+          applicationId: info.user.id,
+          commands: SLASH_COMMANDS,
+          fetchImpl,
+        }).then((result) => {
+          if (result.ok) {
+            logger.info(
+              `[discord-bot] slash commands registered (${SLASH_COMMANDS.map((c) => `/${c.name}`).join(' ')})`,
+            )
+          } else {
+            // 403 here is almost always missing applications.commands scope
+            // on the OAuth invite URL — operator-fixable, but the listener
+            // continues. Adding the hint inline so an operator doesn't have
+            // to grep docs to recognize the failure mode.
+            logger.warn(
+              `[discord-bot] slash command registration failed: ${result.error}` +
+                ' (if 403, re-invite the bot with the applications.commands scope)',
+            )
+          }
+        })
       })
       listener.on('disconnected', () => {
         logger.warn('[discord-bot] disconnected; SDK will reconnect with backoff')
@@ -540,6 +699,9 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
       listener.on('message_create', (event) => {
         void handleMessageCreate(event)
       })
+      listener.on('interaction_create', (event) => {
+        void handleInteractionCreate(event)
+      })
 
       options.router.registerOutbound('discord-bot', outboundCallback)
       options.router.registerTyping('discord-bot', typingCallback)

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

@@ -0,0 +1,82 @@
+import type { SlackSocketModeSlashCommandArgs } from 'agent-messenger/slackbot'
+
+import type { ChannelKey } from '@/channels/types'
+
+// Slack channel ids: 'C' = public, 'G' = private/legacy multi-party DM,
+// 'D' = direct message. Slash-command payloads don't carry `channel_type`,
+// so we read the id prefix directly. The slack-bot inbound classifier uses
+// `event.channel_type === 'im'` for the same purpose, but that field isn't
+// in the slash-command body. Group DMs ('G' prefix) are NOT treated as DMs
+// here — they map to `workspace: team_id` like a regular channel, matching
+// how the inbound classifier handles MPIM messages (channel_type 'mpim'
+// is not 'im' and therefore falls through to the team workspace branch).
+const SLACK_DM_CHANNEL_PREFIXES: readonly string[] = ['D']
+
+export type ParsedSlackSlashCommand = {
+  name: string
+  key: ChannelKey
+  invokerId: string
+}
+
+export type ParseSlashCommandResult =
+  | { kind: 'parsed'; command: ParsedSlackSlashCommand }
+  | { kind: 'ignore'; reason: 'unknown-command' | 'no-invoker' | 'no-channel' | 'no-team' | 'malformed' }
+
+export function parseSlashCommand(
+  body: SlackSocketModeSlashCommandArgs['body'],
+  knownCommands: ReadonlySet<string>,
+): ParseSlashCommandResult {
+  if (typeof body.command !== 'string' || !body.command.startsWith('/')) {
+    return { kind: 'ignore', reason: 'malformed' }
+  }
+  const name = body.command.slice(1).toLowerCase()
+  if (name === '' || !knownCommands.has(name)) {
+    return { kind: 'ignore', reason: 'unknown-command' }
+  }
+  if (typeof body.user_id !== 'string' || body.user_id === '') {
+    return { kind: 'ignore', reason: 'no-invoker' }
+  }
+  if (typeof body.channel_id !== 'string' || body.channel_id === '') {
+    return { kind: 'ignore', reason: 'no-channel' }
+  }
+  // team_id is required for slash commands per Slack's API, but defensively
+  // refuse to construct a ChannelKey without it — otherwise the workspace
+  // field would collide with a real workspace id named '' downstream.
+  if (typeof body.team_id !== 'string' || body.team_id === '') {
+    return { kind: 'ignore', reason: 'no-team' }
+  }
+
+  const isDm = SLACK_DM_CHANNEL_PREFIXES.some((prefix) => body.channel_id.startsWith(prefix))
+  const workspace = isDm ? '@dm' : body.team_id
+
+  return {
+    kind: 'parsed',
+    command: {
+      name,
+      // thread is null because Slack slash commands cannot be invoked from
+      // inside a thread — Slack's compose box always targets the top-level
+      // channel. The router's executeCommand falls back to any live session
+      // in the same workspace+chat when an exact key match misses, so a
+      // thread-keyed live session still gets hit by a thread-less slash.
+      key: { adapter: 'slack-bot', workspace, chat: body.channel_id, thread: null },
+      invokerId: body.user_id,
+    },
+  }
+}
+
+export const SLACK_SLASH_REPLY_ABORTED = 'Stopped the current turn.'
+export const SLACK_SLASH_REPLY_NO_LIVE_SESSION = 'Nothing to stop — no active turn in this channel.'
+export const SLACK_SLASH_REPLY_FAILED = 'Could not stop the current turn (internal error).'
+export const SLACK_SLASH_REPLY_PERMISSION_DENIED =
+  'You do not have permission to stop the current turn in this channel.'
+export const SLACK_SLASH_REPLY_AMBIGUOUS =
+  'Multiple active turns in this channel. Reply `/stop` from inside the specific thread you want to stop.'
+
+// Slack's ack callback accepts an optional response payload that becomes
+// the user-visible reply. `response_type: 'ephemeral'` keeps the reply
+// visible only to the invoker (vs. 'in_channel' which posts to everyone).
+// Control gestures should stay ephemeral — same rationale as Discord's
+// EPHEMERAL flag on interaction callbacks.
+export function buildSlashAckPayload(text: string): { response_type: 'ephemeral'; text: string } {
+  return { response_type: 'ephemeral', text }
+}

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

@@ -1,4 +1,4 @@
-import { SlackBotClient, SlackBotListener } from 'agent-messenger/slackbot'
+import { SlackBotClient, SlackBotListener, type SlackSocketModeSlashCommandArgs } from 'agent-messenger/slackbot'
 
 import {
   MEMBERSHIP_ENUMERATION_CAP,
@@ -33,8 +33,27 @@ import {
   type SlackInboundMessageEvent,
 } from './slack-bot-classify'
 import { createSlackDedupe } from './slack-bot-dedupe'
+import {
+  buildSlashAckPayload,
+  parseSlashCommand,
+  SLACK_SLASH_REPLY_ABORTED,
+  SLACK_SLASH_REPLY_AMBIGUOUS,
+  SLACK_SLASH_REPLY_FAILED,
+  SLACK_SLASH_REPLY_NO_LIVE_SESSION,
+  SLACK_SLASH_REPLY_PERMISSION_DENIED,
+} from './slack-bot-slash-commands'
 import { slackTsToMillis } from './slack-bot-time'
 
+// One slash command per logical agent gesture. Mirrors the discord-bot
+// SLASH_COMMANDS constant so the cross-platform set stays consistent — when
+// we add a new command (e.g. /memory), it appears in both adapters together.
+// The actual registration lives in the Slack App Manifest at src/cli/ui.ts;
+// this constant is the runtime allow-list that gates which delivered
+// 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'])
+
 // 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
 // prefix is intentionally only applied to the named form so we never log
@@ -44,6 +63,101 @@ function formatLabel(name: string | undefined, id: string, prefix = ''): string
   return `${prefix}${name}(${id})`
 }
 
+export type SlackBotAdapterLoggerLike = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+export type SlashCommandHandlerDeps = {
+  router: Pick<ChannelRouter, 'executeCommand'>
+  knownCommandNames: ReadonlySet<string>
+  logger: SlackBotAdapterLoggerLike
+  formatChannelTag: (workspace: string, chat: string) => Promise<string>
+}
+
+// Ack-first invariant: the handler must call args.ack() exactly once on
+// every path AND must do so before any slow network work (resolver calls,
+// post-ack logging). Slack's 3s ack deadline starts when the slash command
+// envelope arrives on the WebSocket; missing it shows the user
+// "/stop didn't respond in time". The synchronous executeCommand happy
+// path is fast (in-memory map lookup + abort), so ack-after-execute is
+// safe; everything else (formatChannelTag, post-ack logging) runs after.
+//
+// Ack failure handling: a thrown ack on the happy path is logged but does
+// NOT trigger the catch-all error-ack below, which would attempt a second
+// ack call and break the exactly-once contract.
+export function createSlashCommandHandler(
+  deps: SlashCommandHandlerDeps,
+): (args: SlackSocketModeSlashCommandArgs) => Promise<void> {
+  return async ({ ack, body }) => {
+    const parsed = parseSlashCommand(body, deps.knownCommandNames)
+    if (parsed.kind === 'ignore') {
+      deps.logger.warn(`[slack-bot] slash command dropped reason=${parsed.reason} command=${body.command}`)
+      try {
+        ack(buildSlashAckPayload(SLACK_SLASH_REPLY_FAILED))
+      } catch (err) {
+        deps.logger.warn(`[slack-bot] slash command ack (drop path) failed: ${describe(err)}`)
+      }
+      return
+    }
+    const { command } = parsed
+
+    // Pre-ACK log: bare ids only (no formatChannelTag — would burn ack budget
+    // on a slow Slack API minute via the channel-name resolver).
+    deps.logger.info(
+      `[slack-bot] slash /${command.name} invoker=${command.invokerId} team=${command.key.workspace} channel=${command.key.chat}`,
+    )
+
+    let result: Awaited<ReturnType<typeof deps.router.executeCommand>>
+    try {
+      result = await deps.router.executeCommand(command.key, command.name, {
+        invokerId: command.invokerId,
+      })
+    } catch (err) {
+      deps.logger.error(`[slack-bot] slash command handler failed: ${describe(err)}`)
+      try {
+        ack(buildSlashAckPayload(SLACK_SLASH_REPLY_FAILED))
+      } catch (ackErr) {
+        deps.logger.warn(`[slack-bot] slash command error-ack failed: ${describe(ackErr)}`)
+      }
+      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
+
+    // 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
+    // exactly-once contract). The abort already happened server-side; only
+    // the user-visible confirmation is lost.
+    try {
+      ack(buildSlashAckPayload(replyContent))
+    } catch (err) {
+      deps.logger.warn(`[slack-bot] slash command ack failed: ${describe(err)}`)
+    }
+
+    // Decorative post-ack logging: resolve channel names now that the 3s
+    // budget is no longer a concern. Best-effort.
+    try {
+      const inboundTag = await deps.formatChannelTag(command.key.workspace, command.key.chat)
+      deps.logger.info(`[slack-bot] slash /${command.name} result=${result.kind} ${inboundTag}`)
+    } catch (err) {
+      deps.logger.info(
+        `[slack-bot] slash /${command.name} result=${result.kind} (channel-tag resolution failed: ${describe(err)})`,
+      )
+    }
+  }
+}
+
 // 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
@@ -661,6 +775,13 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
 
   const dedupe = createSlackDedupe()
 
+  const handleSlashCommand = createSlashCommandHandler({
+    router: options.router,
+    knownCommandNames: SLACK_SLASH_COMMAND_NAMES,
+    logger,
+    formatChannelTag,
+  })
+
   const handleMessageEvent = async (
     event: SlackInboundMessageEvent,
     source: 'message' | 'app_mention',
@@ -777,6 +898,23 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
         ack()
         void handleMessageEvent(promoteAppMentionToMessage(event as SlackInboundAppMentionEvent), 'app_mention')
       })
+      listener.on('slash_commands', (args) => {
+        // The handler owns the ack call itself (the ack payload carries the
+        // user-visible reply text), so we do NOT ack here. inflightInbounds
+        // wrapping mirrors handleMessageEvent so stop() can drain the
+        // handler before tearing down the listener — otherwise a /stop
+        // arriving during stop() would lose its ack and the user sees
+        // "didn't respond in time" even though the abort succeeded.
+        inflightInbounds++
+        void handleSlashCommand(args).finally(() => {
+          inflightInbounds--
+          if (inflightInbounds === 0 && stopWaiters.length > 0) {
+            const waiters = stopWaiters
+            stopWaiters = []
+            for (const w of waiters) w()
+          }
+        })
+      })
 
       options.router.registerOutbound('slack-bot', outboundCallback)
       options.router.registerTyping('slack-bot', typingCallback)