agent-messenger 2.15.0 → 2.16.0

package/skills/agent-kakaotalk/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-kakaotalk
 description: Interact with KakaoTalk - send messages, read chats, manage conversations
-version: 2.15.0
+version: 2.16.0
 allowed-tools: Bash(agent-kakaotalk:*)
 metadata:
   openclaw:
@@ -335,6 +335,20 @@ agent-kakaotalk message list <chat-id> --pretty
 agent-kakaotalk message send <chat-id> "Hello world"
 agent-kakaotalk message send <chat-id> "Hello world" --pretty
 
+# Send a file (auto-routes by MIME: photo / video / audio / generic file)
+agent-kakaotalk message upload <chat-id> ./photo.jpg
+agent-kakaotalk message upload <chat-id> ./clip.mp4
+agent-kakaotalk message upload <chat-id> ./voice.m4a
+agent-kakaotalk message upload <chat-id> ./report.pdf
+
+# Send a multi-photo gallery (2+ images in one message)
+agent-kakaotalk message upload <chat-id> ./img1.jpg ./img2.jpg ./img3.jpg
+
+# Force a specific kind (override auto-routing)
+agent-kakaotalk message upload <chat-id> ./clip.mp4 --as file       # send as generic file, not video
+agent-kakaotalk message upload <chat-id> ./image --as photo         # extension-less file
+agent-kakaotalk message upload <chat-id> ./data.bin --mime application/octet-stream
+
 # Mark messages as read up to a given log ID
 agent-kakaotalk message mark-read <chat-id> <log-id>
 agent-kakaotalk message mark-read <chat-id> <log-id> --pretty
@@ -343,9 +357,49 @@ agent-kakaotalk message mark-read <chat-id> <log-id> --link-id <li>   # open cha
 # Use a specific account
 agent-kakaotalk message list <chat-id> --account <account-id>
 agent-kakaotalk message send <chat-id> "Hello" --account <account-id>
