typeclaw 0.1.0

package/src/server/index.ts

@@ -0,0 +1,436 @@
+import type { Server as BunServer, ServerWebSocket } from 'bun'
+
+import {
+  createSessionWithDispose as defaultCreateSessionWithDispose,
+  type AgentSession,
+  type CreateSessionOptions,
+  type CreateSessionResult,
+} from '@/agent'
+import type { SessionOrigin } from '@/agent/session-origin'
+import type { ChannelRouter } from '@/channels/router'
+import type { HookBus } from '@/plugin'
+import type { BrokerWsData, ContainerBroker } from '@/portbroker'
+import type { ReloadAllResult, ReloadRegistry } from '@/reload'
+import type { PluginRuntime, PluginRuntimeState } from '@/run/plugin-runtime'
+import type { SessionFactory } from '@/sessions'
+import type { ClientMessage, PromptDelivery, QueueStateItem, ReloadResultPayload, ServerMessage } from '@/shared'
+import type { Stream, StreamMessage, StreamMessageId, Unsubscribe } from '@/stream'
+
+export type ReloadAllFn = () => Promise<ReloadAllResult>
+export type CreateSessionFn = (options?: CreateSessionOptions) => Promise<AgentSession | CreateSessionResult>
+
+export type ServerOptions = {
+  port: number
+  reloadAll?: ReloadAllFn
+  reloadRegistry?: ReloadRegistry
+  createSession?: CreateSessionFn
+  sessionFactory?: SessionFactory
+  stream?: Stream
+  channelRouter?: ChannelRouter
+  agentDir?: string
+  pluginRuntime?: PluginRuntime
+  containerName?: string
+  // Optional in-process portbroker handler. When provided, requests to the
+  // /portbroker WS path are routed to it instead of being treated as TUI
+  // sessions. Omit to keep TUI-only behavior (used by tests + non-container
+  // dev runs).
+  containerBroker?: ContainerBroker
+}
+
+export type Server = ReturnType<typeof createServer>
+
+type TuiWsData = { kind: 'tui'; sessionId: string }
+type WsData = TuiWsData | BrokerWsData
+type Ws = ServerWebSocket<TuiWsData>
+
+type QueuedPrompt = {
+  streamMessageId: StreamMessageId
+  text: string
+  delivery: PromptDelivery
+  ts: number
+}
+
+type SessionState = {
+  session: AgentSession
+  sessionFileId: string
+  origin: SessionOrigin
+  sessionManager: { getSessionFile: () => string | undefined } | undefined
+  drainQueue: QueuedPrompt[]
+  draining: boolean
+  unsubBroadcast: Unsubscribe | null
+  unsubPrompts: Unsubscribe | null
+  // Captured at session open so close-time hooks fire against the same
+  // generation that ran session.start. A plugin reload mid-connection does
+  // not re-target this session's lifecycle hooks.
+  runtimeSnapshot: PluginRuntimeState | null
+  dispose: () => Promise<void>
+}
+
+function send(ws: Ws, msg: ServerMessage) {
+  ws.send(JSON.stringify(msg))
+}
+
+export function createServer({
+  port,
+  reloadAll,
+  reloadRegistry,
+  createSession = defaultCreateSessionWithDispose,
+  sessionFactory,
+  stream,
+  channelRouter,
+  agentDir,
+  pluginRuntime,
+  containerName,
+  containerBroker,
+}: ServerOptions) {
+  const sessionStates = new WeakMap<Ws, SessionState>()
+
+  function start(): BunServer<WsData> {
+    const bunServer = Bun.serve<WsData>({
+      port,
+      fetch(req, server) {
+        const url = new URL(req.url)
+        if (url.pathname === '/portbroker') {
+          if (!containerBroker) return new Response('portbroker disabled', { status: 404 })
+          const data: BrokerWsData = { kind: 'portbroker', authed: false }
+          if (server.upgrade(req, { data })) return
+          return new Response('upgrade failed', { status: 400 })
+        }
+        const sessionId = crypto.randomUUID()
+        const data: TuiWsData = { kind: 'tui', sessionId }
+        if (server.upgrade(req, { data })) return
+        return new Response('typeclaw agent', { status: 200 })
+      },
+      websocket: {
+        async open(rawWs) {
+          if (rawWs.data.kind === 'portbroker') {
+            containerBroker?.open(rawWs as ServerWebSocket<BrokerWsData>)
+            return
+          }
+          const ws = rawWs as Ws
+          const sessionManager = sessionFactory?.createPersisted()
+          const sessionFileId = sessionManager?.getSessionId() ?? ws.data.sessionId
+          // Snapshot the runtime once so the entire session lifecycle for this
+          // ws connection sees one consistent generation of registry+hooks. A
+          // reload landing mid-connection swaps the live pointer; this session
+          // keeps using the snapshot it was created with until close.
+          const runtimeSnapshot = pluginRuntime?.get()
+          const pluginsWiring =
+            runtimeSnapshot !== undefined && agentDir !== undefined
+              ? {
+                  registry: runtimeSnapshot.registry,
+                  hooks: runtimeSnapshot.hooks,
+                  sessionId: sessionFileId,
+                  agentDir,
+                }
+              : undefined
+          const origin: SessionOrigin = { kind: 'tui', sessionId: sessionFileId }
+          const result = await createSession({
+            reloadRegistry,
+            sessionManager,
+            origin,
+            ...(stream ? { stream } : {}),
+            ...(channelRouter ? { channelRouter } : {}),
+            ...(pluginsWiring ? { plugins: pluginsWiring } : {}),
+            ...(containerName !== undefined ? { containerName } : {}),
+          })
+          const session = 'session' in result ? result.session : result
+          const dispose = 'session' in result && result.dispose ? result.dispose : async () => {}
+
+          const state: SessionState = {
+            session,
+            sessionFileId,
+            origin,
+            sessionManager,
+            drainQueue: [],
+            draining: false,
+            unsubBroadcast: null,
+            unsubPrompts: null,
+            runtimeSnapshot: runtimeSnapshot ?? null,
+            dispose,
+          }
+          sessionStates.set(ws, state)
+
+          if (runtimeSnapshot !== undefined && agentDir !== undefined) {
+            await runtimeSnapshot.hooks.runSessionStart({ sessionId: sessionFileId, agentDir })
+          }
+
+          forwardSessionEvents(ws, session)
+
+          if (stream) {
+            state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
+              enqueuePrompt(ws, state, msg),
+            )
+
+            state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
+              const payload: ServerMessage = {
+                type: 'notification',
+                payload: msg.payload,
+                ...(msg.replyTo !== undefined ? { replyTo: msg.replyTo } : {}),
+                ...(msg.meta !== undefined ? { meta: msg.meta } : {}),
+              }
+              send(ws, payload)
+            })
+          }
+
+          send(ws, { type: 'connected', sessionId: sessionFileId })
+          console.log(`session ${sessionFileId}: open`)
+        },
+        async message(rawWs, raw) {
+          if (rawWs.data.kind === 'portbroker') {
+            await containerBroker?.message(rawWs as ServerWebSocket<BrokerWsData>, raw as string | Buffer)
+            return
+          }
+          const ws = rawWs as Ws
+          const msg = JSON.parse(String(raw)) as ClientMessage
+          const state = sessionStates.get(ws)
+
+          if (msg.type === 'reload') {
+            await handleReload(ws, reloadAll, reloadRegistry, msg.scope)
+            return
+          }
+
+          if (msg.type === 'abort') {
+            if (!state) return
+            await state.session.abort()
+            return
+          }
+
+          if (msg.type === 'queue_cancel') {
+            if (!state) return
+            const before = state.drainQueue.length
+            state.drainQueue = state.drainQueue.filter((q) => q.streamMessageId !== msg.messageId)
+            if (state.drainQueue.length !== before) pushQueueState(ws, state)
+            return
+          }
+
+          if (msg.type === 'prompt') {
+            if (!state) return
+            if (stream) {
+              stream.publish({
+                target: { kind: 'session', sessionId: state.sessionFileId },
+                payload: { kind: 'prompt', text: msg.text, delivery: msg.delivery ?? 'queue' },
+                meta: { source: 'tui' },
+              })
+              return
+            }
+            send(ws, { type: 'prompt_started', messageId: `local-${crypto.randomUUID()}`, text: msg.text })
+            try {
+              await state.session.prompt(msg.text)
+              send(ws, { type: 'done' })
+            } catch (err) {
+              send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
+            }
+            const fallbackHooks = state.runtimeSnapshot?.hooks
+            if (fallbackHooks !== undefined) {
+              await fallbackHooks.runSessionIdle({
+                sessionId: state.sessionFileId,
+                parentTranscriptPath: state.sessionManager?.getSessionFile(),
+                idleMs: 0,
+              })
+            }
+            return
+          }
+        },
+        async close(rawWs) {
+          if (rawWs.data.kind === 'portbroker') {
+            containerBroker?.close(rawWs as ServerWebSocket<BrokerWsData>)
+            return
+          }
+          const ws = rawWs as Ws
+          const state = sessionStates.get(ws)
+          state?.unsubBroadcast?.()
+          state?.unsubPrompts?.()
+          try {
+            if (state && state.runtimeSnapshot !== null) {
+              await state.runtimeSnapshot.hooks.runSessionEnd({ sessionId: state.sessionFileId })
+            }
+          } finally {
+            if (state) {
+              state.session.dispose()
+              await state.dispose()
+            }
+            sessionStates.delete(ws)
+            console.log(`session ${state?.sessionFileId ?? ws.data.sessionId}: close`)
+          }
+        },
+      },
+    })
+
+    console.log(`typeclaw agent listening on ws://localhost:${bunServer.port}`)
+    return bunServer
+  }
+
+  return { start }
+}
+
+function forwardSessionEvents(ws: Ws, session: AgentSession): void {
+  const toolStartedAt = new Map<string, number>()
+
+  session.subscribe((event) => {
+    switch (event.type) {
+      case 'message_update':
+        if (event.assistantMessageEvent.type === 'text_delta') {
+          send(ws, { type: 'text_delta', delta: event.assistantMessageEvent.delta })
+        }
+        break
+      case 'message_end':
+        // pi-coding-agent encodes upstream LLM failures (billing, rate limit,
+        // network, malformed response, etc.) in the assistant message itself
+        // rather than throwing — `stopReason: 'error'` with a populated
+        // `errorMessage`. Without this branch the user sees an empty turn
+        // because no text deltas were ever emitted, which looks like a freeze.
+        // The server's existing try/catch around `session.prompt()` only
+        // catches throws, so it never sees these.
+        forwardAssistantError(ws, event.message)
+        break
+      case 'tool_execution_start':
+        toolStartedAt.set(event.toolCallId, Date.now())
+        send(ws, {
+          type: 'tool_start',
+          toolCallId: event.toolCallId,
+          name: event.toolName,
+          args: event.args,
+        })
+        break
+      case 'tool_execution_end': {
+        const startedAt = toolStartedAt.get(event.toolCallId)
+        toolStartedAt.delete(event.toolCallId)
+        const durationMs = startedAt === undefined ? 0 : Date.now() - startedAt
+        send(ws, {
+          type: 'tool_end',
+          toolCallId: event.toolCallId,
+          name: event.toolName,
+          error: event.isError,
+          result: event.result,
+          durationMs,
+        })
+        break
+      }
+    }
+  })
+}
+
+function forwardAssistantError(ws: Ws, message: unknown): void {
+  if (typeof message !== 'object' || message === null) return
+  const m = message as { role?: string; stopReason?: string; errorMessage?: string }
+  if (m.role !== 'assistant') return
+  if (m.stopReason !== 'error' && m.stopReason !== 'aborted') return
+  // 'aborted' is fired when the user hits Escape — don't surface it as an
+  // error message because the TUI already shows abort feedback elsewhere.
+  if (m.stopReason === 'aborted') return
+  const text = typeof m.errorMessage === 'string' && m.errorMessage.length > 0 ? m.errorMessage : 'LLM call failed'
+  send(ws, { type: 'error', message: text })
+}
+
+function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage): void {
+  const payload = msg.payload as { kind?: string; text?: string; delivery?: PromptDelivery }
+  if (payload?.kind !== 'prompt' || typeof payload.text !== 'string') return
+  const delivery: PromptDelivery = payload.delivery ?? 'queue'
+  if (delivery === 'interrupt') {
+    void state.session.abort().catch((err) => {
+      send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
+    })
+  }
+  state.drainQueue.push({
+    streamMessageId: msg.id,
+    text: payload.text,
+    delivery,
+    ts: msg.ts,
+  })
+  pushQueueState(ws, state)
+  void drain(ws, state)
+}
+
+// `session.idle` semantically means "the agent finished a prompt and is now
+// awaiting next input". Plugins (notably the bundled memory plugin) own any
+// debouncing on top of this signal. Core fires the hook synchronously after
+// every `prompt()` completion (success or error), passing the current
+// transcript path so plugins can spawn subagents that read it.
+function makeIdleHookCaller(state: SessionState): () => Promise<void> {
+  const hooks: HookBus | undefined = state.runtimeSnapshot?.hooks
+  if (hooks === undefined) return async () => {}
+  return async () => {
+    await hooks.runSessionIdle({
+      sessionId: state.sessionFileId,
+      parentTranscriptPath: state.sessionManager?.getSessionFile(),
+      idleMs: 0,
+      origin: state.origin,
+    })
+  }
+}
+
+async function drain(ws: Ws, state: SessionState): Promise<void> {
+  if (state.draining) return
+  state.draining = true
+  const fireIdle = makeIdleHookCaller(state)
+  try {
+    while (state.drainQueue.length > 0) {
+      const item = state.drainQueue.shift()
+      if (!item) break
+      pushQueueState(ws, state)
+      send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
+
+      try {
+        await state.session.prompt(item.text)
+        send(ws, { type: 'done' })
+      } catch (err) {
+        send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
+      }
+      await fireIdle()
+    }
+  } finally {
+    state.draining = false
+  }
+}
+
+function pushQueueState(ws: Ws, state: SessionState): void {
+  const pending: QueueStateItem[] = state.drainQueue.map((q) => ({
+    id: q.streamMessageId,
+    text: q.text,
+    ts: q.ts,
+  }))
+  send(ws, { type: 'queue_state', pending })
+}
+
+async function handleReload(
+  ws: Ws,
+  reloadAll: ReloadAllFn | undefined,
+  reloadRegistry: ReloadRegistry | undefined,
+  scope: string | undefined,
+): Promise<void> {
+  if (scope !== undefined && scope.length > 0) {
+    if (!reloadRegistry) {
+      send(ws, {
+        type: 'reload_result',
+        results: [{ scope, ok: false, reason: 'no reload registry configured' }],
+      })
+      return
+    }
+    try {
+      const result = await reloadRegistry.reloadOne(scope)
+      send(ws, { type: 'reload_result', results: [result] })
+    } catch (err) {
+      send(ws, {
+        type: 'reload_result',
+        results: [{ scope, ok: false, reason: err instanceof Error ? err.message : String(err) }],
+      })
+    }
+    return
+  }
+
+  if (!reloadAll) {
+    const empty: ReloadResultPayload[] = []
+    send(ws, { type: 'reload_result', results: empty })
+    return
+  }
+  try {
+    const { results } = await reloadAll()
+    send(ws, { type: 'reload_result', results })
+  } catch (err) {
+    send(ws, {
+      type: 'reload_result',
+      results: [{ scope: 'reload', ok: false, reason: err instanceof Error ? err.message : String(err) }],
+    })
+  }
+}

