comisai 1.0.4

package/node_modules/@comis/channels/dist/shared/execution-filter.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Execution Pipeline Phase 3: Response Filtering.
+ *
+ * Handles response sanitization, response filtering (NO_REPLY/HEARTBEAT_OK
+ * suppression), outbound media delivery, voice response pipeline, and
+ * response prefix application.
+ *
+ * Follow-up trigger logic stays in the orchestrator (needs full closure deps).
+ *
+ * @module
+ */
+import { formatSessionKey } from "@comis/core";
+import { sanitizeAssistantResponse, extractFinalTagContent } from "@comis/agent";
+import { buildThreadSendOpts } from "./execution-pipeline.js";
+import { filterResponse } from "./response-filter.js";
+import { executeVoiceResponse } from "./voice-response-pipeline.js";
+import { deliverOutboundMedia } from "./outbound-media-handler.js";
+import { applyPrefix } from "./prefix-template.js";
+import { buildAbortSummary } from "./abort-summary.js";
+// ---------------------------------------------------------------------------
+// Phase function
+// ---------------------------------------------------------------------------
+/**
+ * Sanitize and filter the response, deliver outbound media, and run
+ * voice response pipeline.
+ *
+ * Returns either text to deliver or a reason why delivery was skipped.
+ */
+export async function filterExecutionResponse(deps, adapter, effectiveMsg, originalMsg, sessionKey, agentId, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+result, accumulated, replyTo, resourceAborted, abortReason, diagFinishReason) {
+    // Sanitize raw SDK output via the response sanitization pipeline.
+    let response;
+    if (result.response) {
+        response = sanitizeAssistantResponse(result.response, { enforceFinalTag: deps.enforceFinalTag });
+    }
+    else if (accumulated) {
+        // When falling back to accumulated text (result.response empty),
+        // the accumulated buffer contains text from ALL intermediate turns — including
+        // narration/commentary on tool-call turns (e.g. "Step 1 done...", "Plan: 1...").
+        // Try extracting only <final> content first to strip narration.
+        const finalOnly = extractFinalTagContent(accumulated);
+        response = finalOnly || accumulated;
+    }
+    else {
+        response = "";
+    }
+    if (!response && deps.enforceFinalTag) {
+        deps.logger.warn({
+            agentId: effectiveMsg.metadata?.agentId,
+            hint: "Model did not use <final> tags; response suppressed by enforceFinalTag",
+            errorKind: "validation",
+        }, "enforceFinalTag produced empty response");
+    }
+    if (!response) {
+        // Resource aborts with empty response
+        if (resourceAborted) {
+            deps.logger.warn({
+                agentId,
+                sessionKey: formatSessionKey(sessionKey),
+                finishReason: diagFinishReason,
+                abortReason,
+                hint: "Resource abort produced empty response; sending accomplishment-aware notification to user",
+                errorKind: "resource",
+            }, "Resource abort with empty response");
+            const summary = buildAbortSummary(result);
+            const message = summary
+                ? `I ran out of processing budget. Here's what I completed:\n${summary}\n\nTo continue, send your next message or use +500k for more budget.`
+                : "I've reached my processing limit for this request. Please try again or break the task into smaller steps.";
+            await adapter.sendMessage(effectiveMsg.channelId, message, { replyTo }).catch(() => { });
+            return { deliver: false, reason: "resource_abort_empty" };
+        }
+        // Normal completion with empty response — the LLM finished (finishReason "stop")
+        // but produced no deliverable text. This happens when recovery text isn't
+        // propagated through result.response, or when Gemini returns thinking-only content.
+        // Send a canned acknowledgment so the user is never left with zero feedback.
+        if (diagFinishReason === "stop") {
+            deps.logger.warn({
+                agentId,
+                sessionKey: formatSessionKey(sessionKey),
+                hint: "LLM finished normally but produced empty response after all recovery paths; sending canned acknowledgment",
+                errorKind: "dependency",
+            }, "Empty response on normal completion — sending fallback acknowledgment");
+            await adapter.sendMessage(effectiveMsg.channelId, "I completed the requested operations but wasn't able to generate a summary. Please check the results or ask me to continue.", { replyTo }).catch(() => { });
+            return { deliver: false, reason: "empty_stop_ack" };
+        }
+        deps.logger.debug({
+            step: "empty-response",
+            chatId: effectiveMsg.channelId,
+            reason: diagFinishReason,
+        }, "Empty response, skipping delivery");
+        return { deliver: false, reason: "empty" };
+    }
+    // Response filter: strip <reply> tags, suppress NO_REPLY, HEARTBEAT_OK, empty
+    const filter = filterResponse(response);
+    deps.logger.debug({
+        step: "response-filter",
+        inputLen: response.length,
+        outputLen: filter.cleanedText.length,
+        success: filter.shouldDeliver,
+        reason: filter.suppressedBy ?? "delivered",
+    }, "Response filter applied");
+    if (!filter.shouldDeliver) {
+        deps.eventBus.emit("response:filtered", {
+            channelId: adapter.channelId,
+            suppressedBy: filter.suppressedBy,
+            timestamp: Date.now(),
+        });
+        return { deliver: false, reason: "filtered" };
+    }
+    // Use cleaned text (reply tags stripped) for delivery
+    let finalDeliveryText = filter.cleanedText;
+    // -------------------------------------------------------------------
+    // OUTBOUND MEDIA PIPELINE
+    // -------------------------------------------------------------------
+    if (deps.parseOutboundMedia && deps.outboundMediaFetch) {
+        const parsed = deps.parseOutboundMedia(finalDeliveryText);
+        if (parsed.mediaUrls.length > 0) {
+            deps.logger.debug({
+                step: "outbound-media",
+                mediaCount: parsed.mediaUrls.length,
+                chatId: effectiveMsg.channelId,
+            }, "MEDIA: directives found in response");
+            const mediaResult = await deliverOutboundMedia(parsed.mediaUrls, {
+                fetchUrl: deps.outboundMediaFetch,
+                adapter,
+                channelId: effectiveMsg.channelId,
+                logger: deps.logger,
+                sendOptions: buildThreadSendOpts(effectiveMsg.metadata),
+            });
+            deps.logger.debug({
+                step: "outbound-media-delivered",
+                delivered: mediaResult.delivered,
+                failed: mediaResult.failed,
+            }, "Outbound media delivery complete");
+            finalDeliveryText = parsed.text;
+        }
+    }
+    // -------------------------------------------------------------------
+    // VOICE RESPONSE PIPELINE
+    // -------------------------------------------------------------------
+    if (deps.voiceResponsePipeline) {
+        const voiceResult = await executeVoiceResponse(deps.voiceResponsePipeline, {
+            responseText: finalDeliveryText,
+            originalMessage: originalMsg,
+            adapter,
+            channelType: adapter.channelType,
+            channelId: effectiveMsg.channelId,
+            sendOptions: buildThreadSendOpts(effectiveMsg.metadata),
+        });
+        if (voiceResult.ok && voiceResult.value.voiceSent) {
+            deps.logger.info({ channelType: adapter.channelType, chatId: effectiveMsg.channelId }, "Voice response delivered, skipping text delivery");
+            deps.eventBus.emit("message:sent", {
+                channelId: effectiveMsg.channelId,
+                messageId: "voice-delivery",
+                content: finalDeliveryText,
+            });
+            return { deliver: false, reason: "voice_delivered" };
+        }
+        if (!voiceResult.ok) {
+            deps.logger.warn({
+                channelType: adapter.channelType,
+                chatId: effectiveMsg.channelId,
+                err: voiceResult.error.message,
+                hint: "Voice response pipeline returned error, falling back to text delivery",
+                errorKind: "internal",
+            }, "Voice response pipeline error");
+        }
+    }
+    // If text is empty after stripping MEDIA: lines
+    if (!finalDeliveryText.trim()) {
+        deps.eventBus.emit("message:sent", {
+            channelId: effectiveMsg.channelId,
+            messageId: "media-only-delivery",
+            content: finalDeliveryText,
+        });
+        return { deliver: false, reason: "media_only" };
+    }
+    // === RESPONSE PREFIX ===
+    if (deps.responsePrefixConfig?.template && deps.buildTemplateContext) {
+        const templateCtx = deps.buildTemplateContext(agentId, adapter.channelType, effectiveMsg);
+        finalDeliveryText = applyPrefix(finalDeliveryText, deps.responsePrefixConfig, templateCtx);
+    }
+    return { deliver: true, text: finalDeliveryText };
+}

