typeclaw 0.7.0 → 0.9.0

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/kakaotalk-attachment.ts

@@ -1,5 +1,6 @@
 import {
   KAKAO_EMOTICON_KIND_BY_TYPE,
+  KAKAO_MESSAGE_TYPE,
   type KakaoEmoticonKind,
   type KakaoMessage,
   type KakaoTalkPushEmoticonEvent,
@@ -21,17 +22,6 @@ import {
 // convention used by Slack/Discord/Telegram inbound classifiers, so the
 // agent sees a consistent placeholder shape across platforms.
 
-// KakaoTalk LOCO message_type values. Only the ones we explicitly format
-// are listed; anything else falls into the "generic attachment" branch.
-// Reference: src/skills/typeclaw-channel-kakaotalk/SKILL.md and
-// agent-messenger docs/cli/kakaotalk.mdx.
-const MESSAGE_TYPE_TEXT = 1
-const MESSAGE_TYPE_PHOTO = 2
-const MESSAGE_TYPE_VIDEO = 3
-const MESSAGE_TYPE_AUDIO = 5
-const MESSAGE_TYPE_FILE = 18
-const MESSAGE_TYPE_MULTIPHOTO = 27
-
 // Non-text inputs that the adapter accepts. We use a thin shared shape
 // rather than the SDK's union so the same formatter can serve both push
 // events (no `attachment` on emoticon events — emoticon fields live on
@@ -70,17 +60,17 @@ function summarizeAttachment(event: InboundLike): string | null {
   // agent isn't woken up by phantom `[KakaoTalk message with type=N]`
   // placeholders for noise.
   switch (event.message_type) {
-    case MESSAGE_TYPE_TEXT:
+    case KAKAO_MESSAGE_TYPE.TEXT:
       return null
-    case MESSAGE_TYPE_PHOTO:
+    case KAKAO_MESSAGE_TYPE.PHOTO:
       return summarizePhoto(event.attachment)
-    case MESSAGE_TYPE_VIDEO:
+    case KAKAO_MESSAGE_TYPE.VIDEO:
       return summarizeGeneric('video', event.attachment)
-    case MESSAGE_TYPE_AUDIO:
+    case KAKAO_MESSAGE_TYPE.AUDIO:
       return summarizeGeneric('audio', event.attachment)
-    case MESSAGE_TYPE_FILE:
+    case KAKAO_MESSAGE_TYPE.FILE:
       return summarizeFile(event.attachment)
-    case MESSAGE_TYPE_MULTIPHOTO:
+    case KAKAO_MESSAGE_TYPE.MULTIPHOTO:
       return summarizeGeneric('multiphoto', event.attachment)
     default:
       // Emoticon types route through the dedicated emoticon event before

package/src/channels/adapters/kakaotalk.ts

@@ -2,7 +2,9 @@ import {
   KakaoCredentialManager,
   KakaoTalkClient as RealKakaoTalkClient,
   KakaoTalkListener as RealKakaoTalkListener,
+  type AttachmentInput,
   type KakaoChat,
+  type KakaoMarkReadResult,
   type KakaoMember,
   type KakaoMessage,
   type KakaoProfile,
@@ -32,16 +34,6 @@ import { createKakaoChannelResolver, type KakaoChannelResolver } from './kakaota
 import { classifyInbound, type InboundDropReason } from './kakaotalk-classify'
 import { createFetchAttachmentCallback } from './kakaotalk-fetch-attachment'
 
-// Inlined locally because agent-messenger/kakaotalk's index does not
-// re-export KakaoMarkReadResult even though client.markRead returns it
-// (agent-messenger 2.14.1). Upstream re-export fix is independent.
-export interface KakaoMarkReadResult {
-  success: boolean
-  status_code: number
-  chat_id: string
-  watermark: string
-}
-
 // Structural duck-type of the upstream KakaoTalkClient class. The upstream
 // type is a class with private fields, and TypeScript treats those
 // nominally — test fakes that match the public surface get rejected.
@@ -56,6 +48,13 @@ export interface KakaoTalkClient {
   getChats(options?: { all?: boolean; search?: string }): Promise<KakaoChat[]>
   getMessages(chatId: string, options?: { count?: number; from?: string }): Promise<KakaoMessage[]>
   sendMessage(chatId: string, text: string): Promise<KakaoSendResult>
+  sendAttachment(
+    chatId: string,
+    data: Uint8Array | Buffer,
+    filename: string,
+    mimeType?: string,
+  ): Promise<KakaoSendResult>
+  sendAttachment(chatId: string, attachments: ReadonlyArray<AttachmentInput>): Promise<KakaoSendResult>
   markRead(chatId: string, logId: string, opts?: { linkId?: string }): Promise<KakaoMarkReadResult>
   getProfile(): Promise<KakaoProfile>
   getMembers(chatId: string): Promise<KakaoMember[]>
@@ -160,49 +159,77 @@ function formatLabel(name: string | undefined, id: string, prefix = ''): string
   return `${prefix}${name}(${id})`
 }
 
+async function readAttachmentBuffer(path: string): Promise<Buffer> {
+  const { readFile } = await import('node:fs/promises')
+  return await readFile(path)
+}
+
 export function createOutboundCallback(deps: {
-  client: Pick<KakaoTalkClient, 'sendMessage'>
+  client: Pick<KakaoTalkClient, 'sendMessage' | 'sendAttachment'>
   logger: KakaotalkAdapterLogger
   formatChannelTag: (workspace: string, chat: string) => Promise<string>
+  readFile?: (path: string) => Promise<Buffer>
 }): OutboundCallback {
   const { client, logger, formatChannelTag } = deps
+  const readFile = deps.readFile ?? readAttachmentBuffer
   return async (msg: OutboundMessage): Promise<SendResult> => {
     if (msg.adapter !== 'kakaotalk') {
       return { ok: false, error: `unknown adapter: ${msg.adapter}` }
     }
     const text = msg.text ?? ''
     const attachments = msg.attachments ?? []
+    if (text === '' && attachments.length === 0) {
+      return { ok: false, error: 'message has neither text nor attachments' }
+    }
+    const tag = await formatChannelTag(msg.workspace, msg.chat)
+    logger.info(`[kakaotalk] outbound ${tag} text_len=${text.length} attachments=${attachments.length}`)
+
+    // KakaoTalk has no shared text-with-file send (Slack's initial_comment) — files first, then text.
     if (attachments.length > 0) {
-      // Fail loudly rather than partial-send. The agent contract is "ok=true
-      // means the request as a whole succeeded"; sending text while silently
-      // dropping the attachments would let the agent confidently report
-      // "I sent your file" when the file never arrived.
-      logger.error(
-        `[kakaotalk] outbound rejected: ${attachments.length} attachment(s) supplied but KakaoTalk is text-only`,
-      )
-      return {
-        ok: false,
-        error: 'KakaoTalk does not support attachments; send text without files or use a different channel for files',
+      let items: AttachmentInput[]
+      try {
+        items = await Promise.all(
+          attachments.map(async (a) => {
+            const filename = a.filename ?? a.path.split('/').pop() ?? 'file'
+            const data = await readFile(a.path)
+            return { data, filename }
+          }),
+        )
+      } catch (err) {
+        const message = describe(err)
+        logger.error(`[kakaotalk] readFile failed: ${message}`)
+        return { ok: false, error: `readFile failed: ${message}` }
+      }
+      try {
+        const result = await client.sendAttachment(msg.chat, items)
+        if (!result.success) {
+          logger.error(`[kakaotalk] sendAttachment status_code=${result.status_code} ${tag}`)
+          return { ok: false, error: `kakaotalk attachment send failed with status ${result.status_code}` }
+        }
+        logger.info(`[kakaotalk] uploaded log_id=${result.log_id} attachments=${items.length} ${tag}`)
+      } catch (err) {
+        const message = describe(err)
+        logger.error(`[kakaotalk] sendAttachment failed: ${message}`)
+        return { ok: false, error: message }
       }
     }
-    if (text === '') {
-      return { ok: false, error: 'message has no text (KakaoTalk does not support attachment-only messages)' }
-    }
-    const tag = await formatChannelTag(msg.workspace, msg.chat)
-    logger.info(`[kakaotalk] outbound ${tag} text_len=${text.length}`)
-    try {
-      const result = await client.sendMessage(msg.chat, text)
-      if (!result.success) {
-        logger.error(`[kakaotalk] sendMessage status_code=${result.status_code} ${tag}`)
-        return { ok: false, error: `kakaotalk send failed with status ${result.status_code}` }
+
+    if (text !== '') {
+      try {
+        const result = await client.sendMessage(msg.chat, text)
+        if (!result.success) {
+          logger.error(`[kakaotalk] sendMessage status_code=${result.status_code} ${tag}`)
+          return { ok: false, error: `kakaotalk send failed with status ${result.status_code}` }
+        }
+        logger.info(`[kakaotalk] sent log_id=${result.log_id} ${tag}`)
+      } catch (err) {
+        const message = describe(err)
+        logger.error(`[kakaotalk] sendMessage failed: ${message}`)
+        return { ok: false, error: message }
       }
-      logger.info(`[kakaotalk] sent log_id=${result.log_id} ${tag}`)
-      return { ok: true }
-    } catch (err) {
-      const message = describe(err)
-      logger.error(`[kakaotalk] sendMessage failed: ${message}`)
-      return { ok: false, error: message }
     }
+
+    return { ok: true }
   }
 }
 

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

@@ -6,33 +6,8 @@ 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 SlackInboundMessageEvent = SlackSocketModeMessageEvent
+export type SlackInboundAppMentionEvent = SlackSocketModeAppMentionEvent
 
 export type InboundDropReason =
   | 'self_author' // event.user === botUserId; we never route our own messages back to ourselves

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 }
+}