typeclaw 0.7.0 → 0.9.0

package/src/server/index.ts

@@ -7,9 +7,11 @@ import {
   type CreateSessionResult,
 } from '@/agent'
 import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
+import type { LiveSessionRegistry } from '@/agent/live-sessions'
 import type { LiveSubagentRegistry } from '@/agent/live-subagents'
 import { detectProviderError } from '@/agent/provider-error'
 import type { SessionOrigin } from '@/agent/session-origin'
+import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
 import type { CreateSessionForSubagent } from '@/agent/subagents'
 import type { ChannelRouter } from '@/channels/router'
 import { aggregateCronList, type CronListEntry, loadCron } from '@/cron'
@@ -24,6 +26,9 @@ import type {
   ClientMessage,
   CronListEntryPayload,
   CronListSourcePayload,
+  InspectClientMessage,
+  InspectFramePayload,
+  InspectServerMessage,
   PromptDelivery,
   QueueStateItem,
   ReloadResultPayload,
@@ -102,6 +107,13 @@ export type ServerOptions = {
   // as out-of-scope follow-up.
   liveSubagentRegistry?: LiveSubagentRegistry
   createSessionForSubagent?: CreateSessionForSubagent
+  // Id-keyed registry of live AgentSessions, used by `/inspect` (and any
+  // future read-only session-event consumer) to subscribe to session
+  // events without owning the session lifecycle. Populated by every
+  // session-creation site that wants its sessions inspectable; an absent
+  // registry is fine — `/inspect` will report "session not live, replay
+  // from JSONL only" when it can't resolve the id.
+  liveSessionRegistry?: LiveSessionRegistry
 }
 
 const consoleLogger: ServerLogger = {
@@ -119,10 +131,17 @@ type TuiWsData = { kind: 'tui'; sessionId: string }
 // TUI token can already do anything the TUI can).
 type CommandWsData = { kind: 'command' }
 type TunnelLogsWsData = { kind: 'tunnel-logs'; unsubscribe: Unsubscribe | null }
-type WsData = TuiWsData | CommandWsData | TunnelLogsWsData | BrokerWsData
+type InspectWsData = {
+  kind: 'inspect'
+  unsubAgent: (() => void) | null
+  unsubBroadcast: Unsubscribe | null
+  unsubCron: Unsubscribe | null
+}
+type WsData = TuiWsData | CommandWsData | TunnelLogsWsData | BrokerWsData | InspectWsData
 type Ws = ServerWebSocket<TuiWsData>
 type CommandWs = ServerWebSocket<CommandWsData>
 type TunnelLogsWs = ServerWebSocket<TunnelLogsWsData>
+type InspectWs = ServerWebSocket<InspectWsData>
 type AnyOwnerWs = Ws | CommandWs
 
 type QueuedPrompt = {
@@ -175,6 +194,15 @@ function sendTunnelLog(ws: TunnelLogsWs, msg: TunnelLogsServerMessage): boolean
   }
 }
 
+function sendInspect(ws: InspectWs, msg: InspectServerMessage): boolean {
+  try {
+    ws.send(JSON.stringify(msg))
+    return true
+  } catch {
+    return false
+  }
+}
+
 function encodeBase64(bytes: Uint8Array): string {
   let s = ''
   for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i] ?? 0)
