agent-messenger 2.15.1 → 2.16.0

package/skills/agent-webex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webex
 description: Interact with Cisco Webex - send messages, read spaces, manage memberships
-version: 2.15.1
+version: 2.16.0
 allowed-tools: Bash(agent-webex:*)
 metadata:
   openclaw:

package/skills/agent-wechatbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-wechatbot
 description: Interact with WeChat Official Account using API credentials - send messages, manage templates, list followers
-version: 2.15.1
+version: 2.16.0
 allowed-tools: Bash(agent-wechatbot:*)
 metadata:
   openclaw:

package/skills/agent-whatsapp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsapp
 description: Interact with WhatsApp - send messages, read chats, manage conversations
-version: 2.15.1
+version: 2.16.0
 allowed-tools: Bash(agent-whatsapp:*)
 metadata:
   openclaw:

package/skills/agent-whatsappbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsappbot
 description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
-version: 2.15.1
+version: 2.16.0
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:

package/src/platforms/kakaotalk/attachment-router.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'bun:test'
+
+import { planAttachments, resolveAttachment } from './attachment-router'
+
+const bytes = new Uint8Array([0])
+
+describe('resolveAttachment', () => {
+  it('classifies image MIME as photo', () => {
+    expect(resolveAttachment({ data: bytes, filename: 'x.jpg' }).kind).toBe('photo')
+    expect(resolveAttachment({ data: bytes, filename: 'x.png', mime: 'image/png' }).kind).toBe('photo')
+  })
+
+  it('classifies video MIME as video', () => {
+    expect(resolveAttachment({ data: bytes, filename: 'x.mp4' }).kind).toBe('video')
+  })
+
+  it('classifies audio MIME as audio', () => {
+    expect(resolveAttachment({ data: bytes, filename: 'x.m4a' }).kind).toBe('audio')
+  })
+
+  it('classifies everything else as file', () => {
+    expect(resolveAttachment({ data: bytes, filename: 'x.pdf' }).kind).toBe('file')
+    expect(resolveAttachment({ data: bytes, filename: 'x.zip' }).kind).toBe('file')
+    expect(resolveAttachment({ data: bytes, filename: 'x.unknown-ext' }).kind).toBe('file')
+  })
+
+  it('uses explicit mime override over filename inference', () => {
+    const r = resolveAttachment({ data: bytes, filename: 'x.pdf', mime: 'image/png' })
+    expect(r.kind).toBe('photo')
+    expect(r.mime).toBe('image/png')
+  })
+
+  it('routes upper-case and mixed-case MIME overrides the same as lower-case', () => {
+    expect(resolveAttachment({ data: bytes, filename: 'x.bin', mime: 'IMAGE/JPEG' }).kind).toBe('photo')
+    expect(resolveAttachment({ data: bytes, filename: 'x.bin', mime: 'Video/MP4' }).kind).toBe('video')
+    expect(resolveAttachment({ data: bytes, filename: 'x.bin', mime: 'Audio/MPEG' }).kind).toBe('audio')
+    expect(resolveAttachment({ data: bytes, filename: 'x.bin', mime: 'IMAGE/PNG' }).mime).toBe('image/png')
+  })
+
+  it('preserves data and filename verbatim', () => {
+    const r = resolveAttachment({ data: bytes, filename: 'cat picture.jpg' })
+    expect(r.data).toBe(bytes)
+    expect(r.filename).toBe('cat picture.jpg')
+  })
+})
+
+describe('planAttachments', () => {
+  it('throws on empty array', () => {
+    expect(() => planAttachments([])).toThrow(/empty/i)
+  })
+
+  it('returns single for a one-element array', () => {
+    const plan = planAttachments([{ data: bytes, filename: 'x.jpg' }])
+    expect(plan.kind).toBe('single')
+    if (plan.kind !== 'single') return
+    expect(plan.resolved.kind).toBe('photo')
+  })
+
+  it('returns single (not multiphoto) for a one-photo array', () => {
+    const plan = planAttachments([{ data: bytes, filename: 'a.png' }])
+    expect(plan.kind).toBe('single')
+  })
+
+  it('returns multiphoto when every item resolves to photo', () => {
+    const plan = planAttachments([
+      { data: bytes, filename: 'a.jpg' },
+      { data: bytes, filename: 'b.png' },
+      { data: bytes, filename: 'c.webp' },
+    ])
+    expect(plan.kind).toBe('multiphoto')
+    if (plan.kind !== 'multiphoto') return
+    expect(plan.items.length).toBe(3)
+  })
+
+  it('returns sequential for mixed kinds (image + file)', () => {
+    const plan = planAttachments([
+      { data: bytes, filename: 'photo.jpg' },
+      { data: bytes, filename: 'spec.pdf' },
+    ])
+    expect(plan.kind).toBe('sequential')
+    if (plan.kind !== 'sequential') return
+    expect(plan.resolved.map((r) => r.kind)).toEqual(['photo', 'file'])
+  })
+
+  it('returns sequential for all-video (multiphoto is image-only)', () => {
+    const plan = planAttachments([
+      { data: bytes, filename: 'a.mp4' },
+      { data: bytes, filename: 'b.mp4' },
+    ])
+    expect(plan.kind).toBe('sequential')
+    if (plan.kind !== 'sequential') return
+    expect(plan.resolved.every((r) => r.kind === 'video')).toBe(true)
+  })
+
+  it('honors explicit mime overrides when classifying for the photo gate', () => {
+    const plan = planAttachments([
+      { data: bytes, filename: 'a.pdf', mime: 'image/jpeg' },
+      { data: bytes, filename: 'b.bin', mime: 'image/png' },
+    ])
+    expect(plan.kind).toBe('multiphoto')
+  })
+})

