comisai 1.0.36 → 1.0.40

package/node_modules/@comis/orchestrator/dist/inbound/inbound-pipeline.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Inbound Pipeline: Thin orchestrator for message reception and routing.
+ *
+ * Delegates to 5 focused phase modules:
+ *   1. inbound-resolve  — agent resolution, identity, session key
+ *   2. inbound-preprocess — audio preflight, media preprocessing, compression
+ *   3. inbound-gate     — auto-reply, slash commands, reset triggers, skills
+ *   4. inbound-setup    — ack reaction, typing controller
+ *   5. inbound-route    — debounce, group history, queue routing, execution
+ *
+ * @module
+ */
+import type { AgentExecutor } from "@comis/agent";
+import type { MessageRouter } from "../routing/message-router.js";
+import type { SessionLifecycle } from "@comis/agent";
+import type { CommandQueue } from "../queue/command-queue.js";
+import type { DebounceBuffer } from "../queue/debounce-buffer.js";
+import type { FollowupTrigger } from "../queue/followup-trigger.js";
+import type { PriorityScheduler } from "../queue/priority-scheduler.js";
+import type { SessionLabelStore } from "@comis/agent";
+import type { ActiveRunRegistry, BackgroundSessionResolver } from "@comis/agent";
+import type { ChannelPort, DeliveryQueuePort, NormalizedMessage, SessionKey, TypedEventBus, DeliveryService } from "@comis/core";
+import type { StreamingConfig } from "@comis/core";
+import type { AutoReplyEngineConfig, SendPolicyConfig, QueueConfig, ElevatedReplyConfig, AckReactionConfig } from "@comis/core";
+import type { ComisLogger } from "@comis/core";
+import type { Result } from "@comis/shared";
+import type { BlockPacer, ChannelRegistry, SendOverrideStore, PreflightResult, GroupHistoryBuffer, VoiceResponsePipelineDeps } from "@comis/channels";
+import type { RetryEngine } from "@comis/core";
+/** Narrow deps interface for the inbound pipeline. */
+export interface InboundPipelineDeps {
+    eventBus: TypedEventBus;
+    logger: ComisLogger;
+    messageRouter: MessageRouter;
+    sessionManager: SessionLifecycle;
+    createExecutor: (agentId: string) => AgentExecutor | undefined;
+    channelRegistry?: ChannelRegistry;
+    preprocessMessage?: (msg: NormalizedMessage) => Promise<NormalizedMessage>;
+    commandQueue?: CommandQueue;
+    autoReplyEngineConfig?: AutoReplyEngineConfig;
+    sendPolicyConfig?: SendPolicyConfig;
+    getResetTriggers?: (agentId: string) => string[];
+    identityResolver?: {
+        resolve(provider: string, providerUserId: string): string | undefined;
+    };
+    getDmScopeConfig?: (agentId: string) => {
+        mode?: string;
+        threadIsolation?: boolean;
+    } | undefined;
+    debounceBuffer?: DebounceBuffer;
+    groupHistoryBuffer?: GroupHistoryBuffer;
+    followupTrigger?: FollowupTrigger;
+    followupConfig?: {
+        maxFollowupRuns: number;
+    };
+    priorityScheduler?: PriorityScheduler;
+    queueConfig?: QueueConfig;
+    getElevatedReplyConfig?: (agentId: string) => ElevatedReplyConfig | undefined;
+    sessionLabelStore?: SessionLabelStore;
+    ackReactionConfig?: AckReactionConfig;
+    loadPromptSkill?: (name: string, args?: string) => Promise<Result<{
+        content: string;
+        allowedTools: string[];
+        skillName: string;
+    }, Error>>;
+    getUserInvocableSkillNames?: () => Set<string>;
+    assembleToolsForAgent?: (agentId: string, options?: {
+        sessionKey?: SessionKey;
+    }) => Promise<any[]>;
+    greetingGenerator?: {
+        generate(agentName: string): Promise<Result<string, Error>>;
+    };
+    audioPreflight?: (msg: NormalizedMessage) => Promise<PreflightResult>;
+    voiceResponsePipeline?: VoiceResponsePipelineDeps;
+    parseOutboundMedia?: (text: string) => {
+        text: string;
+        mediaUrls: string[];
+    };
+    outboundMediaFetch?: (url: string) => Promise<Result<{
+        buffer: Buffer;
+        mimeType?: string;
+    }, Error>>;
+    streamingConfig?: StreamingConfig;
+    retryEngine?: RetryEngine;
+    /** Delivery queue for crash-safe message persistence. When present, agent responses are enqueued before send. */
+    deliveryQueue?: DeliveryQueuePort;
+    /** DeliveryService constructed once at the daemon composition root
+     *  (setup-channels.ts). Threaded through the inbound pipeline so
+     *  inbound-gate.ts and execution-deliver.ts use the method form instead
+     *  of the free-standing standalone export. */
+    deliveryService: DeliveryService;
+    /**
+     * Per-instance set of in-flight outbound sendMessage promises. Threaded
+     * through ExecutionPipelineDeps -> DeliverToChannelDeps so deliver-to-channel
+     * can register active sends. Drained in stopAll() with a 5s deadline so
+     * SIGUSR2 cannot tear down adapters mid-send. Created by the channel-manager
+     * factory; do not pass externally.
+     */
+    inFlightSends?: Set<Promise<unknown>>;
+    /** Optional active run registry for SDK-native steer+followup. */
+    activeRunRegistry?: ActiveRunRegistry;
+    /**
+     * Optional composite-key resolver for active-session lookup. When
+     * present, supersedes `activeRunRegistry.has/.get` for production
+     * lookups. Wired by the daemon as
+     * `createBackgroundSessionResolver({ activeRunRegistry })`.
+     */
+    sessionResolver?: BackgroundSessionResolver;
+    /** Handle /config command. Returns response text or undefined if not a config command. */
+    handleConfigCommand?: (args: string[], channelType: string) => Promise<string | undefined>;
+    /** Optional callback for task extraction after successful agent execution. */
+    onTaskExtraction?: (conversationText: string, sessionKey: string, agentId: string) => Promise<void>;
+    /** When true, lifecycle reactor handles queued/thinking reactions -- skip ack reaction. */
+    lifecycleReactionsEnabled?: boolean;
+    /** Response prefix config for template-based prefix/suffix on agent responses. */
+    responsePrefixConfig?: {
+        template: string;
+        position: "prepend" | "append";
+    };
+    /** Template context builder for response prefix variables. */
+    buildTemplateContext?: (agentId: string, channelType: string, msg: NormalizedMessage) => Record<string, string>;
+    /** Optional approval gate for resolving /approve and /deny chat commands. When absent, approval commands pass through as plain text. */
+    approvalGate?: {
+        resolveApproval(requestId: string, approved: boolean, approvedBy: string, reason?: string): void;
+        pending(): Array<{
+            requestId: string;
+            sessionKey: string;
+            action: string;
+            toolName: string;
+        }>;
+        getRequest(requestId: string): {
+            requestId: string;
+            sessionKey: string;
+        } | undefined;
+    };
+    /** Handle general slash commands via command handler. Returns CommandResult or undefined if not a command. */
+    handleSlashCommand?: (text: string, sessionKey: SessionKey, agentId: string) => Promise<{
+        handled: boolean;
+        response?: string;
+        directives?: Record<string, unknown>;
+        cleanedText?: string;
+    } | undefined>;
+    /** Per-agent enforceFinalTag config lookup. Returns boolean or undefined if agent not found. */
+    getEnforceFinalTag?: (agentId: string) => boolean | undefined;
+    /** Optional allowFrom sender filter lookup. Returns allowed sender IDs for a channel type. Empty array = allow all. */
+    getAllowFrom?: (channelType: string) => string[];
+}
+/**
+ * Test message text against configured reset trigger phrases.
+ * Supports literal string matching (case-insensitive) and /regex/ patterns.
+ * Each pattern is wrapped in try/catch to prevent ReDoS from user-configured patterns.
+ */
+export declare function matchesResetTrigger(text: string, triggers: string[]): boolean;
+/**
+ * Process an inbound message through the full pipeline.
+ *
+ * Orchestrates 5 phases: resolve -> preprocess -> gate -> setup -> route.
+ */
+export declare function processInboundMessage(deps: InboundPipelineDeps, adapter: ChannelPort, msg: NormalizedMessage, activePacers: Set<BlockPacer>, sendOverrides: SendOverrideStore): Promise<void>;