package/src/sessions/index.ts

@@ -0,0 +1,23 @@
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { SessionManager } from '@mariozechner/pi-coding-agent'
+
+export type SessionFactory = {
+  createPersisted(): SessionManager
+  sessionDir(): string
+}
+
+export type CreateSessionFactoryOptions = {
+  agentDir: string
+}
+
+export function createSessionFactory({ agentDir }: CreateSessionFactoryOptions): SessionFactory {
+  const dir = join(agentDir, 'sessions')
+  mkdirSync(dir, { recursive: true })
+
+  return {
+    createPersisted: () => SessionManager.create(agentDir, dir),
+    sessionDir: () => dir,
+  }
+}

package/src/shared/index.ts

@@ -0,0 +1,9 @@
+export {
+  type ClientMessage,
+  type PromptDelivery,
+  type QueueStateItem,
+  type ReloadResultPayload,
+  type ServerMessage,
+} from './protocol'
+
+export { formatLocalDate, formatLocalDateTime } from './local-time'

package/src/shared/local-time.ts

@@ -0,0 +1,21 @@
+function pad2(n: number): string {
+  return String(n).padStart(2, '0')
+}
+
+export function formatLocalDate(date: Date = new Date()): string {
+  return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`
+}
+
+export function formatLocalDateTime(date: Date = new Date()): string {
+  const datePart = formatLocalDate(date)
+  const timePart = `${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`
+  const offset = formatTimezoneOffset(date)
+  return `${datePart}T${timePart}${offset}`
+}
+
+function formatTimezoneOffset(date: Date): string {
+  const offsetMinutes = -date.getTimezoneOffset()
+  const sign = offsetMinutes >= 0 ? '+' : '-'
+  const abs = Math.abs(offsetMinutes)
+  return `${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`
+}

package/src/shared/protocol.ts

@@ -0,0 +1,25 @@
+export type ReloadResultPayload =
+  | { scope: string; ok: true; summary: string; details?: unknown }
+  | { scope: string; ok: false; reason: string }
+
+export type PromptDelivery = 'queue' | 'steer' | 'interrupt'
+
+export type ClientMessage =
+  | { type: 'prompt'; text: string; delivery?: PromptDelivery }
+  | { type: 'reload'; scope?: string }
+  | { type: 'abort' }
+  | { type: 'queue_cancel'; messageId: string }
+
+export type QueueStateItem = { id: string; text: string; ts: number }
+
+export type ServerMessage =
+  | { type: 'connected'; sessionId: string }
+  | { type: 'text_delta'; delta: string }
+  | { type: 'tool_start'; toolCallId: string; name: string; args: unknown }
+  | { type: 'tool_end'; toolCallId: string; name: string; error: boolean; result: unknown; durationMs: number }
+  | { type: 'done' }
+  | { type: 'error'; message: string }
+  | { type: 'reload_result'; results: ReloadResultPayload[] }
+  | { type: 'notification'; payload: unknown; replyTo?: string; meta?: Record<string, string> }
+  | { type: 'queue_state'; pending: QueueStateItem[] }
+  | { type: 'prompt_started'; messageId: string; text: string }

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

@@ -0,0 +1,87 @@
+---
+name: typeclaw-channel-kakaotalk
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `kakaotalk`. 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 file attachments. Read it before composing anything for KakaoTalk so you don't dump markdown into a chat window.
+---
+
+# typeclaw-channel-kakaotalk
+
+You are speaking through the `kakaotalk` channel adapter. The adapter wraps `agent-messenger`'s KakaoTalkClient/KakaoTalkListener, which speaks KakaoTalk's LOCO push protocol as a registered tablet sub-device of a real user account.
+
+This means **you are messaging as a person, not as a bot.** Other participants see your typeclaw account's name and profile photo. Match their tone — the people you're talking with assume they're talking to a human.
+
+## What KakaoTalk does NOT support
+
+If you produce any of the following, KakaoTalk will render it literally and the recipient will see the raw markup:
+
+- **Bold / italic / strikethrough** — `**bold**` shows as `**bold**`. Drop the asterisks; emphasize with word choice or capitalization (sparingly).
+- **Headings** — `# H1`, `## H2`, `### H3` all render as raw `#` characters.
+- **Tables** — pipe-delimited tables become a wall of `|` characters. Use bullet lists or short prose paragraphs instead.
+- **Code fences** — ``` blocks render as raw backticks. For short snippets, paste the code inline. For long snippets, summarize and offer to send it via another channel.
+- **Inline code** — `` `foo` `` renders as `` `foo` ``. Just write `foo`.
+- **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.
+- **Attachments** — the adapter is text-only. If the user asks you to send a file, say so and offer an alternative (paste a link, summarize the file, ship it via another channel).
+
+The adapter logs a warning the first time you try to send attachments and then drops them. The user-visible result is "your message arrived without the file."
+
+## 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.
+
+## Message length & cadence
+
+KakaoTalk is mobile-first. The reading surface is small and the user is on their phone. Keep messages **short and conversational**, not essay-length. If you have a long answer:
+
+1. Lead with a one-sentence summary.
+2. Optional: 2–4 short bullet-style lines (use `-` or `•` as line prefixes — the client renders them as text, not lists, but the visual rhythm still helps).
+3. Stop. If the user wants more, they will ask.
+
+Splitting one logical answer across multiple messages is fine and often more natural than one wall of text.
+
+## Engagement model
+
+The adapter exposes three engagement triggers via `channels.kakaotalk.engagement.trigger` in `typeclaw.json`:
+
+- `dm` — every message in a 1:1 chat. Default-on.
+- `reply` — every message in a chat where you sent the previous message. Default-on.
+- `mention` — KakaoTalk has no mention syntax in the protocol. The adapter reads this trigger as "respond when an alias from `alias[]` in `typeclaw.json` appears in the text". Without configured aliases, this trigger never fires.
+
+Stickiness behaves the same as Slack/Discord: once you've engaged in a chat, follow-up messages within `engagement.stickiness.perReply.window` ms will route to you regardless of trigger.
+
+If you find yourself NOT receiving messages you expect to, the most likely cause is the `allow` list. KakaoTalk uses a different grammar from Slack/Discord:
+
+- `kakao:*` — every chat the account can see (use sparingly: this is every group and DM you are a member of)
+- `kakao:dm/*` — every 1:1 chat
+- `kakao:group/*` — every multi-person group chat
+- `kakao:open/*` — every open chat
+- `kakao:<chat-id>` — a specific chat by numeric chat_id
+
+The init wizard's default is `kakao:dm/*` because group chats with personal accounts are sensitive — every member sees every reply. Only broaden the allow list when the user explicitly asks.
+
+## Mark read on every inbound
+
+The adapter sends a LOCO `NOTIREAD` ack to KakaoTalk for every inbound message event it observes. The sender's unread "1" (노란숫자) clears in their client as soon as the agent's container receives the bytes. This is always-on — there is no config flag to turn it off short of editing the source. (An earlier `channels.kakaotalk.autoMarkRead` opt-in field was removed; existing configs still parse but the field is ignored.)
+
+Things to know about this behavior:
+
+- Auto-acking every received message is a distinct behavioral fingerprint compared to a human. A human reads messages when they open the chat; this adapter acks every received message instantly, even ones you never reply to. KakaoTalk's abuse detection may flag accounts that ack rapidly and unconditionally. **Run the kakaotalk adapter only on dedicated agent accounts you can afford to lose.**
+- Dropped messages are still acked. If classify drops the message (your own self-sent loopback, empty text, sender not in `allow`), the unread "1" still clears — the agent has observed the bytes, so the read indicator should match.
+- Open chats (오픈채팅) are skipped: the LOCO `NOTIREAD` packet needs a `linkId` for open chats and the adapter doesn't surface it yet. Unread counters in open chats will not decrement.
+- The phone's home-screen OS unread badge may lag until the phone client foregrounds; the in-chat counter and other participants' indicators update immediately. KakaoTalk client quirk, not a typeclaw bug.
+
+If a markRead call fails (network blip, non-success status from the server, container shutdown), it is logged at warn level (`[kakaotalk] mark-read failed: ...`) and silently moves on — message delivery is never blocked by an ack failure.
+
+## Self-loop guard
+
+The adapter drops every inbound where `event.author_id` equals the logged-in account's `user_id`. Two typeclaw agents talking to each other through KakaoTalk would otherwise loop indefinitely (KakaoTalk has no bot-flag, so neither side can detect the other is automated). Do not try to defeat this guard.
+
+## 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.

package/src/skills/typeclaw-channel-telegram-bot/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: typeclaw-channel-telegram-bot
+description: "How replies sent through the `telegram-bot` channel adapter actually render in Telegram. Read this BEFORE composing a reply that contains formatting markers — `**bold**`, `*italic*`, `_italic_`, `` `code` ``, fenced code blocks (```), `[label](url)`, `~~strike~~`, `||spoiler||`, `# heading`, `- list`, `| table |`, raw `.` `!` `(` `)` `_` `*` punctuation in URLs/IDs, snake_case identifiers — and your draft is going to a Telegram chat or supergroup. Also load if a Telegram user reports your message arrived as raw markdown (literal `**asterisks**`), as garbled text with stray backslashes, or with a Telegram error like `Bad Request: can't parse entities`. Covers: which markers actually render, which ones are stripped or escaped, what Telegram has no equivalent for (headings, bulleted/numbered lists, tables — they fall through as escaped literals), how the adapter's MarkdownV2 escaping behaves, and how to keep your message readable when the rendering and the source diverge."
+---
+
+# typeclaw-channel-telegram-bot
+
+When you reply through the `telegram-bot` channel adapter, your text does NOT go to Telegram unchanged. It goes through `toTelegramMarkdownV2` in `src/channels/adapters/telegram-bot-format.ts`, which translates the common Markdown you write into Telegram's strict **MarkdownV2** dialect and escapes every reserved char that isn't part of a recognized formatting marker. The Telegram Bot API is then called with `parse_mode: 'MarkdownV2'`.
+
+This is necessary because Telegram's MarkdownV2 parser is unforgiving: any unescaped `_ * [ ] ( ) ~ \` > # + - = | { } . !`outside an entity returns`Bad Request: can't parse entities`and the whole message is rejected. Plain text would never crash, but then your`**bold**`would render as the literal six characters`**bold**` — which is the bug this skill exists to prevent you from re-introducing on the user side ("just write what you mean, the adapter will handle it").
+
+## What the adapter renders
+
+These markers translate to native Telegram formatting:
+
+- `**bold**` → bold (renders as `*bold*` on the wire — MarkdownV2 reserves `*` for bold)
+- `__bold__` → bold (when not adjacent to a word char on either side; otherwise treated as literal underscores so `my__var__name` stays a snake_case identifier)
+- `*italic*` → italic (when the asterisks are NOT between word chars — `a*b*c` stays literal)
+- `_italic_` → italic (same word-boundary rule as `*italic*` — `var_name` stays an identifier)
+- `` `inline code` `` → monospace inline code
+- ` ```language\n...code...\n``` ` → fenced code block; the optional language tag rides through (Telegram displays it but does no syntax highlighting)
+- `[label](url)` → clickable hyperlink
+- `~~strike~~` → strikethrough
+- `||spoiler||` → spoiler (tap to reveal)
+
+Empty markers (`****`, ` `` `, `~~~~`, `||||`) are NOT emitted as zero-width entities; they fall through as escaped literals. Telegram rejects empty entities, and the adapter's safety pass catches this for you.
+
+## What the adapter does NOT render
+
+Telegram's MarkdownV2 has no native rendering for any of these. They fall through as escaped literal characters — visible in the message, but not formatted:
+
+- `# Heading`, `## Heading 2`, etc. — appear as `\# Heading` / `\## Heading 2` (the `#` shows but it's not a heading)
+- `- item` / `* item` / `1. item` (bulleted or numbered lists) — the markers escape to `\-` / `\*` / `1\.` and the message stays a plain paragraph with line breaks; Telegram users see the dash or number, not a styled list
+- `| col | col |\n|---|---|\n` (Markdown tables) — every `|` and `-` escapes; the result is illegible. Don't send tables. Send a fenced code block with aligned columns instead.
+- `> quote` — the `>` escapes to `\>`; Telegram does have a native blockquote syntax but the agent's common-Markdown writer has no way to opt into it through this adapter today
+- HTML tags (`<b>`, `<i>`, `<a>`) — the adapter does NOT use HTML mode; tag chars escape and the literal `<b>foo</b>` shows up
+
+When you need any of these effects, **rewrite the message** to use what Telegram does support (bold for emphasis instead of headings; bullet points written as separate lines with bold leading words instead of `-` markers; aligned-column code fences instead of tables).
+
+## Punctuation rules you can stop worrying about
+
+You do NOT need to manually escape any of `_ * [ ] ( ) ~ \` > # + - = | { } . !` in your draft. The adapter handles it.
+
+- Periods, exclamation points, hyphens, plus signs in prose — type them naturally; the adapter escapes them.
+- Snake_case identifiers (`my_var_name`, `foo__bar__baz`) — type them naturally; the word-boundary guards keep them from italicizing.
+- Math/code asterisks in prose (`a*b*c`, `2 * 3 = 6`) — same; the word-boundary guards keep them literal.
+- URLs containing `_`, `.`, `-`, `~` — they pass through fine inside `[label](url)`.
+
+URLs containing **unescaped parentheses** (Wikipedia-style `Foo_(bar)`) intentionally fall back to escaped literal text rather than render as a link — the adapter cannot disambiguate the closing `)` from a content paren. If you need to link such a URL, percent-encode the parens in the URL (`%28`, `%29`) before putting it in the link.
+
+## When the user says "your formatting looks broken"
+
+Three classes of failure to triage in this order:
+
+1. **Literal `**asterisks**` in the rendered message.** Means the adapter was bypassed (someone shipped a regression that flipped `parse_mode` off). Check `src/channels/adapters/telegram-bot.ts` — `sendMessage` MUST include `{ parse_mode: 'MarkdownV2' }` and the text must come from `toTelegramMarkdownV2(...)`. The mutation-guard test in `telegram-bot-outbound.test.ts` exists exactly to catch this.
+2. **Visible backslashes (e.g. `v1\.2\.3`).** Means the user is on a Telegram client too old to honor MarkdownV2 entity-rendering, OR the message was forwarded to a context that doesn't (rare). Nothing the adapter can do — the wire format is correct.
+3. **Telegram error: `Bad Request: can't parse entities`.** Means the formatter emitted invalid MarkdownV2 — either an entity-rule edge case the formatter mishandled, or the agent wrote something pathological (e.g. a literal MarkdownV2-escaped fragment by hand). File a bug against the formatter with the exact input string; do not work around it by sending plain text (that loses formatting for everyone).
+
+## File pointers
+
+- `src/channels/adapters/telegram-bot.ts` — adapter; `createOutboundCallback` is where rendering happens.
+- `src/channels/adapters/telegram-bot-format.ts` — the formatter; pure, no dependencies, fully tested.
+- `src/channels/adapters/telegram-bot-format.test.ts` — every formatter rule above is mutation-guarded by a named test here.
+- `src/channels/adapters/telegram-bot-outbound.test.ts` — the integration mutation guard that pins `parse_mode: 'MarkdownV2'`.