typeclaw 0.9.2 → 0.11.0

package/src/channels/router.ts

@@ -29,7 +29,7 @@ import {
   saveChannelSessions,
   type ChannelSessionRecord,
 } from './persistence'
-import type { ChannelAdapterConfig } from './schema'
+import { QUOTED_REPLY_EXCERPT_MAX_CHARS, type AdapterId, type ChannelAdapterConfig } from './schema'
 import type {
   ChannelHistoryMessage,
   ChannelKey,
@@ -230,6 +230,19 @@ type ObservedInbound = {
   authorIsBot: boolean
   receivedAt: number
   ts: number
+  // Distinguishes scrollback that was bulk-loaded at session cold-start
+  // (`prefetch`) from messages that actually arrived in the channel after
+  // the session went live (`observed`). Both share the same in-memory
+  // shape because the model sees them identically in the prompt's
+  // "Recent context" block, but the quote-anchor decision must treat them
+  // differently: prefetched scrollback is HISTORICAL context, not new
+  // chatter that happened between the primary inbound and the agent's
+  // reply. Counting prefetch entries as "intervening" would fire the
+  // anchor on every fresh-thread first turn (the prefetch stamps
+  // `receivedAt = now()` AFTER the inbound was received during ensureLive,
+  // so by primary-vs-observed timestamp comparison they always look
+  // "later"). See captureQuoteCandidate.
+  source: 'prefetch' | 'observed'
 }
 
 type LiveSession = {
@@ -302,6 +315,40 @@ type LiveSession = {
   // future hard cap without picking a threshold out of thin air.
   sendTimestamps: Map<string, number[]>
   successfulChannelSends: number
+  // Monotonic per-LiveSession turn counter incremented just before each
+  // `live.session.prompt(...)` call in `drain()`. Used as a turn identity
+  // so `skip_response` can record "I skipped turn N" without leaking
+  // across turns. `validateChannelTurn` only honors `skippedTurn` when it
+  // equals `turnSeq`; a stale value from a crashed/aborted prior turn is
+  // ignored (defensive: an unmatched skippedTurn would otherwise silently
+  // drop the next user-facing reply). NOT cleared on drain finally — the
+  // counter is purely monotonic; the matching comparison is what protects
+  // against stale state.
+  turnSeq: number
+  // Snapshot of `successfulChannelSends` taken at turn start (same
+  // moment `turnSeq` increments). Lets `markTurnSkipped` detect "a
+  // channel send already landed in this turn" and reject the skip,
+  // making the rejection symmetric with the send-after-skip lock in
+  // `send()`: commit to silence or commit to replying, not both,
+  // regardless of which order the model tried them in. Updated only at
+  // turn start; reads against the live counter elsewhere are intentional.
+  successfulSendsAtTurnStart: number
+  // Stamped by `markTurnSkipped` (called from the `skip_response` tool)
+  // with the current `turnSeq`. Read at the top of `validateChannelTurn`:
+  // if it matches the just-completed turn, recovery is skipped entirely
+  // (no NO_REPLY check, no Kimi leak check, no assistant-text recovery).
+  // The model has explicitly opted out of this turn and we honor that
+  // unconditionally. `null` when no skip has been recorded.
+  skippedTurn: { turnSeq: number; reason: string } | null
+  // Captured by drain() at batch dequeue; read+cleared by send() on the
+  // first tool-source send of the turn. The anchor decision (delay
+  // threshold + intervening-observed check) is evaluated at SEND time
+  // against this snapshot — not at drain time — because the relevant
+  // signal is how long the user waited from inbound to seeing the reply
+  // land, which only the send-side clock knows. Cleared after first
+  // consumption so multi-part replies anchor only on chunk 1. A new
+  // batch overwrites unconditionally.
+  pendingQuoteCandidate: QuoteAnchorCandidate | null
   // Loop-guard state. See PEER_BOT_TURNS_WINDOW_MS / MAX_* constants
   // above. Updated in route() on every engaged peer-bot inbound, reset on
   // any human inbound. The two axes (window ring buffer + since-human
@@ -356,6 +403,11 @@ export const TURN_CAP_ERROR =
   `Send-cap reached for this turn (${MAX_CHANNEL_SENDS_PER_TURN} messages already sent to this conversation). ` +
   'End your turn now. The user can prompt you again for more output.'
 
+export const SKIP_RESPONSE_LOCK_ERROR =
+  'You called `skip_response` earlier in this turn, which committed to staying silent. ' +
+  'Channel sends are blocked for the rest of this turn. End your turn now; if you have ' +
+  'something to say, send it on the next turn.'
+
 export type ChannelRouter = {
   route: (event: InboundMessage) => Promise<void>
   send: (msg: OutboundMessage, opts?: SendOptions) => Promise<SendResult>
@@ -421,6 +473,31 @@ export type ChannelRouter = {
     durationMs: number
     error?: string
   }) => { kind: 'delivered'; keyId: string } | { kind: 'no-live-session' }
+  // Record that the agent invoked `skip_response` during the current turn
+  // for the channel session identified by `parentSessionId`. The reason is
+  // logged at INFO level inside `validateChannelTurn` (single log line per
+  // skip, so operators see exactly one record per silent turn). Stamps the
+  // current `turnSeq` on the live session so a stale record from an earlier
+  // turn cannot drop a future legitimate reply.
+  //
+  // Returns:
+  //   - 'recorded'      — the live session was found and the skip was stamped
+  //   - 'send-already-happened' — a tool-source channel send already landed
+  //                       in this turn; the skip is refused (symmetric with
+  //                       the send-after-skip lock in `send()`) so the model
+  //                       cannot land a reply AND claim silence. The flag is
+  //                       NOT stamped, so the turn proceeds as a normal
+  //                       reply turn.
+  //   - 'no-live-session' — no matching channel session (e.g. tool fired
+  //                         outside a channel origin); the tool should
+  //                         still log the reason but cannot suppress.
+  markTurnSkipped: (args: {
+    parentSessionId: string
+    reason: string
+  }) =>
+    | { kind: 'recorded'; keyId: string }
+    | { kind: 'send-already-happened'; keyId: string }
+    | { kind: 'no-live-session' }
   stop: () => Promise<void>
   liveCount: () => number
   __testing?: {
@@ -913,6 +990,10 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         lastSentText: new Map(),
         sendTimestamps: new Map(),
         successfulChannelSends: 0,
+        turnSeq: 0,
+        successfulSendsAtTurnStart: 0,
+        skippedTurn: null,
+        pendingQuoteCandidate: null,
         recentEngagedPeerBotTurns: [],
         consecutiveEngagedPeerBotTurns: 0,
         loopGuardActive: false,
@@ -1005,6 +1086,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           authorIsBot: item.message.isBot,
           receivedAt: now(),
           ts: item.message.ts,
+          source: 'prefetch',
         })
       } else {
         observed.push({
@@ -1014,6 +1096,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           authorIsBot: true,
           receivedAt: now(),
           ts: 0,
+          source: 'prefetch',
         })
       }
     }