@@ -201,6 +229,7 @@ export function createServer({
   commandRunnerFactory,
   liveSubagentRegistry,
   createSessionForSubagent,
+  liveSessionRegistry,
 }: ServerOptions) {
   const sessionStates = new WeakMap<Ws, SessionState>()
   const callIdToWs = new Map<string, AnyOwnerWs>()
@@ -318,6 +347,14 @@ export function createServer({
           if (server.upgrade(req, { data })) return
           return new Response('upgrade failed', { status: 400 })
         }
+        if (url.pathname === '/inspect') {
+          if (isWebSocketUpgrade(req) && tuiToken !== undefined && url.searchParams.get('token') !== tuiToken) {
+            return new Response('unauthorized', { status: 401 })
+          }
+          const data: InspectWsData = { kind: 'inspect', unsubAgent: null, unsubBroadcast: null, unsubCron: null }
+          if (server.upgrade(req, { data })) return
+          return new Response('upgrade failed', { status: 400 })
+        }
         // `/commands` is the dedicated host-CLI proxy path. It skips TUI
         // session creation (which costs an AgentSession spawn per command
         // invocation) but uses the same tuiToken because both surfaces
@@ -357,6 +394,7 @@ export function createServer({
             return
           }
           if (rawWs.data.kind === 'tunnel-logs') return
+          if (rawWs.data.kind === 'inspect') return
           const ws = rawWs as Ws
           try {
             const sessionManager = sessionFactory?.createPersisted()
@@ -421,6 +459,7 @@ export function createServer({
               await runtimeSnapshot.hooks.runSessionStart({ sessionId: sessionFileId, agentDir })
             }
 
+            liveSessionRegistry?.register({ sessionId: sessionFileId, session })
             forwardSessionEvents(ws, session, logger, sessionFileId)
 
             if (stream) {
@@ -474,6 +513,10 @@ export function createServer({
             handleTunnelLogsMessage(rawWs as TunnelLogsWs, raw, tunnelManager)
             return
           }
+          if (rawWs.data.kind === 'inspect') {
+            handleInspectMessage(rawWs as InspectWs, raw, liveSessionRegistry, stream)
+            return
+          }
           const ws = rawWs as Ws
           const msg = JSON.parse(String(raw)) as ClientMessage
           const state = sessionStates.get(ws)
@@ -605,6 +648,7 @@ export function createServer({
               await fallbackHooks.runSessionTurnStart({
                 sessionId: state.sessionFileId,
                 agentDir,
+                userPrompt: msg.text,
                 origin: state.origin,
               })
             }
@@ -657,6 +701,16 @@ export function createServer({
             rawWs.data.unsubscribe = null
             return
           }
+          if (rawWs.data.kind === 'inspect') {
+            const d = rawWs.data
+            d.unsubAgent?.()
+            d.unsubBroadcast?.()
+            d.unsubCron?.()
+            d.unsubAgent = null
+            d.unsubBroadcast = null
+            d.unsubCron = null
+            return
+          }
           const ws = rawWs as Ws
           const state = sessionStates.get(ws)
           state?.unsubBroadcast?.()
@@ -677,6 +731,7 @@ export function createServer({
             if (state) {
               state.session.dispose()
               await state.dispose()
+              liveSessionRegistry?.unregister(state.sessionFileId)
             }
             sessionStates.delete(ws)
             console.log(`session ${state?.sessionFileId ?? ws.data.sessionId}: close`)
@@ -751,29 +806,13 @@ function forwardAssistantError(ws: Ws, message: unknown, logger: ServerLogger, s
 }
 
 function routeSubagentCompletionReminder(state: SessionState, msg: StreamMessage, stream: Stream): void {
-  const payload = msg.payload
-  if (payload === null || typeof payload !== 'object') return
-  const p = payload as {
-    kind?: unknown
-    taskId?: unknown
-    subagent?: unknown
-    parentSessionId?: unknown
-    ok?: unknown
-    durationMs?: unknown
-    error?: unknown
-  }
-  if (p.kind !== 'subagent.completed') return
-  if (typeof p.parentSessionId !== 'string' || p.parentSessionId !== state.sessionFileId) return
-
-  const subagent = typeof p.subagent === 'string' ? p.subagent : 'subagent'
-  const taskId = typeof p.taskId === 'string' ? p.taskId : '<unknown>'
-  const ok = p.ok === true
-  const durationMs = typeof p.durationMs === 'number' ? p.durationMs : 0
-  const error = typeof p.error === 'string' ? p.error : undefined
+  const parsed = parseSubagentCompletedPayload(msg.payload)
+  if (parsed === null) return
+  if (parsed.parentSessionId !== state.sessionFileId) return
 
   const idle = state.drainQueue.length === 0 && !state.draining
   const delivery = idle ? 'interrupt' : 'queue'
-  const text = renderCompletionReminder({ subagent, taskId, ok, durationMs, error })
+  const text = renderSubagentCompletionReminder(parsed)
   stream.publish({
     target: { kind: 'session', sessionId: state.sessionFileId },
     payload: { kind: 'prompt', text, delivery },
@@ -781,40 +820,6 @@ function routeSubagentCompletionReminder(state: SessionState, msg: StreamMessage
   })
 }
 
-function renderCompletionReminder(args: {
-  subagent: string
-  taskId: string
-  ok: boolean
-  durationMs: number
-  error?: string
-}): string {
-  const durationStr = formatReminderDuration(args.durationMs)
-  if (args.ok) {
-    return (
-      `<system-reminder>\n` +
-      `Subagent \`${args.subagent}\` (${args.taskId}) completed in ${durationStr}. ` +
-      `Use subagent_output to fetch the result.\n` +
-      `</system-reminder>`
-    )
-  }
-  const err = args.error ?? 'unknown error'
-  return (
-    `<system-reminder>\n` +
-    `Subagent \`${args.subagent}\` (${args.taskId}) FAILED after ${durationStr}: ${err}. ` +
-    `Use subagent_output to inspect.\n` +
-    `</system-reminder>`
-  )
-}
-
-function formatReminderDuration(ms: number): string {
-  if (ms < 1000) return `${ms}ms`
-  const totalSec = Math.floor(ms / 1000)
-  if (totalSec < 60) return `${totalSec}s`
-  const min = Math.floor(totalSec / 60)
-  const sec = totalSec % 60
-  return `${min}m${sec}s`
-}
-
 function enqueuePrompt(
   ws: Ws,
   state: SessionState,
@@ -861,15 +866,16 @@ function makeIdleHookCaller(state: SessionState): () => Promise<void> {
 function makeTurnHookCallers(
   state: SessionState,
   agentDir: string | undefined,
-): { fireTurnStart: () => Promise<void>; fireTurnEnd: () => Promise<void> } {
+): { fireTurnStart: (userPrompt: string) => Promise<void>; fireTurnEnd: () => Promise<void> } {
   const hooks: HookBus | undefined = state.runtimeSnapshot?.hooks
   if (hooks === undefined || agentDir === undefined) {
     return { fireTurnStart: async () => {}, fireTurnEnd: async () => {} }
   }
-  const event = { sessionId: state.sessionFileId, agentDir, origin: state.origin }
+  const turnEndEvent = { sessionId: state.sessionFileId, agentDir, origin: state.origin }
   return {
-    fireTurnStart: () => hooks.runSessionTurnStart(event),
-    fireTurnEnd: () => hooks.runSessionTurnEnd(event),
+    fireTurnStart: (userPrompt) =>
+      hooks.runSessionTurnStart({ sessionId: state.sessionFileId, agentDir, userPrompt, origin: state.origin }),
+    fireTurnEnd: () => hooks.runSessionTurnEnd(turnEndEvent),
   }
 }
 
@@ -885,7 +891,7 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined,
       pushQueueState(ws, state)
       send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
 
-      await fireTurnStart()
+      await fireTurnStart(item.text)
       try {
         await state.session.prompt(item.text)
         send(ws, { type: 'done' })
@@ -1030,6 +1036,181 @@ function handleTunnelStatus(ws: Ws, requestId: string, name: string, tunnelManag
   send(ws, { type: 'tunnel_status_response', requestId, ok: true, tunnel })
 }
 
+function handleInspectMessage(
+  ws: InspectWs,
+  raw: string | Buffer,
+  liveSessionRegistry: LiveSessionRegistry | undefined,
+  stream: Stream | undefined,
+): void {
+  let msg: InspectClientMessage
+  try {
+    msg = JSON.parse(String(raw)) as InspectClientMessage
+  } catch {
+    sendInspect(ws, { type: 'error', message: 'invalid JSON' })
+    ws.close()
+    return
+  }
+  if (msg.type !== 'subscribe' || typeof msg.sessionId !== 'string' || msg.sessionId === '') {
+    sendInspect(ws, { type: 'error', message: 'invalid inspect subscription' })
+    ws.close()
+    return
+  }
+
+  ws.data.unsubAgent?.()
+  ws.data.unsubBroadcast?.()
+  ws.data.unsubCron?.()
+
+  if (stream !== undefined && typeof msg.sinceMs === 'number') {
+    for (const event of stream.scan({ sinceTs: msg.sinceMs, target: { kind: 'broadcast' } })) {
+      sendInspect(ws, {
+        type: 'frame',
+        ts: event.ts,
+        payload: {
+          kind: 'broadcast',
+          payload: event.payload,
+          ...(event.meta !== undefined ? { meta: event.meta } : {}),
+        },
+      })
+    }
+    for (const event of stream.scan({ sinceTs: msg.sinceMs, target: { kind: 'cron' } })) {
+      sendInspect(ws, {
+        type: 'frame',
+        ts: event.ts,
+        payload: { kind: 'cron-fire', jobId: extractJobId(event.target), payload: event.payload },
+      })
+    }
+  }
+
+  const live = liveSessionRegistry?.get(msg.sessionId)
+  if (live !== undefined) {
+    const sessionId = msg.sessionId
+    const startedAtByCallId = new Map<string, number>()
+    ws.data.unsubAgent = live.session.subscribe((event: unknown) => {
+      forwardAgentEventToInspect(ws, event, sessionId, startedAtByCallId)
+    })
+  }
+
+  if (stream !== undefined) {
+    ws.data.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (event) => {
+      sendInspect(ws, {
+        type: 'frame',
+        ts: event.ts,
+        payload: {
+          kind: 'broadcast',
+          payload: event.payload,
+          ...(event.meta !== undefined ? { meta: event.meta } : {}),
+        },
+      })
+    })
+    ws.data.unsubCron = stream.subscribe({ target: { kind: 'cron' } }, (event) => {
+      sendInspect(ws, {
+        type: 'frame',
+        ts: event.ts,
+        payload: { kind: 'cron-fire', jobId: extractJobId(event.target), payload: event.payload },
+      })
+    })
+  }
+
+  sendInspect(ws, { type: 'subscribed', sessionId: msg.sessionId, sessionLive: live !== undefined })
+}
+
+function extractJobId(target: StreamMessage['target']): string {
+  return target.kind === 'cron' ? target.jobId : ''
+}
+
+function forwardAgentEventToInspect(
+  ws: InspectWs,
+  event: unknown,
+  sessionId: string,
+  startedAtByCallId: Map<string, number>,
+): void {
+  if (typeof event !== 'object' || event === null) return
+  const e = event as { type?: unknown }
+  const now = Date.now()
+  if (e.type === 'message_update') {
+    const ev = event as { assistantMessageEvent?: { type?: unknown; delta?: unknown } }
+    const ame = ev.assistantMessageEvent
+    if (ame?.type === 'text_delta' && typeof ame.delta === 'string') {
+      sendInspect(ws, { type: 'frame', ts: now, payload: { kind: 'text_delta', sessionId, delta: ame.delta } })
+    }
+    return
+  }
+  if (e.type === 'tool_execution_start') {
+    const ev = event as { toolCallId?: unknown; toolName?: unknown; args?: unknown }
+    if (typeof ev.toolCallId !== 'string' || typeof ev.toolName !== 'string') return
+    startedAtByCallId.set(ev.toolCallId, now)
+    sendInspect(ws, {
+      type: 'frame',
+      ts: now,
+      payload: { kind: 'tool_start', sessionId, toolCallId: ev.toolCallId, name: ev.toolName, args: ev.args },
+    })
+    return
+  }
+  if (e.type === 'tool_execution_end') {
+    const ev = event as { toolCallId?: unknown; toolName?: unknown; result?: unknown; isError?: unknown }
+    if (typeof ev.toolCallId !== 'string' || typeof ev.toolName !== 'string') return
+    const startedAt = startedAtByCallId.get(ev.toolCallId)
+    startedAtByCallId.delete(ev.toolCallId)
+    const durationMs = startedAt === undefined ? 0 : now - startedAt
+    sendInspect(ws, {
+      type: 'frame',
+      ts: now,
+      payload: {
+        kind: 'tool_end',
+        sessionId,
+        toolCallId: ev.toolCallId,
+        name: ev.toolName,
+        result: ev.result,
+        isError: ev.isError === true,
+        durationMs,
+      },
+    })
+    return
+  }
+  if (e.type === 'message_end') {
+    const ev = event as { message?: unknown }
+    const payload = buildMessageEndPayload(sessionId, ev.message)
+    if (payload !== null) sendInspect(ws, { type: 'frame', ts: now, payload })
+    return
+  }
+}
+
+function buildMessageEndPayload(sessionId: string, message: unknown): InspectFramePayload | null {
+  if (typeof message !== 'object' || message === null) return null
+  const m = message as Record<string, unknown>
+  if (typeof m.role !== 'string') return null
+  const usage = readMessageUsage(m.usage)
+  const payload: InspectFramePayload = {
+    kind: 'message_end',
+    sessionId,
+    role: m.role,
+    content: m.content,
+    ...(typeof m.provider === 'string' ? { provider: m.provider } : {}),
+    ...(typeof m.model === 'string' ? { model: m.model } : {}),
+    ...(typeof m.stopReason === 'string' ? { stopReason: m.stopReason } : {}),
+    ...(typeof m.errorMessage === 'string' ? { errorMessage: m.errorMessage } : {}),
+    ...(usage !== null ? { usage } : {}),
+  }
+  return payload
+}
+
+function readMessageUsage(
+  value: unknown,
+): { input: number; output: number; cacheRead: number; cacheWrite: number; totalTokens: number; cost: number } | null {
+  if (typeof value !== 'object' || value === null) return null
+  const u = value as Record<string, unknown>
+  const cost = u.cost as Record<string, unknown> | undefined
+  const numberOr = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+  return {
+    input: numberOr(u.input),
+    output: numberOr(u.output),
+    cacheRead: numberOr(u.cacheRead),
+    cacheWrite: numberOr(u.cacheWrite),
+    totalTokens: numberOr(u.totalTokens),
+    cost: numberOr(cost?.total),
+  }
+}
+
 function handleTunnelLogsMessage(
   ws: TunnelLogsWs,
   raw: string | Buffer,

package/src/shared/index.ts

@@ -11,6 +11,9 @@ export {
   type DoctorCheckPayload,
   type DoctorFixPayload,
   type DoctorRequestId,
+  type InspectClientMessage,
+  type InspectFramePayload,
+  type InspectServerMessage,
   type PromptDelivery,
   type QueueStateItem,
   type ReloadResultPayload,
@@ -21,4 +24,4 @@ export {
   type TunnelSnapshot,
 } from './protocol'
 
-export { formatLocalDate, formatLocalDateTime } from './local-time'
+export { formatLocalDate, formatLocalDateTime, resolveLocalTimezoneName } from './local-time'

package/src/shared/local-time.ts

@@ -19,3 +19,20 @@ function formatTimezoneOffset(date: Date): string {
   const abs = Math.abs(offsetMinutes)
   return `${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`
 }
+
+// IANA timezone name of the process (e.g. `Asia/Seoul`). Reads the resolved
+// zone from Intl, falling back to `UTC` if the runtime cannot resolve one —
+// this should never happen on Bun + tzdata-equipped containers, but the
+// fallback keeps the prompt renderable rather than throwing during session
+// creation. The returned name is what the agent shows the user when asked
+// "what time is it" — pairing the wall clock with a recognizable zone name
+// is what disambiguates "15:31 +09:00" from "15:31 KST" for a non-technical
+// reader.
+export function resolveLocalTimezoneName(): string {
+  try {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone
+    return zone && zone.length > 0 ? zone : 'UTC'
+  } catch {
+    return 'UTC'
+  }
+}

package/src/shared/protocol.ts

@@ -44,6 +44,55 @@ export type TunnelLogsServerMessage =
   | { type: 'error'; message: string }
   | { type: 'end' }
 
+export type InspectClientMessage = {
+  type: 'subscribe'
+  sessionId: string
+  // sinceMs is a wall-clock cutoff for backfilling broadcasts from the
+  // in-process Stream ring buffer. The client uses Date.now() - duration;
+  // omit to skip broadcast backfill. AgentSession events are NEVER
+  // backfilled (the session's pi-coding-agent subscribe API delivers
+  // future events only).
+  sinceMs?: number
+}
+
+export type InspectFramePayload =
+  | { kind: 'text_delta'; sessionId: string; delta: string }
+  | { kind: 'tool_start'; sessionId: string; toolCallId: string; name: string; args: unknown }
+  | {
+      kind: 'tool_end'
+      sessionId: string
+      toolCallId: string
+      name: string
+      result: unknown
+      isError: boolean
+      durationMs: number
+    }
+  | {
+      kind: 'message_end'
+      sessionId: string
+      role: string
+      content: unknown
+      provider?: string
+      model?: string
+      stopReason?: string
+      errorMessage?: string
+      usage?: {
+        input: number
+        output: number
+        cacheRead: number
+        cacheWrite: number
+        totalTokens: number
+        cost: number
+      }
+    }
+  | { kind: 'broadcast'; payload: unknown; meta?: Record<string, string> }
+  | { kind: 'cron-fire'; jobId: string; payload: unknown }
+
+export type InspectServerMessage =
+  | { type: 'subscribed'; sessionId: string; sessionLive: boolean }
+  | { type: 'frame'; ts: number; payload: InspectFramePayload }
+  | { type: 'error'; message: string }
+
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }
   | { type: 'reload'; scope?: string }

package/src/skills/typeclaw-channel-kakaotalk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channel-kakaotalk
-description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `kakaotalk`, AND before calling `channel_fetch_attachment` against a KakaoTalk URL. KakaoTalk renders messages as plain text — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and other markdown all appear literally. There is no `@mention` syntax, no message threads, no replies-with-quote, and no outbound file attachments or stickers. Inbound photos / files / video / audio CAN be downloaded via `channel_fetch_attachment` (the placeholder text includes the URL); inbound stickers are metadata-only and cannot be fetched. URLs expire ~3 days after the message arrives. Read this skill before composing or fetching anything on KakaoTalk.
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `kakaotalk`, AND before calling `channel_fetch_attachment` against a KakaoTalk URL. KakaoTalk renders messages as plain text — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and other markdown all appear literally. There is no `@mention` syntax, no message threads, no replies-with-quote, and no outbound stickers. Outbound file attachments (photos, videos, audio, generic files, multi-photo galleries) ARE supported — pass them via `attachments[]` on `channel_send` / `channel_reply` and the adapter routes by MIME. Inbound photos / files / video / audio CAN be downloaded via `channel_fetch_attachment` (the placeholder text includes the URL); inbound stickers are metadata-only and cannot be fetched. URLs expire ~3 days after the message arrives. Read this skill before composing or fetching anything on KakaoTalk.
 ---
 
 # typeclaw-channel-kakaotalk
@@ -21,15 +21,19 @@ If you produce any of the following, KakaoTalk will render it literally and the
 - **Links with display text** — `[label](url)` becomes the literal string. Send the bare URL on its own; the KakaoTalk client will auto-link it.
 - **Mentions** — there is no `@user` syntax that the protocol surfaces. Address people by name in the message body.
 - **Threads / replies-with-quote** — every message is a top-level chat post. There is no per-message reply UI.
-- **Outbound attachments / stickers** — agent-messenger's KakaoTalk SDK exposes no upload API. The adapter is outbound text-only. If the user asks you to send a file or sticker, say so and offer an alternative (paste a link, summarize the file, ship it via another channel).
-
-The adapter rejects outbound attachments via `ok: false` rather than partially sending the text — the agent contract is "ok=true means the whole request succeeded", so a silent drop would let you confidently report "I sent your file" when the file never arrived.
+- **Outbound stickers / emoticons** — the KakaoTalk sticker store requires desktop-app purchase flows that the SDK does not replicate. Inbound stickers ARE surfaced (see below), but you cannot send one. If the user asks for a sticker, acknowledge the limit and offer text.
 
 ## What KakaoTalk DOES support
 
 - Plain UTF-8 text. Emoji are fine.
 - URLs auto-linkify in the client. Send them bare — `https://example.com/foo`, no markdown wrapping.
 - Newlines render as line breaks. You can use `\n\n` to space paragraphs.
+- **Outbound file attachments** — photos, videos, audio, generic files, and multi-photo galleries. Pass each as an `OutboundAttachment { path, filename? }` on the `attachments[]` field of `channel_send` / `channel_reply`. The adapter sniffs the MIME from the filename and routes to the right KakaoTalk message type, so the caller does not pick photo-vs-file-vs-multiphoto by hand:
+  - Single attachment → single send. `image/*` renders inline with tap-to-zoom; `video/*` as an inline player; `audio/*` as a voice bubble; everything else as a downloadable file.
+  - Multiple attachments, all image MIMEs → multi-photo gallery (one chat bubble containing every image).
+  - Multiple attachments with mixed kinds (e.g. photo + PDF) → individual sends, one bubble each, in array order.
+  - Each send is fail-fast: if any upload fails the adapter returns `ok: false` immediately rather than partial-success.
+- **Text + attachments in one `channel_send`** — files upload first, then the text posts as a separate chat bubble. KakaoTalk has no Slack-style `initial_comment` that lets text and files share a single send.
 
 ## Inbound attachments and stickers
 
@@ -103,8 +107,4 @@ The adapter drops every inbound where `event.author_id` equals the logged-in acc
 
 ## When you cannot answer in KakaoTalk
 
-If the user asks you to do something the adapter cannot do (send a file, render markdown, post in a thread), say so plainly:
-
-> "I can't attach files through this chat. Want me to drop the file in [other channel] instead?"
-
-Better than silently dropping the attachment and pretending you sent it.
+If the user asks you to do something the adapter cannot do (render markdown, post in a thread, send a sticker), say so plainly. Files are fine — those go through `attachments[]` as described above — but markdown rendering, threading, and stickers are real limits. Acknowledge the limit instead of silently dropping the request.