package/src/platforms/kakaotalk/attachment-router.ts

@@ -0,0 +1,50 @@
+import { guessMimeFromFilename } from './media-upload'
+
+export type AttachmentInput = {
+  data: Uint8Array | Buffer
+  filename: string
+  mime?: string
+}
+
+export type SingleAttachmentKind = 'photo' | 'video' | 'audio' | 'file'
+
+export type ResolvedAttachment = {
+  kind: SingleAttachmentKind
+  mime: string
+  data: Uint8Array | Buffer
+  filename: string
+}
+
+export type AttachmentPlan =
+  | { kind: 'single'; resolved: ResolvedAttachment }
+  | { kind: 'multiphoto'; items: readonly AttachmentInput[] }
+  | { kind: 'sequential'; resolved: readonly ResolvedAttachment[] }
+
+export function resolveAttachment(input: AttachmentInput): ResolvedAttachment {
+  // MIME types are case-insensitive per RFC 2045 §5.1; normalize so an `Image/JPEG`
+  // override still routes to `photo` instead of falling through to `file`.
+  const mime = (input.mime ?? guessMimeFromFilename(input.filename)).toLowerCase()
+  const kind: SingleAttachmentKind = mime.startsWith('image/')
+    ? 'photo'
+    : mime.startsWith('video/')
+      ? 'video'
+      : mime.startsWith('audio/')
+        ? 'audio'
+        : 'file'
+  return { kind, mime, data: input.data, filename: input.filename }
+}
+
+export function planAttachments(items: readonly AttachmentInput[]): AttachmentPlan {
+  if (items.length === 0) {
+    throw new Error('sendAttachment received an empty attachments array')
+  }
+  if (items.length === 1) {
+    return { kind: 'single', resolved: resolveAttachment(items[0]!) }
+  }
+  const resolved = items.map(resolveAttachment)
+  // MULTIPHOTO (message_type 27) is image-only by KakaoTalk's wire protocol.
+  if (resolved.every((r) => r.kind === 'photo')) {
+    return { kind: 'multiphoto', items: items.slice() }
+  }
+  return { kind: 'sequential', resolved }
+}