@@ -1079,7 +1162,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         return
       }
       if (now() - live.typingStartedAt >= MAX_TYPING_HEARTBEAT_MS) {
-        logger.warn(`[channels] ${live.keyId}: typing heartbeat timed out after ${MAX_TYPING_HEARTBEAT_MS}ms`)
+        logger.warn(
+          `[channels] ${live.keyId}: typing indicator paused after ${MAX_TYPING_HEARTBEAT_MS}ms; prompt still in flight`,
+        )
         live.typingTimedOut = true
         void stopTypingHeartbeat(live)
         return
@@ -1204,6 +1289,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const observed = live.contextBuffer.splice(0, live.contextBuffer.length)
         const reminders = live.pendingSystemReminders.splice(0, live.pendingSystemReminders.length)
         const text = composeTurnPrompt(observed, batch, {
+          adapter: live.key.adapter,
           loopGuardActive: live.loopGuardActive,
           systemReminders: reminders,
         })
@@ -1213,6 +1299,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
           live.consecutiveSends.clear()
           live.lastSentText.clear()
+          live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
         } else if (live.lastTurnAuthorId !== null) {
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
           // restore the author identity from the prior turn so author-
@@ -1244,6 +1331,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${live.keyId} prompting batch=${batch.length} text_len=${text.length}`)
         const promptStart = now()
         const successfulSendsBeforePrompt = live.successfulChannelSends
+        live.turnSeq++
+        live.successfulSendsAtTurnStart = successfulSendsBeforePrompt
         await fireSessionTurnStart(live, text)
         try {
           await live.session.prompt(text)
@@ -1340,10 +1429,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     // Role-claim intercept runs BEFORE the channel.respond gate so the
     // operator can bootstrap permissions on a fresh agent that has no
-    // role match rules yet. Cheap pre-check: only DMs whose text contains
-    // a `claim-` prefix can be claim attempts, and only when a handler
+    // role match rules yet. Cheap pre-check: any inbound whose text
+    // contains a `claim-` prefix is a candidate, and only when a handler
     // is registered. Everything else falls straight through to the gate.
-    if (claimHandler !== undefined && event.isDm && extractClaimCode(event.text) !== null) {
+    // Claims are accepted from any chat (DM, group, thread) because the
+    // resulting match rule is platform-wide + author-scoped — see
+    // src/role-claim/match-rule.ts.
+    if (claimHandler !== undefined && extractClaimCode(event.text) !== null) {
       const outcome = await claimHandler({
         adapter: event.adapter,
         workspace: event.workspace,
@@ -1520,6 +1612,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       authorIsBot: event.authorIsBot,
       receivedAt: now(),
       ts: event.ts,
+      source: 'observed',
     })
     if (live.contextBuffer.length > CONTEXT_BUFFER_SIZE) {
       live.contextBuffer.splice(0, live.contextBuffer.length - CONTEXT_BUFFER_SIZE)
@@ -1692,6 +1785,21 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     })
     const live = liveSessions.get(keyId)
     const sendKey = consecutiveSendKey(msg.chat, msg.thread)
+    // Tool-source sends consume the captured quote candidate exactly
+    // once per turn — the intervening-observed check runs HERE against
+    // the live buffer so the relevant signal is actual channel chatter
+    // between inbound and reply landing, not drain-vs-send timing
+    // artifacts. System sources (recovery, role-
+    // claim) skip so they can't accidentally swallow the candidate
+    // before the model's own first reply lands. Even when the decision
+    // returns null (nothing intervened), the candidate is cleared — a
+    // multi-part reply must not retroactively anchor chunk 2.
+    if (live && source === 'tool' && live.pendingQuoteCandidate !== null) {
+      const quoteCandidate = refreshQuoteCandidate(live.pendingQuoteCandidate, live.contextBuffer)
+      const anchor = decideQuoteAnchor(quoteCandidate, now(), options.configForAdapter(msg.adapter))
+      if (anchor !== null) msg = { ...msg, text: prependQuoteAnchor(msg.text ?? '', anchor) }
+      live.pendingQuoteCandidate = null
+    }
     const text = normalizeSendText(msg.text)
 
     // Central enforcement. Tool-initiated sends are subject to two policies:
@@ -1706,6 +1814,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     let priorLastSentText: string | undefined
     let reserved = false
     if (live && source === 'tool') {
+      // Tool-source send after `skip_response` for the same turn is a contract
+      // violation: the model already committed to silence. Reject before any
+      // state mutation so the model gets a clear error and the channel stays
+      // silent. System-source sends (recovery, role-claim) are not affected.
+      if (live.skippedTurn !== null && live.skippedTurn.turnSeq === live.turnSeq) {
+        return { ok: false, error: SKIP_RESPONSE_LOCK_ERROR, code: 'skip-locked' }
+      }
       const currentCount = live.consecutiveSends.get(sendKey) ?? 0
       if (currentCount >= MAX_CHANNEL_SENDS_PER_TURN) {
         return { ok: false, error: TURN_CAP_ERROR, code: 'turn-cap' }
@@ -1792,6 +1907,19 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   }
 
   const validateChannelTurn = async (live: LiveSession, successfulSendsBeforePrompt: number): Promise<void> => {
+    // `skip_response` short-circuit. Must run before the `successfulChannelSends`
+    // check so a model that called both `skip_response` and a channel tool in
+    // the same turn still resolves as "skipped" — the rejection inside `send()`
+    // means the channel tool returned an error and never actually delivered.
+    // Stale-flag protection: only honor when stamped on the just-completed
+    // turn. A flag set by a previous turn that crashed before validation
+    // would otherwise drop the next legitimate user-facing reply.
+    if (live.skippedTurn !== null && live.skippedTurn.turnSeq === live.turnSeq) {
+      const { reason } = live.skippedTurn
+      live.skippedTurn = null
+      logger.info(`[channels] ${live.keyId} skipped_by_tool reason=${JSON.stringify(reason)}`)
+      return
+    }
     if (live.successfulChannelSends > successfulSendsBeforePrompt) return
 
     const candidate = recoverableAssistantText(live.session)
@@ -2038,6 +2166,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return { kind: 'no-live-session' }
   }
 
+  const markTurnSkipped = (args: {
+    parentSessionId: string
+    reason: string
+  }):
+    | { kind: 'recorded'; keyId: string }
+    | { kind: 'send-already-happened'; keyId: string }
+    | { kind: 'no-live-session' } => {
+    for (const live of liveSessions.values()) {
+      if (live.destroyed) continue
+      if (live.sessionId !== args.parentSessionId) continue
+      if (live.successfulChannelSends > live.successfulSendsAtTurnStart) {
+        return { kind: 'send-already-happened', keyId: live.keyId }
+      }
+      live.skippedTurn = { turnSeq: live.turnSeq, reason: args.reason }
+      return { kind: 'recorded', keyId: live.keyId }
+    }
+    return { kind: 'no-live-session' }
+  }
+
   return {
     route,
     send,
@@ -2060,6 +2207,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     executeCommand,
     getSelfAliases: computeSelfAliases,
     injectSubagentCompletionReminder,
+    markTurnSkipped,
     stop,
     liveCount: () => liveSessions.size,
     __testing: {
@@ -2086,7 +2234,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           return
         }
         if (now() - live.typingStartedAt >= MAX_TYPING_HEARTBEAT_MS) {
-          logger.warn(`[channels] ${live.keyId}: typing heartbeat timed out after ${MAX_TYPING_HEARTBEAT_MS}ms`)
+          logger.warn(
+            `[channels] ${live.keyId}: typing indicator paused after ${MAX_TYPING_HEARTBEAT_MS}ms; prompt still in flight`,
+          )
           live.typingTimedOut = true
           await stopTypingHeartbeat(live)
           return
@@ -2126,8 +2276,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 function composeTurnPrompt(
   observed: readonly ObservedInbound[],
   batch: readonly QueuedInbound[],
-  state: { loopGuardActive: boolean; systemReminders?: readonly string[] } = { loopGuardActive: false },
+  state: { adapter?: AdapterId; loopGuardActive: boolean; systemReminders?: readonly string[] } = {
+    loopGuardActive: false,
+  },
 ): string {
+  const adapter = state.adapter ?? 'discord-bot'
   const parts: string[] = []
   // System reminders (subagent-completion wakeups today) lead the turn body
   // because they are typically what triggered the drain — when the prompt
@@ -2193,7 +2346,7 @@ function composeTurnPrompt(
   if (observed.length > 0) {
     parts.push('## Recent context (not addressed to you, for awareness only)')
     for (const o of observed) {
-      parts.push(formatAuthorLine(o.ts, o.authorId, o.authorName, o.authorIsBot, o.text))
+      parts.push(formatAuthorLine(o.ts, adapter, o.authorId, o.authorName, o.authorIsBot, o.text))
     }
     parts.push('')
   }
@@ -2211,7 +2364,7 @@ function composeTurnPrompt(
       )
     }
     for (const b of batch) {
-      parts.push(formatAuthorLine(b.ts, b.authorId, b.authorName, b.authorIsBot, b.text))
+      parts.push(formatAuthorLine(b.ts, adapter, b.authorId, b.authorName, b.authorIsBot, b.text))
     }
   }
   return parts.join('\n')
@@ -2219,6 +2372,7 @@ function composeTurnPrompt(
 
 function formatAuthorLine(
   ts: number,
+  adapter: AdapterId,
   authorId: string,
   authorName: string,
   authorIsBot: boolean,
@@ -2226,7 +2380,156 @@ function formatAuthorLine(
 ): string {
   const tag = authorIsBot ? ' [bot]' : ''
   const stamp = ts > 0 ? `[${new Date(ts).toISOString()}] ` : ''
-  return `${stamp}<@${authorId}> (${authorName})${tag}: ${text}`
+  return `${stamp}${formatAuthorReference(adapter, authorId, authorName)} (${authorName})${tag}: ${text}`
+}
+
+export type QuoteAnchorSource = {
+  adapter: AdapterId
+  authorId: string
+  authorName: string
+  text: string
+}
+
+// Picks the right author syntax for the platform so prompts and rendered
+// quote anchors use the same form the user would type in that channel.
+// Slack/Discord need id mentions (`<@U…>`), GitHub needs handle mentions
+// (`@login`) because inbound author ids are numeric, and adapters without
+// stable id-only mention syntax fall back to plain display names.
+//
+// Notification semantics: Slack and Discord both render `<@…>` as a
+// styled mention link inside blockquotes; whether the mentioned user is
+// PINGED is a separate platform-level UX (Slack pings on first appearance
+// in the message regardless of position, Discord respects the
+// `allowed_mentions` field which defaults to "ping everyone parsed").
+// This matches PR #374's intent — the user IS being notified that the
+// agent replied to them, which is the whole point of a quote anchor.
+function formatAuthorReference(adapter: AdapterId, authorId: string, authorName: string): string {
+  const displayName = authorName.trim() !== '' ? authorName.trim() : authorId
+  switch (adapter) {
+    case 'slack-bot':
+    case 'discord-bot':
+      return `<@${authorId}>`
+    case 'github':
+      return displayName.startsWith('@') ? displayName : `@${displayName}`
+    case 'telegram-bot':
+    case 'kakaotalk':
+      return displayName
+  }
+}
+
+// Renders the single-line `> @mention: excerpt` blockquote prepended to
+// outbound replies when the router decides the reply needs an anchor.
+// Collapses newlines to spaces so a multi-line user message renders on
+// one quoted line (markdown blockquote semantics: a blank line ends the
+// quote, and `> foo\nbar` would split the quote and the reply); strips
+// existing leading `>` so a quote-of-a-quote stays single-level. Empty
+// inbound text (mention-only inbounds like `<@bot>`) falls back to a
+// generic marker so the user still sees "the bot saw your ping".
+export function renderQuoteAnchor(source: QuoteAnchorSource): string {
+  const collapsed = source.text
+    .replace(/\s+/g, ' ')
+    .replace(/^>+\s*/, '')
+    .trim()
+  const excerpt =
+    collapsed === ''
+      ? '(no text)'
+      : collapsed.length > QUOTED_REPLY_EXCERPT_MAX_CHARS
+        ? `${collapsed.slice(0, QUOTED_REPLY_EXCERPT_MAX_CHARS - 1)}…`
+        : collapsed
+  const mention = formatAuthorReference(source.adapter, source.authorId, source.authorName)
+  return `> ${mention}: ${excerpt}`
+}
+
+// Separates the anchor from the reply with a blank line (`\n\n`), not a
+// single `\n`. In standard GFM and Slack's `markdown` block, a single
+// `\n` inside a paragraph is a soft break rendered as whitespace, which
+// keeps the `>` blockquote styling running visually through the next
+// line — i.e. the agent's reply text gets swallowed into the quote. The
+// blank line forces a paragraph boundary that unambiguously ends the
+// blockquote on every renderer (CommonMark, GFM, Slack mrkdwn, Discord
+// markdown).
+export function prependQuoteAnchor(replyText: string, source: QuoteAnchorSource): string {
+  const anchor = renderQuoteAnchor(source)
+  if (replyText === '') return anchor
+  return `${anchor}\n\n${replyText}`
+}
+
+type QuoteAnchorBatchEntry = {
+  text: string
+  authorId: string
+  authorName: string
+  authorIsBot: boolean
+  receivedAt: number
+}
+
+type QuoteAnchorObservedEntry = {
+  receivedAt: number
+  source: 'prefetch' | 'observed'
+}
+
+export type QuoteAnchorCandidate = {
+  source: QuoteAnchorSource
+  primaryReceivedAt: number
+  hadInterveningObserved: boolean
+}
+
+// Snapshot the primary inbound + observed-buffer state at drain time so
+// the send-side decision has the data it needs without holding a
+// reference to the batch arrays. Returns null when there's nothing
+// anchorable (empty batch, primary is a bot).
+//
+// `hadInterveningObserved` counts ONLY live observations (`source ===
+// 'observed'`), not prefetched scrollback. Prefetch stamps `receivedAt =
+// now()` inside ensureLive — wall-clock-later than the primary inbound
+// that triggered ensureLive — so without this gate, every cold-start
+// first turn would see "intervening observed" entries and fire the
+// quote anchor even when the reply lands within milliseconds. The
+// signal we actually want is "did real new chatter arrive between the
+// user's inbound and the agent's reply", which only live observations
+// represent.
+export function captureQuoteCandidate(
+  adapter: AdapterId,
+  batch: readonly QuoteAnchorBatchEntry[],
+  observed: readonly QuoteAnchorObservedEntry[],
+): QuoteAnchorCandidate | null {
+  if (batch.length === 0) return null
+  const primary = batch[batch.length - 1]!
+  if (primary.authorIsBot) return null
+  return {
+    source: { adapter, authorId: primary.authorId, authorName: primary.authorName, text: primary.text },
+    primaryReceivedAt: primary.receivedAt,
+    hadInterveningObserved: hasInterveningObserved(primary.receivedAt, observed),
+  }
+}
+
+function refreshQuoteCandidate(
+  candidate: QuoteAnchorCandidate,
+  observed: readonly QuoteAnchorObservedEntry[],
+): QuoteAnchorCandidate {
+  if (candidate.hadInterveningObserved) return candidate
+  if (!hasInterveningObserved(candidate.primaryReceivedAt, observed)) return candidate
+  return { ...candidate, hadInterveningObserved: true }
+}
+
+function hasInterveningObserved(primaryReceivedAt: number, observed: readonly QuoteAnchorObservedEntry[]): boolean {
+  return observed.some((o) => o.source === 'observed' && o.receivedAt >= primaryReceivedAt)
+}
+
+// Send-time decision: given a captured candidate and the current clock,
+// returns the source to anchor against or null. Skips when:
+//   - quotedReply is disabled in config
+//   - no observed messages came between primary inbound and now
+// A null candidate (no batch yet, or batch was bot-only) always skips.
+export function decideQuoteAnchor(
+  candidate: QuoteAnchorCandidate | null,
+  _nowMs: number,
+  adapterConfig: ChannelAdapterConfig | undefined,
+): QuoteAnchorSource | null {
+  if (candidate === null) return null
+  const config = adapterConfig?.quotedReply
+  if (config !== undefined && config.enabled === false) return null
+  if (!candidate.hadInterveningObserved) return null
+  return candidate.source
 }
 
 type Sliced = { kind: 'message'; message: ChannelHistoryMessage } | { kind: 'elision'; elidedCount: number }

package/src/channels/schema.ts

@@ -87,6 +87,25 @@ const historySchema = z
     },
   })
 
