typeclaw 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -46,7 +46,7 @@
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",
     "@mozilla/readability": "^0.6.0",
-    "agent-messenger": "2.18.0",
+    "agent-messenger": "2.19.0",
     "cheerio": "^1.2.0",
     "citty": "^0.2.2",
     "cron-parser": "^5.5.0",

package/src/agent/system-prompt.ts

@@ -12,7 +12,17 @@ TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your
 - **AGENTS.md** *(read on demand)* — your operating manual. Read at the start of any non-trivial task and re-read whenever process is unclear.
 - **\`memory/topics/\`** *(always injected below, READ-ONLY)* — sharded long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`; never edit memory shards directly.
 
-If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards.
+If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards. **Use this routing when you have something durable to record:**
+
+- *role, function, scope of work, who you are to this user* → IDENTITY.md
+- *voice, tone, register, language preferences, persona quirks* → SOUL.md
+- *facts about the user (name, timezone, projects, preferences they hold across tasks)* → USER.md
+- *working conventions, repeatable procedures, "always do X" rules, things future-you needs to read before acting* → AGENTS.md
+- *one-off context for this conversation only* → don't write a file; it'll be captured in \`memory/streams/\` automatically
+
+When in doubt between SOUL.md and AGENTS.md: if it describes *how you sound*, it's SOUL; if it describes *how you work*, it's AGENTS. Tone preferences ("be more terse") go to SOUL.md; process rules ("always run tests before committing") go to AGENTS.md.
+
+**Edit discipline.** Prefer rewriting in place to growing files. SOUL.md should stay short — a paragraph or two; if it's drifting past a screen, you're using it as a scratchpad and the model that reads it will start ignoring the back half. IDENTITY.md is similar — a few lines of who you are, not a résumé. AGENTS.md is the one allowed to grow. Don't rewrite SOUL.md on the first piece of tone feedback in a session — wait until the user repeats a preference or asks you directly to update it; a single off-day request isn't a durable change.
 
 ## Your workspace
 

package/src/agent/tools/skip-response.ts

@@ -39,10 +39,13 @@ export type SkipResponseDetails = {
 // `skip_response` is preferred whenever the model has a reason worth
 // recording. See session-origin.ts for the prompt-level decision rule.
 //
-// Order-dependence with `channel_reply`/`channel_send`: once `skip_response`
-// fires in a turn, the router rejects any subsequent tool-source send for
-// the same turn with `SKIP_RESPONSE_LOCK_ERROR`. The model gets a clear
-// error and learns to commit on the next turn instead of mid-turn.
+// Order-dependence with `channel_reply`/`channel_send` is asymmetric:
+//   - skip BEFORE any send → commits to silence; the router rejects any
+//     subsequent tool-source send this turn with `SKIP_RESPONSE_LOCK_ERROR`.
+//   - skip AFTER a send → accepted as a terminal no-op (`recorded-after-send`).
+//     The earlier reply stands; this posts nothing and ends the turn. Rejecting
+//     it (the old behavior) drove a livelock: denied a clean silent exit, the
+//     model re-sent, got re-denied on the next skip, and repeated to the cap.
 export function createSkipResponseTool({
   router,
   sessionId,
@@ -55,12 +58,14 @@ export function createSkipResponseTool({
       'Decline to send a user-facing reply this turn, with a logged reason. Use this ' +
       'instead of narrating "I have nothing to add" / "I will stay quiet" in your visible ' +
       'response. The reason is written to host logs (visible via `typeclaw logs -f`) but ' +
-      'never delivered to the user. The contract is bidirectional: after calling this, any ' +
-      '`channel_reply` / `channel_send` in the same turn will be rejected, AND calling this ' +
-      'after a `channel_reply` / `channel_send` has already landed in this turn will also ' +
-      'be rejected — commit to silence or commit to replying, not both. Decide before you ' +
-      'send, and call this as your terminal tool when you decide to stay silent. Prefer ' +
-      'this over the `NO_REPLY` text sentinel whenever you have a reason worth recording.',
+      'never delivered to the user. If you call this BEFORE sending anything this turn, it ' +
+      'commits you to silence and any later `channel_reply` / `channel_send` in the same ' +
+      'turn is rejected. If you call it AFTER a reply has already landed this turn (e.g. you ' +
+      'posted an ack and now want to wait quietly for a backgrounded subagent), it is ' +
+      'accepted as a terminal no-op: your earlier reply stands, nothing further is sent, and ' +
+      'your turn ends. Either way, call this as your terminal tool when you decide to stop ' +
+      'talking — do NOT keep sending "still working" updates. Prefer this over the ' +
+      '`NO_REPLY` text sentinel whenever you have a reason worth recording.',
     parameters: Type.Object({
       reason: Type.String({
         description:
@@ -85,33 +90,20 @@ export function createSkipResponseTool({
       }
 
       const result = router.markTurnSkipped({ parentSessionId: sessionId, reason })
-      if (result.kind === 'send-already-happened') {
-        // Symmetric counterpart of the send-after-skip lock in `router.send()`.
-        // The model already committed to replying earlier in this turn; calling
-        // skip_response now would land the reply AND claim silence at the same
-        // time, which is the contract violation the lock exists to prevent.
-        // Surface a clear error and refuse to stamp the flag so the rest of
-        // the turn behaves as a normal reply turn.
-        logger.warn(
-          formatChannelToolFailure(
-            'skip_response',
-            `channel send already happened this turn (reason=${JSON.stringify(reason)})`,
-          ),
-        )
-        const details: SkipResponseDetails = {
-          ok: false,
-          suppressed: false,
-          reason,
-          error: 'send-already-happened',
-        }
+      if (result.kind === 'recorded-after-send') {
+        // Reply-first skip: an ack already landed; this just ends the turn
+        // quietly. Not suppressed (the reply stands) and not an error (erroring
+        // here is what drove the historical re-send livelock). Router logged it.
+        const details: SkipResponseDetails = { ok: true, suppressed: false, reason }
         return {
           content: [
             {
               type: 'text' as const,
               text:
-                'skip_response denied: you already sent a channel reply in this turn. ' +
-                'Commit to silence or commit to replying, not both. ' +
-                'End your turn now; the reply you already sent stands.',
+                'skip_response accepted: your earlier channel reply this turn stands, and ' +
+                'no further message will be sent. End your turn now — do not send "still ' +
+                'working" updates while a backgrounded subagent runs; the completion ' +
+                'reminder will wake you when it finishes.',
             },
           ],
           details,

package/src/agent/tools/spawn-subagent.ts

@@ -103,6 +103,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
       if (params.description !== undefined) payload.description = params.description
 
       const startedAt = now()
+      const spawnedByRole = permissions?.resolveRole(origin)
       const { handle, completion } = startSubagent(subagentName, {
         registry,
         createSessionForSubagent,
@@ -110,6 +111,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
         userPrompt: params.prompt,
         payload: subagent.payloadSchema ? payload : undefined,
         parentSessionId,
+        ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
         ...(origin !== undefined ? { spawnedByOrigin: origin } : {}),
         taskId,
       })

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

@@ -393,7 +393,14 @@ export function createOutboundCallback(deps: {
     }
 
     try {
-      const sent = await client.sendMessage(msg.chat, text, msg.thread ? { thread_id: msg.thread } : undefined)
+      const sendOptions: { thread_id?: string; reply_to?: string } = {}
+      if (msg.thread) sendOptions.thread_id = msg.thread
+      if (msg.replyTo?.externalMessageId) sendOptions.reply_to = msg.replyTo.externalMessageId
+      const sent = await client.sendMessage(
+        msg.chat,
+        text,
+        Object.keys(sendOptions).length > 0 ? sendOptions : undefined,
+      )
       logger.info(`[discord-bot] sent id=${sent.id} ${tag}`)
       return { ok: true }
     } catch (err) {

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

@@ -45,7 +45,7 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
 
     const selfId = options.selfId()
     const selfLogin = options.selfLogin()
-    const author = readAuthor(payload)
+    const author = readAuthor(event, payload)
     if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
       options.logger.info(
         `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