package/src/platforms/kakaotalk/client.ts

@@ -7,17 +7,23 @@ import { Long } from 'bson'
 import { getConfigDir } from '@/shared/utils/config-dir'
 import { warn } from '@/shared/utils/stderr'
 
+import { type AttachmentInput, type ResolvedAttachment, planAttachments } from './attachment-router'
+import { detectImageDimensions } from './image-meta'
+import { sha1Hex } from './media-upload'
 import { LANG, PC_OS_NAME, getLocoDeviceConfig } from './protocol/config'
+import { uploadMediaToLoco, uploadMultiMediaEntry } from './protocol/media-uploader'
 import { LocoSession } from './protocol/session'
 import type { ChatListResponse, LocoPacket, LoginListResponse, SyncState } from './protocol/types'
-import type {
-  KakaoChat,
-  KakaoDeviceType,
-  KakaoMarkReadResult,
-  KakaoMember,
-  KakaoMessage,
-  KakaoProfile,
-  KakaoSendResult,
+import {
+  KAKAO_MESSAGE_TYPE,
+  type KakaoChat,
+  type KakaoDeviceType,
+  type KakaoMarkReadResult,
+  type KakaoMember,
+  type KakaoMessage,
+  type KakaoMultiPhotoExtra,
+  type KakaoProfile,
+  type KakaoSendResult,
 } from './types'
 
 export type KakaoSessionEvent =
@@ -895,6 +901,307 @@ export class KakaoTalkClient {
     })
   }
 