+// Legacy quote-delay knob retained for config compatibility. Quote anchors
+// are now driven by channel ordering instead: when another live-observed
+// message lands between the inbound and the agent's first reply, the router
+// prepends a platform-specific `> author: ...` blockquote line referencing
+// the inbound. If nothing intervened, the reply is adjacent enough in the
+// channel timeline that it needs no anchor regardless of elapsed wall time.
+export const DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS = 10_000
+
+// Long enough to disambiguate; short enough that a multi-paragraph user
+// message doesn't visually dominate the reply.
+export const QUOTED_REPLY_EXCERPT_MAX_CHARS = 100
+
+const quotedReplySchema = z
+  .object({
+    enabled: z.boolean().default(true),
+    queueDelayMs: z.number().int().min(0).default(DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS),
+  })
+  .default({ enabled: true, queueDelayMs: DEFAULT_QUOTED_REPLY_QUEUE_DELAY_MS })
+
 // Deliberately non-strict: a stale on-disk file may still carry the
 // legacy `allow` field (`migrateLegacyConfigShape` lifts it into
 // `roles.member.match[]` on load, but a between-reload window can
@@ -97,6 +116,7 @@ const adapterSchema = z.object({
   engagement: engagementSchema,
   history: historySchema,
   enabled: z.boolean().default(true),
+  quotedReply: quotedReplySchema.optional(),
 })
 
 export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
@@ -105,6 +125,8 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'discussion_comment.created',
   'issues.opened',
   'pull_request.opened',
+  'pull_request.review_requested',
+  'pull_request.review_request_removed',
   'discussion.created',
   'pull_request_review.submitted',
 ] as const

package/src/channels/types.ts

@@ -84,7 +84,7 @@ export type OutboundMessage = {
   attachments?: OutboundAttachment[]
 }
 
-export type SendErrorCode = 'duplicate' | 'turn-cap' | 'no-adapter' | 'callback-rejected'
+export type SendErrorCode = 'duplicate' | 'turn-cap' | 'no-adapter' | 'callback-rejected' | 'skip-locked'
 
 export type SendResult = { ok: true } | { ok: false; error: string; code?: SendErrorCode }