package/node_modules/@comis/orchestrator/dist/inbound/inbound-pipeline.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Inbound Pipeline: Thin orchestrator for message reception and routing.
+ *
+ * Delegates to 5 focused phase modules:
+ *   1. inbound-resolve  — agent resolution, identity, session key
+ *   2. inbound-preprocess — audio preflight, media preprocessing, compression
+ *   3. inbound-gate     — auto-reply, slash commands, reset triggers, skills
+ *   4. inbound-setup    — ack reaction, typing controller
+ *   5. inbound-route    — debounce, group history, queue routing, execution
+ *
+ * @module
+ */
+import { isRegexSafe } from "@comis/channels";
+// Phase module imports
+import { resolveInboundAgent } from "./inbound-resolve.js";
+import { preprocessInboundMessage } from "./inbound-preprocess.js";
+import { evaluateInboundGate } from "./inbound-gate.js";
+import { setupInboundExecution } from "./inbound-setup.js";
+import { routeInboundMessage } from "./inbound-route.js";
+import { systemNowMs } from "@comis/core";
+// ---------------------------------------------------------------------------
+// Trigger phrase matching
+// ---------------------------------------------------------------------------
+/**
+ * Test message text against configured reset trigger phrases.
+ * Supports literal string matching (case-insensitive) and /regex/ patterns.
+ * Each pattern is wrapped in try/catch to prevent ReDoS from user-configured patterns.
+ */
+export function matchesResetTrigger(text, triggers) {
+    const lowerText = text.toLowerCase().trim();
+    for (const trigger of triggers) {
+        try {
+            if (trigger.startsWith("/") && trigger.endsWith("/") && trigger.length > 2) {
+                const body = trigger.slice(1, -1);
+                const check = isRegexSafe(body);
+                if (!check.safe)
+                    continue; // Skip overly complex patterns
+                const re = new RegExp(body, "i");
+                if (re.test(lowerText))
+                    return true;
+            }
+            else {
+                if (lowerText === trigger.toLowerCase())
+                    return true;
+            }
+        }
+        catch {
+            // Invalid regex -- skip silently (ReDoS prevention)
+        }
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Main inbound pipeline (thin orchestrator)
+// ---------------------------------------------------------------------------
+/**
+ * Process an inbound message through the full pipeline.
+ *
+ * Orchestrates 5 phases: resolve -> preprocess -> gate -> setup -> route.
+ */
+export async function processInboundMessage(deps, adapter, msg, activePacers, sendOverrides) {
+    // Phase 0: Sender allowFrom filtering
+    const allowFrom = deps.getAllowFrom?.(adapter.channelType) ?? [];
+    if (allowFrom.length > 0 && !allowFrom.includes(msg.senderId)) {
+        deps.logger.info({ channelType: adapter.channelType, senderId: msg.senderId, hint: "Sender not in allowFrom list", errorKind: "auth" }, "Sender blocked by allowFrom filter");
+        deps.eventBus.emit("sender:blocked", {
+            channelType: adapter.channelType,
+            senderId: msg.senderId,
+            channelId: msg.channelId,
+            timestamp: systemNowMs(),
+        });
+        return;
+    }
+    // Phase 1: Resolve agent, identity, session key
+    const resolved = resolveInboundAgent(deps, adapter, msg);
+    if (!resolved)
+        return; // No executor -- early exit
+    const { agentId, executor, sessionKey } = resolved;
+    // Phase 2: Audio preflight, media preprocessing, compression
+    const processedMsg = await preprocessInboundMessage(deps, msg, adapter.channelType);
+    // Phase 3: Auto-reply gate, slash commands, reset triggers, prompt skills
+    const gate = await evaluateInboundGate(deps, adapter, processedMsg, sessionKey, agentId, sendOverrides);
+    if (gate.action === "handled" || gate.action === "skip")
+        return;
+    // Phase 4: Ack reaction, typing controller, streaming config
+    const { typingLifecycle, streamCfg } = setupInboundExecution(deps, adapter, gate.processedMsg, msg, sessionKey);
+    // Phase 5: Debounce, group history, steer+followup, queue routing, execution
+    await routeInboundMessage(deps, adapter, gate.processedMsg, msg, sessionKey, agentId, executor, streamCfg, activePacers, sendOverrides, typingLifecycle, gate.directives);
+}

package/node_modules/@comis/orchestrator/dist/inbound/inbound-preprocess.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Inbound Pipeline Phase 2: Media Preprocessing.
+ *
+ * Handles audio preflight transcription, media preprocessing
+ * (voice transcription, image analysis), and attachment compression.
+ *
+ * @module
+ */
+import { isBotMentioned, isGroupMessage } from "@comis/channels";
+import { compressAttachments } from "@comis/channels";
+// ---------------------------------------------------------------------------
+// Phase function
+// ---------------------------------------------------------------------------
+/**
+ * Run audio preflight, media preprocessing, and attachment compression
+ * on an inbound message.
+ *
+ * Returns the (potentially transformed) message after all preprocessing.
+ */
+export async function preprocessInboundMessage(deps, msg, channelType) {
+    let processedMsg = msg;
+    // -------------------------------------------------------------------
+    // AUDIO PREFLIGHT: Transcribe voice before mention gate
+    // -------------------------------------------------------------------
+    // Runs BEFORE preprocessMessage so:
+    //   1. Preflight transcribes audio and sets att.transcription
+    //   2. preprocessMessage sees att.transcription and skips re-transcription
+    //   3. Auto-reply gate sees enriched text with transcript for mention detection
+    //
+    // Only run in group chats with mention-gated activation where:
+    // - Message has audio attachments
+    // - Bot is NOT already mentioned in text/metadata
+    // - audioPreflight callback is available
+    if (deps.audioPreflight) {
+        const isGroup = isGroupMessage(msg);
+        const isMentionGated = deps.autoReplyEngineConfig?.groupActivation === "mention-gated";
+        const hasAudio = msg.attachments?.some((a) => a.type === "audio" || a.mimeType?.startsWith("audio/"));
+        const alreadyMentioned = isBotMentioned(msg);
+        if (isGroup && isMentionGated && hasAudio && !alreadyMentioned) {
+            try {
+                const preflightResult = await deps.audioPreflight(msg);
+                if (preflightResult.transcribed) {
+                    processedMsg = preflightResult.message;
+                    deps.logger.debug({
+                        step: "audio-preflight",
+                        channelType,
+                        chatId: processedMsg.channelId,
+                    }, "Audio preflight transcription applied");
+                }
+            }
+            catch (preflightErr) {
+                deps.logger.warn({ err: preflightErr, channelId: msg.channelId, hint: "Audio preflight failed, voice message may be dropped by mention gate", errorKind: "internal" }, "Audio preflight failed");
+            }
+        }
+    }
+    // Preprocess media attachments (voice transcription, image analysis)
+    // NOTE: processedMsg already set above (either original msg or preflight-enriched)
+    if (deps.preprocessMessage) {
+        try {
+            processedMsg = await deps.preprocessMessage(processedMsg);
+        }
+        catch (preprocessErr) {
+            deps.logger.warn({ err: preprocessErr, channelId: msg.channelId, hint: "Media preprocessing failed; proceeding with original message", errorKind: "internal" }, "Media preprocessing failed, using original message");
+        }
+    }
+    // -------------------------------------------------------------------
+    // Media compression (runs before auto-reply evaluation)
+    // -------------------------------------------------------------------
+    if (deps.autoReplyEngineConfig) {
+        const beforeAttachments = processedMsg.attachments?.length ?? 0;
+        processedMsg = compressAttachments(processedMsg);
+        const afterAttachments = processedMsg.attachments?.length ?? 0;
+        if (beforeAttachments !== afterAttachments) {
+            deps.logger.debug({
+                step: "media-compress",
+                inputLen: beforeAttachments,
+                outputLen: afterAttachments,
+            }, "Attachments compressed");
+        }
+    }
+    return processedMsg;
+}

package/node_modules/@comis/orchestrator/dist/inbound/inbound-resolve.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Inbound Pipeline Phase 1: Agent Resolution.
+ *
+ * Resolves which agent handles the message, maps identity,
+ * constructs the scoped session key, and loads or creates the session.
+ *
+ * @module
+ */
+// Session-key builder lives at packages/orchestrator/src/session-key/session-key-builder.ts.
+// Orchestrator's own TS build cannot import its own published package name, so the import
+// must use the relative path.
+import { buildScopedSessionKey, extractThreadId } from "../session-key/session-key-builder.js";
+// ---------------------------------------------------------------------------
+// Phase function
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the agent, identity, and session key for an inbound message.
+ *
+ * Returns undefined if no executor is configured for the resolved agent
+ * (early exit — message should be dropped).
+ */
+export function resolveInboundAgent(deps, adapter, msg) {
+    // 1. Resolve agent FIRST (only needs RoutableMessage, not SessionKey)
+    const agentId = deps.messageRouter.resolve({
+        channelType: msg.channelType,
+        channelId: msg.channelId,
+        senderId: msg.senderId,
+        guildId: msg.metadata?.guildId,
+    });
+    // 2. Get executor (early exit if none)
+    const executor = deps.createExecutor(agentId);
+    if (!executor) {
+        deps.logger.warn({ agentId, channelId: msg.channelId, hint: "Ensure agent executor is registered before processing messages", errorKind: "config" }, "No executor configured for agent");
+        return undefined;
+    }
+    // 3. Resolve canonical identity (if identityResolver provided)
+    const canonicalId = deps.identityResolver?.resolve(msg.channelType, msg.senderId);
+    const effectiveMsg = canonicalId ? { ...msg, senderId: canonicalId } : msg;
+    // 4. Extract thread ID from platform metadata
+    const threadId = extractThreadId(msg);
+    // 5. Get DM scope config for this agent
+    const dmScopeConfig = deps.getDmScopeConfig?.(agentId);
+    // 6. Build scoped session key
+    const sessionKey = buildScopedSessionKey({
+        msg: effectiveMsg,
+        agentId,
+        adapterChannelId: adapter.channelId,
+        dmScopeMode: dmScopeConfig?.mode ?? undefined,
+        threadId: dmScopeConfig?.threadIsolation ? threadId : undefined,
+    });
+    // 7. Emit message:received with the scoped session key
+    deps.eventBus.emit("message:received", { message: msg, sessionKey });
+    // Load or create session
+    deps.sessionManager.loadOrCreate(sessionKey);
+    return { agentId, executor, sessionKey, effectiveMsg };
+}

package/node_modules/@comis/orchestrator/dist/inbound/inbound-route.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Inbound Pipeline — Message Routing stage.
+ *
+ * Handles debounce buffering, group history injection, steer+followup
+ * routing (SDK-native), command queue routing, and direct execution
+ * fallback.
+ *
+ * @module
+ */
+import type { ChannelPort, NormalizedMessage, SessionKey } from "@comis/core";
+import type { AgentExecutor } from "@comis/agent";
+import type { PerChannelStreamingConfig } from "@comis/core";
+import type { InboundPipelineDeps } from "./inbound-pipeline.js";
+import type { BlockPacer, TypingLifecycleController, SendOverrideStore } from "@comis/channels";
+/** Minimal deps needed for the routing phase. */
+export type RouteDeps = Pick<InboundPipelineDeps, "logger" | "eventBus" | "debounceBuffer" | "groupHistoryBuffer" | "sessionLabelStore" | "commandQueue" | "priorityScheduler" | "queueConfig" | "activeRunRegistry" | "sessionResolver" | "streamingConfig" | "sendPolicyConfig" | "getElevatedReplyConfig" | "channelRegistry" | "retryEngine" | "deliveryQueue" | "deliveryService" | "inFlightSends" | "followupTrigger" | "followupConfig" | "assembleToolsForAgent" | "voiceResponsePipeline" | "parseOutboundMedia" | "outboundMediaFetch" | "onTaskExtraction" | "responsePrefixConfig" | "buildTemplateContext" | "getEnforceFinalTag">;
+/**
+ * Route an inbound message through debounce, group history, steer+followup,
+ * or command queue. Falls back to direct execution when no queue is present.
+ *
+ * This function handles the final routing decision and may call
+ * `executeAndDeliver` directly or enqueue for later execution.
+ */
+export declare function routeInboundMessage(deps: RouteDeps, adapter: ChannelPort, processedMsg: NormalizedMessage, originalMsg: NormalizedMessage, sessionKey: SessionKey, agentId: string, executor: AgentExecutor, streamCfg: PerChannelStreamingConfig, activePacers: Set<BlockPacer>, sendOverrides: SendOverrideStore, typingLifecycle: TypingLifecycleController | undefined, directives: Record<string, unknown> | undefined): Promise<void>;

package/node_modules/@comis/orchestrator/dist/inbound/inbound-route.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Inbound Pipeline — Message Routing stage.
+ *
+ * Handles debounce buffering, group history injection, steer+followup
+ * routing (SDK-native), command queue routing, and direct execution
+ * fallback.
+ *
+ * @module
+ */
+import { formatSessionKey, systemNowMs } from "@comis/core";
+import { isGroupMessage } from "@comis/channels";
+import { executeAndDeliver } from "../execution/execution-pipeline.js";
+import { isBotMentioned } from "@comis/channels";
+/**
+ * Determine which priority lane a message should be assigned to.
+ *
+ * Priority order: follow-up messages -> heartbeat/scheduled -> DMs -> mentioned in group -> default.
+ */
+function assignPriorityLane(msg, laneConfig) {
+    // Follow-up messages
+    if (msg.metadata?.isFollowup) {
+        return { lane: laneConfig.followupLane, reason: "followup" };
+    }
+    // Heartbeat / scheduled
+    if (msg.metadata?.isHeartbeat) {
+        return { lane: laneConfig.scheduledLane, reason: "heartbeat" };
+    }
+    // DMs
+    if (!isGroupMessage(msg)) {
+        return { lane: laneConfig.dmLane, reason: "dm" };
+    }
+    // Group mention
+    if (isBotMentioned(msg)) {
+        return { lane: laneConfig.mentionLane, reason: "mention" };
+    }
+    // Default
+    return { lane: laneConfig.defaultLane, reason: "default" };
+}
+// ---------------------------------------------------------------------------
+// Stage function
+// ---------------------------------------------------------------------------
+/**
+ * Route an inbound message through debounce, group history, steer+followup,
+ * or command queue. Falls back to direct execution when no queue is present.
+ *
+ * This function handles the final routing decision and may call
+ * `executeAndDeliver` directly or enqueue for later execution.
+ */
+export async function routeInboundMessage(deps, adapter, processedMsg, originalMsg, sessionKey, agentId, executor, streamCfg, activePacers, sendOverrides, typingLifecycle, directives) {
+    let msg = processedMsg;
+    // -------------------------------------------------------------------
+    // DEBOUNCE BUFFER GATE
+    // -------------------------------------------------------------------
+    const isDebounced = msg.metadata?.isDebounced === true;
+    if (!isDebounced && deps.debounceBuffer) {
+        deps.logger.debug({
+            step: "debounce-buffered",
+            channelType: adapter.channelType,
+            chatId: msg.channelId,
+        }, "Message buffered for debounce");
+        deps.debounceBuffer.push(sessionKey, msg, adapter.channelType);
+        return; // Message is buffered; execution deferred to flush callback
+    }
+    // -------------------------------------------------------------------
+    // GROUP HISTORY INJECTION
+    // -------------------------------------------------------------------
+    if (deps.groupHistoryBuffer) {
+        const skFormatted = formatSessionKey(sessionKey);
+        let effectiveText = msg.text ?? "";
+        const sessionLabel = deps.sessionLabelStore?.getLabel(sessionKey);
+        const history = deps.groupHistoryBuffer.getFormatted(skFormatted, sessionLabel);
+        if (history) {
+            effectiveText = `${history}\n---\n${effectiveText}`;
+            deps.eventBus.emit("grouphistory:injected", {
+                sessionKey: skFormatted,
+                channelType: adapter.channelType,
+                messageCount: deps.groupHistoryBuffer.depth(skFormatted),
+                charCount: history.length,
+                timestamp: systemNowMs(),
+            });
+            deps.logger.debug({
+                step: "group-history-inject",
+                itemCount: deps.groupHistoryBuffer.depth(skFormatted),
+                inputLen: history.length,
+            }, "Group history injected");
+        }
+        // Also push the current activating message to the buffer (for next activation's context)
+        if (isGroupMessage(msg)) {
+            deps.groupHistoryBuffer.push(skFormatted, msg);
+        }
+        // Create the effective message with injected history
+        if (effectiveText !== (msg.text ?? "")) {
+            msg = { ...msg, text: effectiveText };
+        }
+    }
+    // Build narrow execution pipeline deps from the inbound pipeline deps
+    const execDeps = {
+        eventBus: deps.eventBus,
+        logger: deps.logger,
+        streamingConfig: deps.streamingConfig,
+        sendPolicyConfig: deps.sendPolicyConfig,
+        getElevatedReplyConfig: deps.getElevatedReplyConfig,
+        channelRegistry: deps.channelRegistry,
+        retryEngine: deps.retryEngine,
+        deliveryQueue: deps.deliveryQueue,
+        deliveryService: deps.deliveryService,
+        inFlightSends: deps.inFlightSends,
+        followupTrigger: deps.followupTrigger,
+        followupConfig: deps.followupConfig,
+        commandQueue: deps.commandQueue,
+        assembleToolsForAgent: deps.assembleToolsForAgent,
+        voiceResponsePipeline: deps.voiceResponsePipeline,
+        parseOutboundMedia: deps.parseOutboundMedia,
+        outboundMediaFetch: deps.outboundMediaFetch,
+        onTaskExtraction: deps.onTaskExtraction,
+        responsePrefixConfig: deps.responsePrefixConfig,
+        buildTemplateContext: deps.buildTemplateContext,
+        enforceFinalTag: deps.getEnforceFinalTag?.(agentId),
+    };
+    // -------------------------------------------------------------------
+    // STEER+FOLLOWUP ROUTING
+    // -------------------------------------------------------------------
+    // Active-session lookup goes through BackgroundSessionResolver:
+    // composite (agentId, channelType, channelId) supersedes the single-arg
+    // formatted-key lookup so multi-agent / multi-channel sessions are
+    // distinguishable. The original
+    // `formattedKey = formatSessionKey(sessionKey)` is retained ONLY for
+    // diagnostic log fields (the SessionKey may itself be richer than the
+    // resolver's composite triple).
+    if (deps.sessionResolver && deps.queueConfig) {
+        const channelQueueConfig = deps.queueConfig.perChannel[adapter.channelType];
+        const effectiveMode = channelQueueConfig?.mode ?? deps.queueConfig.defaultMode;
+        if (effectiveMode === "steer+followup") {
+            const formattedKey = formatSessionKey(sessionKey);
+            const runHandle = deps.sessionResolver.resolveActiveSession({
+                agentId,
+                channelType: adapter.channelType,
+                channelId: msg.channelId,
+            });
+            if (runHandle) {
+                const messageText = msg.text ?? "";
+                if (runHandle.isStreaming() && !runHandle.isCompacting()) {
+                    // Session is streaming -- inject via SDK steer
+                    try {
+                        await runHandle.steer(messageText);
+                        deps.eventBus.emit("steer:injected", {
+                            sessionKey,
+                            channelType: adapter.channelType,
+                            agentId,
+                            timestamp: systemNowMs(),
+                        });
+                        deps.logger.debug({ agentId, channelType: adapter.channelType, sessionKey: formattedKey }, "Steer message injected into active session");
+                        return; // Message handled via steer -- do not enqueue
+                    }
+                    catch (steerErr) {
+                        deps.logger.warn({
+                            agentId,
+                            err: steerErr instanceof Error ? steerErr : new Error(String(steerErr)),
+                            hint: "SDK session.steer() failed; message will be queued as follow-up",
+                            errorKind: "internal",
+                        }, "Steer injection failed");
+                        // Fall through to follow-up below
+                    }
+                }
+                if (runHandle.isCompacting()) {
+                    deps.eventBus.emit("steer:rejected", {
+                        sessionKey,
+                        channelType: adapter.channelType,
+                        agentId,
+                        reason: "compacting",
+                        timestamp: systemNowMs(),
+                    });
+                    deps.logger.debug({ agentId, channelType: adapter.channelType, sessionKey: formattedKey }, "Steer rejected: session compacting");
+                }
+                else {
+                    deps.eventBus.emit("steer:rejected", {
+                        sessionKey,
+                        channelType: adapter.channelType,
+                        agentId,
+                        reason: "not_streaming",
+                        timestamp: systemNowMs(),
+                    });
+                    deps.logger.debug({ agentId, channelType: adapter.channelType, sessionKey: formattedKey }, "Steer rejected: session not streaming");
+                }
+                // Queue as follow-up (session exists but steer not possible)
+                try {
+                    await runHandle.followUp(messageText);
+                    deps.eventBus.emit("steer:followup_queued", {
+                        sessionKey,
+                        channelType: adapter.channelType,
+                        agentId,
+                        reason: runHandle.isCompacting() ? "compacting" : "not_streaming",
+                        timestamp: systemNowMs(),
+                    });
+                    deps.logger.debug({ agentId, channelType: adapter.channelType, sessionKey: formattedKey }, "Message queued as follow-up via SDK");
+                    return; // Message handled via follow-up -- do not enqueue
+                }
+                catch (followUpErr) {
+                    deps.logger.warn({
+                        agentId,
+                        err: followUpErr instanceof Error ? followUpErr : new Error(String(followUpErr)),
+                        hint: "SDK session.followUp() failed; falling through to CommandQueue",
+                        errorKind: "internal",
+                    }, "Follow-up queue failed");
+                    // Fall through to normal CommandQueue routing
+                }
+            }
+            // No active run -- fall through to CommandQueue (first message for session)
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Queue-mediated path: route through CommandQueue for serialization
+    // -----------------------------------------------------------------------
+    if (deps.commandQueue) {
+        // Determine priority lane
+        let laneName;
+        if (deps.priorityScheduler && deps.queueConfig?.priorityEnabled) {
+            const laneConfig = deps.queueConfig.laneAssignment;
+            const assignment = assignPriorityLane(msg, laneConfig);
+            laneName = assignment.lane;
+            deps.eventBus.emit("priority:lane_assigned", {
+                sessionKey,
+                channelType: adapter.channelType,
+                lane: assignment.lane,
+                reason: assignment.reason,
+                timestamp: systemNowMs(),
+            });
+        }
+        const enqueueResult = await deps.commandQueue.enqueue(sessionKey, msg, adapter.channelType, async (messages) => {
+            const effectiveMsg = messages[0];
+            await executeAndDeliver(execDeps, adapter, effectiveMsg, originalMsg, executor, sessionKey, agentId, streamCfg, activePacers, sendOverrides, typingLifecycle, directives);
+        }, laneName);
+        if (!enqueueResult.ok) {
+            deps.logger.warn({
+                err: enqueueResult.error.message,
+                hint: "Check if command queue is shut down or overflow policy rejected the message",
+                errorKind: "resource",
+                channelType: adapter.channelType,
+            }, "Message enqueue failed");
+        }
+        return;
+    }
+    // -----------------------------------------------------------------------
+    // Direct execution path (fallback when commandQueue is not provided)
+    // -----------------------------------------------------------------------
+    await executeAndDeliver(execDeps, adapter, msg, originalMsg, executor, sessionKey, agentId, streamCfg, activePacers, sendOverrides, typingLifecycle, directives);
+}