@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/auto-reply/reply/commands-system-prompt.js

@@ -1,7 +1,7 @@
 import { resolveSessionAgentIds } from "../../agents/agent-scope.js";
 import { resolveBootstrapContextForRun } from "../../agents/bootstrap-files.js";
 import { resolveDefaultModelForAgent } from "../../agents/model-selection.js";
-import { createOpenClawCodingTools } from "../../agents/pi-tools.js";
+import { createPoolbotCodingTools } from "../../agents/pi-tools.js";
 import { resolveSandboxRuntimeStatus } from "../../agents/sandbox.js";
 import { buildWorkspaceSkillSnapshot } from "../../agents/skills.js";
 import { getSkillsSnapshotVersion } from "../../agents/skills/refresh.js";
@@ -37,7 +37,7 @@ export async function resolveCommandsSystemPromptBundle(params) {
     });
     const tools = (() => {
         try {
-            return createOpenClawCodingTools({
+            return createPoolbotCodingTools({
                 config: params.cfg,
                 workspaceDir,
                 sessionKey: params.sessionKey,

package/dist/auto-reply/reply/dispatch-from-config.js

@@ -1,14 +1,15 @@
 import { resolveSessionAgentId } from "../../agents/agent-scope.js";
 import { loadSessionStore, resolveStorePath } from "../../config/sessions.js";
 import { logVerbose } from "../../globals.js";
+import { createInternalHookEvent, triggerInternalHook } from "../../hooks/internal-hooks.js";
 import { isDiagnosticsEnabled } from "../../infra/diagnostic-events.js";
 import { logMessageProcessed, logMessageQueued, logSessionStateChange, } from "../../logging/diagnostic.js";
 import { getGlobalHookRunner } from "../../plugins/hook-runner-global.js";
+import { maybeApplyTtsToPayload, normalizeTtsAutoMode, resolveTtsConfig } from "../../tts/tts.js";
 import { getReplyFromConfig } from "../reply.js";
 import { formatAbortReplyText, tryFastAbortFromMessage } from "./abort.js";
 import { shouldSkipDuplicateInbound } from "./inbound-dedupe.js";
 import { isRoutableChannel, routeReply } from "./route-reply.js";
-import { maybeApplyTtsToPayload, normalizeTtsAutoMode, resolveTtsConfig } from "../../tts/tts.js";
 const AUDIO_PLACEHOLDER_RE = /^<media:audio>(\s*\([^)]*\))?$/i;
 const AUDIO_HEADER_RE = /^\[Audio\b/i;
 const normalizeMediaType = (value) => value.split(";")[0]?.trim().toLowerCase();
@@ -18,8 +19,9 @@ const isInboundAudioContext = (ctx) => {
         ...(Array.isArray(ctx.MediaTypes) ? ctx.MediaTypes : []),
     ].filter(Boolean);
     const types = rawTypes.map((type) => normalizeMediaType(type));
-    if (types.some((type) => type === "audio" || type.startsWith("audio/")))
+    if (types.some((type) => type === "audio" || type.startsWith("audio/"))) {
         return true;
+    }
     const body = typeof ctx.BodyForCommands === "string"
         ? ctx.BodyForCommands
         : typeof ctx.CommandBody === "string"
@@ -30,17 +32,20 @@ const isInboundAudioContext = (ctx) => {
                     ? ctx.Body
                     : "";
     const trimmed = body.trim();
-    if (!trimmed)
+    if (!trimmed) {
         return false;
-    if (AUDIO_PLACEHOLDER_RE.test(trimmed))
+    }
+    if (AUDIO_PLACEHOLDER_RE.test(trimmed)) {
         return true;
+    }
     return AUDIO_HEADER_RE.test(trimmed);
 };
 const resolveSessionTtsAuto = (ctx, cfg) => {
     const targetSessionKey = ctx.CommandSource === "native" ? ctx.CommandTargetSessionKey?.trim() : undefined;
     const sessionKey = (targetSessionKey ?? ctx.SessionKey)?.trim();
-    if (!sessionKey)
+    if (!sessionKey) {
         return undefined;
+    }
     const agentId = resolveSessionAgentId({ sessionKey, config: cfg });
     const storePath = resolveStorePath(cfg.session?.store, { agentId });
     try {
@@ -62,8 +67,9 @@ export async function dispatchReplyFromConfig(params) {
     const startTime = diagnosticsEnabled ? Date.now() : 0;
     const canTrackSession = diagnosticsEnabled && Boolean(sessionKey);
     const recordProcessed = (outcome, opts) => {
-        if (!diagnosticsEnabled)
+        if (!diagnosticsEnabled) {
             return;
+        }
         logMessageProcessed({
             channel,
             chatId,
@@ -76,8 +82,9 @@ export async function dispatchReplyFromConfig(params) {
         });
     };
     const markProcessing = () => {
-        if (!canTrackSession || !sessionKey)
+        if (!canTrackSession || !sessionKey) {
             return;
+        }
         logMessageQueued({ sessionKey, channel, source: "dispatch" });
         logSessionStateChange({
             sessionKey,
@@ -86,8 +93,9 @@ export async function dispatchReplyFromConfig(params) {
         });
     };
     const markIdle = (reason) => {
-        if (!canTrackSession || !sessionKey)
+        if (!canTrackSession || !sessionKey) {
             return;
+        }
         logSessionStateChange({
             sessionKey,
             state: "idle",
@@ -101,20 +109,20 @@ export async function dispatchReplyFromConfig(params) {
     const inboundAudio = isInboundAudioContext(ctx);
     const sessionTtsAuto = resolveSessionTtsAuto(ctx, cfg);
     const hookRunner = getGlobalHookRunner();
+    // Extract message context for hooks (plugin and internal)
+    const timestamp = typeof ctx.Timestamp === "number" && Number.isFinite(ctx.Timestamp) ? ctx.Timestamp : undefined;
+    const messageIdForHook = ctx.MessageSidFull ?? ctx.MessageSid ?? ctx.MessageSidFirst ?? ctx.MessageSidLast;
+    const content = typeof ctx.BodyForCommands === "string"
+        ? ctx.BodyForCommands
+        : typeof ctx.RawBody === "string"
+            ? ctx.RawBody
+            : typeof ctx.Body === "string"
+                ? ctx.Body
+                : "";
+    const channelId = (ctx.OriginatingChannel ?? ctx.Surface ?? ctx.Provider ?? "").toLowerCase();
+    const conversationId = ctx.OriginatingTo ?? ctx.To ?? ctx.From ?? undefined;
+    // Trigger plugin hooks (fire-and-forget)
     if (hookRunner?.hasHooks("message_received")) {
-        const timestamp = typeof ctx.Timestamp === "number" && Number.isFinite(ctx.Timestamp)
-            ? ctx.Timestamp
-            : undefined;
-        const messageIdForHook = ctx.MessageSidFull ?? ctx.MessageSid ?? ctx.MessageSidFirst ?? ctx.MessageSidLast;
-        const content = typeof ctx.BodyForCommands === "string"
-            ? ctx.BodyForCommands
-            : typeof ctx.RawBody === "string"
-                ? ctx.RawBody
-                : typeof ctx.Body === "string"
-                    ? ctx.Body
-                    : "";
-        const channelId = (ctx.OriginatingChannel ?? ctx.Surface ?? ctx.Provider ?? "").toLowerCase();
-        const conversationId = ctx.OriginatingTo ?? ctx.To ?? ctx.From ?? undefined;
         void hookRunner
             .runMessageReceived({
             from: ctx.From ?? "",
@@ -139,7 +147,31 @@ export async function dispatchReplyFromConfig(params) {
             conversationId,
         })
             .catch((err) => {
-            logVerbose(`dispatch-from-config: message_received hook failed: ${String(err)}`);
+            logVerbose(`dispatch-from-config: message_received plugin hook failed: ${String(err)}`);
+        });
+    }
+    // Bridge to internal hooks (HOOK.md discovery system) - refs #8807
+    if (sessionKey) {
+        void triggerInternalHook(createInternalHookEvent("message", "received", sessionKey, {
+            from: ctx.From ?? "",
+            content,
+            timestamp,
+            channelId,
+            accountId: ctx.AccountId,
+            conversationId,
+            messageId: messageIdForHook,
+            metadata: {
+                to: ctx.To,
+                provider: ctx.Provider,
+                surface: ctx.Surface,
+                threadId: ctx.MessageThreadId,
+                senderId: ctx.SenderId,
+                senderName: ctx.SenderName,
+                senderUsername: ctx.SenderUsername,
+                senderE164: ctx.SenderE164,
+            },
+        })).catch((err) => {
+            logVerbose(`dispatch-from-config: message_received internal hook failed: ${String(err)}`);
         });
     }
     // Check if we should route replies to originating channel instead of dispatcher.
@@ -163,10 +195,12 @@ export async function dispatchReplyFromConfig(params) {
     const sendPayloadAsync = async (payload, abortSignal, mirror) => {
         // TypeScript doesn't narrow these from the shouldRouteToOriginating check,
         // but they're guaranteed non-null when this function is called.
-        if (!originatingChannel || !originatingTo)
+        if (!originatingChannel || !originatingTo) {
             return;
-        if (abortSignal?.aborted)
+        }
+        if (abortSignal?.aborted) {
             return;
+        }
         const result = await routeReply({
             payload,
             channel: originatingChannel,
@@ -202,8 +236,9 @@ export async function dispatchReplyFromConfig(params) {
                     cfg,
                 });
                 queuedFinal = result.ok;
-                if (result.ok)
+                if (result.ok) {
                     routedFinalCount += 1;
+                }
                 if (!result.ok) {
                     logVerbose(`dispatch-from-config: route-reply (abort) failed: ${result.error ?? "unknown error"}`);
                 }
@@ -211,7 +246,6 @@ export async function dispatchReplyFromConfig(params) {
             else {
                 queuedFinal = dispatcher.sendFinalReply(payload);
             }
-            await dispatcher.waitForIdle();
             const counts = dispatcher.getQueuedCounts();
             counts.final += routedFinalCount;
             recordProcessed("completed", { reason: "fast_abort" });
@@ -223,8 +257,44 @@ export async function dispatchReplyFromConfig(params) {
         // TTS audio separately from the accumulated block content.
         let accumulatedBlockText = "";
         let blockCount = 0;
+        const shouldSendToolSummaries = ctx.ChatType !== "group" && ctx.CommandSource !== "native";
+        const resolveToolDeliveryPayload = (payload) => {
+            if (shouldSendToolSummaries) {
+                return payload;
+            }
+            // Group/native flows intentionally suppress tool summary text, but media-only
+            // tool results (for example TTS audio) must still be delivered.
+            const hasMedia = Boolean(payload.mediaUrl) || (payload.mediaUrls?.length ?? 0) > 0;
+            if (!hasMedia) {
+                return null;
+            }
+            return { ...payload, text: undefined };
+        };
         const replyResult = await (params.replyResolver ?? getReplyFromConfig)(ctx, {
             ...params.replyOptions,
+            onToolResult: (payload) => {
+                const run = async () => {
+                    const ttsPayload = await maybeApplyTtsToPayload({
+                        payload,
+                        cfg,
+                        channel: ttsChannel,
+                        kind: "tool",
+                        inboundAudio,
+                        ttsAuto: sessionTtsAuto,
+                    });
+                    const deliveryPayload = resolveToolDeliveryPayload(ttsPayload);
+                    if (!deliveryPayload) {
+                        return;
+                    }
+                    if (shouldRouteToOriginating) {
+                        await sendPayloadAsync(deliveryPayload, undefined, false);
+                    }
+                    else {
+                        dispatcher.sendToolResult(deliveryPayload);
+                    }
+                };
+                return run();
+            },
             onBlockReply: (payload, context) => {
                 const run = async () => {
                     // Accumulate block text for TTS generation after streaming
@@ -280,8 +350,9 @@ export async function dispatchReplyFromConfig(params) {
                     logVerbose(`dispatch-from-config: route-reply (final) failed: ${result.error ?? "unknown error"}`);
                 }
                 queuedFinal = result.ok || queuedFinal;
-                if (result.ok)
+                if (result.ok) {
                     routedFinalCount += 1;
+                }
             }
             else {
                 queuedFinal = dispatcher.sendFinalReply(ttsReply) || queuedFinal;
@@ -322,8 +393,9 @@ export async function dispatchReplyFromConfig(params) {
                             cfg,
                         });
                         queuedFinal = result.ok || queuedFinal;
-                        if (result.ok)
+                        if (result.ok) {
                             routedFinalCount += 1;
+                        }
                         if (!result.ok) {
                             logVerbose(`dispatch-from-config: route-reply (tts-only) failed: ${result.error ?? "unknown error"}`);
                         }
@@ -338,7 +410,6 @@ export async function dispatchReplyFromConfig(params) {
                 logVerbose(`dispatch-from-config: accumulated block TTS failed: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        await dispatcher.waitForIdle();
         const counts = dispatcher.getQueuedCounts();
         counts.final += routedFinalCount;
         recordProcessed("completed");

package/dist/auto-reply/reply/elevated-unavailable.js

@@ -14,7 +14,7 @@ export function formatElevatedUnavailableMessage(params) {
     lines.push("- agents.list[].tools.elevated.enabled");
     lines.push("- agents.list[].tools.elevated.allowFrom.<provider>");
     if (params.sessionKey) {
-        lines.push(`See: ${formatCliCommand(`openclaw sandbox explain --session ${params.sessionKey}`)}`);
+        lines.push(`See: ${formatCliCommand(`poolbot sandbox explain --session ${params.sessionKey}`)}`);
     }
     return lines.join("\n");
 }

package/dist/auto-reply/reply/inbound-meta.js

@@ -10,10 +10,19 @@ function safeTrim(value) {
 export function buildInboundMetaSystemPrompt(ctx) {
     const chatType = normalizeChatType(ctx.ChatType);
     const isDirect = !chatType || chatType === "direct";
+    const messageId = safeTrim(ctx.MessageSid);
+    const messageIdFull = safeTrim(ctx.MessageSidFull);
+    const replyToId = safeTrim(ctx.ReplyToId);
+    const chatId = safeTrim(ctx.OriginatingTo);
     // Keep system metadata strictly free of attacker-controlled strings (sender names, group subjects, etc.).
     // Those belong in the user-role "untrusted context" blocks.
     const payload = {
         schema: "poolbot.inbound_meta.v1",
+        message_id: messageId,
+        message_id_full: messageIdFull && messageIdFull !== messageId ? messageIdFull : undefined,
+        sender_id: safeTrim(ctx.SenderId),
+        chat_id: chatId,
+        reply_to_id: replyToId,
         channel: safeTrim(ctx.OriginatingChannel) ?? safeTrim(ctx.Surface) ?? safeTrim(ctx.Provider),
         provider: safeTrim(ctx.Provider),
         surface: safeTrim(ctx.Surface),
@@ -45,7 +54,9 @@ export function buildInboundUserContextPrefix(ctx) {
     const chatType = normalizeChatType(ctx.ChatType);
     const isDirect = !chatType || chatType === "direct";
     const conversationInfo = {
-        conversation_label: safeTrim(ctx.ConversationLabel),
+        message_id: safeTrim(ctx.MessageSid),
+        conversation_label: isDirect ? undefined : safeTrim(ctx.ConversationLabel),
+        sender: safeTrim(ctx.SenderE164) ?? safeTrim(ctx.SenderId) ?? safeTrim(ctx.SenderUsername),
         group_subject: safeTrim(ctx.GroupSubject),
         group_channel: safeTrim(ctx.GroupChannel),
         group_space: safeTrim(ctx.GroupSpace),

package/dist/auto-reply/reply/mentions.js

@@ -1,9 +1,7 @@
 import { resolveAgentConfig } from "../../agents/agent-scope.js";
 import { getChannelDock } from "../../channels/dock.js";
 import { normalizeChannelId } from "../../channels/plugins/index.js";
-function escapeRegExp(text) {
-    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
+import { escapeRegExp } from "../../utils.js";
 function deriveMentionPatterns(identity) {
     const patterns = [];
     const name = identity?.name?.trim();
@@ -21,16 +19,18 @@ function deriveMentionPatterns(identity) {
 const BACKSPACE_CHAR = "\u0008";
 export const CURRENT_MESSAGE_MARKER = "[Current message - respond to this]";
 function normalizeMentionPattern(pattern) {
-    if (!pattern.includes(BACKSPACE_CHAR))
+    if (!pattern.includes(BACKSPACE_CHAR)) {
         return pattern;
+    }
     return pattern.split(BACKSPACE_CHAR).join("\\b");
 }
 function normalizeMentionPatterns(patterns) {
     return patterns.map(normalizeMentionPattern);
 }
 function resolveMentionPatterns(cfg, agentId) {
-    if (!cfg)
+    if (!cfg) {
         return [];
+    }
     const agentConfig = agentId ? resolveAgentConfig(cfg, agentId) : undefined;
     const agentGroupChat = agentConfig?.groupChat;
     if (agentGroupChat && Object.hasOwn(agentGroupChat, "mentionPatterns")) {
@@ -60,11 +60,13 @@ export function normalizeMentionText(text) {
     return (text ?? "").replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g, "").toLowerCase();
 }
 export function matchesMentionPatterns(text, mentionRegexes) {
-    if (mentionRegexes.length === 0)
+    if (mentionRegexes.length === 0) {
         return false;
+    }
     const cleaned = normalizeMentionText(text ?? "");
-    if (!cleaned)
+    if (!cleaned) {
         return false;
+    }
     return mentionRegexes.some((re) => re.test(cleaned));
 }
 export function matchesMentionWithExplicit(params) {
@@ -72,11 +74,16 @@ export function matchesMentionWithExplicit(params) {
     const explicit = params.explicit?.isExplicitlyMentioned === true;
     const explicitAvailable = params.explicit?.canResolveExplicit === true;
     const hasAnyMention = params.explicit?.hasAnyMention === true;
-    if (hasAnyMention && explicitAvailable)
-        return explicit || params.mentionRegexes.some((re) => re.test(cleaned));
-    if (!cleaned)
+    // Check transcript if text is empty and transcript is provided
+    const transcriptCleaned = params.transcript ? normalizeMentionText(params.transcript) : "";
+    const textToCheck = cleaned || transcriptCleaned;
+    if (hasAnyMention && explicitAvailable) {
+        return explicit || params.mentionRegexes.some((re) => re.test(textToCheck));
+    }
+    if (!textToCheck) {
         return explicit;
-    return explicit || params.mentionRegexes.some((re) => re.test(cleaned));
+    }
+    return explicit || params.mentionRegexes.some((re) => re.test(textToCheck));
 }
 export function stripStructuralPrefixes(text) {
     // Ignore wrapper labels, timestamps, and sender prefixes so directive-only

package/dist/auto-reply/reply/normalize-reply.js

@@ -1,19 +1,23 @@
+import { sanitizeUserFacingText } from "../../agents/pi-embedded-helpers.js";
 import { stripHeartbeatToken } from "../heartbeat.js";
 import { HEARTBEAT_TOKEN, isSilentReplyText, SILENT_REPLY_TOKEN } from "../tokens.js";
-import { sanitizeUserFacingText } from "../../agents/pi-embedded-helpers.js";
-import { resolveResponsePrefixTemplate, } from "./response-prefix-template.js";
 import { hasLineDirectives, parseLineDirectives } from "./line-directives.js";
+import { resolveResponsePrefixTemplate, } from "./response-prefix-template.js";
 export function normalizeReplyPayload(payload, opts = {}) {
     const hasMedia = Boolean(payload.mediaUrl || (payload.mediaUrls?.length ?? 0) > 0);
     const hasChannelData = Boolean(payload.channelData && Object.keys(payload.channelData).length > 0);
     const trimmed = payload.text?.trim() ?? "";
-    if (!trimmed && !hasMedia && !hasChannelData)
+    if (!trimmed && !hasMedia && !hasChannelData) {
+        opts.onSkip?.("empty");
         return null;
+    }
     const silentToken = opts.silentToken ?? SILENT_REPLY_TOKEN;
     let text = payload.text ?? undefined;
     if (text && isSilentReplyText(text, silentToken)) {
-        if (!hasMedia && !hasChannelData)
+        if (!hasMedia && !hasChannelData) {
+            opts.onSkip?.("silent");
             return null;
+        }
         text = "";
     }
     if (text && !trimmed) {
@@ -23,17 +27,22 @@ export function normalizeReplyPayload(payload, opts = {}) {
     const shouldStripHeartbeat = opts.stripHeartbeat ?? true;
     if (shouldStripHeartbeat && text?.includes(HEARTBEAT_TOKEN)) {
         const stripped = stripHeartbeatToken(text, { mode: "message" });
-        if (stripped.didStrip)
+        if (stripped.didStrip) {
             opts.onHeartbeatStrip?.();
-        if (stripped.shouldSkip && !hasMedia && !hasChannelData)
+        }
+        if (stripped.shouldSkip && !hasMedia && !hasChannelData) {
+            opts.onSkip?.("heartbeat");
             return null;
+        }
         text = stripped.text;
     }
     if (text) {
-        text = sanitizeUserFacingText(text);
+        text = sanitizeUserFacingText(text, { errorContext: Boolean(payload.isError) });
     }
-    if (!text?.trim() && !hasMedia && !hasChannelData)
+    if (!text?.trim() && !hasMedia && !hasChannelData) {
+        opts.onSkip?.("empty");
         return null;
+    }
     // Parse LINE-specific directives from text (quick_replies, location, confirm, buttons)
     let enrichedPayload = { ...payload, text };
     if (text && hasLineDirectives(text)) {

package/dist/auto-reply/reply/reply-dispatcher.js

@@ -1,19 +1,21 @@
+import { sleep } from "../../utils.js";
+import { registerDispatcher } from "./dispatcher-registry.js";
 import { normalizeReplyPayload } from "./normalize-reply.js";
 const DEFAULT_HUMAN_DELAY_MIN_MS = 800;
 const DEFAULT_HUMAN_DELAY_MAX_MS = 2500;
 /** Generate a random delay within the configured range. */
 function getHumanDelay(config) {
     const mode = config?.mode ?? "off";
-    if (mode === "off")
+    if (mode === "off") {
         return 0;
+    }
     const min = mode === "custom" ? (config?.minMs ?? DEFAULT_HUMAN_DELAY_MIN_MS) : DEFAULT_HUMAN_DELAY_MIN_MS;
     const max = mode === "custom" ? (config?.maxMs ?? DEFAULT_HUMAN_DELAY_MAX_MS) : DEFAULT_HUMAN_DELAY_MAX_MS;
-    if (max <= min)
+    if (max <= min) {
         return min;
+    }
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
-/** Sleep for a given number of milliseconds. */
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function normalizeReplyPayloadInternal(payload, opts) {
     // Prefer dynamic context provider over static context
     const prefixContext = opts.responsePrefixContextProvider?.() ?? opts.responsePrefixContext;
@@ -21,12 +23,16 @@ function normalizeReplyPayloadInternal(payload, opts) {
         responsePrefix: opts.responsePrefix,
         responsePrefixContext: prefixContext,
         onHeartbeatStrip: opts.onHeartbeatStrip,
+        onSkip: opts.onSkip,
     });
 }
 export function createReplyDispatcher(options) {
     let sendChain = Promise.resolve();
     // Track in-flight deliveries so we can emit a reliable "idle" signal.
-    let pending = 0;
+    // Start with pending=1 as a "reservation" to prevent premature gateway restart.
+    // This is decremented when markComplete() is called to signal no more replies will come.
+    let pending = 1;
+    let completeCalled = false;
     // Track whether we've sent a block reply (for human delay - skip delay on first block).
     let sentFirstBlock = false;
     // Serialize outbound replies to preserve tool/block/final order.
@@ -35,24 +41,40 @@ export function createReplyDispatcher(options) {
         block: 0,
         final: 0,
     };
+    // Register this dispatcher globally for gateway restart coordination.
+    const { unregister } = registerDispatcher({
+        pending: () => pending,
+        waitForIdle: () => sendChain,
+    });
     const enqueue = (kind, payload) => {
-        const normalized = normalizeReplyPayloadInternal(payload, options);
-        if (!normalized)
+        const normalized = normalizeReplyPayloadInternal(payload, {
+            responsePrefix: options.responsePrefix,
+            responsePrefixContext: options.responsePrefixContext,
+            responsePrefixContextProvider: options.responsePrefixContextProvider,
+            onHeartbeatStrip: options.onHeartbeatStrip,
+            onSkip: (reason) => options.onSkip?.(payload, { kind, reason }),
+        });
+        if (!normalized) {
             return false;
+        }
         queuedCounts[kind] += 1;
         pending += 1;
         // Determine if we should add human-like delay (only for block replies after the first).
         const shouldDelay = kind === "block" && sentFirstBlock;
-        if (kind === "block")
+        if (kind === "block") {
             sentFirstBlock = true;
+        }
         sendChain = sendChain
             .then(async () => {
             // Add human-like delay between block replies for natural rhythm.
             if (shouldDelay) {
                 const delayMs = getHumanDelay(options.humanDelay);
-                if (delayMs > 0)
+                if (delayMs > 0) {
                     await sleep(delayMs);
+                }
             }
+            // Safe: deliver is called inside an async .then() callback, so even a synchronous
+            // throw becomes a rejection that flows through .catch()/.finally(), ensuring cleanup.
             await options.deliver(normalized, { kind });
         })
             .catch((err) => {
@@ -60,22 +82,51 @@ export function createReplyDispatcher(options) {
         })
             .finally(() => {
             pending -= 1;
+            // Clear reservation if:
+            // 1. pending is now 1 (just the reservation left)
+            // 2. markComplete has been called
+            // 3. No more replies will be enqueued
+            if (pending === 1 && completeCalled) {
+                pending -= 1; // Clear the reservation
+            }
             if (pending === 0) {
+                // Unregister from global tracking when idle.
+                unregister();
                 options.onIdle?.();
             }
         });
         return true;
     };
+    const markComplete = () => {
+        if (completeCalled) {
+            return;
+        }
+        completeCalled = true;
+        // If no replies were enqueued (pending is still 1 = just the reservation),
+        // schedule clearing the reservation after current microtasks complete.
+        // This gives any in-flight enqueue() calls a chance to increment pending.
+        void Promise.resolve().then(() => {
+            if (pending === 1 && completeCalled) {
+                // Still just the reservation, no replies were enqueued
+                pending -= 1;
+                if (pending === 0) {
+                    unregister();
+                    options.onIdle?.();
+                }
+            }
+        });
+    };
     return {
         sendToolResult: (payload) => enqueue("tool", payload),
         sendBlockReply: (payload) => enqueue("block", payload),
         sendFinalReply: (payload) => enqueue("final", payload),
         waitForIdle: () => sendChain,
         getQueuedCounts: () => ({ ...queuedCounts }),
+        markComplete,
     };
 }
 export function createReplyDispatcherWithTyping(options) {
-    const { onReplyStart, onIdle, ...dispatcherOptions } = options;
+    const { onReplyStart, onIdle, onCleanup, ...dispatcherOptions } = options;
     let typingController;
     const dispatcher = createReplyDispatcher({
         ...dispatcherOptions,
@@ -88,6 +139,7 @@ export function createReplyDispatcherWithTyping(options) {
         dispatcher,
         replyOptions: {
             onReplyStart,
+            onTypingCleanup: onCleanup,
             onTypingController: (typing) => {
                 typingController = typing;
             },