typeclaw 0.1.0

package/src/channels/adapters/kakaotalk-author-resolver.ts

@@ -0,0 +1,78 @@
+import type { KakaoTalkClient } from './kakaotalk'
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000
+
+export type KakaoAuthorResolver = {
+  resolve: (authorId: string, chatId: string) => Promise<string | null>
+}
+
+export type KakaoAuthorResolverOptions = {
+  client: Pick<KakaoTalkClient, 'getMembers'>
+  now?: () => number
+  ttlMs?: number
+  logger?: { warn: (msg: string) => void }
+}
+
+type ChatCacheEntry = {
+  members: Map<string, string>
+  expiresAt: number
+}
+
+// Resolves author IDs to nicknames via LOCO GETMEM (one call per chat per
+// TTL window). Only invoked when the inline `author_name` from the chat-
+// list snapshot is missing — the agent-messenger client already covers
+// "display members" (~5 per chat) for free, and this resolver fills the
+// gap for larger groups and open chats.
+//
+// Lazy by design: a chat's member list is fetched on the first lookup
+// miss, not eagerly on connect. Most agent folders watch a small handful
+// of chats; prefetching every chat's member list at startup would burn
+// LOCO calls on rooms the agent never sees a message in.
+export function createKakaoAuthorResolver(options: KakaoAuthorResolverOptions): KakaoAuthorResolver {
+  const now = options.now ?? Date.now
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
+  const logger = options.logger
+  const cache = new Map<string, ChatCacheEntry>()
+  const inflight = new Map<string, Promise<ChatCacheEntry | null>>()
+
+  const fetchMembers = (chatId: string): Promise<ChatCacheEntry | null> => {
+    const existing = inflight.get(chatId)
+    if (existing !== undefined) return existing
+    const promise = options.client
+      .getMembers(chatId)
+      .then((members): ChatCacheEntry => {
+        const map = new Map<string, string>()
+        for (const m of members) map.set(m.user_id, m.nickname)
+        const entry: ChatCacheEntry = { members: map, expiresAt: now() + ttlMs }
+        cache.set(chatId, entry)
+        return entry
+      })
+      .catch((err: unknown): null => {
+        // Author resolution is best-effort. Failing here makes the message
+        // render with the raw user_id, which is uglier but still routes.
+        logger?.warn(`[kakaotalk] getMembers(${chatId}) failed: ${describe(err)}`)
+        return null
+      })
+      .finally(() => {
+        inflight.delete(chatId)
+      })
+    inflight.set(chatId, promise)
+    return promise
+  }
+
+  const resolve = async (authorId: string, chatId: string): Promise<string | null> => {
+    const cached = cache.get(chatId)
+    if (cached !== undefined && cached.expiresAt > now()) {
+      return cached.members.get(authorId) ?? null
+    }
+    const fresh = await fetchMembers(chatId)
+    if (fresh === null) return null
+    return fresh.members.get(authorId) ?? null
+  }
+
+  return { resolve }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/adapters/kakaotalk-channel-resolver.ts

@@ -0,0 +1,105 @@
+import { classifyKakaoChat, type KakaoChat, type KakaoChatKind, type KakaoTalkClient } from 'agent-messenger/kakaotalk'
+
+import type { ChannelKey, ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000
+
+export type KakaoWorkspace = '@kakao-dm' | '@kakao-group' | '@kakao-open'
+
+export function kakaoWorkspaceForType(kind: KakaoChatKind): KakaoWorkspace {
+  if (kind === 'dm') return '@kakao-dm'
+  if (kind === 'open') return '@kakao-open'
+  return '@kakao-group'
+}
+
+export type KakaoChatLookupValue = {
+  workspace: KakaoWorkspace
+  isDm: boolean
+}
+
+export type KakaoChannelResolver = {
+  resolve: ChannelNameResolver
+  lookupChat: (chatId: string) => KakaoChatLookupValue | null
+  refresh: () => Promise<void>
+}
+
+export type KakaoChannelResolverOptions = {
+  client: Pick<KakaoTalkClient, 'getChats'>
+  now?: () => number
+  ttlMs?: number
+  logger?: { warn: (msg: string) => void }
+}
+
+type Entry = {
+  workspace: KakaoWorkspace
+  isDm: boolean
+  chatName: string | null
+  expiresAt: number
+}
+
+export function createKakaoChannelResolver(options: KakaoChannelResolverOptions): KakaoChannelResolver {
+  const now = options.now ?? Date.now
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
+  const cache = new Map<string, Entry>()
+  let inflight: Promise<void> | null = null
+
+  const refresh = async (): Promise<void> => {
+    if (inflight !== null) {
+      await inflight
+      return
+    }
+    const promise = loadAll().finally(() => {
+      inflight = null
+    })
+    inflight = promise
+    await promise
+  }
+
+  const loadAll = async (): Promise<void> => {
+    try {
+      const chats = await options.client.getChats({ all: true })
+      const expiresAt = now() + ttlMs
+      for (const chat of chats) ingest(chat, expiresAt)
+    } catch (err) {
+      options.logger?.warn(`[kakaotalk] channel resolver refresh failed: ${describe(err)}`)
+    }
+  }
+
+  const ingest = (chat: KakaoChat, expiresAt: number): void => {
+    const kind = classifyKakaoChat(chat)
+    const workspace = kakaoWorkspaceForType(kind)
+    cache.set(chat.chat_id, {
+      workspace,
+      isDm: kind === 'dm',
+      chatName: chat.title ?? chat.display_name,
+      expiresAt,
+    })
+  }
+
+  const resolve: ChannelNameResolver = async (key: ChannelKey): Promise<ResolvedChannelNames> => {
+    const entry = cache.get(key.chat)
+    if (entry === undefined || entry.expiresAt <= now()) await refresh()
+    const fresh = cache.get(key.chat)
+    if (fresh === undefined) return {}
+    const result: ResolvedChannelNames = {}
+    if (fresh.chatName !== null && fresh.chatName !== '') result.chatName = fresh.chatName
+    return result
+  }
+
+  // Sync lookup. Returns null when the entry is missing OR stale; callers
+  // (e.g. inbound classification, history allow checks) MUST treat null as
+  // "refresh needed", not "unknown forever". The classifier handles this
+  // by awaiting `refresh()` and re-checking before dropping the message —
+  // see kakaotalk.ts handleMessageEvent.
+  const lookupChat = (chatId: string): KakaoChatLookupValue | null => {
+    const entry = cache.get(chatId)
+    if (entry === undefined || entry.expiresAt <= now()) return null
+    return { workspace: entry.workspace, isDm: entry.isDm }
+  }
+
+  return { resolve, lookupChat, refresh }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/adapters/kakaotalk-classify.ts

@@ -0,0 +1,77 @@
+import type { KakaoTalkPushMessageEvent } from 'agent-messenger/kakaotalk'
+
+import { matchesAnyAlias } from '@/channels/engagement'
+import { isAllowed, type ChannelAdapterConfig } from '@/channels/schema'
+import type { InboundMessage } from '@/channels/types'
+
+export type InboundDropReason = 'self_author' | 'empty_text' | 'unknown_chat' | 'not_in_allow_list' | 'pre_connect'
+
+export type InboundClassification =
+  | { kind: 'drop'; reason: InboundDropReason }
+  | { kind: 'route'; payload: InboundMessage }
+
+export type KakaoChatLookup = (chatId: string) => {
+  workspace: '@kakao-dm' | '@kakao-group' | '@kakao-open'
+  isDm: boolean
+} | null
+
+export type KakaoInboundContext = {
+  selfUserId: string | null
+  lookupChat: KakaoChatLookup
+  selfAliases?: readonly string[]
+}
+
+export function classifyInbound(
+  event: KakaoTalkPushMessageEvent,
+  config: ChannelAdapterConfig,
+  context: KakaoInboundContext,
+): InboundClassification {
+  if (context.selfUserId === null) {
+    return { kind: 'drop', reason: 'pre_connect' }
+  }
+  if (String(event.author_id) === context.selfUserId) {
+    return { kind: 'drop', reason: 'self_author' }
+  }
+
+  const text = event.message ?? ''
+  if (text === '') return { kind: 'drop', reason: 'empty_text' }
+
+  const chatInfo = context.lookupChat(event.chat_id)
+  if (chatInfo === null) {
+    return { kind: 'drop', reason: 'unknown_chat' }
+  }
+
+  if (!isAllowed(config.allow, chatInfo.workspace, event.chat_id)) {
+    return { kind: 'drop', reason: 'not_in_allow_list' }
+  }
+
+  // KakaoTalk has no native @-mention syntax in the LOCO protocol that the
+  // SDK exposes (mention rendering happens client-side via display_name
+  // matching). Mention-equivalent engagement comes solely from alias
+  // matching, which the engagement layer treats as equivalent to a direct
+  // mention (see engagement.ts: alias is unconditional and ranks alongside
+  // explicit triggers). Without aliases configured, only `reply` and `dm`
+  // triggers can fire on KakaoTalk.
+  const aliasMatched = matchesAnyAlias(text, context.selfAliases ?? [])
+
+  return {
+    kind: 'route',
+    payload: {
+      adapter: 'kakaotalk',
+      workspace: chatInfo.workspace,
+      chat: event.chat_id,
+      thread: null,
+      text,
+      externalMessageId: event.log_id,
+      authorId: String(event.author_id),
+      authorName: event.author_name ?? String(event.author_id),
+      authorIsBot: false,
+      isBotMention: aliasMatched,
+      replyToBotMessageId: null,
+      mentionsOthers: false,
+      replyToOtherMessageId: null,
+      isDm: chatInfo.isDm,
+      ts: event.sent_at,
+    },
+  }
+}