+  async sendAttachment(
+    chatId: string,
+    data: Uint8Array | Buffer,
+    filename: string,
+    mimeType?: string,
+  ): Promise<KakaoSendResult>
+  async sendAttachment(chatId: string, attachments: ReadonlyArray<AttachmentInput>): Promise<KakaoSendResult>
+  async sendAttachment(
+    chatId: string,
+    dataOrAttachments: Uint8Array | Buffer | ReadonlyArray<AttachmentInput>,
+    filename?: string,
+    mimeType?: string,
+  ): Promise<KakaoSendResult> {
+    const inputs: ReadonlyArray<AttachmentInput> = Array.isArray(dataOrAttachments)
+      ? dataOrAttachments
+      : [{ data: dataOrAttachments, filename: filename!, mime: mimeType }]
+    const plan = planAttachments(inputs)
+    switch (plan.kind) {
+      case 'single':
+        return this.dispatchSingleAttachment(chatId, plan.resolved)
+      case 'multiphoto':
+        return this.sendMultiPhoto(
+          chatId,
+          plan.items.map((it) => ({ data: it.data, filename: it.filename })),
+        )
+      case 'sequential': {
+        let last: KakaoSendResult | null = null
+        for (const r of plan.resolved) {
+          const result = await this.dispatchSingleAttachment(chatId, r)
+          if (!result.success) return result
+          last = result
+        }
+        return last!
+      }
+    }
+  }
+
+  private dispatchSingleAttachment(chatId: string, r: ResolvedAttachment): Promise<KakaoSendResult> {
+    switch (r.kind) {
+      case 'photo':
+        return this.sendPhoto(chatId, r.data, r.filename)
+      case 'video':
+        return this.sendVideo(chatId, r.data, r.filename)
+      case 'audio':
+        return this.sendAudio(chatId, r.data, r.filename)
+      case 'file':
+        return this.sendFile(chatId, r.data, r.filename, r.mime)
+    }
+  }
+
+  async sendPhoto(chatId: string, photo: Uint8Array | Buffer, filename = 'image.jpg'): Promise<KakaoSendResult> {
+    this.ensureAuth()
+    const data = photo instanceof Uint8Array ? photo : new Uint8Array(photo)
+    const dim = detectImageDimensions(data)
+    const checksum = await sha1Hex(data)
+    const ext = filename.includes('.') ? filename.split('.').pop()! : 'jpg'
+
+    return this.sendMediaViaLoco({
+      chatId,
+      data,
+      msgType: KAKAO_MESSAGE_TYPE.PHOTO,
+      filename,
+      checksum,
+      extension: ext,
+      width: dim.width,
+      height: dim.height,
+      errorCode: 'send_photo_failed',
+    })
+  }
+
+  async sendVideo(chatId: string, video: Uint8Array | Buffer, filename = 'video.mp4'): Promise<KakaoSendResult> {
+    this.ensureAuth()
+    const data = video instanceof Uint8Array ? video : new Uint8Array(video)
+    const checksum = await sha1Hex(data)
+    const ext = filename.includes('.') ? filename.split('.').pop()! : 'mp4'
+
+    return this.sendMediaViaLoco({
+      chatId,
+      data,
+      msgType: KAKAO_MESSAGE_TYPE.VIDEO,
+      filename,
+      checksum,
+      extension: ext,
+      errorCode: 'send_video_failed',
+    })
+  }
+
+  async sendAudio(chatId: string, audio: Uint8Array | Buffer, filename = 'audio.m4a'): Promise<KakaoSendResult> {
+    this.ensureAuth()
+    const data = audio instanceof Uint8Array ? audio : new Uint8Array(audio)
+    const checksum = await sha1Hex(data)
+    const ext = filename.includes('.') ? filename.split('.').pop()! : 'm4a'
+
+    return this.sendMediaViaLoco({
+      chatId,
+      data,
+      msgType: KAKAO_MESSAGE_TYPE.AUDIO,
+      filename,
+      checksum,
+      extension: ext,
+      errorCode: 'send_audio_failed',
+    })
+  }
+
+  async sendFile(
+    chatId: string,
+    file: Uint8Array | Buffer,
+    filename: string,
+    mimeType = 'application/octet-stream',
+  ): Promise<KakaoSendResult> {
+    void mimeType
+    this.ensureAuth()
+    const data = file instanceof Uint8Array ? file : new Uint8Array(file)
+    const checksum = await sha1Hex(data)
+    const ext = filename.includes('.') ? filename.split('.').pop()! : ''
+
+    return this.sendMediaViaLoco({
+      chatId,
+      data,
+      msgType: KAKAO_MESSAGE_TYPE.FILE,
+      filename,
+      checksum,
+      extension: ext,
+      errorCode: 'send_file_failed',
+    })
+  }
+
+  async sendMultiPhoto(
+    chatId: string,
+    photos: Array<{ data: Uint8Array | Buffer; filename?: string }>,
+  ): Promise<KakaoSendResult> {
+    this.ensureAuth()
+    if (photos.length < 2) {
+      throw new KakaoTalkError(
+        'sendMultiPhoto requires at least 2 photos; use sendPhoto for a single image',
+        'send_multi_photo_failed',
+      )
+    }
+
+    const prepared = await Promise.all(
+      photos.map(async (p, i) => {
+        const bytes = p.data instanceof Uint8Array ? p.data : new Uint8Array(p.data)
+        const filename = p.filename ?? `image-${i + 1}.jpg`
+        const dim = detectImageDimensions(bytes)
+        const checksum = (await sha1Hex(bytes)).toLowerCase()
+        const ext = filename.includes('.') ? filename.split('.').pop()! : 'jpg'
+        return { bytes, filename, dim, checksum, ext }
+      }),
+    )
+
+    const parsedChatId = parseChatId(chatId)
+
+    return this.executeWithReconnect(async ({ session }) => {
+      try {
+        const mshipResp = await session.shipMultiMedia(
+          parsedChatId,
+          KAKAO_MESSAGE_TYPE.MULTIPHOTO,
+          prepared.map((p) => p.bytes.byteLength),
+          prepared.map((p) => p.checksum),
+          prepared.map((p) => p.ext),
+        )
+
+        if (mshipResp.statusCode !== 0) {
+          throw new KakaoTalkError(`MSHIP rejected (status ${mshipResp.statusCode})`, 'send_multi_photo_failed')
+        }
+
+        const body = mshipResp.body as Record<string, unknown>
+        const kl = body.kl as string[] | undefined
+        const vhl = body.vhl as string[] | undefined
+        const pl = body.pl as number[] | undefined
+        if (
+          !kl ||
+          !vhl ||
+          !pl ||
+          kl.length !== prepared.length ||
+          vhl.length !== prepared.length ||
+          pl.length !== prepared.length
+        ) {
+          throw new KakaoTalkError(
+            `MSHIP response arrays do not match prepared.length=${prepared.length}: ` +
+              `kl=${kl?.length} vhl=${vhl?.length} pl=${pl?.length}`,
+            'send_multi_photo_failed',
+          )
+        }
+
+        await Promise.all(
+          prepared.map((p, i) =>
+            uploadMultiMediaEntry({
+              shipToken: kl[i]!,
+              shipHost: vhl[i]!,
+              shipPort: pl[i]!,
+              chatId: parsedChatId,
+              msgType: KAKAO_MESSAGE_TYPE.MULTIPHOTO,
+              userId: this.userId!,
+              filename: p.filename,
+              data: p.bytes,
+              width: p.dim.width,
+              height: p.dim.height,
+              deviceType: this.deviceType,
+            }),
+          ),
+        )
+
+        const extra: KakaoMultiPhotoExtra = {
+          kl,
+          wl: prepared.map((p) => p.dim.width),
+          hl: prepared.map((p) => p.dim.height),
+          mtl: prepared.map((p) => p.dim.mimeType),
+          sl: prepared.map((p) => p.bytes.byteLength),
+          csl: prepared.map((p) => p.checksum),
+          cmtl: prepared.map(() => ''),
+        }
+
+        const forwardResp = await session.forwardChat(
+          parsedChatId,
+          KAKAO_MESSAGE_TYPE.MULTIPHOTO,
+          extra as unknown as Record<string, unknown>,
+        )
+
+        return {
+          success: forwardResp.statusCode === 0,
+          status_code: forwardResp.statusCode,
+          chat_id: chatId,
+          log_id: longToString((forwardResp.body as Record<string, unknown>).logId),
+          sent_at: ((forwardResp.body as Record<string, unknown>).sendAt as number | undefined) ?? 0,
+        }
+      } catch (error) {
+        throw wrapError(error, 'send_multi_photo_failed')
+      }
+    })
+  }
+
+  private async sendMediaViaLoco(opts: {
+    chatId: string
+    data: Uint8Array
+    msgType: number
+    filename: string
+    checksum: string
+    extension: string
+    width?: number
+    height?: number
+    errorCode: string
+  }): Promise<KakaoSendResult> {
+    const parsedChatId = parseChatId(opts.chatId)
+    return this.executeWithReconnect(async ({ session }) => {
+      try {
+        const shipResp = await session.shipMedia(
+          parsedChatId,
+          opts.msgType,
+          opts.data.byteLength,
+          opts.checksum,
+          opts.extension,
+        )
+
+        if (shipResp.statusCode !== 0) {
+          throw new KakaoTalkError(`SHIP rejected (status ${shipResp.statusCode})`, opts.errorCode)
+        }
+
+        const body = shipResp.body as Record<string, unknown>
+        const shipToken = body.k as string | undefined
+        const shipHost = body.vh as string | undefined
+        const shipPort = body.p as number | undefined
+
+        if (typeof shipToken !== 'string' || typeof shipHost !== 'string' || typeof shipPort !== 'number') {
+          throw new KakaoTalkError(
+            `SHIP response missing fields: k=${shipToken} vh=${shipHost} p=${shipPort}`,
+            opts.errorCode,
+          )
+        }
+
+        const uploadRes = await uploadMediaToLoco({
+          shipToken,
+          shipHost,
+          shipPort,
+          chatId: parsedChatId,
+          msgType: opts.msgType,
+          userId: this.userId!,
+          filename: opts.filename,
+          data: opts.data,
+          width: opts.width,
+          height: opts.height,
+          deviceType: this.deviceType,
+        })
+
+        const completeBody = uploadRes.completePacket?.body as Record<string, unknown> | undefined
+        const chatLog = completeBody?.chatLog as Record<string, unknown> | undefined
+        const logId = chatLog?.logId
+
+        return {
+          success: uploadRes.completePacket !== null && uploadRes.postStatusCode === 0,
+          status_code: uploadRes.postStatusCode,
+          chat_id: opts.chatId,
+          log_id: longToString(logId),
+          sent_at: (chatLog?.sendAt as number | undefined) ?? 0,
+        }
+      } catch (error) {
+        throw wrapError(error, opts.errorCode)
+      }
+    })
+  }
+
   /**
    * Advance the read watermark for `chatId` up to and including `logId`.
    * The caller decides open vs normal: pass `opts.linkId` for open chats

package/src/platforms/kakaotalk/commands/message.ts

@@ -1,3 +1,6 @@
+import { readFileSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+
 import { Command } from 'commander'
 
 import { handleError } from '@/shared/utils/error-handler'
@@ -33,6 +36,56 @@ async function sendAction(
   }
 }
 
+type UploadKind = 'auto' | 'photo' | 'video' | 'audio' | 'file' | 'multi'
+
+async function uploadAction(
+  chatId: string,
+  filePaths: string[],
+  options: { account?: string; pretty?: boolean; as?: UploadKind; mime?: string },
+): Promise<void> {
+  try {
+    const kind: UploadKind = options.as ?? (filePaths.length > 1 ? 'multi' : 'auto')
+
+    const result = await withKakaoClient(options, async (client) => {
+      if (kind === 'multi') {
+        if (filePaths.length < 2) {
+          throw new Error('--as=multi requires 2 or more files')
+        }
+        return client.sendMultiPhoto(
+          chatId,
+          filePaths.map((p) => ({ data: readFileSync(resolve(p)), filename: basename(p) })),
+        )
+      }
+
+      if (filePaths.length !== 1) {
+        throw new Error(`--as=${kind} accepts exactly one file path`)
+      }
+      const path = resolve(filePaths[0]!)
+      const data = readFileSync(path)
+      const filename = basename(path)
+
+      switch (kind) {
+        case 'auto':
+          return client.sendAttachment(chatId, data, filename, options.mime)
+        case 'photo':
+          return client.sendPhoto(chatId, data, filename)
+        case 'video':
+          return client.sendVideo(chatId, data, filename)
+        case 'audio':
+          return client.sendAudio(chatId, data, filename)
+        case 'file':
+          return client.sendFile(chatId, data, filename, options.mime ?? 'application/octet-stream')
+      }
+    })
+    console.log(formatOutput(result, options.pretty))
+    if (!result.success) {
+      process.exit(1)
+    }
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
 async function markReadAction(
   chatId: string,
   logId: string,
@@ -72,6 +125,19 @@ export const messageCommand = new Command('message')
       .option('--pretty', 'Pretty print JSON output')
       .action(sendAction),
   )
+  .addCommand(
+    new Command('upload')
+      .description(
+        'Send one or more files to a chat. MIME is sniffed from the filename (or --mime) and dispatched to the matching KakaoTalk message_type. Pass 2+ files (or --as=multi) for a multi-photo gallery.',
+      )
+      .argument('<chat-id>', 'Chat room ID')
+      .argument('<file-paths...>', 'One or more file paths')
+      .option('--account <id>', 'Use a specific KakaoTalk account')
+      .option('--as <kind>', 'Force a specific kind: auto | photo | video | audio | file | multi')
+      .option('--mime <type>', 'Override MIME type (otherwise inferred from filename)')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(uploadAction),
+  )
   .addCommand(
     new Command('mark-read')
       .description('Mark messages in a chat room as read up to a given log ID')