typeclaw 0.37.3 → 0.37.5

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

@@ -61,56 +61,81 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     }
 
     const delivery = req.headers.get('x-github-delivery') ?? ''
-    if (delivery !== '' && options.dedup.has(delivery)) {
-      options.logger.info(`[github] duplicate delivery ignored id=${delivery}`)
-      return ok()
-    }
-
     const event = req.headers.get('x-github-event') ?? ''
     const payload = parseJson(body)
     if (payload === null) return ok()
-    const action = readString(payload, 'action')
-    if (!isGithubEventAllowed(options.allowlist(), event, action)) return ok()
-
-    const selfId = options.selfId()
-    const selfLogin = options.selfLogin()
-    const author = readAuthor(event, payload)
-    if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
-      maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
-      options.logger.info(
-        `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
-      )
-      return ok()
-    }
+    // The HTTP request is only transport; event handling is the shared core.
+    await processVerifiedGithubDelivery(options, { event, delivery, payload })
+    return ok()
+  }
+}
 
-    // A push to an open PR (`synchronize`) is not a message to react to — it is
-    // a trigger to re-evaluate the bot's own outstanding review obligations on
-    // this PR: unresolved review threads it authored AND a sticky
-    // CHANGES_REQUESTED block (which leaves no threads when filed as a top-level
-    // verdict — the black hole this path closes). Both need an API round-trip,
-    // so it runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
-    // session when an obligation is outstanding. Returning here also keeps
-    // synchronize out of the generic awareness-only fallthrough below.
-    if (event === 'pull_request' && action === 'synchronize') {
-      if (delivery !== '') options.dedup.add(delivery)
-      scheduleReviewFollowup({ payload, selfLogin, options })
-      return ok()
+// Post-verification core shared by the live HTTP handler AND the missed-delivery
+// recovery sweep (recover-failed-deliveries.ts), which pulls lost payloads from
+// GitHub's authenticated deliveries API and re-injects them with no HTTP request
+// or signature. Routing both through this one function is the load-bearing
+// invariant: recovery must never become a second, divergent event pipeline.
+// `delivery` is the `X-GitHub-Delivery` GUID (stable across redeliveries, equal
+// to a delivery's `guid`) used as the dedup key, so a recovered event and its
+// later/duplicate live delivery collapse to one route. HMAC is the caller's job:
+// the live handler verifies the body; the sweep trusts the authenticated API.
+export async function processVerifiedGithubDelivery(
+  options: GithubWebhookHandlerOptions,
+  input: { event: string; delivery: string; payload: Record<string, unknown> },
+): Promise<void> {
+  const { event, delivery, payload } = input
+  if (delivery !== '') {
+    if (options.dedup.has(delivery)) {
+      options.logger.info(`[github] duplicate delivery ignored id=${delivery}`)
+      return
     }
+    // Reserve the delivery id synchronously, BEFORE the awaits below, so a live
+    // webhook and the recovery sweep can never both clear the dedup gate for the
+    // same event and route it twice. JS is single-threaded: nothing else runs
+    // between this has-check and add, so the reservation is atomic. The awaits
+    // and classify that follow are all throw-safe, so reserving early cannot
+    // strand a routable event.
+    options.dedup.add(delivery)
+  }
 
-    const teamIsBotMember = await resolveTeamMembership(event, payload, options)
-    const reviewCommentParent = await resolveReviewCommentParent(event, payload, selfId, selfLogin, options)
-    const classified = classifyGithubInbound(event, payload, selfLogin, {
-      teamIsBotMember,
-      authType: options.authType?.() ?? 'pat',
-      reviewOn: options.reviewOn?.() ?? 'review_requested',
-      ...(reviewCommentParent !== null ? { reviewCommentParent } : {}),
-    })
-    if (classified === null) return ok()
-
-    if (delivery !== '') options.dedup.add(delivery)
-    options.route(withApprovalPolicy(classified, options.allowApprove?.() ?? true))
-    return ok()
+  const action = readString(payload, 'action')
+  if (!isGithubEventAllowed(options.allowlist(), event, action)) return
+
+  const selfId = options.selfId()
+  const selfLogin = options.selfLogin()
+  const author = readAuthor(event, payload)
+  if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
+    maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
+    options.logger.info(
+      `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
+    )
+    return
   }
