@spinabot/brigade 1.3.2 → 1.5.0

package/dist/agents/channels/inbound-pipeline.js

@@ -24,9 +24,10 @@
  */
 import { createSubsystemLogger } from "../../logging/subsystem-logger.js";
 import { getActiveRegistry } from "../extensions/active-registry.js";
-import { addAllowFrom, evaluateAccess, readAllowFrom, readGroupAllowFrom, removeAllowFrom, upsertPairingRequest, } from "./access-control/index.js";
+import { addAllowFrom, approvePairingCode, evaluateAccess, formatAllowFrom, readAllowFrom, readChannelOwner, readGroupAllowFrom, readPendingPairings, removeAllowFrom, revokePairingCode, upsertPairingRequest, } from "./access-control/index.js";
 import { isAbortTrigger } from "./abort-triggers.js";
 import { buildAgentSwitchCommands } from "./agent-switch-command.js";
+import { decodeGeneralCallbackData, isGeneralCallbackData } from "./general-callback.js";
 import { tryConsumeChannelApprovalCallback, tryConsumeChannelApprovalReply, } from "./approval-router.js";
 import { recordLastChannelForAgent } from "./last-channel.js";
 import { recordLastSentMessage } from "./last-sent-message.js";
@@ -35,6 +36,8 @@ import { resolveAgentRoute } from "../routing/resolve-route.js";
 import { normalizeAccountId } from "../routing/account-id.js";
 import { resolveThreadSessionKeys } from "../routing/session-key.js";
 import { resolveLinkedPeerIdFromConfig } from "../identity-links.js";
+import { resolveInboundConversation } from "./channel-messaging-registry.js";
+import { consultChannelDmPolicy } from "./channel-security-registry.js";
 import { sanitizeReplyForChannel } from "./reply-sanitizer.js";
 import { classifyErrorReason, isBrigadeRetryError } from "../error-classifier.js";
 import { isRetryExhaustedError } from "../retry-policy.js";