package/node_modules/@comis/channels/dist/shared/execution-pipeline.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Execution Pipeline: Thin orchestrator for outbound delivery.
+ *
+ * Delegates to 4 focused phase modules:
+ *   1. execution-policy  — send policy gate, trust level, elevated reply routing
+ *   2. execution-execute — LLM execution with timeout, thinking filter, abort
+ *   3. execution-filter  — response sanitization, filtering, media, voice, prefix
+ *   4. execution-deliver — chunking, coalescing, block pacing, delivery
+ *
+ * Keeps follow-up trigger logic here (needs full closure deps for re-enqueue).
+ *
+ * @module
+ */
+import type { ChannelPort, NormalizedMessage, SessionKey, TypedEventBus, DeliveryQueuePort } from "@comis/core";
+import type { PerChannelStreamingConfig, StreamingConfig } from "@comis/core";
+import type { SendPolicyConfig, ElevatedReplyConfig } from "@comis/core";
+import type { SendMessageOptions } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+import type { Result } from "@comis/shared";
+import type { AgentExecutor } from "@comis/agent";
+import type { CommandQueue } from "@comis/agent";
+import type { FollowupTrigger } from "@comis/agent";
+import type { BlockPacer } from "./block-pacer.js";
+import type { TypingLifecycleController } from "./typing-lifecycle-controller.js";
+import type { ChannelRegistry } from "./channel-registry.js";
+import type { SendOverrideStore } from "./send-policy.js";
+import type { RetryEngine } from "./retry-engine.js";
+import type { VoiceResponsePipelineDeps } from "./voice-response-pipeline.js";
+/** Maps channelType to the metadata key containing the platform message ID for reply-to. */
+export declare const REPLY_TO_META_KEY: Record<string, string>;
+/**
+ * Metadata keys that carry thread context -- must be propagated to followup messages.
+ * Mirror of TELEGRAM_THREAD_META_KEYS in thread-context.ts -- kept in sync via
+ * cross-reference unit test.
+ */
+export declare const THREAD_PROPAGATION_KEYS: readonly ["threadId", "telegramThreadId", "telegramIsForum", "telegramThreadScope"];
+/**
+ * Build thread-related SendMessageOptions from inbound message metadata.
+ * Returns undefined when no thread context present.
+ */
+export declare function buildThreadSendOpts(metadata?: Record<string, unknown>): Pick<SendMessageOptions, "threadId" | "extra"> | undefined;
+/** Narrow deps interface for the execution pipeline. */
+export interface ExecutionPipelineDeps {
+    eventBus: TypedEventBus;
+    logger: ComisLogger;
+    streamingConfig?: StreamingConfig;
+    sendPolicyConfig?: SendPolicyConfig;
+    getElevatedReplyConfig?: (agentId: string) => ElevatedReplyConfig | undefined;
+    channelRegistry?: ChannelRegistry;
+    retryEngine?: RetryEngine;
+    followupTrigger?: FollowupTrigger;
+    followupConfig?: {
+        maxFollowupRuns: number;
+    };
+    commandQueue?: CommandQueue;
+    assembleToolsForAgent?: (agentId: string, options?: {
+        sessionKey?: SessionKey;
+    }) => Promise<any[]>;
+    voiceResponsePipeline?: VoiceResponsePipelineDeps;
+    parseOutboundMedia?: (text: string) => {
+        text: string;
+        mediaUrls: string[];
+    };
+    outboundMediaFetch?: (url: string) => Promise<Result<{
+        buffer: Buffer;
+        mimeType?: string;
+    }, Error>>;
+    /** Optional callback for task extraction after successful agent execution. */
+    onTaskExtraction?: (conversationText: string, sessionKey: string, agentId: string) => Promise<void>;
+    /** 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>;
+    /** Wall-clock timeout for agent execution, in ms. Default: 600,000 (10 min). */
+    executionTimeoutMs?: number;
+    /** Delivery queue for crash-safe persistence. */
+    deliveryQueue?: DeliveryQueuePort;
+    /** When true, only content inside <final> blocks reaches users. */
+    enforceFinalTag?: boolean;
+}
+/**
+ * Resolve per-channel streaming configuration.
+ *
+ * Priority: per-channel override > global defaults > hardcoded defaults.
+ */
+export declare function resolveStreamingConfig(channelType: string, streamingConfig?: StreamingConfig): PerChannelStreamingConfig;
+/**
+ * Execute a message with block streaming delivery.
+ *
+ * Orchestrates 4 phases: policy -> execute -> filter -> deliver.
+ */
+export declare function executeAndDeliver(deps: ExecutionPipelineDeps, adapter: ChannelPort, effectiveMsg: NormalizedMessage, originalMsg: NormalizedMessage, executor: AgentExecutor, sessionKey: SessionKey, agentId: string, blockStreamCfg: PerChannelStreamingConfig, activePacers: Set<BlockPacer>, sendOverrides: SendOverrideStore, typingLifecycle?: TypingLifecycleController, directives?: Record<string, unknown>): Promise<void>;

