agent-messenger 2.15.1 → 2.17.0

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.1
+version: 2.17.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.1
+version: 2.17.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.1
+version: 2.17.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.1
+version: 2.17.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.1
+version: 2.17.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.1
+version: 2.17.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.1
+version: 2.17.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.17.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.17.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.17.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 }
+}