typeclaw 0.12.0 → 0.13.0

package/src/bundled-plugins/reviewer/skills/general.ts

@@ -0,0 +1,68 @@
+import type { LoadableSkill } from '@/plugin'
+
+export const GENERAL_REVIEW_SKILL_NAME = 'general'
+
+export const GENERAL_REVIEW_SKILL_DESCRIPTION =
+  'Fallback for review targets that do not fit a specific domain skill: a written argument, a proposal, a draft, a mixed-format artifact. Apply the universal review philosophy without domain-specific shortcuts.'
+
+export const GENERAL_REVIEW_SKILL_CONTENT = `# general
+
+You have been asked to review something that does not clearly fit a specific domain skill (not a code PR, not a plan, not a design doc, not docs — or it is a mix). Apply the universal review philosophy on top of the reviewer's neutral output contract.
+
+## How to acquire the target
+
+- **A URL** — \`webfetch\` it. If it is a private resource the fetch cannot reach, say so in \`<summary>\` and review what was provided in the payload.
+- **A file path** — \`read\` it. \`ls\` the parent directory if siblings might be relevant.
+- **Inline text in the payload** — read the payload carefully; quote from it when forming evidence.
+- **A reference to something the caller has** — ask the caller to provide it. Return a single \`blocker\` finding describing what you need and a \`comment\` verdict.
+
+## How to read carefully
+
+A general review is the hardest because there are no domain shortcuts. Replace shortcuts with discipline:
+
+1. **State the target's purpose in your own words.** What is the artifact trying to achieve? Who is it for? Put this in \`<summary>\`. If you cannot state it after reading, that itself is a finding — the artifact does not communicate its purpose.
+2. **Identify the load-bearing claims.** What does the artifact assert that, if wrong, would invalidate the whole thing? List them mentally before looking for issues.
+3. **Stress-test the load-bearing claims.** For each one: is the evidence sufficient? Are the assumptions stated? Are the counter-arguments addressed?
+4. **Stress-test the boundaries.** Where does the artifact's argument or design stop applying? Does it acknowledge that boundary, or does it overgeneralize?
+5. **Stress-test the audience fit.** Will the intended reader understand it? Is the prerequisite knowledge stated? Are the unstated assumptions reasonable for that audience?
+
+## What to look for
+
+- **Internal contradiction.** Two statements that cannot both be true. The artifact must reconcile them or pick one.
+- **Unsupported claims.** Any assertion the artifact relies on but does not justify. The author may have a reason — say so and ask, do not assume incompetence.
+- **Hidden assumptions.** Things the argument quietly requires to be true but does not state. These are the most common failure mode in general writing.
+- **Missing alternatives.** If the artifact recommends X, did it explain why not Y? A serious proposal acknowledges the alternatives it rejected.
+- **Scope drift.** The artifact promises to cover A but spends half its bytes on B. Either the scope is wrong or the title is wrong.
+- **Verifiability.** If the artifact claims success criteria, are they measurable? "Better performance" with no metric is unverifiable.
+- **Logical structure.** Premises → reasoning → conclusion. Where the chain breaks, point at the break.
+
+## What NOT to find
+
+- **Stylistic preferences.** Sentence rhythm, word choice variation, paragraph length. Skip unless they actively impede understanding.
+- **Re-summarizing the artifact as a finding.** "This document discusses X" is not a review.
+- **Generic feedback.** "Could be clearer" without pointing at a specific passage is noise.
+- **Disagreements that are taste, not error.** If the author chose path A and you would have chosen B, that is not a finding unless A is actually worse for a stated reason.
+
+## Severity hints
+
+- **blocker** — A logical break, a fatal contradiction, a load-bearing claim that is verifiably false, an audience-fit problem so severe the intended reader cannot use the artifact.
+- **concern** — An unsupported claim that needs justification, a missing alternative that weakens the recommendation, a scope ambiguity that will mislead readers.
+- **nit** — A small clarity issue, a passage that could be tightened, a minor inconsistency.
+- **praise** — A non-obvious insight, a tricky trade-off well-handled, a passage that earns the reader's trust. Rare.
+
+## Verdict mapping
+
+- **approve** — No blockers. The artifact stands on its own.
+- **request-changes** — At least one blocker.
+- **comment** — Useful observations without a clean accept/reject. Common for early drafts, exploratory documents, or partial reviews.
+
+## Final output
+
+Return findings inside the reviewer's neutral \`<review>\` block. Do NOT invent your own output format.
+`
+
+export const GENERAL_REVIEW_SKILL: LoadableSkill = {
+  name: GENERAL_REVIEW_SKILL_NAME,
+  description: GENERAL_REVIEW_SKILL_DESCRIPTION,
+  content: GENERAL_REVIEW_SKILL_CONTENT,
+}