package/node_modules/@comis/channels/dist/shared/execution-pipeline.js

@@ -0,0 +1,294 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Execution Pipeline: Thin orchestrator for outbound delivery.
+ *
+ * Delegates to 4 focused phase modules:
+ *   1. execution-policy  — send policy gate, trust level, elevated reply routing
+ *   2. execution-execute — LLM execution with timeout, thinking filter, abort
+ *   3. execution-filter  — response sanitization, filtering, media, voice, prefix
+ *   4. execution-deliver — chunking, coalescing, block pacing, delivery
+ *
+ * Keeps follow-up trigger logic here (needs full closure deps for re-enqueue).
+ *
+ * @module
+ */
+import { randomUUID } from "node:crypto";
+import { formatSessionKey, runWithContext, createDeliveryOrigin } from "@comis/core";
+// Phase module imports
+import { evaluateExecutionPolicy } from "./execution-policy.js";
+import { executeLlm } from "./execution-execute.js";
+import { filterExecutionResponse } from "./execution-filter.js";
+import { deliverExecutionResponse } from "./execution-deliver.js";
+// ---------------------------------------------------------------------------
+// Platform-specific configuration
+// ---------------------------------------------------------------------------
+/** Maps channelType to the metadata key containing the platform message ID for reply-to. */
+export const REPLY_TO_META_KEY = {
+    telegram: "telegramMessageId",
+    discord: "discordMessageId",
+    slack: "slackTs",
+    whatsapp: "whatsappMessageId",
+};
+/**
+ * Metadata keys that carry thread context -- must be propagated to followup messages.
+ * Mirror of TELEGRAM_THREAD_META_KEYS in thread-context.ts -- kept in sync via
+ * cross-reference unit test.
+ */
+export const THREAD_PROPAGATION_KEYS = [
+    "threadId", "telegramThreadId", "telegramIsForum", "telegramThreadScope",
+];
+/**
+ * Build thread-related SendMessageOptions from inbound message metadata.
+ * Returns undefined when no thread context present.
+ */
+export function buildThreadSendOpts(metadata) {
+    const threadId = metadata?.threadId;
+    if (!threadId)
+        return undefined;
+    return {
+        threadId,
+        extra: metadata?.telegramThreadScope
+            ? { telegramThreadScope: metadata.telegramThreadScope }
+            : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Streaming config resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve per-channel streaming configuration.
+ *
+ * Priority: per-channel override > global defaults > hardcoded defaults.
+ */
+export function resolveStreamingConfig(channelType, streamingConfig) {
+    const global = streamingConfig;
+    if (!global) {
+        return {
+            enabled: true,
+            chunkMode: "paragraph",
+            chunkMinChars: 100,
+            deliveryTiming: { mode: "natural", minMs: 800, maxMs: 2500, jitterMs: 200, firstBlockDelayMs: 0 },
+            coalescer: { minChars: 0, maxChars: 500, idleMs: 1500, codeBlockPolicy: "standalone", adaptiveIdle: false },
+            typingMode: "thinking",
+            typingRefreshMs: 6000,
+            typingCircuitBreakerThreshold: 3,
+            typingTtlMs: 60000,
+            useMarkdownIR: true,
+            tableMode: "code",
+            replyMode: "first",
+        };
+    }
+    const perChannel = global.perChannel[channelType];
+    if (perChannel)
+        return perChannel;
+    return {
+        enabled: global.enabled,
+        chunkMode: global.defaultChunkMode,
+        chunkMinChars: 100,
+        deliveryTiming: global.defaultDeliveryTiming,
+        coalescer: global.defaultCoalescer,
+        typingMode: global.defaultTypingMode,
+        typingRefreshMs: global.defaultTypingRefreshMs,
+        typingCircuitBreakerThreshold: 3,
+        typingTtlMs: 60000,
+        useMarkdownIR: global.defaultUseMarkdownIR ?? true,
+        tableMode: global.defaultTableMode ?? "code",
+        replyMode: global.defaultReplyMode ?? "first",
+    };
+}
+// ---------------------------------------------------------------------------
+// Main execution pipeline (thin orchestrator)
+// ---------------------------------------------------------------------------
+/**
+ * Execute a message with block streaming delivery.
+ *
+ * Orchestrates 4 phases: policy -> execute -> filter -> deliver.
+ */
+export async function executeAndDeliver(deps, adapter, effectiveMsg, originalMsg, executor, sessionKey, agentId, blockStreamCfg, activePacers, sendOverrides, typingLifecycle, directives) {
+    // Track lifecycle timing for diagnostic:message_processed event
+    const receivedAt = Date.now();
+    /** Emit diagnostic:message_processed with current lifecycle state. */
+    function emitDiagnostic(tokensUsed, cost, finishReason) {
+        deps.eventBus.emit("diagnostic:message_processed", {
+            messageId: effectiveMsg.id,
+            channelId: effectiveMsg.channelId,
+            channelType: adapter.channelType,
+            agentId,
+            sessionKey: formatSessionKey(sessionKey),
+            receivedAt,
+            executionDurationMs: Date.now() - receivedAt,
+            deliveryDurationMs: 0,
+            totalDurationMs: Date.now() - receivedAt,
+            tokensUsed,
+            cost,
+            success: true,
+            finishReason,
+            timestamp: Date.now(),
+        });
+    }
+    // Resolve tools for this agent.
+    // Pass sessionKey so setup-tools can thread the session's persistent
+    // FileStateTracker (per SessionTrackerRegistry) through the assembled
+    // tool pipeline -- keeps cross-turn file read state alive and removes
+    // the [not_read] bootstrap trap for seeded workspace files.
+    const tools = deps.assembleToolsForAgent
+        ? await deps.assembleToolsForAgent(agentId, { sessionKey })
+        : undefined;
+    if (tools) {
+        deps.logger.debug({ agentId, toolCount: tools.length }, "Tools assembled for agent");
+    }
+    // Phase 1: Send policy gate, trust level, elevated reply routing
+    const policy = evaluateExecutionPolicy(deps, adapter, effectiveMsg, originalMsg, sessionKey, agentId, sendOverrides);
+    if (!policy.allowed) {
+        // Still execute the agent (for session history), just skip sending
+        const policyResult = await runWithContext({
+            traceId: randomUUID(),
+            tenantId: sessionKey.tenantId,
+            userId: sessionKey.userId,
+            sessionKey: formatSessionKey(sessionKey),
+            startedAt: Date.now(),
+            trustLevel: policy.trustLevel,
+            channelType: adapter.channelType,
+            deliveryOrigin: createDeliveryOrigin({
+                channelType: adapter.channelType,
+                channelId: effectiveMsg.channelId,
+                userId: sessionKey.userId,
+                threadId: effectiveMsg.metadata?.threadId,
+                tenantId: sessionKey.tenantId,
+            }),
+        }, () => executor.execute(effectiveMsg, sessionKey, tools, undefined, agentId, directives, undefined, { operationType: "interactive" }));
+        emitDiagnostic(policyResult.tokensUsed.total, policyResult.cost.total, policyResult.finishReason);
+        return;
+    }
+    // Phase 2: LLM execution with timeout, thinking filter, abort signal
+    const execResult = await executeLlm(deps, adapter, policy.effectiveMsg, sessionKey, agentId, executor, policy.trustLevel, blockStreamCfg, policy.replyTo, typingLifecycle, tools, directives);
+    try {
+        if (execResult.timedOut) {
+            emitDiagnostic(0, 0, "timeout");
+            return;
+        }
+        // Follow-up trigger check — stays in orchestrator for closure access
+        handleFollowupTrigger(deps, adapter, policy.effectiveMsg, sessionKey, agentId, executor, execResult.result, execResult.finishReason, blockStreamCfg, activePacers, sendOverrides);
+        // Signal execution complete for thinking mode
+        if (typingLifecycle && blockStreamCfg.typingMode !== "message") {
+            typingLifecycle.markRunComplete();
+        }
+        // Phase 3: Response sanitization, filtering, media, voice, prefix
+        const filterResult = await filterExecutionResponse(deps, adapter, policy.effectiveMsg, originalMsg, sessionKey, agentId, execResult.result, execResult.accumulated, policy.replyTo, execResult.resourceAborted, execResult.abortReason, execResult.finishReason);
+        if (!filterResult.deliver) {
+            if (filterResult.reason === "filtered") {
+                emitDiagnostic(execResult.tokensUsed, execResult.cost, "filtered");
+            }
+            else if (filterResult.reason === "voice_delivered") {
+                emitDiagnostic(execResult.tokensUsed, execResult.cost, execResult.finishReason);
+            }
+            else {
+                emitDiagnostic(execResult.tokensUsed, execResult.cost, execResult.finishReason);
+            }
+            return;
+        }
+        // Phase 4: Chunking, coalescing, block pacing, delivery
+        await deliverExecutionResponse(deps, adapter, policy.effectiveMsg, filterResult.text, blockStreamCfg, activePacers, policy.replyTo, execResult.deliverySignal, typingLifecycle);
+        // Emit message:sent event with the cleaned response content
+        deps.eventBus.emit("message:sent", {
+            channelId: policy.effectiveMsg.channelId,
+            messageId: "block-delivery",
+            content: filterResult.text,
+        });
+        // Task extraction: extract commitments/follow-ups from the conversation (non-blocking)
+        if (deps.onTaskExtraction && filterResult.text) {
+            deps.onTaskExtraction(filterResult.text, formatSessionKey(sessionKey), agentId).catch((err) => {
+                deps.logger.debug({ err: err instanceof Error ? err.message : String(err) }, "Task extraction callback error (non-blocking)");
+            });
+        }
+        // Emit diagnostic:message_processed for full lifecycle tracking
+        emitDiagnostic(execResult.tokensUsed, execResult.cost, execResult.finishReason);
+    }
+    finally {
+        // Cleanup event listeners from execution phase
+        execResult.cleanup();
+        // Ensure typing is always stopped on error/completion
+        if (typingLifecycle) {
+            const wasActive = typingLifecycle.controller.isActive;
+            const startedAt = typingLifecycle.controller.startedAt;
+            typingLifecycle.dispose();
+            if (wasActive) {
+                deps.eventBus.emit("typing:stopped", {
+                    channelId: adapter.channelId,
+                    chatId: policy.effectiveMsg.channelId,
+                    durationMs: Date.now() - startedAt,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Follow-up trigger (kept in orchestrator for closure deps access)
+// ---------------------------------------------------------------------------
+/** Check and enqueue follow-up if trigger conditions are met. */
+function handleFollowupTrigger(deps, adapter, effectiveMsg, sessionKey, agentId, executor, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+result, diagFinishReason, blockStreamCfg, activePacers, sendOverrides) {
+    if (!deps.followupTrigger || !deps.commandQueue)
+        return;
+    const resultMeta = {};
+    const resMeta = result.metadata;
+    if (resMeta?.needs_followup)
+        resultMeta.needs_followup = true;
+    if (resMeta?.compaction_triggered)
+        resultMeta.compaction_triggered = true;
+    if (diagFinishReason === "compaction")
+        resultMeta.compaction_triggered = true;
+    if (!deps.followupTrigger.shouldFollowup(resultMeta))
+        return;
+    const chainId = effectiveMsg.metadata?.followupChainId ?? randomUUID();
+    const currentDepth = deps.followupTrigger.getChainDepth(chainId);
+    const maxDepth = deps.followupConfig?.maxFollowupRuns ?? 3;
+    if (currentDepth >= maxDepth) {
+        deps.eventBus.emit("followup:depth_exceeded", {
+            sessionKey: formatSessionKey(sessionKey),
+            chainId,
+            maxDepth,
+            timestamp: Date.now(),
+        });
+        return;
+    }
+    const newDepth = deps.followupTrigger.incrementChain(chainId);
+    const threadMeta = {};
+    for (const key of THREAD_PROPAGATION_KEYS) {
+        if (effectiveMsg.metadata?.[key] != null) {
+            threadMeta[key] = effectiveMsg.metadata[key];
+        }
+    }
+    const followupMsg = deps.followupTrigger.createFollowupMessage(sessionKey, adapter.channelType, effectiveMsg.channelId, resultMeta.compaction_triggered ? "compaction" : "tool_result", chainId, newDepth, Object.keys(threadMeta).length > 0 ? threadMeta : undefined);
+    deps.eventBus.emit("followup:enqueued", {
+        sessionKey: formatSessionKey(sessionKey),
+        channelType: adapter.channelType,
+        reason: resultMeta.compaction_triggered ? "compaction" : "tool_result",
+        chainId,
+        chainDepth: newDepth,
+        timestamp: Date.now(),
+    });
+    // Re-enqueue follow-up through command queue (fire-and-forget)
+    deps.commandQueue.enqueue(sessionKey, followupMsg, adapter.channelType, async (messages) => {
+        const fMsg = messages[0];
+        await executeAndDeliver(deps, adapter, fMsg, fMsg, executor, sessionKey, agentId, blockStreamCfg, activePacers, sendOverrides, undefined);
+    }).then((enqueueResult) => {
+        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,
+            }, "Follow-up enqueue failed");
+        }
+    }).catch((e) => {
+        deps.logger.warn({
+            err: e instanceof Error ? e.message : String(e),
+            hint: "Unexpected error during follow-up enqueue",
+            errorKind: "internal",
+            channelType: adapter.channelType,
+        }, "Follow-up enqueue failed");
+    });
+}

package/node_modules/@comis/channels/dist/shared/execution-policy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Execution Pipeline Phase 1: Send Policy and Trust Routing.
+ *
+ * Evaluates the send policy gate, resolves sender trust level,
+ * and applies elevated reply model/prompt routing.
+ *
+ * @module
+ */
+import type { ChannelPort, NormalizedMessage, SessionKey } from "@comis/core";
+import type { ExecutionPipelineDeps } from "./execution-pipeline.js";
+import type { SendOverrideStore } from "./send-policy.js";
+/** Minimal deps needed for the policy phase. */
+export type PolicyDeps = Pick<ExecutionPipelineDeps, "eventBus" | "logger" | "sendPolicyConfig" | "getElevatedReplyConfig" | "channelRegistry">;
+/** Result of policy evaluation. */
+export interface PolicyResult {
+    /** Whether the message should proceed to execution+delivery. */
+    allowed: boolean;
+    /** Resolved sender trust level. */
+    trustLevel: "guest" | "user" | "admin";
+    /** Message with elevated reply metadata injected (model route, prompt override). */
+    effectiveMsg: NormalizedMessage;
+    /** Metadata key for reply-to. */
+    replyToMetaKey: string | undefined;
+    /** Message ID for reply-to (group only). */
+    replyTo: string | undefined;
+}
+/**
+ * Evaluate send policy, resolve trust level, and apply elevated reply routing.
+ *
+ * When `allowed` is false, the caller should still run execution (for session
+ * history) but skip delivery. The caller is responsible for running the
+ * silent execution in that case.
+ */
+export declare function evaluateExecutionPolicy(deps: PolicyDeps, adapter: ChannelPort, effectiveMsg: NormalizedMessage, originalMsg: NormalizedMessage, sessionKey: SessionKey, agentId: string, sendOverrides: SendOverrideStore): PolicyResult;