+
+  // A push to an open PR (`synchronize`) is not a message to react to — it is
+  // a trigger to re-evaluate the bot's own outstanding review obligations on
+  // this PR: unresolved review threads it authored AND a sticky
+  // CHANGES_REQUESTED block (which leaves no threads when filed as a top-level
+  // verdict — the black hole this path closes). Both need an API round-trip,
+  // so it runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
+  // session when an obligation is outstanding. Returning here also keeps
+  // synchronize out of the generic awareness-only fallthrough below.
+  if (event === 'pull_request' && action === 'synchronize') {
+    scheduleReviewFollowup({ payload, selfLogin, options })
+    return
+  }
+
+  const teamIsBotMember = await resolveTeamMembership(event, payload, options)
+  const reviewCommentParent = await resolveReviewCommentParent(event, payload, selfId, selfLogin, options)
+  const classified = classifyGithubInbound(event, payload, selfLogin, {
+    teamIsBotMember,
+    authType: options.authType?.() ?? 'pat',
+    reviewOn: options.reviewOn?.() ?? 'review_requested',
+    ...(reviewCommentParent !== null ? { reviewCommentParent } : {}),
+  })
+  if (classified === null) return
+
+  options.route(withApprovalPolicy(classified, options.allowApprove?.() ?? true))
 }
 
 export const PR_APPROVAL_DISABLED_NOTE =

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

@@ -11,7 +11,7 @@ import { createDeliveryDedup } from './dedup'
 import { findPermissionGaps } from './event-permissions'
 import { createGithubFetchAttachmentCallback } from './fetch-attachment'
 import { createGithubHistoryCallback } from './history'
-import { createGithubWebhookHandler } from './inbound'
+import { createGithubWebhookHandler, processVerifiedGithubDelivery, type GithubWebhookHandlerOptions } from './inbound'
 import { applyManagedPath, buildManagedPath, resolveAgentId } from './managed-path'
 import { createGithubMembershipResolver } from './membership'
 import { createGithubOutboundCallback } from './outbound'
@@ -22,6 +22,7 @@ import {
 } from './permission-guidance'
 import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
 import { reconcileOpenPrs } from './reconcile-open-prs'
+import { createRecoveredGuidLog, recoverFailedGithubDeliveries } from './recover-failed-deliveries'
 import { createGithubReviewStateResolver } from './review-state'
 import { createGithubReviewThreadResolver } from './review-thread-resolver'
 import { createTeamMembershipChecker } from './team-membership'
@@ -67,6 +68,10 @@ export type GithubAdapterOptions = {
   // 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 }
+  // How often to sweep each managed hook's GitHub delivery log for events whose
+  // inbound delivery failed (and that GitHub never redelivered), re-injecting
+  // them through the live event path. Zero disables the sweep. Default: 5 min.
+  deliveryRecoveryIntervalMs?: number
   // Write-side of the GithubTokenBridge. On App-auth start the adapter
   // registers a per-repo minter here so plugin hooks can resolve a token for
   // ad-hoc `gh` commands; it unregisters on stop and on start rollback. PAT
@@ -89,6 +94,12 @@ const consoleLogger: GithubAdapterLogger = {
 
 const DEFAULT_WEBHOOK_REGISTRATION_DELAY_MS = 2_000
 const DEFAULT_TOKEN_REFRESH_INTERVAL_MS = 30 * 60 * 1000
+const DEFAULT_DELIVERY_RECOVERY_INTERVAL_MS = 5 * 60 * 1000
+// GitHub retains the delivery log for 3 days; sweep a little under that so a
+// failed delivery is always still listable on the next interval.
+const DELIVERY_RECOVERY_LOOKBACK_MS = 70 * 60 * 60 * 1000
+// Bounds an LLM-session storm if a bad tunnel window drops a large burst.
+const MAX_RECOVERED_PER_SWEEP = 50
 
 export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
   const logger = options.logger ?? consoleLogger
@@ -105,8 +116,15 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   let started = false
   let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
   let tokenRefreshTimer: { clear: () => void } | null = null
+  let deliveryRecoveryTimer: { clear: () => void } | null = null
   let unregisterTokenBridge: (() => void) | null = null
   const workspaceByChat = new Map<string, string>()
+  const setIntervalFn =
+    options.setInterval ??
+    ((handler: () => void, ms: number) => {
+      const timer = setInterval(handler, ms)
+      return { clear: () => clearInterval(timer) }
+    })
 
   const rememberWorkspace = (workspace: string, chat: string): void => {
     workspaceByChat.set(chat, workspace)
@@ -174,7 +192,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         logger.error(`[github] route failed: ${err instanceof Error ? err.message : String(err)}`)
       })
   }
