@swarmclawai/swarmclaw 0.7.1 → 0.7.3

package/src/lib/server/connectors/slack.ts

@@ -2,9 +2,104 @@ import { App, LogLevel } from '@slack/bolt'
 import fs from 'fs'
 import path from 'path'
 import type { Connector } from '@/types'
-import type { PlatformConnector, ConnectorInstance, InboundMessage } from './types'
+import type { PlatformConnector, ConnectorInstance, InboundMessage, InboundThreadHistoryEntry } from './types'
 import { downloadInboundMediaToUpload, inferInboundMediaType, mimeFromPath, isImageMime } from './media'
-import { isNoMessage } from './manager'
+import { getConnectorReplySendOptions, isNoMessage, recordConnectorOutboundDelivery } from './manager'
+
+function normalizeSlackEmoji(input: string): string {
+  const raw = input.trim().replace(/^:|:$/g, '')
+  if (!raw) return 'eyes'
+  if (raw === '👀') return 'eyes'
+  if (raw === '✅') return 'white_check_mark'
+  if (raw === '🤐') return 'zipper_mouth_face'
+  return raw
+}
+
+function parseSlackTimestamp(raw: unknown): number {
+  const value = typeof raw === 'string' ? Number.parseFloat(raw) : typeof raw === 'number' ? raw : Number.NaN
+  return Number.isFinite(value) ? value : 0
+}
+
+async function resolveSlackUserDisplayName(client: any, userId?: string): Promise<string | undefined> {
+  if (!userId) return undefined
+  try {
+    const userInfo = await client.users.info({ user: userId })
+    return userInfo.user?.real_name || userInfo.user?.name || userId
+  } catch {
+    return userId
+  }
+}
+
+function buildSlackThreadTitle(channelName: string, starterText: string, fallbackTs: string): string {
+  const snippet = starterText.replace(/\s+/g, ' ').trim().slice(0, 56)
+  if (snippet) return `${channelName} · ${snippet}`
+  return `${channelName} thread ${fallbackTs}`
+}
+
+async function hydrateSlackThreadContext(params: {
+  client: any
+  inbound: InboundMessage
+  currentTs?: string
+  botUserId?: string
+}): Promise<void> {
+  const threadTs = params.inbound.threadId
+  if (!threadTs) return
+  try {
+    const result = await params.client.conversations.replies({
+      channel: params.inbound.channelId,
+      ts: threadTs,
+      limit: 12,
+      inclusive: true,
+    })
+    const messages = Array.isArray((result as any)?.messages) ? (result as any).messages as any[] : []
+    if (!messages.length) return
+
+    const userIds = [...new Set(messages.map((message) => typeof message?.user === 'string' ? message.user : '').filter(Boolean))]
+    const nameMap = new Map<string, string>()
+    await Promise.all(userIds.map(async (userId) => {
+      const name = await resolveSlackUserDisplayName(params.client, userId)
+      if (name) nameMap.set(userId, name)
+    }))
+
+    const starter = messages[0]
+    const starterText = typeof starter?.text === 'string' ? starter.text.trim() : ''
+    const starterSenderName = nameMap.get(starter?.user)
+      || starter?.username
+      || starter?.user
+      || (starter?.bot_id ? 'Slack Bot' : '')
+    const currentTsValue = parseSlackTimestamp(params.currentTs)
+    const history: InboundThreadHistoryEntry[] = messages
+      .filter((message) => {
+        const tsValue = parseSlackTimestamp(message?.ts)
+        if (!tsValue) return false
+        if (String(message?.ts) === String(threadTs)) return false
+        if (currentTsValue && tsValue >= currentTsValue) return false
+        return true
+      })
+      .slice(-6)
+      .map((message) => ({
+        role: (message?.bot_id || (params.botUserId && message?.user === params.botUserId) ? 'assistant' : 'user') as 'assistant' | 'user',
+        senderName: nameMap.get(message?.user) || message?.username || message?.user || (message?.bot_id ? 'Slack Bot' : 'Unknown'),
+        text: typeof message?.text === 'string' ? message.text : '',
+        messageId: typeof message?.ts === 'string' ? message.ts : undefined,
+      }))
+      .filter((entry) => entry.text.trim().length > 0)
+
+    params.inbound.threadParentChannelId = params.inbound.channelId
+    params.inbound.threadParentChannelName = params.inbound.channelName || params.inbound.channelId
+    params.inbound.threadStarterText = starterText || undefined
+    params.inbound.threadStarterSenderName = starterSenderName || undefined
+    params.inbound.threadTitle = buildSlackThreadTitle(
+      params.inbound.channelName || params.inbound.channelId,
+      starterText,
+      threadTs,
+    )
+    params.inbound.threadPersonaLabel = params.inbound.threadTitle
+    params.inbound.threadHistory = history.length ? history : undefined
+  } catch (err: unknown) {
+    console.warn(`[slack] Thread context bootstrap failed: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
 
 const slack: PlatformConnector = {
   async start(connector, botToken, onMessage): Promise<ConnectorInstance> {
@@ -136,24 +231,50 @@ const slack: PlatformConnector = {
         senderId: msg.user,
         senderName,
         text: msg.text || (media.length > 0 ? '(media message)' : ''),
+        isGroup: !String(channelId).startsWith('D'),
+        messageId: msg.ts || undefined,
+        replyToMessageId: msg.thread_ts && msg.thread_ts !== msg.ts ? msg.thread_ts : undefined,
+        threadId: msg.thread_ts || undefined,
+        mentionsBot: !!(botUserId && typeof msg.text === 'string' && msg.text.includes(`<@${botUserId}>`)),
         imageUrl: media.find((m) => m.type === 'image')?.url,
         media,
       }
+      await hydrateSlackThreadContext({ client, inbound, currentTs: msg.ts || undefined, botUserId })
 
       try {
         const response = await onMessage(inbound)
 
         if (isNoMessage(response)) return
 
+        const replyOptions = getConnectorReplySendOptions({ connectorId: connector.id, inbound })
+        const threadTs = replyOptions.threadId || replyOptions.replyToMessageId
+        let lastMessageId: string | undefined
+
         // Slack has a 4000 char limit for messages
         if (response.length <= 4000) {
-          await say(response)
+          const sent = await client.chat.postMessage({
+            channel: channelId,
+            text: response,
+            thread_ts: threadTs,
+          })
+          lastMessageId = sent.ts || undefined
         } else {
           const chunks = response.match(/[\s\S]{1,3990}/g) || [response]
           for (const chunk of chunks) {
-            await say(chunk)
+            const sent = await client.chat.postMessage({
+              channel: channelId,
+              text: chunk,
+              thread_ts: threadTs,
+            })
+            lastMessageId = sent.ts || undefined
           }
         }
+        await recordConnectorOutboundDelivery({
+          connectorId: connector.id,
+          inbound,
+          messageId: lastMessageId,
+          state: 'sent',
+        })
       } catch (err: any) {
         console.error(`[slack] Error handling message:`, err.message)
         try {
@@ -179,12 +300,36 @@ const slack: PlatformConnector = {
         senderId: event.user || 'unknown',
         senderName,
         text: event.text.replace(/<@[^>]+>/g, '').trim(), // Strip @mentions
+        isGroup: !String(event.channel).startsWith('D'),
+        messageId: (event as any).ts || undefined,
+        replyToMessageId: (event as any).thread_ts && (event as any).thread_ts !== (event as any).ts
+          ? (event as any).thread_ts
+          : undefined,
+        threadId: (event as any).thread_ts || undefined,
+        mentionsBot: true,
       }
+      await hydrateSlackThreadContext({
+        client,
+        inbound,
+        currentTs: (event as any).ts || undefined,
+        botUserId,
+      })
 
       try {
         const response = await onMessage(inbound)
         if (isNoMessage(response)) return
-        await say(response)
+        const replyOptions = getConnectorReplySendOptions({ connectorId: connector.id, inbound })
+        const sent = await client.chat.postMessage({
+          channel: event.channel,
+          text: response,
+          thread_ts: replyOptions.threadId || replyOptions.replyToMessageId,
+        })
+        await recordConnectorOutboundDelivery({
+          connectorId: connector.id,
+          inbound,
+          messageId: sent.ts || undefined,
+          state: 'sent',
+        })
       } catch (err: any) {
         console.error(`[slack] Error handling mention:`, err.message)
       }
@@ -202,6 +347,7 @@ const slack: PlatformConnector = {
       },
       async sendMessage(channelId, text, options) {
         const webClient = app.client
+        const threadTs = options?.threadId?.trim() || options?.replyToMessageId?.trim() || undefined
 
         // File upload (local path or URL)
         const hasMedia = options?.mediaPath || options?.imageUrl || options?.fileUrl
@@ -219,18 +365,25 @@ const slack: PlatformConnector = {
           }
 
           if (fileContent) {
-            const result = await webClient.filesUploadV2({
+            const uploadArgsBase = {
               channel_id: channelId,
               file: fileContent,
               filename: fileName,
               initial_comment: options?.caption || text || undefined,
-            })
+            }
+            const result = threadTs
+              ? await webClient.filesUploadV2({
+                  ...uploadArgsBase,
+                  thread_ts: threadTs,
+                })
+              : await webClient.filesUploadV2(uploadArgsBase)
             return { messageId: (result as any)?.files?.[0]?.id }
           } else if (fileUrl) {
             // Send URL as message with unfurl
             const msg = await webClient.chat.postMessage({
               channel: channelId,
               text: `${options?.caption || text || ''}\n${fileUrl}`.trim(),
+              thread_ts: threadTs,
               unfurl_links: true,
               unfurl_media: true,
             })
@@ -241,17 +394,43 @@ const slack: PlatformConnector = {
         // Text only
         const payload = text || options?.caption || ''
         if (payload.length <= 4000) {
-          const msg = await webClient.chat.postMessage({ channel: channelId, text: payload })
+          const msg = await webClient.chat.postMessage({ channel: channelId, text: payload, thread_ts: threadTs })
           return { messageId: msg.ts || undefined }
         }
         const chunks = payload.match(/[\s\S]{1,3990}/g) || [payload]
         let lastTs: string | undefined
         for (const chunk of chunks) {
-          const msg = await webClient.chat.postMessage({ channel: channelId, text: chunk })
+          const msg = await webClient.chat.postMessage({ channel: channelId, text: chunk, thread_ts: threadTs })
           lastTs = msg.ts || undefined
         }
         return { messageId: lastTs }
       },
+      async sendReaction(channelId, messageId, emoji) {
+        await app.client.reactions.add({
+          channel: channelId,
+          timestamp: messageId,
+          name: normalizeSlackEmoji(emoji),
+        })
+      },
+      async editMessage(channelId, messageId, newText) {
+        await app.client.chat.update({
+          channel: channelId,
+          ts: messageId,
+          text: newText,
+        })
+      },
+      async deleteMessage(channelId, messageId) {
+        await app.client.chat.delete({
+          channel: channelId,
+          ts: messageId,
+        })
+      },
+      async pinMessage(channelId, messageId) {
+        await app.client.pins.add({
+          channel: channelId,
+          timestamp: messageId,
+        })
+      },
       async stop() {
         appStopped = true
         await app.stop()

package/src/lib/server/connectors/telegram.ts

@@ -4,11 +4,12 @@ import path from 'path'
 import type { Connector } from '@/types'
 import type { PlatformConnector, ConnectorInstance, InboundMessage, InboundMediaType } from './types'
 import { downloadInboundMediaToUpload, inferInboundMediaType, mimeFromPath, isImageMime, isAudioMime } from './media'
-import { isNoMessage } from './manager'
+import { getConnectorReplySendOptions, isNoMessage, recordConnectorOutboundDelivery } from './manager'
 
 const telegram: PlatformConnector = {
   async start(connector, botToken, onMessage): Promise<ConnectorInstance> {
     const bot = new Bot(botToken)
+    let botUsername = ''
 
     // Optional: restrict to specific chat IDs
     const allowedChats = connector.config.chatIds
@@ -140,6 +141,11 @@ const telegram: PlatformConnector = {
         senderId: String(ctx.from.id),
         senderName: ctx.from.first_name + (ctx.from.last_name ? ` ${ctx.from.last_name}` : ''),
         text: text || (media.length > 0 ? '(media message)' : ''),
+        isGroup: ctx.chat.type !== 'private',
+        messageId: String(raw.message_id),
+        replyToMessageId: raw.reply_to_message?.message_id ? String(raw.reply_to_message.message_id) : undefined,
+        threadId: raw.message_thread_id ? String(raw.message_thread_id) : undefined,
+        mentionsBot: !!(botUsername && text && new RegExp(`@${botUsername}\\b`, 'i').test(String(text))),
         imageUrl: media.find((m) => m.type === 'image')?.url,
         media,
       }
@@ -150,15 +156,34 @@ const telegram: PlatformConnector = {
 
         if (isNoMessage(response)) return
 
+        const replyOptions = getConnectorReplySendOptions({ connectorId: connector.id, inbound })
+        const baseOptions: Record<string, unknown> = {}
+        if (replyOptions.replyToMessageId) {
+          baseOptions.reply_parameters = { message_id: Number(replyOptions.replyToMessageId) }
+        }
+        if (replyOptions.threadId) {
+          baseOptions.message_thread_id = Number(replyOptions.threadId)
+        }
+
+        let lastMessageId: string | undefined
+
         // Telegram has a 4096 char limit
         if (response.length <= 4096) {
-          await ctx.reply(response)
+          const sent = await ctx.api.sendMessage(ctx.chat.id, response, baseOptions as any)
+          lastMessageId = String(sent.message_id)
         } else {
           const chunks = response.match(/[\s\S]{1,4090}/g) || [response]
-          for (const chunk of chunks) {
-            await ctx.api.sendMessage(ctx.chat.id, chunk)
+          for (let i = 0; i < chunks.length; i += 1) {
+            const sent = await ctx.api.sendMessage(ctx.chat.id, chunks[i], (i === 0 ? baseOptions : {}) as any)
+            lastMessageId = String(sent.message_id)
           }
         }
+        await recordConnectorOutboundDelivery({
+          connectorId: connector.id,
+          inbound,
+          messageId: lastMessageId,
+          state: 'sent',
+        })
       } catch (err: any) {
         console.error(`[telegram] Error handling message:`, err.message)
         try {
@@ -174,6 +199,7 @@ const telegram: PlatformConnector = {
     bot.start({
       allowed_updates: ['message', 'edited_message'],
       onStart: (botInfo) => {
+        botUsername = botInfo.username || ''
         console.log(`[telegram] Bot started as @${botInfo.username} — polling for updates`)
       },
     }).catch((err) => {
@@ -189,6 +215,13 @@ const telegram: PlatformConnector = {
       async sendMessage(channelId, text, options) {
         const chatId = channelId
         const caption = options?.caption || text || undefined
+        const extra: Record<string, unknown> = {}
+        if (options?.replyToMessageId) {
+          extra.reply_parameters = { message_id: Number(options.replyToMessageId) }
+        }
+        if (options?.threadId) {
+          extra.message_thread_id = Number(options.threadId)
+        }
 
         // Local file
         if (options?.mediaPath) {
@@ -196,21 +229,21 @@ const telegram: PlatformConnector = {
           const mime = options.mimeType || mimeFromPath(options.mediaPath)
           const inputFile = new InputFile(options.mediaPath, options.fileName || path.basename(options.mediaPath))
           if (isImageMime(mime)) {
-            const msg = await bot.api.sendPhoto(chatId, inputFile, { caption })
+            const msg = await bot.api.sendPhoto(chatId, inputFile, { caption, ...(extra as any) })
             return { messageId: String(msg.message_id) }
           } else if (isAudioMime(mime)) {
             const msg = options?.ptt
-              ? await bot.api.sendVoice(chatId, inputFile, { caption })
-              : await bot.api.sendAudio(chatId, inputFile, { caption })
+              ? await bot.api.sendVoice(chatId, inputFile, { caption, ...(extra as any) })
+              : await bot.api.sendAudio(chatId, inputFile, { caption, ...(extra as any) })
             return { messageId: String(msg.message_id) }
           } else {
-            const msg = await bot.api.sendDocument(chatId, inputFile, { caption })
+            const msg = await bot.api.sendDocument(chatId, inputFile, { caption, ...(extra as any) })
             return { messageId: String(msg.message_id) }
           }
         }
         // URL-based image
         if (options?.imageUrl) {
-          const msg = await bot.api.sendPhoto(chatId, options.imageUrl, { caption })
+          const msg = await bot.api.sendPhoto(chatId, options.imageUrl, { caption, ...(extra as any) })
           return { messageId: String(msg.message_id) }
         }
         // URL-based file
@@ -218,25 +251,42 @@ const telegram: PlatformConnector = {
           const mime = options.mimeType || ''
           const msg = isAudioMime(mime)
             ? options?.ptt
-              ? await bot.api.sendVoice(chatId, options.fileUrl, { caption })
-              : await bot.api.sendAudio(chatId, options.fileUrl, { caption })
-            : await bot.api.sendDocument(chatId, options.fileUrl, { caption })
+              ? await bot.api.sendVoice(chatId, options.fileUrl, { caption, ...(extra as any) })
+              : await bot.api.sendAudio(chatId, options.fileUrl, { caption, ...(extra as any) })
+            : await bot.api.sendDocument(chatId, options.fileUrl, { caption, ...(extra as any) })
           return { messageId: String(msg.message_id) }
         }
         // Text only
         const payload = text || caption || ''
         if (payload.length <= 4096) {
-          const msg = await bot.api.sendMessage(chatId, payload)
+          const msg = await bot.api.sendMessage(chatId, payload, extra as any)
           return { messageId: String(msg.message_id) }
         }
         const chunks = payload.match(/[\s\S]{1,4090}/g) || [payload]
         let lastId: string | undefined
-        for (const chunk of chunks) {
-          const msg = await bot.api.sendMessage(chatId, chunk)
+        for (let i = 0; i < chunks.length; i += 1) {
+          const msg = await bot.api.sendMessage(chatId, chunks[i], (i === 0 ? extra : {}) as any)
           lastId = String(msg.message_id)
         }
         return { messageId: lastId }
       },
+      async sendReaction(channelId, messageId, emoji) {
+        const fn = (bot.api as any).setMessageReaction
+        if (typeof fn !== 'function') return
+        await fn.call(bot.api, channelId, Number(messageId), [{ type: 'emoji', emoji }])
+      },
+      async editMessage(channelId, messageId, newText) {
+        await bot.api.editMessageText(channelId, Number(messageId), newText)
+      },
+      async deleteMessage(channelId, messageId) {
+        await bot.api.deleteMessage(channelId, Number(messageId))
+      },
+      async pinMessage(channelId, messageId) {
+        await bot.api.pinChatMessage(channelId, Number(messageId))
+      },
+      async sendTyping(channelId) {
+        await bot.api.sendChatAction(channelId, 'typing')
+      },
       async stop() {
         botRunning = false
         await bot.stop()

package/src/lib/server/connectors/thread-context.test.ts

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { buildConnectorThreadContextBlock, resolveThreadPersonaLabel } from './thread-context'
+
+test('resolveThreadPersonaLabel prefers explicit and title-based labels', () => {
+  assert.equal(resolveThreadPersonaLabel({
+    platform: 'slack',
+    threadPersonaLabel: 'Incident Bridge',
+    threadTitle: 'ignored',
+    threadStarterText: 'ignored',
+    threadId: 't1',
+    channelName: 'ops',
+  }), 'Incident Bridge')
+
+  assert.equal(resolveThreadPersonaLabel({
+    platform: 'discord',
+    threadPersonaLabel: undefined,
+    threadTitle: 'Release Coordination',
+    threadStarterText: 'root message',
+    threadId: 't1',
+    channelName: 'deploys',
+  }), 'Release Coordination')
+})
+
+test('buildConnectorThreadContextBlock includes starter, history, and first-turn note', () => {
+  const block = buildConnectorThreadContextBlock({
+    platform: 'slack',
+    threadId: 'thread-1',
+    threadTitle: 'Checkout Incident',
+    threadStarterText: 'Prod checkout is returning 500s.',
+    threadStarterSenderName: 'Alice',
+    threadParentChannelName: 'incidents',
+    threadHistory: [
+      { role: 'assistant', senderName: 'Swarmy', text: 'I am tracing the failing service now.' },
+      { role: 'user', senderName: 'Bob', text: 'Looks isolated to EU traffic.' },
+    ],
+  }, { isFirstThreadTurn: true })
+
+  assert.match(block, /Native Thread Context/)
+  assert.match(block, /Thread persona: Checkout Incident/)
+  assert.match(block, /Thread starter: Alice: Prod checkout is returning 500s\./)
+  assert.match(block, /first turn in a thread-bound session/i)
+  assert.match(block, /\[assistant\] Swarmy: I am tracing the failing service now\./)
+})

package/src/lib/server/connectors/thread-context.ts

@@ -0,0 +1,72 @@
+import type { InboundMessage, InboundThreadHistoryEntry } from './types'
+
+function normalizeText(value: unknown, maxChars: number): string {
+  return String(value || '').replace(/\s+/g, ' ').trim().slice(0, maxChars)
+}
+
+export function resolveThreadPersonaLabel(msg: Pick<InboundMessage, 'threadPersonaLabel' | 'threadTitle' | 'threadStarterText' | 'threadId' | 'channelName' | 'platform'>): string | null {
+  const explicit = normalizeText(msg.threadPersonaLabel, 120)
+  if (explicit) return explicit
+  const title = normalizeText(msg.threadTitle, 120)
+  if (title) return title
+  const starter = normalizeText(msg.threadStarterText, 72)
+  if (starter) {
+    return `${msg.platform} thread: ${starter}`.slice(0, 120)
+  }
+  const channel = normalizeText(msg.channelName, 64)
+  if (msg.threadId && channel) return `${channel} thread`
+  if (msg.threadId) return `${msg.platform} thread`
+  return null
+}
+
+function formatHistoryEntry(entry: InboundThreadHistoryEntry): string {
+  const speaker = normalizeText(entry.senderName, 60) || (entry.role === 'assistant' ? 'assistant' : 'user')
+  const text = normalizeText(entry.text, 220)
+  return `- [${entry.role}] ${speaker}: ${text}`
+}
+
+export function buildConnectorThreadContextBlock(
+  msg: Pick<
+    InboundMessage,
+    'platform'
+    | 'threadId'
+    | 'replyToMessageId'
+    | 'threadTitle'
+    | 'threadStarterText'
+    | 'threadStarterSenderName'
+    | 'threadParentChannelName'
+    | 'threadHistory'
+    | 'threadPersonaLabel'
+  >,
+  opts?: { isFirstThreadTurn?: boolean },
+): string {
+  const hasThreadContext = !!(
+    msg.threadId
+    || msg.replyToMessageId
+    || msg.threadTitle
+    || msg.threadStarterText
+    || (Array.isArray(msg.threadHistory) && msg.threadHistory.length > 0)
+  )
+  if (!hasThreadContext) return ''
+
+  const persona = resolveThreadPersonaLabel(msg)
+  const lines = ['## Native Thread Context']
+  if (persona) lines.push(`Thread persona: ${persona}`)
+  if (msg.threadTitle) lines.push(`Thread title: ${normalizeText(msg.threadTitle, 140)}`)
+  if (msg.threadParentChannelName) lines.push(`Parent channel: ${normalizeText(msg.threadParentChannelName, 100)}`)
+  if (opts?.isFirstThreadTurn) {
+    lines.push('This is the first turn in a thread-bound session. Treat the starter and history below as earlier context from the same conversation.')
+  }
+  if (msg.threadStarterText) {
+    const speaker = normalizeText(msg.threadStarterSenderName, 60) || 'unknown'
+    lines.push(`Thread starter: ${speaker}: ${normalizeText(msg.threadStarterText, 260)}`)
+  }
+  if (Array.isArray(msg.threadHistory) && msg.threadHistory.length > 0) {
+    lines.push('Recent thread history before this turn:')
+    for (const entry of msg.threadHistory.slice(-6)) {
+      lines.push(formatHistoryEntry(entry))
+    }
+  }
+  lines.push('Respond as part of this ongoing thread, not as if the message started a brand new conversation.')
+  return lines.join('\n')
+}

package/src/lib/server/connectors/types.ts

@@ -2,6 +2,13 @@ import type { Connector } from '@/types'
 
 export type InboundMediaType = 'image' | 'video' | 'audio' | 'document' | 'file'
 
+export interface InboundThreadHistoryEntry {
+  role: 'user' | 'assistant'
+  senderName: string
+  text: string
+  messageId?: string
+}
+
 export interface InboundMedia {
   type: InboundMediaType
   fileName?: string
@@ -22,12 +29,43 @@ export interface InboundMessage {
   senderName: string       // display name
   text: string
   isGroup?: boolean
+  messageId?: string
   imageUrl?: string
   media?: InboundMedia[]
   replyToMessageId?: string
+  threadId?: string
+  threadTitle?: string
+  threadStarterText?: string
+  threadStarterSenderName?: string
+  threadPersonaLabel?: string
+  threadParentChannelId?: string
+  threadParentChannelName?: string
+  threadHistory?: InboundThreadHistoryEntry[]
+  mentionsBot?: boolean
   agentIdOverride?: string
 }
 
+export interface OutboundSendOptions {
+  imageUrl?: string
+  fileUrl?: string
+  /** Absolute local file path (e.g. screenshot saved to disk) */
+  mediaPath?: string
+  mimeType?: string
+  fileName?: string
+  caption?: string
+  /** Send audio as a WhatsApp voice note (push-to-talk) */
+  ptt?: boolean
+  /** Platform-native reply target when supported */
+  replyToMessageId?: string
+  /** Platform-native thread or topic identifier when supported */
+  threadId?: string
+}
+
+export interface OutboundTypingOptions {
+  /** Platform-native thread or topic identifier when supported */
+  threadId?: string
+}
+
 /** A running connector instance */
 export interface ConnectorInstance {
   connector: Connector
@@ -36,17 +74,7 @@ export interface ConnectorInstance {
   sendMessage?: (
     channelId: string,
     text: string,
-    options?: {
-      imageUrl?: string
-      fileUrl?: string
-      /** Absolute local file path (e.g. screenshot saved to disk) */
-      mediaPath?: string
-      mimeType?: string
-      fileName?: string
-      caption?: string
-      /** Send audio as a WhatsApp voice note (push-to-talk) */
-      ptt?: boolean
-    },
+    options?: OutboundSendOptions,
   ) => Promise<{ messageId?: string } | void>
   /** Current QR code data URL (WhatsApp only, null when paired) */
   qrDataUrl?: string | null
@@ -62,6 +90,8 @@ export interface ConnectorInstance {
   deleteMessage?: (channelId: string, messageId: string) => Promise<void>
   /** Rich messaging: pin a message */
   pinMessage?: (channelId: string, messageId: string) => Promise<void>
+  /** Best-effort typing or "working" indicator for the target conversation */
+  sendTyping?: (channelId: string, options?: OutboundTypingOptions) => Promise<void>
   /** Health check: returns true if the underlying connection is alive */
   isAlive?: () => boolean
 }