@@ -146,9 +149,11 @@ function buildChallengeReply(args) {
         "```",
         args.code,
         "```",
-        "Share it with your admin — they'll approve you by running:",
+        "Send this code to your admin. They approve you by either:",
+        `  •  replying  *\`/approve ${args.code}\`*  to this bot, or`,
+        `  •  running this on the server:`,
         "```",
-        `brigade pairing approve ${args.code}`,
+        `brigade pairing approve ${args.code} --channel ${args.channelId}`,
         "```",
         "✨  Once approved, just send your next message.",
         "⏱️  _Expires in 1 hour._",
@@ -158,11 +163,17 @@ function buildChallengeReply(args) {
 }
 /** Bundled built-in channel commands an operator can DM to admin the bot. */
 export function buildBundledCommands(adapter) {
-    const isOperator = (senderId) => {
+    const norm = (s) => s.replace(/\s+/g, "");
+    const isOperator = (senderId, accountId) => {
+        const id = norm(senderId);
+        // The linked-self id (WhatsApp: the bot runs AS the operator).
         const self = adapter.selfId?.();
-        if (!self)
-            return false;
-        return self.replace(/\s+/g, "") === senderId.replace(/\s+/g, "");
+        if (self && norm(self) === id)
+            return true;
+        // The recorded channel owner (Telegram: bot ≠ operator, owner is claimed
+        // via first /start). accountId scopes multi-account installs.
+        const owner = readChannelOwner(adapter.id, accountId ?? null);
+        return !!owner && norm(owner) === id;
     };
     return [
         {
@@ -171,7 +182,11 @@ export function buildBundledCommands(adapter) {
             handler: () => [
                 "Brigade channel commands:",
                 "  /help            — show this list",
+                "  /start           — welcome + how to use this bot",
                 "  /status          — show your access state on this channel",
+                "  /pending         — operator-only: list people waiting for approval",
+                "  /approve <code>  — operator-only: approve a waiting person by their code",
+                "  /deny <code>     — operator-only: reject a pending request",
                 "  /allowlist list  — operator-only: show approved senders",
                 "  /allowlist add <id> | /allowlist remove <id> — operator-only",
                 "  /agent <id>      — pin future messages from you to that agent",
@@ -185,11 +200,85 @@ export function buildBundledCommands(adapter) {
                 "  stop / cancel / abort — kill the current turn",
             ].join("\n"),
         },
+        {
+            name: "start",
+            description: "Welcome message + how to use this bot.",
+            handler: (ctx) => {
+                if (isOperator(ctx.from, ctx.accountId ?? null)) {
+                    return [
+                        "🦁 *Brigade* — your private AI crew is online.",
+                        "",
+                        "Just send a message to chat with your crew.",
+                        "Admin: /pending, /approve <code>, /allowlist, /agents, /org.",
+                        "Type /help for the full list.",
+                    ].join("\n");
+                }
+                return [
+                    "🦁 *Brigade* — your private AI crew.",
+                    "",
+                    "Send a message and your crew will reply.",
+                    "Type /help to see what you can do, or /whoami to see who answers you.",
+                ].join("\n");
+            },
+        },
+        {
+            name: "pending",
+            description: "Operator-only: list people waiting for approval.",
+            handler: (ctx) => {
+                if (!isOperator(ctx.from, ctx.accountId ?? null))
+                    return "This command can only be run by the operator (the linked account).";
+                const pending = readPendingPairings(ctx.channel, ctx.accountId ?? null);
+                if (pending.length === 0)
+                    return "No one is waiting for approval right now.";
+                const lines = pending.map((r) => {
+                    const who = r.senderName ? `${r.senderName} (${r.senderId})` : r.senderId;
+                    return `  ${r.code}  —  ${who}`;
+                });
+                return [
+                    `${pending.length} waiting for approval:`,
+                    ...lines,
+                    "",
+                    "Approve with /approve <code>, or reject with /deny <code>.",
+                ].join("\n");
+            },
+        },
+        {
+            name: "approve",
+            description: "Operator-only: approve a waiting person by their pairing code.",
+            handler: (ctx) => {
+                if (!isOperator(ctx.from, ctx.accountId ?? null))
+                    return "This command can only be run by the operator (the linked account).";
+                const code = ctx.args.trim().split(/\s+/)[0] ?? "";
+                if (!code)
+                    return "Usage: /approve <code>   (see waiting codes with /pending)";
+                const approved = approvePairingCode(ctx.channel, code, ctx.accountId ?? null);
+                if (!approved)
+                    return `No pending request with code "${code}". Check /pending.`;
+                const who = approved.senderName
+                    ? `${approved.senderName} (${approved.senderId})`
+                    : approved.senderId;
+                return `✅ Approved ${who}. They can chat now — no restart needed.`;
+            },
+        },
+        {
+            name: "deny",
+            description: "Operator-only: reject a pending request by its pairing code.",
+            handler: (ctx) => {
+                if (!isOperator(ctx.from, ctx.accountId ?? null))
+                    return "This command can only be run by the operator (the linked account).";
+                const code = ctx.args.trim().split(/\s+/)[0] ?? "";
+                if (!code)
+                    return "Usage: /deny <code>   (see waiting codes with /pending)";
+                return revokePairingCode(ctx.channel, code, ctx.accountId ?? null)
+                    ? `⛔ Rejected request ${code}.`
+                    : `No pending request with code "${code}".`;
+            },
+        },
         {
             name: "status",
             description: "Show your access state on this channel.",
             handler: (ctx) => {
-                const op = isOperator(ctx.from);
+                const op = isOperator(ctx.from, ctx.accountId ?? null);
                 const allow = readAllowFrom(ctx.channel);
                 const role = op ? "operator (self)" : allow.includes(ctx.from) ? "approved" : "unapproved";
                 return [
@@ -204,15 +293,15 @@ export function buildBundledCommands(adapter) {
             name: "allowlist",
             description: "Operator-only: list / add / remove approved senders.",
             handler: (ctx) => {
-                if (!isOperator(ctx.from))
+                if (!isOperator(ctx.from, ctx.accountId ?? null))
                     return "This command can only be run by the operator (the linked account).";
                 const parts = ctx.args.trim().split(/\s+/);
                 const sub = (parts[0] ?? "list").toLowerCase();
                 if (sub === "list" || !sub) {
                     const allow = readAllowFrom(ctx.channel);
-                    return allow.length === 0
-                        ? "Allow-from list is empty."
-                        : `Allow-from (${allow.length}):\n  ${allow.join("\n  ")}`;
+                    // Shared display formatter so the in-chat `/allowlist list` and the
+                    // `brigade channels allow list` CLI render the list identically.
+                    return formatAllowFrom(allow);
                 }
                 const target = parts[1];
                 if (sub === "add" && target) {
@@ -260,13 +349,23 @@ async function safeSendText(adapter, conversationId, text, opts) {
         });
     }
 }
-/** Build the opts object the adapter expects, omitting undefined keys. */
-function buildSendOpts(threadId, accountId) {
+/**
+ * Build the opts object the adapter expects, omitting undefined keys.
+ *
+ * `replyToId` is OPTIONAL and additive: pass the inbound message's id ONLY at a
+ * genuine reply-to-inbound send site so the adapter quotes the message it
+ * answers (WhatsApp quote / Telegram `reply_parameters`). Omit it everywhere
+ * else — a build with no `replyToId` produces a byte-identical opts object to
+ * before this field existed, so non-reply sends are unchanged.
+ */
+function buildSendOpts(threadId, accountId, replyToId) {
     const out = {};
     if (threadId)
         out.threadId = threadId;
     if (accountId)
         out.accountId = accountId;
+    if (replyToId)
+        out.replyToId = replyToId;
     return Object.keys(out).length > 0 ? out : undefined;
 }
 /**
@@ -288,9 +387,48 @@ export async function runChannelInboundPipeline(ctx, msg) {
             !msg.callbackQuery) {
             return;
         }
+        // Plugin hook: `inbound_claim` (CLAIMING). A plugin may take ownership of
+        // this raw inbound BEFORE Brigade's access-control gate runs — the first
+        // handler to return `{ handled: true }` claims it and we abandon the
+        // inbound entirely (no gate, no command, no dispatch). Fires only when a
+        // registry is mounted (gateway boot); a non-gateway path skips it.
+        {
+            const registry = getActiveRegistry();
+            if (registry) {
+                const claim = await registry.fireHook("inbound_claim", {
+                    channel: adapter.id,
+                    msg,
+                });
+                if (claim.handled) {
+                    log.debug("inbound claimed by plugin hook", {
+                        channel: adapter.id,
+                        conversationId: msg.conversationId,
+                        by: claim.by,
+                    });
+                    return;
+                }
+            }
+        }
         // Access-control gate.
         const isGroup = msg.isGroup === true || msg.chatType === "group";
-        const dmPolicy = resolveDmPolicy(cfg, adapter.id);
+        // Central config-read policy (AUTHORITATIVE). A channel plugin MAY also
+        // register a SUPPLEMENTARY security adapter; we consult it right here and
+        // reconcile under a strict TIGHTEN-ONLY rule — the adapter can make the
+        // effective DM policy stricter (owner-only > allowlist > open > the config)
+        // but can NEVER loosen it, and a channel that doesn't opt in leaves
+        // `dmPolicy` byte-identical to the local read. Never throws.
+        const localDmPolicy = resolveDmPolicy(cfg, adapter.id);
+        const dmPolicy = consultChannelDmPolicy({
+            channelId: adapter.id,
+            base: localDmPolicy,
+            ctx: {
+                account: undefined,
+                accountId: msg.accountId?.trim() || "",
+                cfg,
+                ...(msg.from?.trim() ? { peerId: msg.from.trim() } : {}),
+                peerKind: isGroup ? "group" : "direct",
+            },
+        });
         const groupPolicy = resolveGroupPolicy(cfg, adapter.id);
         const cfgEntry = channelAccessCfg(cfg, adapter.id);
         // Per-account ACL — multi-account WhatsApp installs partition the
@@ -307,7 +445,14 @@ export async function runChannelInboundPipeline(ctx, msg) {
         const groupAllowJids = configIds(cfgEntry.groupAllowJids);
         const selfId = adapter.selfId?.();
         const mentioned = !!(selfId && msg.mentions?.includes(selfId));
-        const senderIsOwner = !!(selfId && selfId.trim() === msg.from.trim());
+        const fromId = msg.from.trim();
+        // On WhatsApp the bot runs AS the operator, so selfId === operator. On a
+        // separate-bot channel (Telegram) the operator is the RECORDED owner —
+        // established securely by the first CLI `pairing approve` (gateway-machine
+        // access is the proof), NOT by anyone who merely texts /start.
+        const isSelfOperator = !!(selfId && selfId.trim() === fromId);
+        const channelOwner = readChannelOwner(adapter.id, aclAccountId);
+        const senderIsOwner = isSelfOperator || (!!channelOwner && channelOwner === fromId);
         // "Addressed" superset for groups: mention OR a reply/quote to one of the
         // bot's OWN messages OR within the active follow-up window for this speaker.
         // Lets a member tag once / reply to the bot and keep the thread going
@@ -320,20 +465,24 @@ export async function runChannelInboundPipeline(ctx, msg) {
         const addressed = isGroup
             ? mentioned || isReplyToBot || withinGroupFollowUp(fuKey, groupFollowUpWindowMs)
             : mentioned;
-        const decision = evaluateAccess({
-            policy: dmPolicy,
-            groupPolicy,
-            senderId: msg.from,
-            ...(msg.senderLid !== undefined ? { senderLid: msg.senderLid } : {}),
-            selfId,
-            allowFrom,
-            groupAllowFrom,
-            groupAllowJids,
-            groupId: msg.conversationId,
-            isGroup,
-            mentioned,
-            addressed,
-        });
+        // The owner is ALWAYS admitted — skip the pairing/allowlist gate entirely
+        // (covers the just-claimed Telegram owner, whose id isn't selfId).
+        const decision = senderIsOwner
+            ? { kind: "allow", reason: "owner" }
+            : evaluateAccess({
+                policy: dmPolicy,
+                groupPolicy,
+                senderId: msg.from,
+                ...(msg.senderLid !== undefined ? { senderLid: msg.senderLid } : {}),
+                selfId,
+                allowFrom,
+                groupAllowFrom,
+                groupAllowJids,
+                groupId: msg.conversationId,
+                isGroup,
+                mentioned,
+                addressed,
+            });
         // Keep the active-conversation window alive on every admitted group turn,
         // so an ongoing back-and-forth doesn't require re-tagging.
         if (isGroup && decision.kind === "allow")
@@ -380,9 +529,13 @@ export async function runChannelInboundPipeline(ctx, msg) {
             await safeSendText(adapter, msg.conversationId, buildChallengeReply({
                 code,
                 senderId: challengeSenderId,
+                channelId: adapter.id,
                 channelLabel: adapter.label,
                 idLabel: adapter.pairing?.idLabel,
-            }), buildSendOpts(msg.threadId, msg.accountId));
+            }), 
+            // Genuine reply-to-inbound: quote the message that triggered the
+            // challenge so the requester sees what they're being asked to verify.
+            buildSendOpts(msg.threadId, msg.accountId, msg.messageId));
             if (msg.messageId && adapter.markRead) {
                 try {
                     await adapter.markRead(msg.conversationId, msg.messageId, msg.participantId);
@@ -443,9 +596,31 @@ export async function runChannelInboundPipeline(ctx, msg) {
                 await safeSendText(adapter, msg.conversationId, cbResult.reason ?? "Not authorized to answer that approval.", buildSendOpts(msg.threadId, msg.accountId));
                 return;
             }
-            // A callback that matched no pending approval (stale / foreign
-            // button) is dropped silently, there is nothing to dispatch.
-            return;
+            // GENERAL (agent-attached) button: not an approval. Decode the
+            // app-defined token and route it through the pipeline as a synthetic
+            // turn so the agent that attached the button can react to the tap.
+            // We rewrite `msg.text` and FALL THROUGH to the normal routing +
+            // dispatch path below (instead of returning).
+            if (isGeneralCallbackData(msg.callbackQuery.data)) {
+                const token = decodeGeneralCallbackData(msg.callbackQuery.data);
+                if (token) {
+                    // Synthetic inbound text the agent sees for the tap. Kept short +
+                    // explicit so the agent can branch on the token it set.
+                    msg.text = `[button] ${token}`;
+                    // Clear the callbackQuery so the downstream path treats this as a
+                    // normal text turn (and doesn't re-enter this block).
+                    msg.callbackQuery = undefined;
+                    // fall through ↓
+                }
+                else {
+                    return;
+                }
+            }
+            else {
+                // A callback that matched no pending approval (stale / foreign
+                // button) is dropped silently, there is nothing to dispatch.
+                return;
+            }
         }
         // ── Sender ADMITTED — only now pay for media. ──────────────────────
         // Deferred downloads (msg.resolveMedia) run here, after the access
@@ -573,11 +748,18 @@ export async function runChannelInboundPipeline(ctx, msg) {
         const rawAccountId = msg.accountId?.trim() || msg.conversationId;
         const normalizedAccountId = normalizeAccountId(rawAccountId);
         const peerKind = isGroup ? "group" : "direct";
+        // INBOUND conversation resolution (the inverse of the outbound
+        // `resolveOutboundTarget`): canonicalise the incoming peer id via the
+        // channel's registered `messaging` adapter so a name-addressed inbound
+        // collapses onto the SAME conversation/session outbound resolves to. When
+        // the channel doesn't opt in, this returns `msg.from` unchanged, so the
+        // config-link resolve + routing below are byte-identical to before.
+        const inboundPeerId = resolveInboundConversation({ channelId: adapter.id, peerId: msg.from });
         const canonicalPeerId = resolveLinkedPeerIdFromConfig({
             config: cfg,
             channel: adapter.id,
-            peerId: msg.from,
-        }) ?? msg.from;
+            peerId: inboundPeerId,
+        }) ?? inboundPeerId;
         const route = resolveAgentRoute({
             cfg,
             channel: adapter.id,
@@ -633,7 +815,34 @@ export async function runChannelInboundPipeline(ctx, msg) {
             }
             return;
         }
-        // Immediate dispatch.
+        // Plugin hook: `before_dispatch` (CLAIMING). A plugin may claim the turn
+        // just before it dispatches to the agent — claim → skip dispatch entirely
+        // (no reply). Fired for the immediate path here; the debounced path fires
+        // the same hook inside `flushDispatch` before its own dispatch.
+        {
+            const registry = getActiveRegistry();
+            if (registry) {
+                const claim = await registry.fireHook("before_dispatch", {
+                    channel: adapter.id,
+                    agentId: resolvedAgentId,
+                    sessionKey,
+                    text,
+                    conversationId: msg.conversationId,
+                    ...(msg.threadId !== undefined ? { threadId: msg.threadId } : {}),
+                    ...(msg.accountId !== undefined ? { accountId: msg.accountId } : {}),
+                });
+                if (claim.handled) {
+                    log.debug("dispatch claimed by plugin hook", {
+                        channel: adapter.id,
+                        conversationId: msg.conversationId,
+                        by: claim.by,
+                    });
+                    return;
+                }
+            }
+        }
+        // Immediate dispatch. Pass the inbound's id as the reply target so the
+        // agent's answer NATIVELY quotes the message it answers.
         await dispatchTurn(ctx, {
             text,
             sessionKey,
@@ -641,6 +850,7 @@ export async function runChannelInboundPipeline(ctx, msg) {
             conversationId: msg.conversationId,
             ...(msg.threadId !== undefined ? { threadId: msg.threadId } : {}),
             ...(msg.accountId !== undefined ? { accountId: msg.accountId } : {}),
+            ...(msg.messageId !== undefined ? { replyToId: msg.messageId } : {}),
             senderIsOwner,
             channelApprovalRoute,
         });
@@ -682,6 +892,34 @@ export async function runChannelInboundPipeline(ctx, msg) {
                 /* cosmetic */
             }
         }
+        // Live-streaming: if the adapter advertises `beginReplyStream` AND it
+        // returns a stream (the adapter gates on its own config), open it and
+        // feed the gateway's accumulating answer text into it as tokens arrive.
+        // The stream is best-effort UX — the FINAL reply below is still sent
+        // authoritatively (or skipped when the stream already delivered it).
+        let replyStream = null;
+        if (typeof c.adapter.beginReplyStream === "function") {
+            try {
+                replyStream = c.adapter.beginReplyStream(a.conversationId, buildSendOpts(a.threadId, a.accountId, a.replyToId));
+            }
+            catch {
+                replyStream = null;
+            }
+        }
+        // Only forward deltas when a stream is actually open; the sink sanitizes
+        // upstream, but a closed/aborted stream must drop late deltas.
+        const onReplyDelta = replyStream
+            ? (text) => {
+                if (controller.signal.aborted)
+                    return;
+                try {
+                    replyStream?.update(text);
+                }
+                catch {
+                    /* stream hiccup never breaks the turn */
+                }
+            }
+            : undefined;
         let result;
         try {
             result = await c.runTurn({
@@ -693,9 +931,11 @@ export async function runChannelInboundPipeline(ctx, msg) {
                 ...(a.channelApprovalRoute !== undefined
                     ? { channelApprovalRoute: a.channelApprovalRoute }
                     : {}),
+                ...(onReplyDelta ? { onReplyDelta } : {}),
             });
         }
         catch (err) {
+            replyStream?.stop();
             if (c.inflight.get(ilKey) === controller)
                 c.inflight.delete(ilKey);
             if (c.adapter.setComposing) {
@@ -718,15 +958,118 @@ export async function runChannelInboundPipeline(ctx, msg) {
                 /* cosmetic */
             }
         }
-        if (controller.signal.aborted)
+        if (controller.signal.aborted) {
+            replyStream?.stop();
             return;
+        }
         const reply = sanitizeReplyForChannel(result.reply?.trim() ?? "");
         if (reply) {
+            // Plugin hook: `reply_dispatch` (CLAIMING). A plugin may suppress /
+            // take over the outgoing reply — if a handler claims (`{ handled:
+            // true }`), it OWNS delivery: Brigade sends nothing of its own AND
+            // emits no reasoning trace + records no last-sent message. Consulted
+            // FIRST (before reasoning, before any stream finalize / sendText) so a
+            // replaced reply never leaks its reasoning or a half-stream. Fires only
+            // when a registry is mounted; identical for the streaming +
+            // non-streaming paths below.
+            const replyRegistry = getActiveRegistry();
+            if (replyRegistry) {
+                const claim = await replyRegistry.fireHook("reply_dispatch", {
+                    channel: c.adapter.id,
+                    agentId: a.agentId,
+                    conversationId: a.conversationId,
+                    reply,
+                    ...(a.threadId !== undefined ? { threadId: a.threadId } : {}),
+                    ...(a.accountId !== undefined ? { accountId: a.accountId } : {}),
+                });
+                if (claim.handled) {
+                    log.debug("reply suppressed by plugin hook", {
+                        channel: c.adapter.id,
+                        conversationId: a.conversationId,
+                        by: claim.by,
+                    });
+                    // A claimed reply means the plugin owns delivery — abandon any
+                    // open stream WITHOUT finalizing so it doesn't leak a placeholder.
+                    replyStream?.stop();
+                    return;
+                }
+            }
+            // Reasoning lane (OPTIONAL, default OFF): when the adapter opts in, hand
+            // it the RAW reply so it can deliver a `<think>` trace as a separate
+            // prefixed message BEFORE the answer. The adapter gates on its own
+            // config; a no-op adapter (or disabled config) sends nothing. Runs for
+            // BOTH streaming + non-streaming paths so reasoning always precedes the
+            // answer. Best-effort — never blocks the answer below.
+            if (typeof c.adapter.deliverReasoning === "function") {
+                try {
+                    await c.adapter.deliverReasoning(a.conversationId, result.reply ?? "", buildSendOpts(a.threadId, a.accountId, a.replyToId));
+                }
+                catch (err) {
+                    log.warn("deliverReasoning failed (non-fatal)", {
+                        channel: c.adapter.id,
+                        conversationId: a.conversationId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            // STREAMING path: when a live stream is open, FINALIZE it with the
+            // complete reply (it edits the in-progress message to the full text +
+            // rolls overflow into new messages). This replaces the single
+            // `sendText` below — the stream is now authoritative for delivery. On a
+            // successful finalize the streamed send fires `message_sent` (VOID) just
+            // like the non-streaming path, then returns.
+            if (replyStream) {
+                try {
+                    const sent = await replyStream.finalize(reply);
+                    const streamedMessageId = sent && typeof sent === "object" ? sent.messageId : undefined;
+                    recordLastSentMessage({
+                        agentId: a.agentId,
+                        channelId: c.adapter.id,
+                        conversationId: a.conversationId,
+                        messageId: streamedMessageId,
+                        ...(a.threadId !== undefined ? { threadId: a.threadId } : {}),
+                        ...(a.accountId !== undefined ? { accountId: a.accountId } : {}),
+                    });
+                    // Plugin hook: `message_sent` (VOID) — telemetry after the streamed
+                    // reply lands. Awaited so async handler work flushes; the result is
+                    // ignored (void handlers can never alter or block delivery).
+                    if (replyRegistry) {
+                        await replyRegistry.fireHook("message_sent", {
+                            channel: c.adapter.id,
+                            agentId: a.agentId,
+                            conversationId: a.conversationId,
+                            text: reply,
+                            messageId: streamedMessageId,
+                            ...(a.threadId !== undefined ? { threadId: a.threadId } : {}),
+                            ...(a.accountId !== undefined ? { accountId: a.accountId } : {}),
+                        });
+                    }
+                    return;
+                }
+                catch (err) {
+                    // Stream finalize failed — fall through to the non-streaming
+                    // sendText so the recipient still gets the complete reply.
+                    log.warn("reply stream finalize failed; falling back to sendText", {
+                        channel: c.adapter.id,
+                        conversationId: a.conversationId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    try {
+                        replyStream.stop();
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }
+            }
+            // NON-STREAMING path (or a stream that failed to finalize above). The
+            // `reply_dispatch` claim was already consulted at the top of this block,
+            // so a suppressed reply never reaches here.
             // Capture the sent id (additive `{ messageId }` return) so the agent
             // can later reference "my last message" via `message_action` without
             // having to track ids itself. Channels that return void simply leave
             // the last-sent record unset.
-            const sent = await c.adapter.sendText(a.conversationId, reply, buildSendOpts(a.threadId, a.accountId));
+            const sent = await c.adapter.sendText(a.conversationId, reply, buildSendOpts(a.threadId, a.accountId, a.replyToId));
             recordLastSentMessage({
                 agentId: a.agentId,
                 channelId: c.adapter.id,
@@ -735,6 +1078,25 @@ export async function runChannelInboundPipeline(ctx, msg) {
                 ...(a.threadId !== undefined ? { threadId: a.threadId } : {}),
                 ...(a.accountId !== undefined ? { accountId: a.accountId } : {}),
             });
+            // Plugin hook: `message_sent` (VOID) — fire-and-forget telemetry after a
+            // reply lands. Awaited (so a handler's async work is flushed) but the
+            // result is ignored; void handlers can never alter or block delivery.
+            if (replyRegistry) {
+                await replyRegistry.fireHook("message_sent", {
+                    channel: c.adapter.id,
+                    agentId: a.agentId,
+                    conversationId: a.conversationId,
+                    text: reply,
+                    messageId: sent && typeof sent === "object" ? sent.messageId : undefined,
+                    ...(a.threadId !== undefined ? { threadId: a.threadId } : {}),
+                    ...(a.accountId !== undefined ? { accountId: a.accountId } : {}),
+                });
+            }
+        }
+        else {
+            // No reply text but a stream may have been opened (and possibly already
+            // sent a placeholder) — stop it so it doesn't leak.
+            replyStream?.stop();
         }
     }
     // Flush a debounce slot.
@@ -747,6 +1109,33 @@ export async function runChannelInboundPipeline(ctx, msg) {
         const conversationId = slot.baseMsg.conversationId;
         const threadId = slot.baseMsg.threadId;
         const accountId = slot.baseMsg.accountId;
+        // Coalesced turn: quote the FIRST message of the debounce window (the one
+        // that opened the slot) as the reply target.
+        const replyToId = slot.baseMsg.messageId;
+        // Plugin hook: `before_dispatch` (CLAIMING) — debounced path. Same hook
+        // as the immediate path above; a claim here skips the coalesced dispatch.
+        {
+            const registry = getActiveRegistry();
+            if (registry) {
+                const claim = await registry.fireHook("before_dispatch", {
+                    channel: c.adapter.id,
+                    agentId: slot.agentId,
+                    sessionKey: slot.sessionKey,
+                    text: combined,
+                    conversationId,
+                    ...(threadId !== undefined ? { threadId } : {}),
+                    ...(accountId !== undefined ? { accountId } : {}),
+                });
+                if (claim.handled) {
+                    log.debug("debounced dispatch claimed by plugin hook", {
+                        channel: c.adapter.id,
+                        conversationId,
+                        by: claim.by,
+                    });
+                    return;
+                }
+            }
+        }
         try {
             await dispatchTurn(c, {
                 text: combined,
@@ -755,6 +1144,7 @@ export async function runChannelInboundPipeline(ctx, msg) {
                 conversationId,
                 ...(threadId !== undefined ? { threadId } : {}),
                 ...(accountId !== undefined ? { accountId } : {}),
+                ...(replyToId !== undefined ? { replyToId } : {}),
                 senderIsOwner: slot.senderIsOwner,
                 channelApprovalRoute: slot.channelApprovalRoute,
             });