-  const handler = createGithubWebhookHandler({
+  const handlerOptions: GithubWebhookHandlerOptions = {
     webhookSecret,
     dedup,
     allowlist: () => options.configRef().eventAllowlist,
@@ -188,7 +206,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     fetchImpl,
     logger,
     route: routeInbound,
-  })
+  }
+  const handler = createGithubWebhookHandler(handlerOptions)
 
   return {
     async start(): Promise<void> {
@@ -251,12 +270,6 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
               )
             })
           }
-          const setIntervalFn =
-            options.setInterval ??
-            ((handler: () => void, ms: number) => {
-              const timer = setInterval(handler, ms)
-              return { clear: () => clearInterval(timer) }
-            })
           tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
         }
       } else {
@@ -355,10 +368,45 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
           logger.warn(`[github] reconcile pass failed: ${err instanceof Error ? err.message : String(err)}`)
         })
       }
+      // Periodically recover inbound deliveries that failed at the tunnel and
+      // were never redelivered (the cloudflare-quick 502 loss). Registered only
+      // when we manage hooks to query, and driven by the same injectable timer
+      // as the token refresh. The first sweep fires after one interval — NOT
+      // inside start() — so start() stays free of surprise API traffic; the
+      // reconcile pass above already covers the review-needed case immediately.
+      const deliveryRecoveryIntervalMs = options.deliveryRecoveryIntervalMs ?? DEFAULT_DELIVERY_RECOVERY_INTERVAL_MS
+      if (managedHooks.length > 0 && deliveryRecoveryIntervalMs > 0) {
+        // Created once and captured by `sweep`, so recovery idempotency persists
+        // across ticks even when the shared live dedup evicts the guid.
+        const recoveredLog = createRecoveredGuidLog(DELIVERY_RECOVERY_LOOKBACK_MS)
+        const sweep = () => {
+          recoverFailedGithubDeliveries({
+            hooks: managedHooks,
+            token: (repoSlug: string) => auth.token({ repoSlug }),
+            process: (input) => processVerifiedGithubDelivery(handlerOptions, input),
+            alreadySeen: (guid: string) => dedup.has(guid),
+            recoveredLog,
+            lookbackMs: DELIVERY_RECOVERY_LOOKBACK_MS,
+            maxPerSweep: MAX_RECOVERED_PER_SWEEP,
+            logger,
+            fetchImpl,
+          }).catch((err: unknown) => {
+            logger.warn(`[github] delivery recovery sweep failed: ${err instanceof Error ? err.message : String(err)}`)
+          })
+        }
+        deliveryRecoveryTimer = setIntervalFn(sweep, deliveryRecoveryIntervalMs)
+      }
     },
     async stop(): Promise<void> {
       if (!started) return
       started = false
+      // Stop the recovery sweep first: its async work outlives the synchronous
+      // unregister calls below, and a tick landing mid-teardown would query a
+      // hook we're about to deregister and could route during shutdown.
+      if (deliveryRecoveryTimer !== null) {
+        deliveryRecoveryTimer.clear()
+        deliveryRecoveryTimer = null
+      }
       options.router.unregisterOutbound('github', outbound)
       options.router.unregisterReaction('github', reaction)
       options.router.unregisterRemoveReaction('github', removeReaction)

package/src/channels/adapters/github/recover-failed-deliveries.ts

@@ -0,0 +1,270 @@
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+// Recovers webhook events whose delivery to our ingress FAILED and that GitHub
+// never successfully redelivered. The production failure mode is inbound-only: a
+// cloudflare-quick tunnel drops ~half its deliveries with 502 "failed to connect
+// to host", and GitHub does not auto-redeliver issue_comment events — so a
+// `@bot review please` comment is lost with no log entry and no reply.
+//
+// This sweep is OUTBOUND-only, so it never touches the broken inbound leg: it
+// lists each managed hook's delivery log, finds events with no successful
+// delivery, fetches the original payload from GitHub's authenticated deliveries
+// API, and feeds it through the SAME processVerifiedGithubDelivery core a live
+// webhook uses (passed in as `process`). It is a floor, not the primary path —
+// webhooks remain low-latency when delivery works; reconcile-open-prs.ts is the
+// sibling floor for review-state drift.
+
+export type ManagedHook = { repo: string; hookId: number }
+
+// Recovery-owned idempotency keyed by delivery GUID, retained for the FULL
+// lookback window. The shared live dedup cannot serve this alone: it is a
+// fixed 1000-entry LRU, so during a 70h lookback across many repos it can evict
+// a GUID we already recovered, after which the still-listed failed delivery
+// would be re-fetched and re-routed. This TTL log holds only RECOVERED GUIDs
+// (failed-then-recovered deliveries, a small set), expiring each exactly when it
+// also falls out of the scan window — so a recovered delivery is routed once
+// regardless of live-dedup churn. (The shared dedup still guards the live-vs-
+// sweep concurrency race; this guards cross-sweep durability.)
+export type RecoveredGuidLog = { has: (guid: string) => boolean; record: (guid: string) => void }
+
+export function createRecoveredGuidLog(ttlMs: number, now: () => number = Date.now): RecoveredGuidLog {
+  const expiresAt = new Map<string, number>()
+  return {
+    has(guid: string): boolean {
+      const expiry = expiresAt.get(guid)
+      if (expiry === undefined) return false
+      if (expiry <= now()) {
+        expiresAt.delete(guid)
+        return false
+      }
+      return true
+    },
+    record(guid: string): void {
+      const t = now()
+      for (const [g, expiry] of expiresAt) if (expiry <= t) expiresAt.delete(g)
+      expiresAt.set(guid, t + ttlMs)
+    },
+  }
+}
+
+export type RecoverFailedDeliveriesOptions = {
+  hooks: readonly ManagedHook[]
+  token: (repoSlug: string) => Promise<string>
+  // The shared processVerifiedGithubDelivery, bound to the adapter's handler
+  // options. `delivery` is the GUID; the core dedups, filters by allowlist,
+  // drops self-authored, and routes exactly as the live path does.
+  process: (input: { event: string; delivery: string; payload: Record<string, unknown> }) => Promise<void>
+  // Fast-path skip backed by the LIVE delivery dedup (shared with the webhook
+  // handler): a guid here was just routed live (or reserved by `process` on
+  // entry), so skip it. Best-effort only — it is a 1000-entry LRU and may evict
+  // within the lookback window, which is exactly why `recoveredLog` exists.
+  alreadySeen: (guid: string) => boolean
+  // Durable recovery idempotency for the whole lookback window (see
+  // createRecoveredGuidLog). Caller-owned so it persists across sweeps.
+  recoveredLog: RecoveredGuidLog
+  lookbackMs: number
+  maxPerSweep: number
+  logger: { info: (m: string) => void; warn: (m: string) => void }
+  now?: () => number
+  fetchImpl?: typeof fetch
+}
+
+export type RecoverOutcome = { recovered: number; scanned: number }
+
+export async function recoverFailedGithubDeliveries(options: RecoverFailedDeliveriesOptions): Promise<RecoverOutcome> {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const now = options.now ?? Date.now
+  const cutoff = now() - options.lookbackMs
+  let recovered = 0
+  let scanned = 0
+
+  for (const hook of options.hooks) {
+    // maxPerSweep is a GLOBAL budget across all hooks (an LLM-session storm
+    // guard), so pass the remaining budget into each hook rather than letting
+    // every hook recover up to the full cap independently.
+    const remaining = options.maxPerSweep - recovered
+    if (remaining <= 0) break
+    const target = parseRepo(hook.repo)
+    if (target === null) {
+      options.logger.warn(`[github] recovery skipped malformed repo slug "${hook.repo}"`)
+      continue
+    }
+    try {
+      const result = await recoverHook(hook, target, cutoff, options, remaining, fetchImpl)
+      scanned += result.scanned
+      recovered += result.recovered
+      if (result.recovered > 0) {
+        options.logger.info(`[github] recovered ${result.recovered} missed delivery(s) on ${hook.repo}`)
+      }
+    } catch (err) {
+      // Per-hook isolation: one repo's token/list/detail failure must not abort
+      // the others. The next interval retries this hook.
+      options.logger.warn(`[github] delivery recovery failed for ${hook.repo}: ${describe(err)}`)
+    }
+  }
+  return { recovered, scanned }
+}
+
+async function recoverHook(
+  hook: ManagedHook,
+  target: RepoTarget,
+  cutoff: number,
+  options: RecoverFailedDeliveriesOptions,
+  budget: number,
+  fetchImpl: typeof fetch,
+): Promise<RecoverOutcome> {
+  const token = await options.token(hook.repo)
+  const deliveries = await listRecentDeliveries(fetchImpl, token, target, hook.hookId, cutoff)
+
+  // Any 2xx/3xx delivery for a guid means the event got through (e.g. GitHub
+  // auto-redelivered, or a manual redeliver succeeded). Never recover those.
+  const succeededGuids = new Set<string>()
+  for (const d of deliveries) {
+    if (isSuccess(d.statusCode)) succeededGuids.add(d.guid)
+  }
+
+  let recovered = 0
+  let scanned = 0
+  const handledThisSweep = new Set<string>()
+  for (const delivery of deliveries) {
+    if (recovered >= budget) break
+    if (isSuccess(delivery.statusCode)) continue
+    scanned += 1
+    const guid = delivery.guid
+    if (guid === '') continue
+    if (
+      succeededGuids.has(guid) ||
+      handledThisSweep.has(guid) ||
+      options.alreadySeen(guid) ||
+      options.recoveredLog.has(guid)
+    ) {
+      continue
+    }
+    handledThisSweep.add(guid)
+
+    const payload = await fetchDeliveryPayload(fetchImpl, token, target, hook.hookId, delivery.id)
+    if (payload === null) continue
+    await options.process({ event: delivery.event, delivery: guid, payload })
+    // Record AFTER process resolves: an unexpected throw leaves the guid
+    // unrecorded so the next sweep retries it. A no-op classify still records
+    // (process returned), so a non-routable failed delivery is not refetched.
+    options.recoveredLog.record(guid)
+    recovered += 1
+  }
+  return { recovered, scanned }
+}
+
+type RepoTarget = { owner: string; repo: string }
+
+type DeliverySummary = { id: number; guid: string; event: string; statusCode: number }
+
+async function listRecentDeliveries(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: RepoTarget,
+  hookId: number,
+  cutoff: number,
+): Promise<DeliverySummary[]> {
+  const summaries: DeliverySummary[] = []
+  let url: string | null =
+    `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/hooks/${hookId}/deliveries?per_page=100`
+  while (url !== null) {
+    const response = await fetchImpl(url, { headers: githubJsonHeaders(token) })
+    if (!response.ok) {
+      const body = await response.text().catch(() => '')
+      throw new Error(`GitHub deliveries ${response.status}${body !== '' ? `: ${body}` : ''}`)
+    }
+    const page = (await response.json().catch(() => null)) as DeliveryRow[] | null
+    if (page === null) throw new Error('GitHub deliveries returned non-JSON')
+    // Deliveries are newest-first; once a page's oldest entry predates the
+    // lookback cutoff we can stop paginating instead of walking the full log.
+    let reachedCutoff = false
+    for (const row of page) {
+      const parsed = parseDeliveryRow(row)
+      if (parsed === null) continue
+      if (parsed.deliveredAt !== null && parsed.deliveredAt < cutoff) {
+        reachedCutoff = true
+        continue
+      }
+      summaries.push(parsed.summary)
+    }
+    if (reachedCutoff) break
+    url = nextLink(response.headers.get('link'))
+  }
+  return summaries
+}
+
+async function fetchDeliveryPayload(
+  fetchImpl: typeof fetch,
+  token: string,
+  target: RepoTarget,
+  hookId: number,
+  deliveryId: number,
+): Promise<Record<string, unknown> | null> {
+  const response = await fetchImpl(
+    `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}/hooks/${hookId}/deliveries/${deliveryId}`,
+    { headers: githubJsonHeaders(token) },
+  )
+  if (!response.ok) return null
+  const raw = (await response.json().catch(() => null)) as { request?: { payload?: unknown } } | null
+  return coercePayload(raw?.request?.payload)
+}
+
+function coercePayload(value: unknown): Record<string, unknown> | null {
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value) as unknown
+      return isRecord(parsed) ? parsed : null
+    } catch {
+      return null
+    }
+  }
+  return isRecord(value) ? value : null
+}
+
+// GitHub records a non-delivery (connection refused / DNS / tunnel down) as
+// status_code 0, and HTTP failures as 4xx/5xx. Treat 2xx and 3xx as success.
+function isSuccess(statusCode: number): boolean {
+  return statusCode >= 200 && statusCode < 400
+}
+
+type DeliveryRow = {
+  id?: unknown
+  guid?: unknown
+  event?: unknown
+  status_code?: unknown
+  delivered_at?: unknown
+}
+
+function parseDeliveryRow(row: DeliveryRow): { summary: DeliverySummary; deliveredAt: number | null } | null {
+  const id = typeof row.id === 'number' ? row.id : null
+  const guid = typeof row.guid === 'string' ? row.guid : null
+  const event = typeof row.event === 'string' ? row.event : null
+  const statusCode = typeof row.status_code === 'number' ? row.status_code : null
+  if (id === null || guid === null || event === null || statusCode === null) return null
+  const deliveredAt = typeof row.delivered_at === 'string' ? Date.parse(row.delivered_at) || null : null
+  return { summary: { id, guid, event, statusCode }, deliveredAt }
+}
+
+function parseRepo(slug: string): RepoTarget | null {
+  const [owner, repo, ...rest] = slug.trim().split('/')
+  if (owner === undefined || owner === '' || repo === undefined || repo === '' || rest.length > 0) return null
+  return { owner, repo }
+}
+
+function nextLink(linkHeader: string | null): string | null {
+  if (linkHeader === null) return null
+  for (const part of linkHeader.split(',')) {
+    const m = /<([^>]+)>;\s*rel="next"/.exec(part)
+    if (m !== null) return m[1] ?? null
+  }
+  return null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/adapters/kakaotalk.ts

@@ -1,3 +1,5 @@
+import { basename } from 'node:path'
+
 import {
   KakaoCredentialManager,
   KakaoTalkClient as RealKakaoTalkClient,
@@ -203,7 +205,9 @@ export function createOutboundCallback(deps: {
       try {
         items = await Promise.all(
           attachments.map(async (a) => {
-            const filename = a.filename ?? a.path.split('/').pop() ?? 'file'
+            // basename (not split('/')) so a native-Windows host's backslash
+            // attachment paths still yield just the filename (issue #899).
+            const filename = a.filename ?? (basename(a.path) || 'file')
             const data = await readFile(a.path)
             return { data, filename }
           }),

package/src/channels/adapters/mention-hints.ts

@@ -0,0 +1,75 @@
+import type { AdapterId } from '../schema'
+
+export type DiscordMentionUser = { id: string; username?: string; global_name?: string | null }
+
+export type MentionHintOptions = { botUserId?: string | null }
+
+// Slack encodes user mentions as `<@U…>`/`<@W…>`, optionally with a native
+// `|label` fallback suffix. We capture the id and the whole token so the bare
+// `<@id>` can be reconstructed (dropping any legacy label) and a resolved hint
+// appended after it.
+const SLACK_MENTION_PATTERN = /<@([UW][A-Z0-9]+)(?:\|[^>]*)?>/g
+
+// Discord uses `<@id>` and the nickname form `<@!id>`; the `!` is optional and
+// irrelevant to the target user, so it is captured but discarded on rewrite.
+const DISCORD_MENTION_PATTERN = /<@!?(\d+)>/g
+
+// User ids the agent addressed by @-mention in an outbound message, so the
+// router can grant them sticky credit (their reply answers us without a
+// re-mention). Only Slack (`<@U…>`) and Discord (`<@id>`) encode mentions as
+// raw id tokens that map 1:1 to an inbound `authorId`; Telegram (`@username`),
+// GitHub (`@login`), LINE and KakaoTalk have no token→authorId mapping here, so
+// they return [] by design and the caller falls back to existing rules.
+export function extractMentionedUserIds(adapter: AdapterId, text: string): string[] {
+  const pattern =
+    adapter === 'slack-bot' ? SLACK_MENTION_PATTERN : adapter === 'discord-bot' ? DISCORD_MENTION_PATTERN : null
+  if (pattern === null) return []
+  const ids = new Set<string>()
+  for (const match of text.matchAll(pattern)) ids.add(match[1]!)
+  return Array.from(ids)
+}
+
+export async function addSlackMentionHints(
+  text: string,
+  resolveUserName: (id: string) => Promise<string>,
+  options: MentionHintOptions = {},
+): Promise<string> {
+  const ids = new Set<string>()
+  for (const match of text.matchAll(SLACK_MENTION_PATTERN)) ids.add(match[1]!)
+  if (ids.size === 0) return text
+
+  const hints = new Map<string, string>()
+  await Promise.all(
+    Array.from(ids).map(async (id) => {
+      const hint = resolveHint(id, await resolveUserName(id), options.botUserId)
+      if (hint !== null) hints.set(id, hint)
+    }),
+  )
+
+  return text.replace(SLACK_MENTION_PATTERN, (_token, id: string) => renderToken(id, hints.get(id)))
+}
+
+export function addDiscordMentionHints(
+  text: string,
+  usersById: Map<string, DiscordMentionUser>,
+  options: MentionHintOptions = {},
+): string {
+  return text.replace(DISCORD_MENTION_PATTERN, (token, id: string) => {
+    const user = usersById.get(id)
+    const name = user === undefined ? id : (user.global_name ?? user.username ?? id)
+    const hint = resolveHint(id, name, options.botUserId)
+    return hint === null ? token : `${token} (${hint})`
+  })
+}
+
+function resolveHint(id: string, resolvedName: string, botUserId: string | null | undefined): string | null {
+  if (id === botUserId) return 'you'
+  // The resolver echoes the id back when it cannot find a name; a bare id is
+  // not a useful hint, so leave the token unannotated in that case.
+  if (resolvedName === id || resolvedName === '') return null
+  return resolvedName
+}
+
+function renderToken(id: string, hint: string | undefined): string {
+  return hint === undefined ? `<@${id}>` : `<@${id}> (${hint})`
+}

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

@@ -32,6 +32,7 @@ import type {
 } from '@/channels/types'
 import { chunkMarkdown } from '@/markdown'
 
+import { addSlackMentionHints } from './mention-hints'
 import { createSlackAuthorResolver, type SlackAuthorResolver } from './slack-bot-author-resolver'
 import { createSlackChannelResolver } from './slack-bot-channel-resolver'
 import {
@@ -703,11 +704,14 @@ export function createSlackHistoryCallback(deps: {
     // users.info entry. The resolver caches/coalesces, so repeated authors
     // cost one lookup each.
     if (authorResolver !== undefined) {
+      const resolver = authorResolver
+      const botId = botUserIdRef()
       await Promise.all(
         mapped.map(async (message, index) => {
+          message.text = await addSlackMentionHints(message.text, resolver.resolve, { botUserId: botId })
           const userId = rawMessages[index]?.user
           if (userId === undefined || userId === '') return
-          message.authorName = await authorResolver.resolve(userId)
+          message.authorName = await resolver.resolve(userId)
         }),
       )
     }
@@ -1133,9 +1137,10 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
       }
 
       dedupe.mark(event)
+      const hintedText = await addSlackMentionHints(verdict.payload.text, authorResolver.resolve, { botUserId })
       const slackAttachments = Array.isArray(event.attachments) ? event.attachments : undefined
       const referenceResult = await enrichSlackReferenceContext({
-        text: verdict.payload.text,
+        text: hintedText,
         channelId: event.channel,
         messageTs: event.ts,
         ...(slackAttachments !== undefined ? { attachments: slackAttachments } : {}),
@@ -1143,6 +1148,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
       })
       const enriched = {
         ...verdict.payload,
+        text: hintedText,
         authorName: resolvedUserName,
         ...(referenceResult.referenceContext !== undefined
           ? { referenceContext: referenceResult.referenceContext }