typeclaw 0.23.0 → 0.24.0

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

@@ -1,5 +1,6 @@
 import { createHmac, timingSafeEqual } from 'node:crypto'
 
+import type { GithubReviewOn } from '@/channels/schema'
 import type { InboundMessage } from '@/channels/types'
 
 import type { GithubAuthContext } from './auth'
@@ -23,6 +24,14 @@ export type GithubWebhookHandlerOptions = {
   // an appended operator-policy note telling the agent not to submit an APPROVE
   // review; the github skill keys off that note to downgrade approve→COMMENT.
   allowApprove?: () => boolean
+  // Which pull_request action triggers an agent code review. Defaults to
+  // 'review_requested' when omitted, preserving the request-driven behavior.
+  // 'opened' additionally wakes the bot to review every PR the moment it opens;
+  // 'off' suppresses the dedicated review-trigger synthesis entirely (an
+  // explicit review_requested no longer wakes a session). Orthogonal to the
+  // eventAllowlist (the outer "process this webhook?" gate) — this is the inner
+  // "does an admitted pull_request event become a review-trigger inbound?" gate.
+  reviewOn?: () => GithubReviewOn
   route: (message: InboundMessage) => void
   logger: GithubInboundLogger
   // Optional: resolves whether the bot is a member of the given team. When
@@ -75,6 +84,7 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     const classified = classifyGithubInbound(event, payload, selfLogin, {
       teamIsBotMember,
       authType: options.authType?.() ?? 'pat',
+      reviewOn: options.reviewOn?.() ?? 'review_requested',
     })
     if (classified === null) return ok()
 
@@ -173,7 +183,7 @@ export function classifyGithubInbound(
   event: string,
   payload: Record<string, unknown>,
   selfLogin: string | null,
-  options?: { teamIsBotMember?: boolean; authType?: 'pat' | 'app' },
+  options?: { teamIsBotMember?: boolean; authType?: 'pat' | 'app'; reviewOn?: GithubReviewOn },
 ): InboundMessage | null {
   const repository = readRepository(payload)
   if (repository === null) return null
@@ -248,14 +258,22 @@ export function classifyGithubInbound(
     const number = readNumber(issue, 'number')
     const id = readNumber(issue, 'id') ?? number
     if (number === null || id === null) return null
+    const action = readString(payload, 'action')
+    const opener = readUser(issue.user)
+    const hasBody = readString(issue, 'body')?.trim() ? true : false
+    const text =
+      action === 'opened'
+        ? bodyOrOpenedTitle(issue.body, opener, 'issue', number, readString(issue, 'title'))
+        : issue.body
     return buildInbound(
       { ...base, chat: `issue:${number}`, thread: null },
-      issue.body,
+      text,
       id,
-      readUser(issue.user),
+      opener,
       selfLogin,
       issue.created_at,
       { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
+      action === 'opened' && !hasBody,
     )
   }
 
@@ -266,7 +284,12 @@ export function classifyGithubInbound(
     const id = readNumber(pr, 'id') ?? number
     if (number === null || id === null) return null
     const action = readString(payload, 'action')
+    const reviewOn = options?.reviewOn ?? 'review_requested'
     if (action === 'review_requested' || action === 'review_request_removed') {
+      // `off` disables the dedicated review trigger: these two actions exist
+      // only to drive review-request behavior here, so under `off` they wake no
+      // session rather than falling through to awareness-only context.
+      if (reviewOn === 'off') return null
       return classifyReviewRequest({
         action,
         payload,
@@ -278,14 +301,30 @@ export function classifyGithubInbound(
         teamIsBotMember: options?.teamIsBotMember,
       })
     }
+    if (action === 'opened' && reviewOn === 'opened') {
+      const trigger = classifyOpenedReviewTrigger({
+        payload,
+        pr,
+        number,
+        base,
+        selfLogin,
+        authType: options?.authType ?? 'pat',
+      })
+      if (trigger !== null) return trigger
+    }
+    const opener = readUser(pr.user)
+    const hasBody = readString(pr, 'body')?.trim() ? true : false
+    const prText =
+      action === 'opened' ? bodyOrOpenedTitle(pr.body, opener, 'PR', number, readString(pr, 'title')) : pr.body
     return buildInbound(
       { ...base, chat: `pr:${number}`, thread: null },
-      pr.body,
+      prText,
       id,
-      readUser(pr.user),
+      opener,
       selfLogin,
       pr.created_at,
       { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
+      action === 'opened' && !hasBody,
     )
   }
 
@@ -296,14 +335,23 @@ export function classifyGithubInbound(
     const number = readNumber(pr, 'number')
     const id = readNumber(review, 'id')
     if (number === null || id === null) return null
+    const reviewer = readUser(review.user)
+    const body = readString(review, 'body')
+    const hasBody = body !== null && body.trim() !== ''
+    const text = hasBody
+      ? body
+      : reviewer !== null
+        ? synthesizeReviewStateText(reviewer.login, number, readString(pr, 'title'), readString(review, 'state'))
+        : ''
     return buildInbound(
       { ...base, chat: `pr:${number}`, thread: null },
-      review.body,
+      text,
       id,
-      readUser(review.user),
+      reviewer,
       selfLogin,
       review.submitted_at,
       null,
+      !hasBody,
     )
   }
 
@@ -313,14 +361,22 @@ export function classifyGithubInbound(
     const number = readNumber(discussion, 'number')
     const id = readNumber(discussion, 'id') ?? number
     if (number === null || id === null) return null
+    const action = readString(payload, 'action')
+    const opener = readUser(discussion.user)
+    const hasBody = readString(discussion, 'body')?.trim() ? true : false
+    const text =
+      action === 'created'
+        ? bodyOrOpenedTitle(discussion.body, opener, 'discussion', number, readString(discussion, 'title'))
+        : discussion.body
     return buildInbound(
       { ...base, chat: `discussion:${number}`, thread: null },
-      discussion.body,
+      text,
       id,
-      readUser(discussion.user),
+      opener,
       selfLogin,
       discussion.created_at,
       null,
+      action === 'created' && !hasBody,
     )
   }
 
@@ -418,6 +474,53 @@ function classifyReviewRequest(input: ReviewRequestInput): InboundMessage | null
   }
 }
 
+type OpenedReviewTriggerInput = {
+  payload: Record<string, unknown>
+  pr: Record<string, unknown>
+  number: number
+  base: Pick<InboundMessage, 'adapter' | 'workspace' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'>
+  selfLogin: string | null
+  authType: 'pat' | 'app'
+}
+
+function classifyOpenedReviewTrigger(input: OpenedReviewTriggerInput): InboundMessage | null {
+  const { payload, pr, number, base, selfLogin, authType } = input
+  if (selfLogin === null) return null
+  const sender = readUser(payload.sender) ?? readUser(pr.user)
+  if (sender === null) return null
+  // Defensive self-loop guard mirroring classifyReviewRequest: the handler-level
+  // self-author drop already discards bot-opened PRs, but the decoy account is a
+  // distinct login, so a decoy-opened PR would otherwise wake a self-review.
+  const decoyLogin = resolveDecoyReviewerLogin(selfLogin, authType)
+  if (sender.login === selfLogin || (decoyLogin !== null && sender.login === decoyLogin)) return null
+
+  const title = readString(pr, 'title') ?? `#${number}`
+  const head = readString(readRecord(pr.head), 'ref')
+  const baseRef = readString(readRecord(pr.base), 'ref')
+  const branchSegment = head !== null && baseRef !== null ? ` Branch: ${head} → ${baseRef}.` : ''
+  const text =
+    `@${sender.login} opened PR #${number}: "${title}".${branchSegment}` +
+    ' Please review the changes line-by-line and post your feedback.'
+
+  const updatedAt = readString(pr, 'updated_at') ?? ''
+  const prId = readNumber(pr, 'id') ?? number
+  const externalMessageId = `pr-${prId}-opened-${updatedAt}`
+
+  return {
+    ...base,
+    chat: `pr:${number}`,
+    thread: null,
+    text,
+    externalMessageId,
+    authorId: String(sender.id),
+    authorName: sender.login,
+    authorIsBot: sender.type === 'Bot',
+    isBotMention: true,
+    replyToBotMessageId: null,
+    ts: updatedAt !== '' ? Date.parse(updatedAt) || 0 : 0,
+  }
+}
+
 export type GithubReviewerTeam = { slug: string; id: number; org: string | null }
 
 export function readReviewerTeam(value: unknown): GithubReviewerTeam | null {
@@ -440,9 +543,21 @@ function buildInbound(
   selfLogin: string | null,
   rawTs: unknown,
   reactionTarget: GithubReactionTarget | null,
+  synthesizedAwareness = false,
 ): InboundMessage | null {
   if (user === null) return null
   const text = typeof rawText === 'string' ? rawText : ''
+  // A body-less inbound reaches engagement as contentless text; in a solo-human
+  // channel the fallback engages on it and the agent replies with a generic
+  // greeting. The other adapters drop empty text at their classifier — this is
+  // the matching guard. Events whose empty body still carries signal (review
+  // state, opened-PR/issue title) synthesize non-empty text upstream and so
+  // never reach this drop.
+  if (text.trim() === '') return null
+  // Synthesized awareness lines carry an `@author` prefix describing who acted;
+  // that handle is the author, never a third-party mention of the bot, so the
+  // body-text mention heuristic must not fire on it.
+  const isBotMention = !synthesizedAwareness && selfLogin !== null && text.includes(`@${selfLogin}`)
   return {
     ...key,
     text,
@@ -451,12 +566,48 @@ function buildInbound(
     authorId: String(user.id),
     authorName: user.login,
     authorIsBot: user.type === 'Bot',
-    isBotMention: selfLogin !== null && text.includes(`@${selfLogin}`),
+    isBotMention,
     replyToBotMessageId: null,
     ts: typeof rawTs === 'string' ? Date.parse(rawTs) || 0 : 0,
   }
 }
 
+function bodyOrOpenedTitle(
+  rawBody: unknown,
+  opener: GithubUser | null,
+  kind: 'issue' | 'PR' | 'discussion',
+  number: number,
+  title: string | null,
+): string {
+  const body = typeof rawBody === 'string' ? rawBody : ''
+  if (body.trim() !== '' || opener === null) return body
+  const label = title !== null && title.trim() !== '' ? `: "${title}"` : ''
+  return `@${opener.login} opened ${kind} #${number}${label}.`
+}
+
+// Neutral phrasing per review state — must never imply a review was requested
+// or that action is needed; a COMMENTED review in particular must not read as
+// "please review", which is the review-request path's wording.
+function synthesizeReviewStateText(
+  reviewer: string,
+  number: number,
+  title: string | null,
+  state: string | null,
+): string {
+  const label = title !== null && title.trim() !== '' ? `: "${title}"` : ''
+  // GitHub's pull_request_review webhook can send the state in either case
+  // depending on the source (webhook payload vs REST), so normalize before
+  // matching — an unmatched state would silently fall back to the neutral verb.
+  const normalized = state?.toLowerCase() ?? null
+  const verb =
+    normalized === 'approved'
+      ? 'approved'
+      : normalized === 'changes_requested'
+        ? 'requested changes on'
+        : 'submitted a review on'
+  return `@${reviewer} ${verb} PR #${number}${label}.`
+}
+
 async function resolveTeamMembership(
   event: string,
   payload: Record<string, unknown>,

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

@@ -21,6 +21,7 @@ import {
   parseListHooksPermissionStatus,
 } from './permission-guidance'
 import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
+import { createGithubReviewThreadResolver } from './review-thread-resolver'
 import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
 
@@ -137,6 +138,11 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     workspaceForChat: (chat) => workspaceByChat.get(chat) ?? null,
   })
   const membership = createGithubMembershipResolver({ token: authToken, fetchImpl })
+  const reviewThreadResolver = createGithubReviewThreadResolver({
+    token: authToken,
+    selfLogin: () => selfLogin,
+    fetchImpl,
+  })
   const channelNameResolver = createGithubChannelNameResolver({ token: authToken, fetchImpl })
   // GitHub addresses by `@login`, not the numeric id, so `username` carries
   // the login the model should type; the id is kept for completeness.
@@ -155,6 +161,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     selfLogin: () => selfLogin,
     authType: () => options.secrets.auth.type,
     allowApprove: () => options.configRef().review.approve,
+    reviewOn: () => options.configRef().review.on,
     isBotInTeam,
     authToken,
     fetchImpl,
@@ -187,6 +194,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       options.router.registerMembership('github', membership)
       options.router.registerChannelNameResolver('github', channelNameResolver)
       options.router.registerSelfIdentity('github', selfIdentityResolver)
+      options.router.registerReviewThreadResolver('github', reviewThreadResolver)
       options.router.registerFetchAttachment('github', fetchAttachment)
       try {
         server = (options.httpListenImpl ?? listenWithBun)(options.configRef().webhookPort, handler)
@@ -201,6 +209,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         options.router.unregisterMembership('github', membership)
         options.router.unregisterChannelNameResolver('github', channelNameResolver)
         options.router.unregisterSelfIdentity('github', selfIdentityResolver)
+        options.router.unregisterReviewThreadResolver('github', reviewThreadResolver)
         options.router.unregisterFetchAttachment('github', fetchAttachment)
         await auth.dispose()
         delete process.env.GH_TOKEN
@@ -324,6 +333,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       options.router.unregisterMembership('github', membership)
       options.router.unregisterChannelNameResolver('github', channelNameResolver)
       options.router.unregisterSelfIdentity('github', selfIdentityResolver)
+      options.router.unregisterReviewThreadResolver('github', reviewThreadResolver)
       options.router.unregisterFetchAttachment('github', fetchAttachment)
       await server?.stop()
       // Detach hooks AFTER closing the listener so any in-flight deliveries

package/src/channels/adapters/github/review-thread-resolver.ts

@@ -0,0 +1,246 @@
+import type { ReviewThreadResolveRequest, ReviewThreadResolveResult, ReviewThreadResolver } from '@/channels/types'
+
+import type { GithubAuthContext } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+const GRAPHQL_ENDPOINT = `${GITHUB_API_BASE}/graphql`
+
+// One page of review threads. `first: 100` is the GraphQL max; a busy PR can
+// carry more, so the resolver paginates until it matches the root comment id
+// or exhausts the pages — stopping early on a 404-equivalent (thread absent)
+// rather than fabricating a node id.
+const THREADS_QUERY = `query($owner:String!,$name:String!,$number:Int!,$after:String){repository(owner:$owner,name:$name){pullRequest(number:$number){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor}nodes{id isResolved comments(first:1){nodes{databaseId author{login}}}}}}}}`
+
+const RESOLVE_MUTATION = `mutation($threadId:ID!){resolveReviewThread(input:{threadId:$threadId}){thread{id isResolved}}}`
+
+type ReviewThreadNode = {
+  id: string
+  isResolved: boolean
+  rootCommentId: number | null
+  rootAuthorLogin: string | null
+}
+
+type ThreadLookup =
+  | { kind: 'found'; thread: ReviewThreadNode }
+  | { kind: 'absent' }
+  | { kind: 'error'; result: ReviewThreadResolveResult & { ok: false } }
+
+export function createGithubReviewThreadResolver(deps: {
+  token: (context?: GithubAuthContext) => Promise<string>
+  selfLogin: () => string | null
+  fetchImpl?: typeof fetch
+}): ReviewThreadResolver {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (req): Promise<ReviewThreadResolveResult> => {
+    if (req.adapter !== 'github') {
+      return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    }
+    const target = parseTarget(req)
+    if (target === null) {
+      return {
+        ok: false,
+        error: `unparseable github review-thread target (chat=${req.chat}, root=${req.rootCommentId})`,
+        code: 'transient',
+      }
+    }
+    const selfLogin = deps.selfLogin()
+    if (selfLogin === null) {
+      return {
+        ok: false,
+        error: 'github self-identity not resolved; cannot verify thread authorship',
+        code: 'transient',
+      }
+    }
+
+    const token = await deps.token({ repoSlug: `${target.owner}/${target.repo}` })
+    const lookup = await findThread(fetchImpl, token, target)
+    if (lookup.kind === 'error') return lookup.result
+    if (lookup.kind === 'absent') {
+      return {
+        ok: false,
+        error: `no review thread rooted at comment ${target.rootCommentId} on ${req.chat}`,
+        code: 'no-match',
+      }
+    }
+
+    const thread = lookup.thread
+    // The load-bearing guard: only the bot may resolve the bot's own thread.
+    // Resolving a human reviewer's thread would erase their open question.
+    if (thread.rootAuthorLogin !== selfLogin) {
+      return {
+        ok: false,
+        error: `refusing to resolve thread authored by @${thread.rootAuthorLogin ?? 'unknown'} (not @${selfLogin})`,
+        code: 'not-author',
+      }
+    }
+    if (thread.isResolved) return { ok: true, alreadyResolved: true }
+
+    return await runResolveMutation(fetchImpl, token, thread.id)
+  }
+}
+
+type ResolveTarget = { owner: string; repo: string; prNumber: number; rootCommentId: number }
+
+function parseTarget(req: ReviewThreadResolveRequest): ResolveTarget | null {
+  const [owner, repo, ...rest] = req.workspace.split('/')
+  if (owner === undefined || owner === '' || repo === undefined || repo === '' || rest.length > 0) return null
+  const prMatch = /^pr:(\d+)$/.exec(req.chat)
+  if (prMatch === null) return null
+  const prNumber = parseDecimalId(prMatch[1])
+  const rootCommentId = parseDecimalId(req.rootCommentId)
+  if (prNumber === null || rootCommentId === null) return null
+  return { owner, repo, prNumber, rootCommentId }
+}
+
+// Strict decimal-id parse: `Number()` would coerce '' -> 0, '1e2' -> 100, and
+// silently round ids past 2^53 (GitHub comment ids are large), any of which
+// could match the WRONG thread. Demand a plain run of digits and a safe
+// integer, so a malformed or oversized id fails closed (no resolution) rather
+// than resolving a collided thread.
+function parseDecimalId(value: string | undefined): number | null {
+  if (value === undefined || !/^\d+$/.test(value)) return null
+  const n = Number(value)
+  return Number.isSafeInteger(n) ? n : null
+}
+
+async function findThread(fetchImpl: typeof fetch, token: string, target: ResolveTarget): Promise<ThreadLookup> {
+  let after: string | null = null
+  for (;;) {
+    let response: Response
+    try {
+      response = await fetchImpl(GRAPHQL_ENDPOINT, {
+        method: 'POST',
+        headers: githubJsonHeaders(token),
+        body: JSON.stringify({
+          query: THREADS_QUERY,
+          variables: { owner: target.owner, name: target.repo, number: target.prNumber, after },
+        }),
+      })
+    } catch (err) {
+      return {
+        kind: 'error',
+        result: { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' },
+      }
+    }
+    const parsed = await parseThreadsPage(response)
+    if (parsed.kind === 'error') return { kind: 'error', result: parsed.result }
+
+    for (const node of parsed.nodes) {
+      if (node.rootCommentId === target.rootCommentId) return { kind: 'found', thread: node }
+    }
+    if (!parsed.hasNextPage || parsed.endCursor === null) return { kind: 'absent' }
+    after = parsed.endCursor
+  }
+}
+
+type ThreadsPage =
+  | { kind: 'ok'; nodes: ReviewThreadNode[]; hasNextPage: boolean; endCursor: string | null }
+  | { kind: 'error'; result: ReviewThreadResolveResult & { ok: false } }
+
+async function parseThreadsPage(response: Response): Promise<ThreadsPage> {
+  if (!response.ok) {
+    const text = await response.text().catch(() => '')
+    return {
+      kind: 'error',
+      result: {
+        ok: false,
+        error: `GitHub GraphQL ${response.status}${text !== '' ? `: ${text}` : ''}`,
+        code: classifyStatus(response.status),
+      },
+    }
+  }
+  const body = (await response.json().catch(() => null)) as GraphqlThreadsResponse | null
+  if (body === null)
+    return { kind: 'error', result: { ok: false, error: 'GitHub GraphQL returned non-JSON', code: 'transient' } }
+  if (body.errors !== undefined && body.errors.length > 0) {
+    return {
+      kind: 'error',
+      result: {
+        ok: false,
+        error: `GitHub GraphQL error: ${body.errors.map((e) => e.message).join('; ')}`,
+        code: 'transient',
+      },
+    }
+  }
+  const connection = body.data?.repository?.pullRequest?.reviewThreads
+  if (connection === undefined)
+    return {
+      kind: 'error',
+      result: { ok: false, error: 'GitHub GraphQL response missing reviewThreads', code: 'transient' },
+    }
+  const nodes = connection.nodes.map((n) => {
+    const root = n.comments.nodes[0]
+    return {
+      id: n.id,
+      isResolved: n.isResolved,
+      rootCommentId: root?.databaseId ?? null,
+      rootAuthorLogin: root?.author?.login ?? null,
+    }
+  })
+  return { kind: 'ok', nodes, hasNextPage: connection.pageInfo.hasNextPage, endCursor: connection.pageInfo.endCursor }
+}
+
+async function runResolveMutation(
+  fetchImpl: typeof fetch,
+  token: string,
+  threadId: string,
+): Promise<ReviewThreadResolveResult> {
+  let response: Response
+  try {
+    response = await fetchImpl(GRAPHQL_ENDPOINT, {
+      method: 'POST',
+      headers: githubJsonHeaders(token),
+      body: JSON.stringify({ query: RESOLVE_MUTATION, variables: { threadId } }),
+    })
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+  }
+  if (!response.ok) {
+    const text = await response.text().catch(() => '')
+    return {
+      ok: false,
+      error: `GitHub GraphQL ${response.status}${text !== '' ? `: ${text}` : ''}`,
+      code: classifyStatus(response.status),
+    }
+  }
+  const body = (await response.json().catch(() => null)) as GraphqlResolveResponse | null
+  if (body === null) return { ok: false, error: 'GitHub GraphQL returned non-JSON', code: 'transient' }
+  if (body.errors !== undefined && body.errors.length > 0) {
+    return {
+      ok: false,
+      error: `GitHub GraphQL error: ${body.errors.map((e) => e.message).join('; ')}`,
+      code: 'transient',
+    }
+  }
+  if (body.data?.resolveReviewThread?.thread?.isResolved === true) return { ok: true }
+  return { ok: false, error: 'resolveReviewThread mutation did not report isResolved', code: 'transient' }
+}
+
+function classifyStatus(status: number): 'permission-denied' | 'not-found' | 'transient' {
+  if (status === 401 || status === 403) return 'permission-denied'
+  if (status === 404) return 'not-found'
+  return 'transient'
+}
+
+type GraphqlThreadsResponse = {
+  data?: {
+    repository?: {
+      pullRequest?: {
+        reviewThreads?: {
+          pageInfo: { hasNextPage: boolean; endCursor: string | null }
+          nodes: Array<{
+            id: string
+            isResolved: boolean
+            comments: { nodes: Array<{ databaseId?: number; author?: { login?: string } }> }
+          }>
+        }
+      }
+    }
+  }
+  errors?: Array<{ message: string }>
+}
+
+type GraphqlResolveResponse = {
+  data?: { resolveReviewThread?: { thread?: { id: string; isResolved: boolean } } }
+  errors?: Array<{ message: string }>
+}

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

@@ -1,8 +1,8 @@
-import type { KakaoTalkPushMessageEvent } from 'agent-messenger/kakaotalk'
+import { KAKAO_MESSAGE_TYPE, type KakaoTalkPushMessageEvent } from 'agent-messenger/kakaotalk'
 
 import { matchesAnyAlias } from '@/channels/engagement'
 import type { ChannelAdapterConfig } from '@/channels/schema'
-import type { InboundAttachment, InboundMessage } from '@/channels/types'
+import type { InboundAttachment, InboundMessage, InboundReferenceContext } from '@/channels/types'
 
 export type InboundDropReason = 'self_author' | 'empty_text' | 'unknown_chat' | 'pre_connect' | 'bot_message'
 
@@ -49,7 +49,9 @@ export function classifyInbound(
     return { kind: 'drop', reason: 'bot_message' }
   }
 
-  const text = event.message ?? ''
+  const rawText = event.message ?? ''
+  const replyContext = parseReplyContext(event, context.selfUserId)
+  const text = rawText
   if (text === '') return { kind: 'drop', reason: 'empty_text' }
 
   const chatInfo = context.lookupChat(event.chat_id)
@@ -64,7 +66,7 @@ export function classifyInbound(
   // mention (see engagement.ts: alias is unconditional and ranks alongside
   // explicit triggers). Without aliases configured, only `reply` and `dm`
   // triggers can fire on KakaoTalk.
-  const aliasMatched = matchesAnyAlias(text, context.selfAliases ?? [])
+  const aliasMatched = matchesAnyAlias(rawText, context.selfAliases ?? [])
 
   return {
     kind: 'route',
@@ -74,6 +76,7 @@ export function classifyInbound(
       chat: event.chat_id,
       thread: null,
       text,
+      ...referenceContextPayload(replyContext),
       ...(context.attachments !== undefined && context.attachments.length > 0
         ? { attachments: context.attachments }
         : {}),
@@ -82,9 +85,9 @@ export function classifyInbound(
       authorName: event.author_name ?? String(event.author_id),
       authorIsBot: false,
       isBotMention: aliasMatched,
-      replyToBotMessageId: null,
+      replyToBotMessageId: replyContext?.target === 'bot' ? replyContext.logId : null,
       mentionsOthers: false,
-      replyToOtherMessageId: null,
+      replyToOtherMessageId: replyContext?.target === 'other' ? replyContext.logId : null,
       isDm: chatInfo.isDm,
       // SDK delivers `sent_at` in Unix seconds (LOCO `sendAt`); contract
       // wants ms (see `src/channels/types.ts`). Without `* 1000`, ms-based
@@ -93,3 +96,61 @@ export function classifyInbound(
     },
   }
 }
+
+type ParsedReplyContext = {
+  logId: string
+  authorId: string
+  authorName: string
+  quotedText: string | null
+  target: 'bot' | 'other'
+}
+
+function parseReplyContext(event: KakaoTalkPushMessageEvent, selfUserId: string): ParsedReplyContext | null {
+  if (event.message_type !== KAKAO_MESSAGE_TYPE.REPLY) return null
+  if (event.attachment === null) return null
+
+  const logId = stringField(event.attachment, 'src_logId')
+  const sourceUserId = numericField(event.attachment, 'src_userId')
+  if (logId === null || sourceUserId === null) return null
+
+  const sourceAuthorId = String(sourceUserId)
+  const quotedText = stringField(event.attachment, 'src_message')
+  return {
+    logId,
+    authorId: sourceAuthorId,
+    // classifyInbound is synchronous and has no cheap author resolver access;
+    // fall back to Kakao's stable source user id rather than fetching.
+    authorName: sourceAuthorId,
+    quotedText,
+    target: sourceAuthorId === selfUserId ? 'bot' : 'other',
+  }
+}
+
+function referenceContextPayload(
+  replyContext: ParsedReplyContext | null,
+): { referenceContext: InboundReferenceContext } | Record<string, never> {
+  if (replyContext === null || replyContext.quotedText === null || replyContext.quotedText.trim() === '') return {}
+  return {
+    referenceContext: {
+      kind: 'reply',
+      sources: [
+        {
+          adapter: 'kakaotalk',
+          authorId: replyContext.authorId,
+          authorName: replyContext.authorName,
+          text: replyContext.quotedText,
+        },
+      ],
+    },
+  }
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key]
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+function numericField(record: Record<string, unknown>, key: string): number | null {
+  const value = record[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}