typeclaw 0.12.0 → 0.14.0

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),

package/src/channels/adapters/kakaotalk.ts

@@ -26,9 +26,15 @@ import type {
   OutboundMessage,
   ResolvedChannelNames,
   SendResult,
+  InboundAttachment,
 } from '@/channels/types'
 
-import { emoticonEventToMessageEvent, formatHistoryText, formatInboundText } from './kakaotalk-attachment'
+import {
+  emoticonEventToMessageEvent,
+  splitEmoticonInbound,
+  splitHistoryInbound,
+  splitInbound,
+} from './kakaotalk-attachment'
 import { createKakaoAuthorResolver, type KakaoAuthorResolver } from './kakaotalk-author-resolver'
 import { createKakaoChannelResolver, type KakaoChannelResolver } from './kakaotalk-channel-resolver'
 import { classifyInbound, type InboundDropReason } from './kakaotalk-classify'
@@ -252,11 +258,13 @@ export function createKakaoHistoryCallback(deps: {
         messages.map(async (m) => {
           const authorId = String(m.author_id)
           const authorName = m.author_name ?? (await authorResolver.resolve(authorId, args.chat)) ?? authorId
+          const { text, attachments } = splitHistoryInbound(m)
           return {
             externalMessageId: m.log_id,
             authorId,
             authorName,
-            text: formatHistoryText(m),
+            text,
+            ...(attachments.length > 0 ? { attachments } : {}),
             ts: m.sent_at * 1000,
             isBot: selfId !== null && authorId === selfId,
             replyToBotMessageId: null,
@@ -331,13 +339,8 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
   const fetchAttachmentCallback = createFetchAttachmentCallback({ logger })
 
   const handleMessageEvent = async (event: KakaoTalkPushMessageEvent): Promise<void> => {
-    // Synthesize the displayed text BEFORE classify so attachments
-    // (photo, file, video, ...) survive classifyInbound's empty_text
-    // drop and reach the agent with a `[KakaoTalk message with ...]`
-    // placeholder. For text-only messages this is a no-op —
-    // formatInboundText returns event.message unchanged. See
-    // kakaotalk-attachment.ts for the per-message-type rules.
-    await processInbound({ ...event, message: formatInboundText(event) })
+    const { text, attachments } = splitInbound(event)
+    await processInbound({ ...event, message: text }, attachments)
   }
 
   const handleEmoticonEvent = async (event: KakaoTalkPushEmoticonEvent): Promise<void> => {
@@ -347,10 +350,14 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
     // self-author / unknown-chat rules apply identically across plain
     // messages and stickers — there is no second classifier to keep in
     // sync.
-    await processInbound(emoticonEventToMessageEvent(event))
+    const { attachments } = splitEmoticonInbound(event)
+    await processInbound(emoticonEventToMessageEvent(event), attachments)
   }
 
-  const processInbound = async (event: KakaoTalkPushMessageEvent): Promise<void> => {
+  const processInbound = async (
+    event: KakaoTalkPushMessageEvent,
+    attachments: readonly InboundAttachment[] = [],
+  ): Promise<void> => {
     inflightInbounds++
     try {
       if (channelResolver.lookupChat(event.chat_id) === null) {
@@ -391,6 +398,7 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
       const verdict = classifyInbound(event, options.configRef(), {
         selfUserId,
         lookupChat: (id) => channelResolver.lookupChat(id),
+        ...(attachments.length > 0 ? { attachments } : {}),
         ...(options.selfAliasesRef ? { selfAliases: options.selfAliasesRef() } : {}),
       })
       if (verdict.kind === 'drop') {

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

@@ -2,7 +2,7 @@ import type { SlackFile, SlackSocketModeAppMentionEvent, SlackSocketModeMessageE
 
 import { matchesAnyAlias } from '@/channels/engagement'
 import type { ChannelAdapterConfig } from '@/channels/schema'
-import type { InboundMessage } from '@/channels/types'
+import type { InboundAttachment, InboundMessage } from '@/channels/types'
 
 import { slackTsToMillis } from './slack-bot-time'
 
@@ -61,7 +61,7 @@ export function classifyInbound(
   }
 
   const rawText = event.text ?? ''
-  const text = inboundText(event)
+  const { text, attachments } = splitInbound(event)
   if (text === '') return { kind: 'drop', reason: 'empty_text' }
 
   const isDm = event.channel_type === 'im'
@@ -72,8 +72,8 @@ export function classifyInbound(
   }
 
   // Mention parsing runs against the raw user-typed text only — the
-  // appended `[Slack message with attachment: ...]` summary contains URLs
-  // and ids that must not be misread as mentions or group broadcasts.
+  // appended `[Slack attachment #N: ...]` placeholder contains metadata
+  // that must not be misread as mentions or group broadcasts.
   // Group mentions (`<!here>`, `<!channel>`, `<!everyone>`) are coerced to
   // direct mentions: the user fired a broadcast that explicitly includes the
   // bot, and from the engagement layer's perspective there is no meaningful
@@ -131,6 +131,7 @@ export function classifyInbound(
       chat: event.channel,
       thread,
       text,
+      ...(attachments.length > 0 ? { attachments } : {}),
       externalMessageId: event.ts,
       authorId: event.user,
       authorName: event.user,
@@ -166,19 +167,34 @@ function extractMentionedUserIds(text: string): string[] {
   return Array.from(seen)
 }
 
-function inboundText(event: SlackInboundMessageEvent): string {
+type SplitInbound = { text: string; attachments: InboundAttachment[] }
+
+function splitInbound(event: SlackInboundMessageEvent): SplitInbound {
   const rawText = event.text ?? ''
-  const mediaSummary = summarizeSlackMedia(event)
-  if (mediaSummary.length === 0) return rawText
-  const summary = `[Slack message with ${mediaSummary.join('; ')}]`
-  return rawText === '' ? summary : `${rawText}\n${summary}`
+  const attachments = describeSlackMedia(event)
+  if (attachments.length === 0) return { text: rawText, attachments: [] }
+  const summary = attachments.map(renderPlaceholder).join('\n')
+  const text = rawText === '' ? summary : `${rawText}\n${summary}`
+  return { text, attachments }
+}
+
+function describeSlackMedia(event: SlackInboundMessageEvent): InboundAttachment[] {
+  return (event.files ?? []).map((file, index) => describeSlackFile(file, index + 1))
 }
 
-function summarizeSlackMedia(event: SlackInboundMessageEvent): string[] {
-  return (event.files ?? []).map(summarizeSlackFile)
+function describeSlackFile(file: SlackFile, id: number): InboundAttachment {
+  return {
+    id,
+    kind: 'file',
+    ref: file.id,
+    filename: file.name,
+    mimetype: file.mimetype,
+  }
 }
 
-function summarizeSlackFile(file: SlackFile): string {
-  const parts: string[] = [`attachment: ${file.name}`, `(${file.mimetype})`, `id=${file.id}`]
-  return parts.join(' ')
+function renderPlaceholder(attachment: InboundAttachment): string {
+  const parts: string[] = [`Slack 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/slack-bot.ts

@@ -692,8 +692,9 @@ export function createOutboundCallback(deps: {
 // plain HTTP tool. Routing through the SDK's `downloadFile(fileId)` is
 // the only path that works — it issues `files.info` to fetch metadata
 // (mimetype + name) then GETs `url_private` with the bot token. The
-// classifier emits `id=Fxxxx` in the inbound text exactly so the agent
-// can hand the id back to this callback.
+// classifiers now keep the bare `Fxxxx` id in structured InboundAttachment.ref
+// (legacy persisted state may still carry the old prompt-visible `id=` shape,
+// which channel_fetch_attachment strips before reaching this callback).
 export function createFetchAttachmentCallback(deps: {
   client: Pick<SlackBotClient, 'downloadFile'>
   logger: SlackBotAdapterLogger

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

@@ -1,7 +1,7 @@
 import type { TelegramBotUser, TelegramMessage, TelegramMessageEntity } from 'agent-messenger/telegrambot'
 
 import type { ChannelAdapterConfig } from '@/channels/schema'
-import type { InboundMessage } from '@/channels/types'
+import type { InboundAttachment, InboundMessage } from '@/channels/types'
 
 export type InboundDropReason = 'self_author' | 'no_user' | 'empty_text' | 'pre_connect'
 
@@ -31,7 +31,7 @@ export function classifyInbound(
     return { kind: 'drop', reason: 'self_author' }
   }
 
-  const text = inboundText(event)
+  const { text, attachments } = splitInbound(event)
   if (text === '') return { kind: 'drop', reason: 'empty_text' }
 
   const chat = String(event.chat.id)
@@ -70,6 +70,7 @@ export function classifyInbound(
       chat,
       thread,
       text,
+      ...(attachments.length > 0 ? { attachments } : {}),
       externalMessageId: String(event.message_id),
       authorId: String(author.id),
       authorName: formatAuthorName(author),
@@ -130,24 +131,46 @@ function isUserMentionForBot(
   return false
 }
 
-function inboundText(event: TelegramMessage): string {
+type SplitInbound = { text: string; attachments: InboundAttachment[] }
+
+function splitInbound(event: TelegramMessage): SplitInbound {
   const body = event.text ?? event.caption ?? ''
-  const mediaSummary = summarizeMedia(event)
-  if (mediaSummary.length === 0) return body
-  const summary = `[Telegram message with ${mediaSummary.join('; ')}]`
-  return body === '' ? summary : `${body}\n${summary}`
+  const attachments = describeMedia(event)
+  if (attachments.length === 0) return { text: body, attachments: [] }
+  const summary = attachments.map(renderPlaceholder).join('\n')
+  const text = body === '' ? summary : `${body}\n${summary}`
+  return { text, attachments }
 }
 
-function summarizeMedia(event: TelegramMessage): string[] {
-  const parts: string[] = []
+function describeMedia(event: TelegramMessage): InboundAttachment[] {
+  const parts: InboundAttachment[] = []
   if (event.document !== undefined) {
-    const name = event.document.file_name ?? event.document.file_id
-    const mime = event.document.mime_type !== undefined ? ` (${event.document.mime_type})` : ''
-    parts.push(`document: ${name}${mime} file_id=${event.document.file_id}`)
+    parts.push({
+      id: parts.length + 1,
+      kind: 'file',
+      ref: event.document.file_id,
+      ...(event.document.file_name !== undefined ? { filename: event.document.file_name } : {}),
+      ...(event.document.mime_type !== undefined ? { mimetype: event.document.mime_type } : {}),
+    })
   }
   if (event.photo !== undefined && event.photo.length > 0) {
     const largest = event.photo[event.photo.length - 1]!
-    parts.push(`photo: ${largest.width}x${largest.height} file_id=${largest.file_id}`)
+    parts.push({
+      id: parts.length + 1,
+      kind: 'photo',
+      ref: largest.file_id,
+      width: largest.width,
+      height: largest.height,
+    })
   }
   return parts
 }
+
+function renderPlaceholder(attachment: InboundAttachment): string {
+  const parts: string[] = [`Telegram attachment #${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}`)
+  return `[${parts.join(' ')}]`
+}

package/src/channels/adapters/telegram-bot.ts

@@ -279,9 +279,9 @@ type TelegramFileResponse = {
 // Telegram's file download is a two-step protocol: `getFile` returns a
 // short-lived `file_path`, then the file lives at
 // `api.telegram.org/file/bot<TOKEN>/<file_path>`. `ref` here is the
-// `file_id` carried in the inbound classifier's `[Telegram message with
-// document: ... file_id=<id>]` summary; the agent passes it back through
-// the `channel_fetch_attachment` tool.
+// `file_id` carried in structured InboundAttachment.ref. The agent only sees
+// `[Telegram attachment #N: ...]` and passes that id through the
+// `channel_fetch_attachment` tool; the router resolves it to this callback.
 //
 // SSRF boundary: `ref` is `encodeURIComponent`'d into a query parameter
 // of a fixed `api.telegram.org/bot<TOKEN>/getFile?file_id=...` URL, so