@@ -363,13 +363,52 @@ function readRepository(payload: Record<string, unknown>): { owner: string; name
   return { owner: ownerLogin, name }
 }
 
-function readAuthor(payload: Record<string, unknown>): GithubUser | null {
-  const candidates = [payload.comment, payload.issue, payload.pull_request, payload.discussion, payload.review]
-  for (const candidate of candidates) {
+function readAuthor(event: string, payload: Record<string, unknown>): GithubUser | null {
+  for (const candidate of eventAuthorCandidates(event, payload)) {
     const user = readUser(readRecord(candidate)?.user)
     if (user !== null) return user
   }
-  return null
+  // Every GitHub webhook payload carries `sender` — the actor who triggered the
+  // delivery. It is the universal fallback so events not enumerated above (and
+  // any future ones the user adds to eventAllowlist) still drop self-authored
+  // deliveries instead of slipping past the guard.
+  return readUser(payload.sender)
+}
+
+// Maps each event to the entity whose `user` is the true author of THIS event,
+// listed before broader containers. A pull_request_review payload ships both
+// `pull_request` (the PR author) and `review` (the reviewer); the self-author
+// drop must see the reviewer, so `review` must come first. PR #455's flat order
+// (`pull_request` before `review`) made a self-review on someone else's PR
+// resolve to the PR author, slip past the drop, and loop (see PR #460).
+//
+// `pull_request` and `pull_request_review_thread` carry only the `pull_request`
+// container, whose `user` is the PR OPENER — not the actor of this delivery.
+// For these events the self-author question is "who triggered the action?"
+// (review_requested, edited, reopened, resolved, …), which is always
+// `payload.sender`, never the opener. Mapping them to `[]` makes readAuthor
+// skip the opener and fall through to the `sender` fallback. PR #462's
+// `['pull_request']` resolved to the opener, so a human action on a
+// bot-opened PR matched the bot and was wrongly dropped (the inbound landed
+// as awareness-only "Recent context" and the agent never replied).
+const PRIMARY_AUTHOR_KEYS: Record<string, readonly string[]> = {
+  issue_comment: ['comment'],
+  pull_request_review_comment: ['comment'],
+  discussion_comment: ['comment'],
+  commit_comment: ['comment'],
+  pull_request_review: ['review'],
+  pull_request_review_thread: [],
+  issues: ['issue'],
+  pull_request: [],
+  discussion: ['discussion'],
+  release: ['release'],
+}
+
+const FALLBACK_AUTHOR_KEYS = ['comment', 'review', 'issue', 'pull_request', 'discussion', 'release'] as const
+
+function eventAuthorCandidates(event: string, payload: Record<string, unknown>): unknown[] {
+  const keys = PRIMARY_AUTHOR_KEYS[event] ?? FALLBACK_AUTHOR_KEYS
+  return keys.map((key) => payload[key])
 }
 
 // Matches by id OR login. Issue #452 captured a self-responding loop where

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

@@ -53,6 +53,14 @@ export type GithubAdapterOptions = {
   // Test-only: replaces the wall-clock sleep used for the registration
   // delay above. Production leaves it undefined and we use `setTimeout`.
   sleep?: (ms: number) => Promise<void>
+  // How often to proactively refresh the token and update GH_TOKEN
+  // when the adapter is running but has not made an outbound API call
+  // recently. Zero disables the background refresh entirely.
+  // Default: 30 minutes.
+  tokenRefreshIntervalMs?: number
+  // Test-only: replaces `setInterval` so tests can control when the
+  // background refresh fires without waiting on real wall-clock time.
+  setInterval?: (handler: () => void, ms: number) => { clear: () => void }
 }
 
 export type GithubAdapter = {
@@ -68,6 +76,7 @@ const consoleLogger: GithubAdapterLogger = {
 }
 
 const DEFAULT_WEBHOOK_REGISTRATION_DELAY_MS = 2_000
+const DEFAULT_TOKEN_REFRESH_INTERVAL_MS = 30 * 60 * 1000
 
 export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
   const logger = options.logger ?? consoleLogger
@@ -83,6 +92,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   let selfLogin: string | null = null
   let started = false
   let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
+  let tokenRefreshTimer: { clear: () => void } | null = null
   const workspaceByChat = new Map<string, string>()
 
   const rememberWorkspace = (workspace: string, chat: string): void => {
@@ -168,6 +178,24 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       // automatically when within 5 minutes of expiry.
       process.env.GH_TOKEN = await auth.token()
       started = true
+      // Keep GH_TOKEN warm even when the adapter is only receiving inbound
+      // webhooks and not making outbound API calls. This prevents `gh` CLI
+      // calls from the agent from failing with 401 after the token expires.
+      const tokenRefreshIntervalMs = options.tokenRefreshIntervalMs ?? DEFAULT_TOKEN_REFRESH_INTERVAL_MS
+      if (tokenRefreshIntervalMs > 0) {
+        const refresh = () => {
+          tokenFn().catch((err) => {
+            logger.error(`[github] periodic token refresh failed: ${err instanceof Error ? err.message : String(err)}`)
+          })
+        }
+        const setIntervalFn =
+          options.setInterval ??
+          ((handler: () => void, ms: number) => {
+            const timer = setInterval(handler, ms)
+            return { clear: () => clearInterval(timer) }
+          })
+        tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
+      }
       logger.info(`[github] webhook listening on port ${options.configRef().webhookPort} as @${self.login}`)
       // Best-effort: App-only preflight that compares the installation's granted
       // permissions against the configured eventAllowlist and warns about gaps.
@@ -241,6 +269,10 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         logDeregistrationOutcome(logger, deregistration)
         managedHooks = []
       }
+      if (tokenRefreshTimer !== null) {
+        tokenRefreshTimer.clear()
+        tokenRefreshTimer = null
+      }
       await auth.dispose()
       delete process.env.GH_TOKEN
       server = null

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

@@ -0,0 +1,239 @@
+// KakaoTalk's LOCO protocol renders no rich text — bytes display verbatim, so
+// the agent's Markdown (`**bold**`, `### heading`, fenced ```blocks```) leaks
+// literal `*`/`#`/backtick noise into the chat. This strips the formatting
+// markers and keeps the content. Mirrors telegram-bot-format.ts, but emits
+// plain content instead of re-encoding to MarkdownV2. Links collapse to
+// `label (url)` so the destination survives; list/quote markers stay (they
+// read fine unrendered).
+
+export function toKakaoPlainText(input: string): string {
+  // Pull fenced code out first so a `*` inside a block is not re-tokenized as
+  // italic.
+  const out: string[] = []
+  let i = 0
+  while (i < input.length) {
+    if (matchesAt(input, i, '```')) {
+      const fenceEnd = findFenceEnd(input, i + 3)
+      if (fenceEnd !== -1) {
+        out.push(renderFence(input.slice(i + 3, fenceEnd)))
+        i = fenceEnd + 3
+        continue
+      }
+      // Unterminated fence — strip the open backticks and render the rest
+      // inline so we never infinite-loop and never drop the tail.
+      out.push(renderInline(stripLeadingFence(input.slice(i + 3))))
+      break
+    }
+    const nextFence = input.indexOf('```', i)
+    const segmentEnd = nextFence === -1 ? input.length : nextFence
+    out.push(renderLines(input.slice(i, segmentEnd)))
+    i = segmentEnd
+  }
+  return out.join('')
+}
+
+function matchesAt(s: string, idx: number, needle: string): boolean {
+  return s.slice(idx, idx + needle.length) === needle
+}
+
+function findFenceEnd(s: string, start: number): number {
+  return s.indexOf('```', start)
+}
+
+function stripLeadingFence(inner: string): string {
+  // Drop an optional language hint and the newline after an opening fence.
+  const newline = inner.indexOf('\n')
+  if (newline === -1) return inner
+  const candidate = inner.slice(0, newline).trim()
+  if (candidate === '' || /^[A-Za-z0-9_+\-.]+$/.test(candidate)) {
+    return inner.slice(newline + 1)
+  }
+  return inner
+}
+
+function renderFence(inner: string): string {
+  // Keep the code body verbatim, drop the fences and any language hint.
+  let body = inner
+  const newline = inner.indexOf('\n')
+  if (newline !== -1) {
+    const candidate = inner.slice(0, newline).trim()
+    if (candidate === '' || /^[A-Za-z0-9_+\-.]+$/.test(candidate)) {
+      body = inner.slice(newline + 1)
+    }
+  }
+  if (body.endsWith('\n')) body = body.slice(0, -1)
+  return body
+}
+
+// Strip per-line block markers (heading hashes, blockquote arrows) before
+// running the inline tokenizer on each line. List markers (`- `, `* `, `1.`)
+// are left intact — they read fine as plain text and signal structure.
+function renderLines(text: string): string {
+  const lines = text.split('\n')
+  const rendered = lines.map((line) => renderInline(stripBlockMarkers(line)))
+  return rendered.join('\n')
+}
+
+function stripBlockMarkers(line: string): string {
+  // `### heading` → `heading`; `> quote` → `quote`. Only acts on leading
+  // markers after optional indentation so mid-line `#`/`>` stay literal.
+  const heading = /^(\s*)#{1,6}\s+(.*)$/.exec(line)
+  if (heading !== null) return heading[1]! + heading[2]!
+  const quote = /^(\s*)>\s?(.*)$/.exec(line)
+  if (quote !== null) return quote[1]! + quote[2]!
+  return line
+}
+
+// Inline tokenizer. Recognizes (in priority order):
+//   1. Inline code:   `code`        → code
+//   2. Links:         [text](url)   → text (url)
+//   3. Bold:          **text** / __text__ → text
+//   4. Strikethrough: ~~text~~      → text
+//   5. Italic:        *text* / _text_     → text
+//
+// Bold is checked before italic so `**` is not eaten as two italic markers.
+// Word-boundary guards keep snake_case identifiers and `a*b` math from being
+// mistaken for emphasis — the same rules the Telegram formatter uses.
+function renderInline(text: string): string {
+  const out: string[] = []
+  let i = 0
+  while (i < text.length) {
+    const ch = text[i]!
+
+    if (ch === '`') {
+      const close = text.indexOf('`', i + 1)
+      if (close !== -1) {
+        out.push(text.slice(i + 1, close))
+        i = close + 1
+        continue
+      }
+    }
+
+    if (ch === '[') {
+      const link = parseLink(text, i)
+      if (link !== null) {
+        const label = renderInline(link.label)
+        out.push(link.url === '' ? label : `${label} (${link.url})`)
+        i = link.end
+        continue
+      }
+    }
+
+    if (ch === '*' && text[i + 1] === '*') {
+      const close = findClose(text, i + 2, '**')
+      if (close !== -1 && close > i + 2) {
+        out.push(renderInline(text.slice(i + 2, close)))
+        i = close + 2
+        continue
+      }
+    }
+    if (ch === '_' && text[i + 1] === '_' && !isWordChar(text[i - 1])) {
+      const close = findClose(text, i + 2, '__')
+      if (close !== -1 && close > i + 2 && !isWordChar(text[close + 2])) {
+        out.push(renderInline(text.slice(i + 2, close)))
+        i = close + 2
+        continue
+      }
+    }
+
+    if (ch === '~' && text[i + 1] === '~') {
+      const close = findClose(text, i + 2, '~~')
+      if (close !== -1 && close > i + 2) {
+        out.push(renderInline(text.slice(i + 2, close)))
+        i = close + 2
+        continue
+      }
+    }
+
+    if (ch === '*' && !isWordChar(text[i - 1])) {
+      const close = findInlineClose(text, i + 1, '*')
+      if (close !== -1 && !isWordChar(text[close + 1])) {
+        const inner = text.slice(i + 1, close)
+        if (inner !== '' && !/^\s|\s$/.test(inner)) {
+          out.push(renderInline(inner))
+          i = close + 1
+          continue
+        }
+      }
+    }
+    if (ch === '_' && !isWordChar(text[i - 1])) {
+      const close = findInlineClose(text, i + 1, '_')
+      if (close !== -1 && !isWordChar(text[close + 1])) {
+        const inner = text.slice(i + 1, close)
+        if (inner !== '' && !/^\s|\s$/.test(inner)) {
+          out.push(renderInline(inner))
+          i = close + 1
+          continue
+        }
+      }
+    }
+
+    out.push(ch)
+    i++
+  }
+  return out.join('')
+}
+
+function findClose(text: string, from: number, marker: string): number {
+  let i = from
+  while (i <= text.length - marker.length) {
+    if (text[i] === '\\') {
+      i += 2
+      continue
+    }
+    if (matchesAt(text, i, marker)) return i
+    i++
+  }
+  return -1
+}
+
+function findInlineClose(text: string, from: number, marker: string): number {
+  let i = from
+  while (i < text.length) {
+    if (text[i] === '\n') return -1
+    if (text[i] === '\\') {
+      i += 2
+      continue
+    }
+    if (matchesAt(text, i, marker)) return i
+    i++
+  }
+  return -1
+}
+
+function parseLink(text: string, start: number): { label: string; url: string; end: number } | null {
+  let i = start + 1
+  const labelStart = i
+  while (i < text.length) {
+    const c = text[i]!
+    if (c === '\\') {
+      i += 2
+      continue
+    }
+    if (c === ']') break
+    if (c === '\n') return null
+    i++
+  }
+  if (text[i] !== ']' || text[i + 1] !== '(') return null
+  const label = text.slice(labelStart, i)
+  const urlStart = i + 2
+  let j = urlStart
+  while (j < text.length) {
+    const c = text[j]!
+    if (c === '\\') {
+      j += 2
+      continue
+    }
+    if (c === ')') break
+    if (c === '(') return null
+    if (c === '\n') return null
+    j++
+  }
+  if (text[j] !== ')') return null
+  return { label, url: text.slice(urlStart, j), end: j + 1 }
+}
+
+function isWordChar(ch: string | undefined): boolean {
+  if (ch === undefined) return false
+  return /[A-Za-z0-9_]/.test(ch)
+}

package/src/channels/adapters/kakaotalk.ts

@@ -8,6 +8,7 @@ import {
   type KakaoMember,
   type KakaoMessage,
   type KakaoProfile,
+  type KakaoReplyTarget,
   type KakaoSendResult,
   type KakaoTalkListenerEventMap,
   type KakaoTalkPushEmoticonEvent,
@@ -15,7 +16,7 @@ import {
 } from 'agent-messenger/kakaotalk'
 import type { KakaoAccountCredentials, KakaoConfig, PendingLoginState } from 'agent-messenger/kakaotalk'
 
-import type { ChannelRouter } from '@/channels/router'
+import { prependQuoteAnchor, type ChannelRouter } from '@/channels/router'
 import type { ChannelAdapterConfig } from '@/channels/schema'
 import type {
   ChannelHistoryMessage,
@@ -39,6 +40,7 @@ import { createKakaoAuthorResolver, type KakaoAuthorResolver } from './kakaotalk
 import { createKakaoChannelResolver, type KakaoChannelResolver } from './kakaotalk-channel-resolver'
 import { classifyInbound, type InboundDropReason } from './kakaotalk-classify'
 import { createFetchAttachmentCallback } from './kakaotalk-fetch-attachment'
+import { toKakaoPlainText } from './kakaotalk-format'
 
 // Structural duck-type of the upstream KakaoTalkClient class. The upstream
 // type is a class with private fields, and TypeScript treats those
@@ -53,7 +55,7 @@ export interface KakaoTalkClient {
   ): Promise<this>
   getChats(options?: { all?: boolean; search?: string }): Promise<KakaoChat[]>
   getMessages(chatId: string, options?: { count?: number; from?: string }): Promise<KakaoMessage[]>
-  sendMessage(chatId: string, text: string): Promise<KakaoSendResult>
+  sendMessage(chatId: string, text: string, options?: { replyTo?: KakaoReplyTarget }): Promise<KakaoSendResult>
   sendAttachment(
     chatId: string,
     data: Uint8Array | Buffer,
@@ -160,6 +162,11 @@ export type KakaotalkAdapter = {
 
 export const KAKAO_HISTORY_LIMIT_MAX = 200
 
+// How far back to scan for a reply target's source message. Matches the upstream
+// CLI's window; an anchored reply targets the message just answered, so the
+// target is almost always near the head of this window.
+const KAKAO_REPLY_LOOKUP_COUNT = 100
+
 function formatLabel(name: string | undefined, id: string, prefix = ''): string {
   if (name === undefined || name === '' || name === id) return id
   return `${prefix}${name}(${id})`
@@ -171,7 +178,7 @@ async function readAttachmentBuffer(path: string): Promise<Buffer> {
 }
 
 export function createOutboundCallback(deps: {
-  client: Pick<KakaoTalkClient, 'sendMessage' | 'sendAttachment'>
+  client: Pick<KakaoTalkClient, 'sendMessage' | 'sendAttachment' | 'getMessages'>
   logger: KakaotalkAdapterLogger
   formatChannelTag: (workspace: string, chat: string) => Promise<string>
   readFile?: (path: string) => Promise<Buffer>
@@ -182,7 +189,7 @@ export function createOutboundCallback(deps: {
     if (msg.adapter !== 'kakaotalk') {
       return { ok: false, error: `unknown adapter: ${msg.adapter}` }
     }
-    const text = msg.text ?? ''
+    const text = toKakaoPlainText(msg.text ?? '')
     const attachments = msg.attachments ?? []
     if (text === '' && attachments.length === 0) {
       return { ok: false, error: 'message has neither text nor attachments' }
@@ -221,8 +228,26 @@ export function createOutboundCallback(deps: {
     }
 
     if (text !== '') {
+      // KakaoTalk's native reply payload is built from the *source* message
+      // (author, original text, type), which the SDK does not derive from a
+      // bare log_id — we resolve it from recent history. If that lookup can't
+      // find the target (scrolled past the window, or the fetch failed), we
+      // degrade to the same blockquote anchor the router uses for quote-mode
+      // adapters, so the reply still visibly references the right message.
+      let outboundText = text
+      let replyTarget: KakaoReplyTarget | undefined
+      if (msg.replyTo !== undefined) {
+        replyTarget = await resolveKakaoReplyTarget(client, msg.chat, msg.replyTo.externalMessageId, logger)
+        if (replyTarget === undefined && msg.replyTo.source !== undefined) {
+          outboundText = prependQuoteAnchor(text, msg.replyTo.source)
+        }
+      }
       try {
-        const result = await client.sendMessage(msg.chat, text)
+        const result = await client.sendMessage(
+          msg.chat,
+          outboundText,
+          replyTarget !== undefined ? { replyTo: replyTarget } : undefined,
+        )
         if (!result.success) {
           logger.error(`[kakaotalk] sendMessage status_code=${result.status_code} ${tag}`)
           return { ok: false, error: `kakaotalk send failed with status ${result.status_code}` }
@@ -239,6 +264,30 @@ export function createOutboundCallback(deps: {
   }
 }
 
+// KakaoTalk replies need the full source message, not just its log_id. Resolve
+// it from the chat's recent history (matching the upstream CLI's approach).
+// Returns undefined when the target isn't in the fetched window or the fetch
+// throws — the caller degrades to the blockquote fallback in that case.
+async function resolveKakaoReplyTarget(
+  client: Pick<KakaoTalkClient, 'getMessages'>,
+  chatId: string,
+  externalMessageId: string,
+  logger: KakaotalkAdapterLogger,
+): Promise<KakaoReplyTarget | undefined> {
+  try {
+    const messages = await client.getMessages(chatId, { count: KAKAO_REPLY_LOOKUP_COUNT })
+    const target = messages.find((m) => m.log_id === externalMessageId)
+    if (target === undefined) {
+      logger.warn(`[kakaotalk] reply target log_id=${externalMessageId} not in last ${KAKAO_REPLY_LOOKUP_COUNT}`)
+      return undefined
+    }
+    return { log_id: target.log_id, author_id: target.author_id, message: target.message, type: target.type }
+  } catch (err) {
+    logger.warn(`[kakaotalk] reply target lookup failed: ${describe(err)}`)
+    return undefined
+  }
+}
+
 export function createKakaoHistoryCallback(deps: {
   client: Pick<KakaoTalkClient, 'getMessages'>
   logger: KakaotalkAdapterLogger