agent-messenger 2.15.1 → 2.17.0

package/src/platforms/kakaotalk/index.ts

@@ -12,8 +12,13 @@ export type {
   KakaoDeviceType,
   KakaoEmoticonKind,
   KakaoEmoticonMessageType,
+  KakaoFileExtra,
+  KakaoLoginResult,
+  KakaoMarkReadResult,
   KakaoMember,
   KakaoMessage,
+  KakaoMultiPhotoExtra,
+  KakaoPhotoExtra,
   KakaoProfile,
   KakaoSendResult,
   KakaoTalkListenerEventMap,
@@ -27,9 +32,11 @@ export type {
 export {
   KAKAO_EMOTICON_KIND_BY_TYPE,
   KAKAO_EMOTICON_MESSAGE_TYPES,
+  KAKAO_MESSAGE_TYPE,
   KakaoAccountCredentialsSchema,
   KakaoChatSchema,
   KakaoConfigSchema,
+  KakaoMarkReadResultSchema,
   KakaoMemberSchema,
   KakaoMessageSchema,
   KakaoProfileSchema,
@@ -39,3 +46,9 @@ export {
   KakaoTalkPushMessageEventSchema,
   KakaoTalkPushReadEventSchema,
 } from './types'
+export { attemptLogin, generateDeviceUuid, loginFlow, registerDevice, requestPasscode } from './auth/kakao-login'
+export type { LoginCredentials } from './auth/kakao-login'
+export { sha1Hex } from './media-upload'
+export { detectImageDimensions } from './image-meta'
+export type { AttachmentInput, AttachmentPlan, ResolvedAttachment, SingleAttachmentKind } from './attachment-router'
+export { planAttachments, resolveAttachment } from './attachment-router'

package/src/platforms/kakaotalk/media-upload.ts

@@ -0,0 +1,44 @@
+// SHA-1 hex (uppercase, 40 chars) — required as the `cs` (checksum) field
+// on SHIP requests and on the inbound photo `extra` JSON. Verified by inbound
+// capture of a real KakaoTalk client photo (2026-05).
+export async function sha1Hex(data: Uint8Array): Promise<string> {
+  const hashBuf = await crypto.subtle.digest('SHA-1', data)
+  return Array.from(new Uint8Array(hashBuf))
+    .map((b) => b.toString(16).padStart(2, '0').toUpperCase())
+    .join('')
+}
+
+const MIME_BY_EXT: Record<string, string> = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  mp4: 'video/mp4',
+  mov: 'video/quicktime',
+  webm: 'video/webm',
+  mkv: 'video/x-matroska',
+  m4v: 'video/x-m4v',
+  m4a: 'audio/m4a',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  pdf: 'application/pdf',
+  csv: 'text/csv',
+  txt: 'text/plain',
+  json: 'application/json',
+  zip: 'application/zip',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+}
+
+export function guessMimeFromFilename(filename: string): string {
+  const dot = filename.lastIndexOf('.')
+  if (dot < 0 || dot === filename.length - 1) return 'application/octet-stream'
+  const ext = filename.slice(dot + 1).toLowerCase()
+  return MIME_BY_EXT[ext] ?? 'application/octet-stream'
+}

package/src/platforms/kakaotalk/protocol/connection.ts

@@ -50,6 +50,17 @@ export class LocoConnection {
     await this.write(handshakePacket)
   }
 
+  // Writes raw bytes onto the LOCO stream after applying the same AES-128-GCM
+  // framing as encrypted packets — used by the media-upload POST step where
+  // the protocol expects the file payload to follow the POST request inside
+  // the same encrypted channel (chunked into N frames automatically by the
+  // crypto layer's 4-byte-size + nonce + ciphertext + tag wrapping).
+  async writeRaw(data: Buffer): Promise<void> {
+    if (!this.crypto) throw new Error('crypto not initialised')
+    const encrypted = this.crypto.encrypt(data)
+    await this.write(encrypted)
+  }
+
   async sendPacket(method: string, body: Record<string, unknown> = {}): Promise<LocoPacket> {
     const packetId = ++this.packetIdCounter
     const packet: LocoPacket = {

package/src/platforms/kakaotalk/protocol/media-uploader.ts

@@ -0,0 +1,129 @@
+import { Long } from 'bson'
+
+import type { KakaoDeviceType } from '../types'
+import { MCCMNC, getLocoDeviceConfig } from './config'
+import { LocoConnection } from './connection'
+import type { LocoPacket } from './types'
+
+export interface UploadToLocoOptions {
+  shipToken: string
+  shipHost: string
+  shipPort: number
+  chatId: Long
+  msgType: number
+  userId: string
+  filename: string
+  data: Uint8Array
+  width?: number
+  height?: number
+  deviceType: KakaoDeviceType
+  onProgress?: (sent: number, total: number) => void
+}
+
+export interface UploadToLocoResult {
+  completePacket: LocoPacket | null
+  postStatusCode: number
+  postOffset: number
+}
+
+const DEFAULT_NETWORK_TYPE = 0
+const DEFAULT_COMPLETE_TIMEOUT_MS = 60_000
+
+// Drives the SHIP → connect → POST → stream → COMPLETE pipeline that KakaoTalk
+// uses for chat-media uploads. The caller has already done SHIP on the main
+// session and received {k, vh, p}; this opens a dedicated TCP+LOCO connection
+// to (vh, p), sends POST with the ticket + chat metadata, streams the raw file
+// bytes, and waits for the server's COMPLETE push that triggers the actual
+// chat-message registration.
+//
+// Field names (u/k/t/s/c/mid/w/h/mm/nt/os/av/f/ns) match the APK's
+// `SR/g0.java` (PostJob) verbatim. The COMPLETE handshake is a server-pushed
+// packet whose body contains the resulting chatLog struct.
+export async function uploadMediaToLoco(opts: UploadToLocoOptions): Promise<UploadToLocoResult> {
+  return runPostStreamComplete(opts, 'POST')
+}
+
+// Single-entry MPOST upload — runs the same connect → POST → stream → COMPLETE
+// pipeline as uploadMediaToLoco but with MPOST as the opcode (used after MSHIP
+// for each entry in a multi-photo batch). Callers fan-out across all entries
+// in parallel and then issue one FORWARD to register the gallery message.
+export async function uploadMultiMediaEntry(opts: UploadToLocoOptions): Promise<UploadToLocoResult> {
+  return runPostStreamComplete(opts, 'MPOST')
+}
+
+async function runPostStreamComplete(opts: UploadToLocoOptions, opcode: 'POST' | 'MPOST'): Promise<UploadToLocoResult> {
+  const device = getLocoDeviceConfig(opts.deviceType)
+
+  const conn = new LocoConnection()
+  await conn.connectSecure(opts.shipHost, opts.shipPort)
+
+  const totalSize = opts.data.byteLength
+  let completeResolve: ((p: LocoPacket | null) => void) | null = null
+  let completeTimeout: ReturnType<typeof setTimeout> | null = null
+  const completePromise = new Promise<LocoPacket | null>((resolve) => {
+    completeResolve = resolve
+    completeTimeout = setTimeout(() => {
+      completeTimeout = null
+      resolve(null)
+    }, DEFAULT_COMPLETE_TIMEOUT_MS)
+  })
+  conn.onPush((push) => {
+    if (push.method === 'COMPLETE' && completeResolve) {
+      if (completeTimeout) {
+        clearTimeout(completeTimeout)
+        completeTimeout = null
+      }
+      completeResolve(push)
+      completeResolve = null
+    }
+  })
+
+  try {
+    const postBody: Record<string, unknown> = {
+      k: opts.shipToken,
+      s: totalSize,
+      t: opts.msgType,
+      u: Long.fromString(opts.userId),
+      os: device.os,
+      av: device.appVersion,
+      nt: DEFAULT_NETWORK_TYPE,
+      mm: MCCMNC,
+    }
+    if (opcode === 'POST') {
+      postBody.f = opts.filename
+      postBody.c = opts.chatId
+      postBody.mid = Long.ONE
+      postBody.ns = true
+      if (typeof opts.width === 'number') postBody.w = opts.width
+      if (typeof opts.height === 'number') postBody.h = opts.height
+    } else {
+      postBody.dt = 0
+      postBody.scp = 0
+    }
+
+    const postResp = await conn.sendPacket(opcode, postBody)
+    const postOffsetRaw = (postResp.body as Record<string, unknown>).o
+    const postOffset = typeof postOffsetRaw === 'number' ? postOffsetRaw : 0
+
+    const bytesToSend = opts.data.subarray(postOffset)
+    if (bytesToSend.length > 0) {
+      await conn.writeRaw(Buffer.from(bytesToSend))
+      opts.onProgress?.(totalSize, totalSize)
+    }
+
+    const completePacket = await completePromise
+    const postStatusCode = postResp.statusCode
+
+    return {
+      completePacket,
+      postStatusCode,
+      postOffset,
+    }
+  } finally {
+    if (completeTimeout) {
+      clearTimeout(completeTimeout)
+      completeTimeout = null
+    }
+    conn.close()
+  }
+}

package/src/platforms/kakaotalk/protocol/session.ts

@@ -126,6 +126,73 @@ export class LocoSession {
     })
   }
 
+  // Sends a WRITE with non-text message_type plus the JSON-stringified `extra`
+  // payload that KakaoTalk clients render as the attachment (photo, file, etc).
+  // See types.ts → KakaoPhotoExtra / KakaoFileExtra for the per-type shape.
+  async sendAttachment(chatId: Long, type: number, extra: Record<string, unknown>, caption = ''): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    return this.connection.sendPacket('WRITE', {
+      chatId,
+      msg: caption,
+      type,
+      noSeen: false,
+      extra: JSON.stringify(extra),
+    })
+  }
+
+  // SHIP — request a media-upload ticket. Reserves a slot on a media LOCO
+  // server and returns the token (k), host (vh), and port (p) the client must
+  // connect to next. Sent on the main session.
+  async shipMedia(chatId: Long, type: number, size: number, checksum: string, extension: string): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    const body: Record<string, unknown> = {
+      c: chatId,
+      t: type,
+      s: Long.fromNumber(size),
+      cs: checksum,
+    }
+    if (extension.length > 0) body.e = extension
+    return this.connection.sendPacket('SHIP', body)
+  }
+
+  // MSHIP — multi-file equivalent of SHIP. Per-file fields become parallel
+  // arrays (sl/csl/el) and the response carries kl/vhl/pl arrays the caller
+  // must fan out across — one MPOST connection per entry.
+  async shipMultiMedia(
+    chatId: Long,
+    type: number,
+    sizes: number[],
+    checksums: string[],
+    extensions: string[],
+  ): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    return this.connection.sendPacket('MSHIP', {
+      c: chatId,
+      t: type,
+      sl: sizes.map((s) => Long.fromNumber(s)),
+      csl: checksums,
+      el: extensions,
+    })
+  }
+
+  // FORWARD — used after MPOST: registers a multi-attachment chatlog as one
+  // message. Same shape as WRITE but the server routes the attachment to
+  // multi-media rendering (galleries, multi-photo posts).
+  async forwardChat(chatId: Long, type: number, extra: Record<string, unknown>, caption = ''): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    return this.connection.sendPacket('FORWARD', {
+      chatId,
+      msg: caption,
+      type,
+      noSeen: false,
+      extra: JSON.stringify(extra),
+    })
+  }
+
+  getConnection(): LocoConnection | null {
+    return this.connection
+  }
+
   async syncMessages(chatId: Long, count = 20, cursor?: Long, maxLogId?: Long): Promise<LocoPacket> {
     if (!this.connection) throw new Error('Not connected')
     return this.connection.sendPacket('SYNCMSG', {

package/src/platforms/kakaotalk/types.ts

@@ -119,6 +119,63 @@ export interface KakaoSendResult {
   sent_at: number
 }
 
+// LOCO message_type values. Source: KakaoTalk APK 26.4.2 + typeclaw inbound parser.
+export const KAKAO_MESSAGE_TYPE = {
+  TEXT: 1,
+  PHOTO: 2,
+  VIDEO: 3,
+  AUDIO: 5,
+  FILE: 18,
+  MULTIPHOTO: 27,
+} as const
+
+// PHOTO `extra` keys verified by inbound capture of a real KakaoTalk client
+// photo message (2026-05). The bare minimum the receiver needs to render
+// the inline preview is k/s/w/h/mt/cs — url and thumbnailUrl are server-issued
+// pre-signed URLs that the recipient regenerates locally from k, so we don't
+// supply them on outbound.
+export interface KakaoPhotoExtra {
+  k: string
+  s: number
+  w: number
+  h: number
+  mt: string
+  cs: string
+  url?: string
+  thumbnailUrl?: string
+  thumbnailWidth?: number
+  thumbnailHeight?: number
+  expire?: number
+}
+
+export interface KakaoFileExtra {
+  k: string
+  s: number
+  name: string
+  mt: string
+  cs: string
+  expire?: number
+  url?: string
+}
+
+// MULTIPHOTO extra — each per-file field of KakaoPhotoExtra becomes a
+// parallel array. Verified by inbound capture of a real multi-photo message
+// (2026-05). csl uses lowercase hex (unlike PHOTO's cs which is uppercase).
+export interface KakaoMultiPhotoExtra {
+  kl: string[]
+  wl: number[]
+  hl: number[]
+  mtl: string[]
+  sl: number[]
+  csl: string[]
+  cmtl?: string[]
+  imageUrls?: string[]
+  thumbnailUrls?: string[]
+  thumbnailWidths?: number[]
+  thumbnailHeights?: number[]
+  expire?: number
+}
+
 export interface KakaoMarkReadResult {
   success: boolean
   status_code: number

package/src/platforms/slackbot/types.ts

@@ -334,6 +334,18 @@ export interface SlackSocketModeMessageEvent {
   event_ts?: string
   edited?: { user: string; ts: string }
   hidden?: boolean
+  // Set on every reply within a thread; identifies the author of the message
+  // the thread is rooted at. Useful for deciding whether a reply targets the
+  // bot, another human, or an unknown parent.
+  parent_user_id?: string
+  // 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.
+  client_msg_id?: string
+  // Attachments delivered inline on the same message event. Slack does not
+  // fire a separate file_share envelope for messages we receive over Socket
+  // Mode, so consumers reading attachments off `message` events look here.
+  files?: SlackFile[]
   [key: string]: unknown
 }
 
@@ -345,6 +357,10 @@ export interface SlackSocketModeAppMentionEvent {
   ts: string
   thread_ts?: string
   event_ts?: string
+  // `app_mention` envelopes do not always carry `client_msg_id`, but typing
+  // it keeps the promotion to a message-shaped event lossless if Slack ever
+  // starts sending it on this event.
+  client_msg_id?: string
   [key: string]: unknown
 }