package/src/channels/adapters/discord-bot-classify.ts

@@ -6,7 +6,7 @@ import type {
 } from 'agent-messenger/discordbot'
 
 import type { ChannelAdapterConfig } from '@/channels/schema'
-import type { InboundMessage } from '@/channels/types'
+import type { InboundAttachment, InboundMessage } from '@/channels/types'
 
 export type InboundDropReason =
   | 'self_author' // event.author.id === botUserId; we never route our own messages back to ourselves
@@ -35,7 +35,7 @@ export function classifyInbound(
   if (botUserId !== null && event.author.id === botUserId) {
     return { kind: 'drop', reason: 'self_author' }
   }
-  const text = inboundText(event)
+  const { text, attachments } = splitInbound(event)
   if (text === '') return { kind: 'drop', reason: 'empty_content' }
 
   const isDm = event.guild_id === undefined
@@ -80,6 +80,7 @@ export function classifyInbound(
       chat: event.channel_id,
       thread: null,
       text,
+      ...(attachments.length > 0 ? { attachments } : {}),
       externalMessageId: event.id,
       authorId: event.author.id,
       // Discord's post-2023 username system allows pure-numeric handles (e.g.
@@ -107,38 +108,45 @@ function isReplyToBot(event: DiscordGatewayMessageCreateEvent, botUserId: string
   return (event.mentions ?? []).some((m) => m.id === botUserId)
 }
 
-function inboundText(event: DiscordGatewayMessageCreateEvent): string {
-  const mediaSummary = summarizeDiscordMedia(event)
-  if (mediaSummary.length === 0) return event.content
-  const summary = `[Discord message with ${mediaSummary.join('; ')}]`
-  return event.content === '' ? summary : `${event.content}\n${summary}`
+type SplitInbound = { text: string; attachments: InboundAttachment[] }
+
+function splitInbound(event: DiscordGatewayMessageCreateEvent): SplitInbound {
+  const attachments = describeDiscordMedia(event)
+  if (attachments.length === 0) return { text: event.content, attachments: [] }
+  const summary = attachments.map(renderPlaceholder).join('\n')
+  const text = event.content === '' ? summary : `${event.content}\n${summary}`
+  return { text, attachments }
 }
 
-function summarizeDiscordMedia(event: DiscordGatewayMessageCreateEvent): string[] {
+function describeDiscordMedia(event: DiscordGatewayMessageCreateEvent): InboundAttachment[] {
   return [
-    ...(event.attachments ?? []).map(summarizeAttachment),
-    ...(event.embeds ?? []).map(summarizeEmbed),
-    ...(event.sticker_items ?? []).map(summarizeSticker),
-  ]
+    ...(event.attachments ?? []).map(describeAttachment),
+    ...(event.embeds ?? []).map(describeEmbed),
+    ...(event.sticker_items ?? []).map(describeSticker),
+  ].map((attachment, index) => ({ ...attachment, id: index + 1 }))
 }
 
-function summarizeAttachment(attachment: DiscordFile): string {
-  return compactJoin(' ', [
-    `attachment: ${attachment.filename}`,
-    attachment.content_type === undefined ? undefined : `(${attachment.content_type})`,
-    attachment.url,
-  ])
+function describeAttachment(attachment: DiscordFile): Omit<InboundAttachment, 'id'> {
+  return {
+    kind: 'file',
+    ref: attachment.url,
+    filename: attachment.filename,
+    ...(attachment.content_type !== undefined ? { mimetype: attachment.content_type } : {}),
+  }
 }
 
-function summarizeEmbed(embed: DiscordGatewayEmbed): string {
+function describeEmbed(embed: DiscordGatewayEmbed): Omit<InboundAttachment, 'id'> {
   const label = embed.title ?? embed.description ?? embed.url ?? embed.type ?? 'embed'
-  return compactJoin(' ', ['embed:', label, embed.url !== undefined && embed.url !== label ? embed.url : undefined])
+  return { kind: 'embed', ref: embed.url ?? '', filename: label }
 }
 
-function summarizeSticker(sticker: DiscordGatewayStickerItem): string {
-  return `sticker: ${sticker.name}`
+function describeSticker(sticker: DiscordGatewayStickerItem): Omit<InboundAttachment, 'id'> {
+  return { kind: 'sticker', ref: '', filename: sticker.name }
 }
 
-function compactJoin(separator: string, parts: Array<string | undefined>): string {
-  return parts.filter((part) => part !== undefined && part !== '').join(separator)
+function renderPlaceholder(attachment: InboundAttachment): string {
+  const parts: string[] = [`Discord attachment #${attachment.id}: ${attachment.kind}`]
+  if (attachment.mimetype !== undefined) parts.push(attachment.mimetype)
+  if (attachment.filename !== undefined) parts.push(`name=${attachment.filename}`)
+  return `[${parts.join(' ')}]`
 }

package/src/channels/adapters/github/inbound.ts

@@ -44,11 +44,17 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     if (!isGithubEventAllowed(options.allowlist(), event, action)) return ok()
 
     const selfId = options.selfId()
+    const selfLogin = options.selfLogin()
     const author = readAuthor(payload)
-    if (selfId !== null && author !== null && String(author.id) === selfId) return ok()
+    if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
+      options.logger.info(
+        `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
+      )
+      return ok()
+    }
 
     const teamIsBotMember = await resolveTeamMembership(event, payload, options)
-    const classified = classifyGithubInbound(event, payload, options.selfLogin(), {
+    const classified = classifyGithubInbound(event, payload, selfLogin, {
       teamIsBotMember,
     })
     if (classified === null) return ok()
@@ -366,6 +372,17 @@ function readAuthor(payload: Record<string, unknown>): GithubUser | null {
   return null
 }
 
+// Matches by id OR login. Issue #452 captured a self-responding loop where
+// the id-only guard didn't fire and the bot replied to its own comments ~8
+// times in a row. Login is the second line of defense and aligns with the
+// slack/discord/telegram/kakaotalk adapters, which all drop self-authored
+// events at the classifier layer.
+function isSelfAuthor(author: GithubUser, selfId: string | null, selfLogin: string | null): boolean {
+  if (selfId !== null && String(author.id) === selfId) return true
+  if (selfLogin !== null && author.login === selfLogin) return true
+  return false
+}
+
 type GithubUser = { login: string; id: number; type?: string }
 
 function readUser(value: unknown): GithubUser | null {

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

@@ -7,79 +7,84 @@ import {
   type KakaoTalkPushMessageEvent,
 } from 'agent-messenger/kakaotalk'
 
-// agent-messenger 2.15.0 added two inbound surfaces that 2.14.1 hid from
-// the adapter: `KakaoTalkPushMessageEvent.attachment` (photos, files, etc.)
-// and a separate `emoticon` listener event for stickers. The SDK leaves
-// the `attachment` Record opaque on purpose ("treat it as opaque and
-// narrow per `type`", docs/sdk/kakaotalk.mdx). For photos (type=2) the
-// keys are documented (`k`, `w`, `h`, `mt`, `url`). For everything else
-// (video, audio, voice, file, contact, multi-photo, ...) the SDK has
-// neither test fixtures nor field documentation, so we fall back to a
-// generic JSON-keys preview that still gives the agent something useful
-// to reason about.
+import type { InboundAttachment } from '@/channels/types'
+
+// Splits an inbound KakaoTalk event into (text, attachments[]). Text is
+// what the agent sees in its prompt; attachments[] carries the fetchable
+// `ref` (URL or file id) plus safe-to-print metadata that the router uses
+// to resolve `channel_fetch_attachment` / `look_at` calls by `attachment_id`.
 //
-// The synthesized text follows the same `[KakaoTalk message with ...]`
-// convention used by Slack/Discord/Telegram inbound classifiers, so the
-// agent sees a consistent placeholder shape across platforms.
-
-// Non-text inputs that the adapter accepts. We use a thin shared shape
-// rather than the SDK's union so the same formatter can serve both push
-// events (no `attachment` on emoticon events — emoticon fields live on
-// the event itself) and history messages.
+// The placeholder rendered into text is intentionally REF-FREE. Past
+// regressions where the agent pasted a malformed ref (a bare KakaoCDN
+// `k` key, an expired pre-signed URL, the wrong dialect across adapters)
+// all stemmed from welding the ref into the prompt text. Keeping the ref
+// out of the LLM's view means there is exactly ONE way to fetch an
+// attachment — by its in-turn id — and the router validates that id
+// against the actual inbounds, blocking hallucinated attachments by
+// construction.
+
 type InboundLike = {
   message: string
   message_type: number
   attachment: Record<string, unknown> | null
 }
 
-export function formatInboundText(event: InboundLike): string {
+export type SplitInbound = {
+  text: string
+  attachments: InboundAttachment[]
+}
+
+export function splitInbound(event: InboundLike, startId = 1): SplitInbound {
   const rawText = event.message ?? ''
-  const summary = summarizeAttachment(event)
-  if (summary === null) return rawText
-  const wrapped = `[KakaoTalk message with ${summary}]`
-  return rawText === '' ? wrapped : `${rawText}\n${wrapped}`
-}
-
-// Synthesizes the displayed text for a sticker / emoticon event. Stickers
-// have no `message` field on the push event — the SDK extracts `pack_id`
-// and `sticker_path` from the LOCO attachment for us, so we render those
-// directly into the placeholder. Matches Discord's `sticker: name` shape
-// (src/channels/adapters/discord-bot-classify.ts) but adds Kakao-specific
-// fields the agent can use to disambiguate which sticker the user sent.
-export function formatEmoticonText(
+  const attachment = describeAttachment(event)
+  if (attachment === null) return { text: rawText, attachments: [] }
+
+  const id = startId
+  const placeholder = renderPlaceholder(id, attachment)
+  const text = rawText === '' ? placeholder : `${rawText}\n${placeholder}`
+  return { text, attachments: [{ ...attachment, id }] }
+}
+
+export function splitEmoticonInbound(
   event: Pick<KakaoTalkPushEmoticonEvent, 'emoticon_kind' | 'pack_id' | 'sticker_path'>,
-): string {
-  return `[KakaoTalk message with ${summarizeEmoticon(event)}]`
+  startId = 1,
+): SplitInbound {
+  const id = startId
+  const attachment = describeEmoticon(event, id)
+  const placeholder = renderPlaceholder(id, attachment)
+  return { text: placeholder, attachments: [attachment] }
 }
 
-function summarizeAttachment(event: InboundLike): string | null {
-  // Narrow to message types we know how to render. Anything else (system
-  // events, deleted messages, future LOCO control packets that the SDK
-  // surfaces as MSG with empty text) intentionally falls through to a
-  // null summary so classifyInbound's empty_text drop fires and the
-  // agent isn't woken up by phantom `[KakaoTalk message with type=N]`
-  // placeholders for noise.
+export function splitHistoryInbound(message: KakaoMessage, startId = 1): SplitInbound {
+  return splitInbound(
+    {
+      message: message.message,
+      message_type: message.type,
+      attachment: message.attachment,
+    },
+    startId,
+  )
+}
+
+type DescribedAttachment = Omit<InboundAttachment, 'id'>
+
+function describeAttachment(event: InboundLike): DescribedAttachment | null {
   switch (event.message_type) {
     case KAKAO_MESSAGE_TYPE.TEXT:
       return null
     case KAKAO_MESSAGE_TYPE.PHOTO:
-      return summarizePhoto(event.attachment)
+      return describePhoto(event.attachment)
     case KAKAO_MESSAGE_TYPE.VIDEO:
-      return summarizeGeneric('video', event.attachment)
+      return describeGeneric('video', event.attachment)
     case KAKAO_MESSAGE_TYPE.AUDIO:
-      return summarizeGeneric('audio', event.attachment)
+      return describeGeneric('audio', event.attachment)
     case KAKAO_MESSAGE_TYPE.FILE:
-      return summarizeFile(event.attachment)
+      return describeFile(event.attachment)
     case KAKAO_MESSAGE_TYPE.MULTIPHOTO:
-      return summarizeGeneric('multiphoto', event.attachment)
+      return describeGeneric('multiphoto', event.attachment)
     default:
-      // Emoticon types route through the dedicated emoticon event before
-      // they reach this function, but a history fetch can still return
-      // them as plain KakaoMessage rows. Render them with the same
-      // sticker shape so chronology is consistent across live and
-      // history paths.
       if (isEmoticonType(event.message_type)) {
-        return summarizeHistoricalEmoticon(event.message_type, event.attachment)
+        return describeHistoricalEmoticon(event.message_type, event.attachment)
       }
       return null
   }
@@ -89,86 +94,105 @@ function isEmoticonType(type: number): boolean {
   return type in KAKAO_EMOTICON_KIND_BY_TYPE
 }
 
-function summarizePhoto(attachment: Record<string, unknown> | null): string {
-  if (attachment === null) return 'photo'
-  const parts = ['photo']
+function describePhoto(attachment: Record<string, unknown> | null): DescribedAttachment {
+  const base: DescribedAttachment = { kind: 'photo', ref: '' }
+  if (attachment === null) return base
   const width = numericField(attachment, 'w')
   const height = numericField(attachment, 'h')
-  if (width !== null && height !== null) parts.push(`${width}x${height}`)
   const mime = stringField(attachment, 'mt')
-  if (mime !== null) parts.push(`(${mime})`)
-  // Prefer the public URL over the CDN key — the URL is dereferenceable,
-  // the key is an internal CDN path. Either is acceptable as a `ref` if
-  // we ever wire fetchAttachment for photos.
-  const url = stringField(attachment, 'url') ?? stringField(attachment, 'k')
-  if (url !== null) parts.push(url)
-  return parts.join(' ')
-}
-
-function summarizeFile(attachment: Record<string, unknown> | null): string {
-  if (attachment === null) return 'file'
-  const parts = ['file']
-  // File attachments are not documented by the SDK; these field names are
-  // best-effort common keys (`name`, `size`, `mt`, `url`) used by similar
-  // protocols. If a key is absent we just omit it rather than fabricating
-  // a value.
+  // Prefer the public pre-signed URL; fall back to the CDN key only as a
+  // diagnostic hint in metadata, NEVER as `ref`. The bare key is not a
+  // valid HTTPS URL and historically caused agents to call
+  // channel_fetch_attachment with a malformed string. Without a real URL,
+  // the agent will still see the placeholder ("a photo arrived") and can
+  // ask the user to re-share if needed.
+  const url = stringField(attachment, 'url')
+  const out: DescribedAttachment = {
+    ...base,
+    ref: url ?? '',
+    ...(mime !== null ? { mimetype: mime } : {}),
+    ...(width !== null ? { width } : {}),
+    ...(height !== null ? { height } : {}),
+  }
+  return out
+}
+
+function describeFile(attachment: Record<string, unknown> | null): DescribedAttachment {
+  const base: DescribedAttachment = { kind: 'file', ref: '' }
+  if (attachment === null) return base
   const name = stringField(attachment, 'name')
-  if (name !== null) parts.push(name)
   const mime = stringField(attachment, 'mt')
-  if (mime !== null) parts.push(`(${mime})`)
   const size = numericField(attachment, 'size') ?? numericField(attachment, 's')
-  if (size !== null) parts.push(`size=${size}`)
-  const url = stringField(attachment, 'url')
-  if (url !== null) parts.push(url)
-  return parts.length === 1 ? `file ${attachmentKeysSummary(attachment)}` : parts.join(' ')
-}
-
-function summarizeGeneric(label: string, attachment: Record<string, unknown> | null): string {
-  if (attachment === null) return label
-  // Prefer a dereferenceable URL over a keys-only preview: the agent uses
-  // the URL as the `ref` for channel_fetch_attachment, so making it visible
-  // in the placeholder is what turns video/audio/multiphoto from
-  // "described" into "fetchable". When the SDK hands us an opaque payload
-  // with no `url` (the documented case for these types), fall back to
-  // listing the available keys so we never lie about what arrived.
   const url = stringField(attachment, 'url')
-  if (url !== null) return `${label} (${attachmentKeysSummary(attachment)}) ${url}`
-  return `${label} ${attachmentKeysSummary(attachment)}`
+  return {
+    ...base,
+    ref: url ?? '',
+    ...(name !== null ? { filename: name } : {}),
+    ...(mime !== null ? { mimetype: mime } : {}),
+    ...(size !== null ? { sizeBytes: size } : {}),
+  }
 }
 
-// Last-resort renderer: list the attachment's keys so the agent at least
-// knows what shape the payload had. We deliberately do NOT dump values —
-// some attachment payloads contain long base64 strings or large URLs that
-// would blow the agent's context window if pasted whole.
-function attachmentKeysSummary(attachment: Record<string, unknown>): string {
-  const keys = Object.keys(attachment).sort()
-  if (keys.length === 0) return '(empty)'
-  return `keys=[${keys.join(',')}]`
+function describeGeneric(
+  kind: 'video' | 'audio' | 'multiphoto',
+  attachment: Record<string, unknown> | null,
+): DescribedAttachment {
+  const base: DescribedAttachment = { kind, ref: '' }
+  if (attachment === null) return base
+  const url = stringField(attachment, 'url')
+  const mime = stringField(attachment, 'mt')
+  return {
+    ...base,
+    ref: url ?? '',
+    ...(mime !== null ? { mimetype: mime } : {}),
+  }
 }
 
-function summarizeEmoticon(
+function describeEmoticon(
   event: Pick<KakaoTalkPushEmoticonEvent, 'emoticon_kind' | 'pack_id' | 'sticker_path'>,
-): string {
-  const parts = [`sticker (${event.emoticon_kind})`]
-  if (event.pack_id !== null) parts.push(`pack=${event.pack_id}`)
-  if (event.sticker_path !== null) parts.push(`path=${event.sticker_path}`)
-  return parts.join(' ')
+  id: number,
+): InboundAttachment {
+  // Stickers have no fetchable ref in the LOCO push payload; they are
+  // rendered client-side from `pack_id` + `sticker_path` against a
+  // packaged sprite set. Surface those as filename so the placeholder is
+  // informative, and leave `ref` empty — channel_fetch_attachment will
+  // refuse the lookup and tell the agent the sticker is unfetchable.
+  const filename =
+    event.sticker_path !== null && event.sticker_path !== '' ? event.sticker_path : `sticker-${event.emoticon_kind}`
+  return {
+    id,
+    kind: 'sticker',
+    ref: '',
+    filename,
+  }
 }
 
-function summarizeHistoricalEmoticon(messageType: number, attachment: Record<string, unknown> | null): string {
+function describeHistoricalEmoticon(
+  messageType: number,
+  attachment: Record<string, unknown> | null,
+): DescribedAttachment {
   const kind: KakaoEmoticonKind | undefined =
     KAKAO_EMOTICON_KIND_BY_TYPE[messageType as keyof typeof KAKAO_EMOTICON_KIND_BY_TYPE]
-  const parts = [`sticker (${kind ?? `type=${messageType}`})`]
+  let filename: string | null = null
   if (attachment !== null) {
-    const path = stringField(attachment, 'path') ?? stringField(attachment, 'emoticonItemPath')
-    if (path !== null) {
-      const dotIndex = path.indexOf('.')
-      const head = dotIndex > 0 ? path.slice(0, dotIndex) : null
-      if (head !== null && /^\d+$/.test(head)) parts.push(`pack=${head}`)
-      parts.push(`path=${path}`)
-    }
+    filename = stringField(attachment, 'path') ?? stringField(attachment, 'emoticonItemPath')
+  }
+  return {
+    kind: 'sticker',
+    ref: '',
+    ...(filename !== null ? { filename } : { filename: kind ?? `sticker-${messageType}` }),
   }
-  return parts.join(' ')
+}
+
+function renderPlaceholder(id: number, attachment: DescribedAttachment | InboundAttachment): string {
+  const parts: string[] = [`KakaoTalk attachment #${id}: ${attachment.kind}`]
+  if (attachment.width !== undefined && attachment.height !== undefined) {
+    parts.push(`${attachment.width}x${attachment.height}`)
+  }
+  if (attachment.mimetype !== undefined) parts.push(attachment.mimetype)
+  if (attachment.filename !== undefined) parts.push(`name=${attachment.filename}`)
+  if (attachment.sizeBytes !== undefined) parts.push(`size=${attachment.sizeBytes}`)
+  return `[${parts.join(' ')}]`
 }
 
 function stringField(record: Record<string, unknown>, key: string): string | null {
@@ -181,34 +205,17 @@ function numericField(record: Record<string, unknown>, key: string): number | nu
   return typeof value === 'number' && Number.isFinite(value) ? value : null
 }
 
-// Wraps a KakaoTalk emoticon push event into the MSG-shaped payload that
-// `classifyInbound` expects. We synthesize `message` from the sticker
-// metadata so the classifier's empty-text drop doesn't fire on stickers,
-// and we carry the original message_type through so a later code path
-// can still distinguish stickers from text if needed.
 export function emoticonEventToMessageEvent(event: KakaoTalkPushEmoticonEvent): KakaoTalkPushMessageEvent {
+  const { text } = splitEmoticonInbound(event)
   return {
     type: 'MSG',
     chat_id: event.chat_id,
     log_id: event.log_id,
     author_id: event.author_id,
     author_name: event.author_name,
-    message: formatEmoticonText(event),
+    message: text,
     message_type: event.message_type,
     attachment: null,
     sent_at: event.sent_at,
   }
 }
-
-// Helper used by the history callback to convert a KakaoMessage (which
-// shares the same `attachment` shape as the push event) into displayable
-// text. Kept separate from `formatInboundText` so the live and history
-// paths can evolve independently — e.g. history may eventually surface
-// thumbnails or extra fields the push event doesn't carry.
-export function formatHistoryText(message: KakaoMessage): string {
-  return formatInboundText({
-    message: message.message,
-    message_type: message.type,
-    attachment: message.attachment,
-  })
-}

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

@@ -2,7 +2,7 @@ import type { KakaoTalkPushMessageEvent } from 'agent-messenger/kakaotalk'
 
 import { matchesAnyAlias } from '@/channels/engagement'
 import type { ChannelAdapterConfig } from '@/channels/schema'
-import type { InboundMessage } from '@/channels/types'
+import type { InboundAttachment, InboundMessage } from '@/channels/types'
 
 export type InboundDropReason = 'self_author' | 'empty_text' | 'unknown_chat' | 'pre_connect' | 'bot_message'
 
@@ -28,6 +28,10 @@ export type KakaoInboundContext = {
   selfUserId: string | null
   lookupChat: KakaoChatLookup
   selfAliases?: readonly string[]
+  // The adapter splits attachment refs out of prompt-visible text before
+  // classification. Keeping them on context makes classifyInbound's payload
+  // construction the single place that stamps InboundMessage fields.
+  attachments?: readonly InboundAttachment[]
 }
 
 export function classifyInbound(
@@ -70,6 +74,9 @@ export function classifyInbound(
       chat: event.chat_id,
       thread: null,
       text,
+      ...(context.attachments !== undefined && context.attachments.length > 0
+        ? { attachments: context.attachments }
+        : {}),
       externalMessageId: event.log_id,
       authorId: String(event.author_id),
       authorName: event.author_name ?? String(event.author_id),