+agent-kakaotalk message upload <chat-id> ./photo.jpg --account <account-id>
 agent-kakaotalk message mark-read <chat-id> <log-id> --account <account-id>
 ```
 
+#### Sending Attachments
+
+`message upload` sends photos, videos, audio, and arbitrary files to a chat. The CLI sniffs the MIME type from the filename and dispatches to the matching KakaoTalk message type, so the common case is a single command and a file path:
+
+```bash
+agent-kakaotalk message upload <chat-id> ./report.pdf
+```
+
+Routing rules:
+
+| Filename / MIME | Sent as | KakaoTalk renders it as |
+| --- | --- | --- |
+| `image/*` (`.jpg`, `.png`, `.gif`, `.webp`) | photo | Inline image with tap-to-zoom |
+| `video/*` (`.mp4`, `.mov`, `.webm`) | video | Inline player with play button |
+| `audio/*` (`.m4a`, `.mp3`, `.wav`, `.ogg`) | audio | Voice-message bubble with waveform |
+| anything else | file | Generic file attachment with download icon |
+
+Multi-photo galleries (one message that contains several images): pass 2+ files and the CLI uses the gallery flow automatically.
+
+```bash
+agent-kakaotalk message upload <chat-id> ./img1.jpg ./img2.jpg ./img3.jpg
+```
+
+Override the auto-routing with `--as <photo|video|audio|file|multi>` when you need explicit control — for example, to send an `.mp4` as a generic downloadable file instead of an inline video. Use `--mime <type>` to override MIME detection (handy for extension-less files or when the caller knows better than the filename).
+
+Output (JSON by default; `--pretty` pretty-prints the same JSON):
+
+```json
+{ "success": true, "status_code": 0, "chat_id": "9876543210", "log_id": "3846830417126748160", "sent_at": 1779509936 }
+```
+
+The process exits non-zero when `success` is `false`.
+
+Notes:
+- All attachment kinds use the same SHIP / POST / COMPLETE LOCO pipeline (and MSHIP / MPOST / FORWARD for multi-photo). The server registers the chatlog itself once the upload finishes; no follow-up text message is needed.
+- KakaoTalk caps single-message attachment sizes server-side (currently ~300MB for files, ~20MB per image in multi-photo). The CLI surfaces the server's status code on rejection.
+- Filenames are preserved on the recipient side for `file` kind, used as a display label for `audio`, and ignored for `photo` / `video` (the client renders the bytes directly).
+- Each upload opens one fresh TCP+LOCO connection per attachment. Multi-photo opens N connections in parallel.
+
 #### Mark as Read
 
 `message mark-read` sends a LOCO `NOTIREAD` packet to advance the server-side read watermark for a chat. The watermark is a `log_id` — typically the latest message's `log_id` from `message list` — not a timestamp.
@@ -368,7 +422,7 @@ Notes:
 
 Each message includes:
 - `log_id` — unique message identifier
-- `type` — message type (1 = text, 2 = photo, 12 = sticker, 20 = animated sticker, etc.)
+- `type` — message type (1 = text, 2 = photo, 3 = video, 5 = audio, 12 = sticker, 18 = file, 20 = animated sticker, 27 = multi-photo, etc.)
 - `author_id` — sender's user ID
 - `author_name` — sender's nickname when known from the chat list (otherwise `null`; only the room's "display members" are cached)
 - `message` — message text content (empty string for non-text messages like stickers)
@@ -526,6 +580,11 @@ try {
   const chatId = chats[0].chat_id
   const result = await client.sendMessage(chatId, 'Hello from SDK!')
 
+  // Send a file (photo / video / audio / file auto-routed by MIME). Pass
+  // an array to send several at once — all-image arrays become a gallery.
+  const photo = await Bun.file('./photo.jpg').bytes()
+  await client.sendAttachment(chatId, photo, 'photo.jpg')
+
   // Read messages
   const messages = await client.getMessages(chatId, { count: 50 })
 } finally {
@@ -541,14 +600,13 @@ See the [KakaoTalk SDK documentation](https://agent-messenger.dev/docs/sdk/kakao
 ## Limitations
 
 - Auto-extraction of email/password from the desktop app is **macOS and Windows only** (KakaoTalk desktop is not available on Linux). Linux users must pass `--email` and `--password` (or `--password-file`) explicitly — the LOCO protocol, login flow, and all messaging features work on Linux.
-- No file upload or download
 - No channel/chat room creation or management
 - No friend list management
 - No reactions or emoji
 - No message editing or deletion
 - No open chat (오픈채팅) browsing or joining
 - No search across chats
-- Read-only for rich content: photos, stickers, files, and other non-text messages are exposed via the `attachment` field on each message, but sending them is not supported
+- Stickers / emoticons cannot be sent (inbound stickers expose pack/path metadata, but the sticker store requires desktop-app purchase flows the SDK does not replicate). Photos, videos, audio, and arbitrary files can both be received and sent — see [`message upload`](#message-commands) and [`KakaoTalkClient.sendAttachment`](#sdk-programmatic-usage).
 - Chat IDs are numeric and not human-readable — use `chat list` to discover them
 
 ## Troubleshooting

package/skills/agent-kakaotalk/references/common-patterns.md

@@ -55,9 +55,48 @@ agent-kakaotalk message send "$TARGET_CHAT" "Hey Alice!"
 
 **When to use**: First time interacting with a chat, or when the user references a chat by name.
 
-> Note: `display_name` joins the chat's member nicknames. For the user-set room title (matching the KakaoTalk app), see [Pattern 9](#pattern-9-resolve-canonical-room-titles).
+> Note: `display_name` joins the chat's member nicknames. For the user-set room title (matching the KakaoTalk app), see [Pattern 10](#pattern-10-resolve-canonical-room-titles).
 
-## Pattern 3: Monitor Chat for New Messages
+## Pattern 3: Send Files, Photos, Videos, and Audio
+
+**Use case**: Upload an attachment to a chat (photo, video, voice, generic file, or multi-photo gallery)
+
+```bash
+#!/bin/bash
+
+CHAT_ID="9876543210"
+
+# Single file — MIME is sniffed from the filename and routed to the right kind
+agent-kakaotalk message upload "$CHAT_ID" ./photo.jpg     # → photo (inline preview)
+agent-kakaotalk message upload "$CHAT_ID" ./clip.mp4      # → video (inline player)
+agent-kakaotalk message upload "$CHAT_ID" ./voice.m4a     # → audio (voice bubble)
+agent-kakaotalk message upload "$CHAT_ID" ./report.pdf    # → file (download icon)
+
+# Multi-photo gallery — pass 2+ files and the CLI uses the gallery flow
+agent-kakaotalk message upload "$CHAT_ID" ./img1.jpg ./img2.jpg ./img3.jpg
+
+# Force a specific kind to override auto-routing
+agent-kakaotalk message upload "$CHAT_ID" ./clip.mp4 --as file   # send as generic file, not inline video
+
+# Override MIME detection for extension-less files
+agent-kakaotalk message upload "$CHAT_ID" ./data.bin --mime application/octet-stream
+
+# With error handling
+RESULT=$(agent-kakaotalk message upload "$CHAT_ID" ./photo.jpg)
+SUCCESS=$(echo "$RESULT" | jq -r '.success')
+if [ "$SUCCESS" = "true" ]; then
+  echo "Uploaded as log_id $(echo "$RESULT" | jq -r '.log_id')"
+else
+  echo "Upload failed: $(echo "$RESULT" | jq -r '.status_code')"
+  exit 1
+fi
+```
+
+**When to use**: Sending screenshots, generated reports, deployment artifacts, voice notes, or photo bundles to a chat.
+
+**Routing rules**: `image/*` → photo, `video/*` → video, `audio/*` → audio (voice memo), everything else → generic file. The full SHIP / POST / COMPLETE LOCO pipeline is handled internally — no separate "send text after upload" step is needed. KakaoTalk caps single-message attachment sizes server-side; the CLI surfaces the server's status code on rejection.
+
+## Pattern 4: Monitor Chat for New Messages
 
 **Use case**: Watch a chat room and respond to new messages
 
@@ -91,7 +130,7 @@ done
 
 **Limitations**: Polling-based, not real-time. Each poll establishes a LOCO connection, so use reasonable intervals (10s+).
 
-## Pattern 4: Read Recent Chat History
+## Pattern 5: Read Recent Chat History
 
 **Use case**: Catch up on what happened in a chat
 
@@ -113,7 +152,7 @@ echo "$MESSAGES" | jq -r '.[] | "\(.author_id): \(.message // "[non-text]")"'
 
 **When to use**: Context gathering, summarizing conversations, catching up on missed messages.
 
-## Pattern 5: Fetch More Messages
+## Pattern 6: Fetch More Messages
 
 **Use case**: Read more messages than the default 20
 
@@ -148,7 +187,7 @@ NEW_MESSAGES=$(agent-kakaotalk message list "$CHAT_ID" --from "$LAST_SEEN")
 
 **Pagination details**: The CLI now prefers KakaoTalk's `MCHATLOGS` flow for history reads, fetching message batches from the requested `--from` point and returning the last N messages after deduplication and ascending sort. If that path cannot provide results, it falls back to `CHATONROOM` + `SYNCMSG` for compatibility. As a safety net, both paths are capped at 50 internal pages. A warning is printed to stderr only when that cap is actually hit and the returned history may be incomplete.
 
-## Pattern 6: Multi-Chat Broadcast
+## Pattern 7: Multi-Chat Broadcast
 
 **Use case**: Send the same message to multiple chats
 
@@ -176,7 +215,7 @@ done
 
 **When to use**: Announcements, notifications across multiple chats.
 
-## Pattern 7: Multi-Account Operations
+## Pattern 8: Multi-Account Operations
 
 **Use case**: Manage and operate across multiple KakaoTalk accounts
 
@@ -201,7 +240,7 @@ agent-kakaotalk auth status --account 1111111111
 
 **When to use**: Managing multiple KakaoTalk identities, sending messages as different accounts, or checking status across accounts.
 
-## Pattern 8: Unread Message Summary
+## Pattern 9: Unread Message Summary
 
 **Use case**: Check which chats have unread messages
 
@@ -223,7 +262,7 @@ echo "$UNREAD" | jq -r '.[] | "  \(.display_name // "Unknown") — \(.unread_cou
 
 **When to use**: Morning catch-up, checking for urgent messages, triage.
 
-## Pattern 9: Resolve Canonical Room Titles
+## Pattern 10: Resolve Canonical Room Titles
 
 **Use case**: Show user-set room names (matching the official KakaoTalk app) instead of comma-joined member nicknames
 
@@ -269,7 +308,7 @@ const chats = await client.getChats({ resolveTitles: true })
 const title = await client.getChatTitle('9876543210')
 ```
 
-## Pattern 10: Error Handling and Retry
+## Pattern 11: Error Handling and Retry
 
 **Use case**: Robust message sending with retries
 
@@ -454,9 +493,9 @@ The `deviceType` determines the LOCO protocol identity: `'tablet'` sends `os: 'a
 
 ### Auto-Reconnect
 
-`getChats`, `getMessages`, and `sendMessage` automatically reconnect once when the LOCO session dies (e.g. the KakaoTalk desktop app reclaims the session or the network drops). The reconnect is transparent — callers don't need to handle session-drop errors.
+`getChats`, `getMessages`, `sendMessage`, and `sendAttachment` (plus the underlying typed helpers `sendPhoto` / `sendVideo` / `sendAudio` / `sendFile` / `sendMultiPhoto`) automatically reconnect once when the LOCO session dies (e.g. the KakaoTalk desktop app reclaims the session or the network drops). The reconnect is transparent — callers don't need to handle session-drop errors.
 
-Reconnect only triggers on actual session death. Operation-level errors (invalid chat ID, server rejection, etc.) are thrown immediately without retry, so side effects like `sendMessage` are never duplicated.
+Reconnect only triggers on actual session death. Operation-level errors (invalid chat ID, server rejection, etc.) are thrown immediately without retry, so side effects like `sendMessage` or `sendAttachment` are never duplicated.
 
 ## See Also
 

package/skills/agent-line/SKILL.md

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

package/skills/agent-slack/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slack
 description: Interact with Slack workspaces - send messages, read channels, manage reactions
-version: 2.15.0
+version: 2.16.0
 allowed-tools: Bash(agent-slack:*)
 metadata:
   openclaw:

package/skills/agent-slackbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slackbot
 description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
-version: 2.15.0
+version: 2.16.0
 allowed-tools: Bash(agent-slackbot:*)
 metadata:
   openclaw:

package/skills/agent-teams/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-teams
 description: Interact with Microsoft Teams - send messages, read channels, manage reactions
-version: 2.15.0
+version: 2.16.0
 allowed-tools: Bash(agent-teams:*)
 metadata:
   openclaw:

package/skills/agent-telegram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegram
 description: Interact with Telegram through TDLib - authenticate, inspect chats, and send messages
-version: 2.15.0
+version: 2.16.0
 allowed-tools: Bash(agent-telegram:*)
 ---
 

package/skills/agent-telegrambot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegrambot
 description: Interact with Telegram using bot tokens - send messages, read chats, manage reactions
-version: 2.15.0
+version: 2.16.0
 allowed-tools: Bash(agent-telegrambot:*)
 metadata:
   openclaw:

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