typeclaw 0.32.1 → 0.34.0

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

@@ -0,0 +1,129 @@
+import type { LineChat, LineClient } from 'agent-messenger/line'
+
+import type { ChannelKey, ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000
+
+// LINE's chat list is fetched in a bounded page; there is no `{ all: true }`
+// equivalent the way KakaoTalk has. This cap is generous for a personal
+// account but keeps the GETCHATS payload bounded.
+const CHAT_FETCH_LIMIT = 500
+
+export type LineWorkspace = '@line-dm' | '@line-group' | '@line-square'
+
+// `user` is a 1:1 DM; `group` and `room` are both multi-party invite chats
+// (LINE's legacy "room" vs modern "group" distinction is immaterial to
+// engagement, so they share a bucket); `square` is an OpenChat-style public
+// community, kept separate because it is the most public surface and least-
+// privilege rules want to target it on its own.
+export function lineWorkspaceForType(type: LineChat['type']): LineWorkspace {
+  if (type === 'user') return '@line-dm'
+  if (type === 'square') return '@line-square'
+  return '@line-group'
+}
+
+export type LineChatLookupValue = {
+  workspace: LineWorkspace
+  isDm: boolean
+}
+
+export type LineChannelResolver = {
+  resolve: ChannelNameResolver
+  lookupChat: (chatId: string) => LineChatLookupValue | null
+  refresh: () => Promise<void>
+  // Register a chat learned from an inbound push event when `refresh()` did
+  // not surface it (a new chat that hasn't propagated to GETCHATS yet).
+  // Provisional entries default to @line-group — the strictest multi-party
+  // bucket — so allow-rule enforcement stays conservative until the next real
+  // refresh upgrades the entry to its authoritative type.
+  ingestProvisional: (chatId: string) => void
+}
+
+export type LineChannelResolverOptions = {
+  client: Pick<LineClient, 'getChats'>
+  now?: () => number
+  ttlMs?: number
+  logger?: { warn: (msg: string) => void }
+}
+
+type Entry = {
+  workspace: LineWorkspace
+  isDm: boolean
+  chatName: string | null
+  expiresAt: number
+}
+
+export function createLineChannelResolver(options: LineChannelResolverOptions): LineChannelResolver {
+  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({ limit: CHAT_FETCH_LIMIT })
+      const expiresAt = now() + ttlMs
+      for (const chat of chats) ingest(chat, expiresAt)
+    } catch (err) {
+      options.logger?.warn(`[line] channel resolver refresh failed: ${describe(err)}`)
+    }
+  }
+
+  const ingest = (chat: LineChat, expiresAt: number): void => {
+    const workspace = lineWorkspaceForType(chat.type)
+    cache.set(chat.chat_id, {
+      workspace,
+      isDm: chat.type === 'user',
+      chatName: chat.display_name === '' ? null : 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 MUST
+  // treat null as "refresh needed", not "unknown forever" — the adapter awaits
+  // refresh() and re-checks before dropping a message as unknown_chat.
+  const lookupChat = (chatId: string): LineChatLookupValue | null => {
+    const entry = cache.get(chatId)
+    if (entry === undefined || entry.expiresAt <= now()) return null
+    return { workspace: entry.workspace, isDm: entry.isDm }
+  }
+
+  const ingestProvisional = (chatId: string): void => {
+    const existing = cache.get(chatId)
+    if (existing !== undefined && existing.expiresAt > now()) return
+    cache.set(chatId, {
+      workspace: '@line-group',
+      isDm: false,
+      chatName: null,
+      expiresAt: now() + ttlMs,
+    })
+  }
+
+  return { resolve, lookupChat, refresh, ingestProvisional }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

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

@@ -0,0 +1,80 @@
+import type { LinePushMessageEvent } from 'agent-messenger/line'
+
+import { matchesAnyAlias } from '@/channels/engagement'
+import type { ChannelAdapterConfig } from '@/channels/schema'
+import type { InboundMessage } from '@/channels/types'
+
+export type InboundDropReason = 'self_author' | 'empty_text' | 'unknown_chat' | 'pre_connect'
+
+export type InboundClassification =
+  | { kind: 'drop'; reason: InboundDropReason }
+  | { kind: 'route'; payload: InboundMessage }
+
+export type LineChatLookup = (chatId: string) => {
+  workspace: '@line-dm' | '@line-group' | '@line-square'
+  isDm: boolean
+} | null
+
+export type LineInboundContext = {
+  selfUserId: string | null
+  lookupChat: LineChatLookup
+  selfAliases?: readonly string[]
+  // LINE push events lack `author_name`, so the adapter resolves it (best
+  // effort) and passes it here; falls back to the raw author id.
+  authorName?: string
+}
+
+export function classifyInbound(
+  event: LinePushMessageEvent,
+  _config: ChannelAdapterConfig,
+  context: LineInboundContext,
+): InboundClassification {
+  if (context.selfUserId === null) {
+    return { kind: 'drop', reason: 'pre_connect' }
+  }
+  if (event.author_id === context.selfUserId) {
+    return { kind: 'drop', reason: 'self_author' }
+  }
+
+  const text = event.text ?? ''
+  if (text === '') return { kind: 'drop', reason: 'empty_text' }
+
+  const chatInfo = context.lookupChat(event.chat_id)
+  if (chatInfo === null) {
+    return { kind: 'drop', reason: 'unknown_chat' }
+  }
+
+  // LINE has no native @-mention the push protocol surfaces. Like KakaoTalk,
+  // mention-equivalent engagement comes solely from plain-text alias matching,
+  // which the engagement layer ranks alongside an explicit mention.
+  const aliasMatched = matchesAnyAlias(text, context.selfAliases ?? [])
+  const authorName = context.authorName ?? event.author_id
+
+  // LINE's `sent_at` is an ISO-ish string (vs KakaoTalk's Unix seconds). The
+  // contract wants ms since epoch; a malformed timestamp degrades to 0
+  // ("unknown") so the formatter omits the time prefix rather than stamping a
+  // wrong clock.
+  const parsed = Date.parse(event.sent_at)
+  const ts = Number.isNaN(parsed) ? 0 : parsed
+
+  return {
+    kind: 'route',
+    payload: {
+      adapter: 'line',
+      workspace: chatInfo.workspace,
+      chat: event.chat_id,
+      thread: null,
+      text,
+      externalMessageId: event.message_id,
+      authorId: event.author_id,
+      authorName,
+      authorIsBot: false,
+      isBotMention: aliasMatched,
+      replyToBotMessageId: null,
+      mentionsOthers: false,
+      replyToOtherMessageId: null,
+      isDm: chatInfo.isDm,
+      ts,
+    },
+  }
+}

package/src/channels/adapters/line-format.ts

@@ -0,0 +1,11 @@
+import { toKakaoPlainText } from './kakaotalk-format'
+
+// LINE chat renders no rich text, exactly like KakaoTalk's LOCO surface:
+// `**bold**`, `### headings`, `| tables |`, and fenced code blocks all show
+// their literal markers. The markdown-stripping rules are identical, so this
+// reuses the KakaoTalk stripper rather than maintaining a second copy that
+// would drift. If LINE ever grows a formatting quirk KakaoTalk lacks, fork the
+// implementation here.
+export function toLinePlainText(input: string): string {
+  return toKakaoPlainText(input)
+}

package/src/channels/adapters/line.ts

@@ -0,0 +1,350 @@
+import {
+  LineClient as RealLineClient,
+  LineListener as RealLineListener,
+  type LineAccountCredentials,
+  type LineChat,
+  type LineConfig,
+  type LineListenerEventMap,
+  type LineMessage,
+  type LineProfile,
+  type LinePushMessageEvent,
+  type LineSendResult,
+} from 'agent-messenger/line'
+
+import type { ChannelRouter } from '@/channels/router'
+import type { ChannelAdapterConfig } from '@/channels/schema'
+import type {
+  ChannelHistoryMessage,
+  FetchHistoryArgs,
+  FetchHistoryResult,
+  HistoryCallback,
+  OutboundCallback,
+  OutboundMessage,
+  ResolvedChannelNames,
+  SendResult,
+} from '@/channels/types'
+
+import { createLineChannelResolver } from './line-channel-resolver'
+import { classifyInbound } from './line-classify'
+import { toLinePlainText } from './line-format'
+
+// Structural duck-type of the upstream LineClient class. Declaring this as an
+// interface (rather than reusing the nominal class type) lets test fakes
+// satisfy the public surface without inheriting the class's private fields.
+// The cast on the const below bridges the runtime class onto this interface.
+export interface LineClient {
+  login(credentials?: LineAccountCredentials): Promise<this>
+  getProfile(): Promise<LineProfile>
+  getChats(options?: { limit?: number }): Promise<LineChat[]>
+  getMessages(chatId: string, options?: { count?: number }): Promise<LineMessage[]>
+  sendMessage(chatId: string, text: string): Promise<LineSendResult>
+  close(): void
+}
+
+export interface LineListener {
+  start(): Promise<void>
+  stop(): void
+  on<K extends keyof LineListenerEventMap>(event: K, listener: (...args: LineListenerEventMap[K]) => void): this
+  off<K extends keyof LineListenerEventMap>(event: K, listener: (...args: LineListenerEventMap[K]) => void): this
+}
+
+export type LineCredentialStore = {
+  load(): Promise<LineConfig>
+  getAccount(id?: string): Promise<LineAccountCredentials | null>
+}
+
+const LineClient = RealLineClient as unknown as new () => LineClient
+const LineListener = RealLineListener as unknown as new (client: LineClient) => LineListener
+
+export type LineAdapterLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+const consoleLogger: LineAdapterLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export type LineAdapterOptions = {
+  router: ChannelRouter
+  configRef: () => ChannelAdapterConfig
+  logger?: LineAdapterLogger
+  selfAliasesRef?: () => readonly string[]
+  credentialsStore?: LineCredentialStore
+  client?: LineClient
+  listenerFactory?: (client: LineClient) => LineListener
+}
+
+export type LineAdapter = {
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  isConnected: () => boolean
+}
+
+export const LINE_HISTORY_LIMIT_MAX = 200
+
+export function createOutboundCallback(deps: {
+  client: Pick<LineClient, 'sendMessage'>
+  logger: LineAdapterLogger
+  formatChannelTag: (workspace: string, chat: string) => Promise<string>
+}): OutboundCallback {
+  const { client, logger, formatChannelTag } = deps
+  return async (msg: OutboundMessage): Promise<SendResult> => {
+    if (msg.adapter !== 'line') {
+      return { ok: false, error: `unknown adapter: ${msg.adapter}` }
+    }
+    // LINE's SDK exposes text sends only — there is no attachment upload
+    // primitive, so an outbound carrying attachments is rejected loudly
+    // rather than silently dropping the files.
+    if (msg.attachments !== undefined && msg.attachments.length > 0) {
+      return { ok: false, error: 'line adapter does not support outbound attachments' }
+    }
+    const text = toLinePlainText(msg.text ?? '')
+    if (text === '') {
+      return { ok: false, error: 'message has no text' }
+    }
+    const tag = await formatChannelTag(msg.workspace, msg.chat)
+    logger.info(`[line] outbound ${tag} text_len=${text.length}`)
+    try {
+      const result = await client.sendMessage(msg.chat, text)
+      if (!result.success) {
+        logger.error(`[line] sendMessage non-success ${tag}`)
+        return { ok: false, error: 'line send failed' }
+      }
+      logger.info(`[line] sent message_id=${result.message_id} ${tag}`)
+    } catch (err) {
+      const message = describe(err)
+      logger.error(`[line] sendMessage failed: ${message}`)
+      return { ok: false, error: message }
+    }
+    return { ok: true }
+  }
+}
+
+export function createLineHistoryCallback(deps: {
+  client: Pick<LineClient, 'getMessages'>
+  logger: LineAdapterLogger
+  selfUserIdRef: () => string | null
+}): HistoryCallback {
+  const { client, logger, selfUserIdRef } = deps
+  return async (args: FetchHistoryArgs): Promise<FetchHistoryResult> => {
+    const limit = clampLimit(args.limit, LINE_HISTORY_LIMIT_MAX)
+    try {
+      const messages = await client.getMessages(args.chat, { count: limit })
+      const selfId = selfUserIdRef()
+      const mapped: ChannelHistoryMessage[] = messages.map((m) => {
+        const parsed = Date.parse(m.sent_at)
+        return {
+          externalMessageId: m.message_id,
+          authorId: m.author_id,
+          authorName: m.author_name ?? m.author_id,
+          text: m.text ?? '',
+          ts: Number.isNaN(parsed) ? 0 : parsed,
+          isBot: selfId !== null && m.author_id === selfId,
+          replyToBotMessageId: null,
+        }
+      })
+      return { ok: true, messages: mapped }
+    } catch (err) {
+      const message = describe(err)
+      logger.warn(`[line] history fetch failed: ${message}`)
+      return { ok: false, error: message }
+    }
+  }
+}
+
+function clampLimit(requested: number, max: number): number {
+  if (!Number.isFinite(requested) || requested <= 0) return max
+  return Math.min(Math.floor(requested), max)
+}
+
+export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
+  const logger = options.logger ?? consoleLogger
+  const client = options.client ?? new LineClient()
+  let listener: LineListener | null = null
+  let selfUserId: string | null = null
+  let connected = false
+  let started = false
+  let inflightInbounds = 0
+  let stopWaiters: Array<() => void> = []
+
+  const channelResolver = createLineChannelResolver({ client, logger })
+
+  const formatChannelTag = async (workspace: string, chat: string): Promise<string> => {
+    const names = await channelResolver
+      .resolve({ adapter: 'line', workspace, chat, thread: null })
+      .catch(() => ({}) as ResolvedChannelNames)
+    return `bucket=${workspace} chat=${formatLabel(names.chatName, chat)}`
+  }
+
+  const historyCallback = createLineHistoryCallback({
+    client,
+    logger,
+    selfUserIdRef: () => selfUserId,
+  })
+
+  const outboundCallback = createOutboundCallback({ client, logger, formatChannelTag })
+
+  const processInbound = async (event: LinePushMessageEvent): Promise<void> => {
+    inflightInbounds++
+    try {
+      if (channelResolver.lookupChat(event.chat_id) === null) {
+        await channelResolver.refresh()
+        if (channelResolver.lookupChat(event.chat_id) === null) {
+          // The push event itself proves the chat exists even when GETCHATS
+          // hasn't surfaced it yet. Register a provisional @line-group entry
+          // (the strictest multi-party bucket) so the message is not silently
+          // dropped as unknown_chat; the next refresh upgrades it.
+          channelResolver.ingestProvisional(event.chat_id)
+          logger.warn(
+            `[line] provisional chat=${event.chat_id} message_id=${event.message_id} bucket=@line-group reason=not_in_getchats`,
+          )
+        }
+      }
+
+      const bucket = channelResolver.lookupChat(event.chat_id)?.workspace ?? '@line-group'
+      const inboundTag = await formatChannelTag(bucket, event.chat_id)
+      logger.info(
+        `[line] inbound message_id=${event.message_id} author=${event.author_id} ${inboundTag} text_len=${(event.text ?? '').length}`,
+      )
+
+      const verdict = classifyInbound(event, options.configRef(), {
+        selfUserId,
+        lookupChat: (id) => channelResolver.lookupChat(id),
+        ...(options.selfAliasesRef ? { selfAliases: options.selfAliasesRef() } : {}),
+      })
+      if (verdict.kind === 'drop') {
+        logger.info(`[line] dropped message_id=${event.message_id} reason=${verdict.reason}`)
+        return
+      }
+
+      logger.info(
+        `[line] routed message_id=${event.message_id} ${inboundTag} mention=${verdict.payload.isBotMention} dm=${verdict.payload.isDm}`,
+      )
+      await options.router.route(verdict.payload)
+    } catch (err) {
+      logger.error(`[line] handleInbound failed: ${describe(err)}`)
+    } finally {
+      inflightInbounds--
+      if (inflightInbounds === 0 && stopWaiters.length > 0) {
+        const waiters = stopWaiters
+        stopWaiters = []
+        for (const w of waiters) w()
+      }
+    }
+  }
+
+  return {
+    async start(): Promise<void> {
+      if (started) return
+      started = true
+      try {
+        const credentialStore = options.credentialsStore ?? null
+        if (credentialStore !== null) {
+          const account = await credentialStore.getAccount()
+          if (account === null) {
+            throw new Error('no LINE account in secrets.json#channels.line (run typeclaw init to authenticate)')
+          }
+          await client.login(account)
+        } else {
+          await client.login()
+        }
+      } catch (err) {
+        started = false
+        logger.error(`[line] login failed: ${describe(err)}`)
+        throw err
+      }
+
+      try {
+        const profile = await client.getProfile()
+        selfUserId = profile.mid
+        logger.info(`[line] authenticated as ${profile.display_name || profile.mid} (${profile.mid})`)
+      } catch (err) {
+        started = false
+        logger.error(`[line] getProfile failed: ${describe(err)}`)
+        throw err
+      }
+
+      try {
+        await channelResolver.refresh()
+      } catch (err) {
+        logger.warn(`[line] initial chat list fetch failed: ${describe(err)}`)
+      }
+
+      listener = options.listenerFactory ? options.listenerFactory(client) : new LineListener(client)
+      listener.on('connected', (info) => {
+        connected = true
+        logger.info(`[line] connected (account_id=${info.account_id})`)
+      })
+      listener.on('disconnected', () => {
+        connected = false
+        logger.warn('[line] disconnected; SDK will reconnect with backoff')
+      })
+      listener.on('error', (err) => {
+        logger.error(`[line] listener error: ${describe(err)}`)
+      })
+      listener.on('message', (event) => {
+        void processInbound(event)
+      })
+
+      try {
+        await listener.start()
+      } catch (err) {
+        try {
+          listener.stop()
+        } catch {
+          // best-effort cleanup; the start failure is what we surface
+        }
+        listener = null
+        started = false
+        logger.error(`[line] listener start failed: ${describe(err)}`)
+        throw err
+      }
+
+      // Registration happens AFTER listener.start() resolves so a start
+      // failure cannot leave the router pointing at callbacks for a
+      // half-initialized adapter. stop() unregisters in inverse order.
+      options.router.registerOutbound('line', outboundCallback)
+      options.router.registerChannelNameResolver('line', channelResolver.resolve)
+      options.router.registerHistory('line', historyCallback)
+    },
+
+    async stop(): Promise<void> {
+      if (!started) return
+      started = false
+      options.router.unregisterOutbound('line', outboundCallback)
+      options.router.unregisterChannelNameResolver('line', channelResolver.resolve)
+      options.router.unregisterHistory('line', historyCallback)
+      if (inflightInbounds > 0) {
+        await new Promise<void>((resolve) => {
+          stopWaiters.push(resolve)
+        })
+      }
+      listener?.stop()
+      listener = null
+      try {
+        client.close()
+      } catch {
+        // close() throwing on a half-initialized client is benign.
+      }
+      selfUserId = null
+      connected = false
+    },
+
+    isConnected(): boolean {
+      return connected && selfUserId !== null
+    },
+  }
+}
+
+function formatLabel(name: string | undefined, id: string): string {
+  if (name === undefined || name === '' || name === id) return id
+  return `${name}(${id})`
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/engagement.ts

@@ -37,8 +37,10 @@ export class StickyLedger {
     return expiresAt !== undefined && expiresAt > now
   }
 
-  clear(key: string): void {
+  clear(key: string): number {
+    const cleared = this.byKey.get(key)?.size ?? 0
     this.byKey.delete(key)
+    return cleared
   }
 }
 
@@ -60,7 +62,7 @@ export type EngagementInput = {
   // once. Empty list means alias-based engagement is off — useful for
   // tests and for agents that explicitly want strict-mention behavior.
   // Match semantics: case-insensitive substring of inbound text. This is
-  // the operator contract documented in typeclaw-config; if a name is too
+  // the operator contract documented in typeclaw-channels; if a name is too
   // generic ("bot", "ai") it WILL produce false matches and the operator
   // owns curation.
   selfAliases: readonly string[]