comisai 1.0.34 → 1.0.37

package/node_modules/@comis/agent/dist/executor/executor-post-execution.js

@@ -13,7 +13,9 @@
  *
  * @module
  */
-import { suppressError } from "@comis/shared";
+import { tryGetContext, } from "@comis/core";
+import { suppressError, isSilentResponse } from "@comis/shared";
+import { drainAt, markRead, markConsumed, formatDrainKey, } from "./drain-helper.js";
 import { setBreakpointIndex, deleteBreakpointIndex, getBreakpointIndexMapSize, } from "./executor-session-state.js";
 import { mergeSessionStats } from "./pi-executor.js";
 import { recordLastResponseTs } from "./ttl-guard.js";
@@ -124,6 +126,63 @@ export function isDuplicatePairedMemory(content, agentId) {
 export function resetPairedMemoryDedupForTests() {
     pairedMemoryDedup.clear();
 }
+/**
+ * Map an SDK finishReason to the SessionMetadata.sessionEnd.endReason enum.
+ * Unknown reasons fall through to "error" — that's a defensive bucket for
+ * provider strings we haven't classified yet (rather than dropping the
+ * session_end entry entirely). Module-level so the post-execution path
+ * doesn't reallocate it on every turn.
+ */
+const END_REASON_MAP = {
+    stop: "success", end_turn: "success", error: "error",
+    budget_exceeded: "budget_exceeded", budget_exhausted: "budget_exhausted",
+    circuit_open: "circuit_open",
+    provider_degraded: "provider_degraded", max_steps: "error",
+    context_loop: "error", context_exhausted: "error",
+};
+/**
+ * Build the SessionMetadata payload written to `_session-metadata.json` at the
+ * end of an execution.
+ *
+ * `traceId` and `runId` are deliberately distinct:
+ * - `traceId` is the request-scope AsyncLocalStorage value set by
+ *   `runWithContext` at the channel boundary (execution-execute.ts) and injected
+ *   into every daemon log line by the Pino tracing mixin. Operators grep
+ *   daemon.log for this exact value. Pass `tryGetContext()?.traceId` here.
+ * - `runId` is the executor-scope UUID minted in pi-executor.ts per
+ *   `executor.execute()` call. It keys cost-tracker / token_usage rows.
+ *
+ * They happen to be 1:1 in the steady-state interactive path (one inbound
+ * message → one execution), but the schema treats them as distinct because
+ * heartbeat / sub-agent paths can fan out one trace into multiple executions.
+ *
+ * Pure: no I/O, no side effects. The fire-and-forget try/catch around
+ * `writeSessionMetadata` lives at the call site.
+ */
+export function buildSessionEndMetadata(args) {
+    return {
+        ...(args.traceId && { traceId: args.traceId }),
+        runId: args.executionId,
+        sessionEnd: {
+            type: "session_end",
+            timestamp: new Date().toISOString(),
+            endReason: END_REASON_MAP[args.finishReason] ?? "error",
+            durationMs: args.durationMs,
+            totalTokens: args.totalTokens,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Drain-seam re-exports.
+//
+// Canonical implementations live in ./drain-helper.ts so the bridge
+// (packages/agent/src/bridge/pi-event-bridge.ts) can import them without
+// creating a cycle through pi-executor.js. The bridge owns the
+// `drainInflightByKey: Map<string, Promise<void>>` gate state in
+// `BridgeMetricsState` and threads it into drainAt at the
+// `tool_execution_end` call site (inline-consumption + composite drain).
+// ---------------------------------------------------------------------------
+export { drainAt, markRead, markConsumed, formatDrainKey, };
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
@@ -139,7 +198,12 @@ export function resetPairedMemoryDedupForTests() {
  * @param params - All inputs needed for post-execution cleanup
  */
 export async function postExecution(params) {
-    const { result, session, sm, config, msg, sessionKey, formattedKey, agentId, executionStartMs, executionId, bridge, unsubscribe, contextEngineRef, ceSetup, streamSetup, getTruncationSummary, getTurnBudgetSummary, executionPlanRef, isOnboarding, geminiCacheHit, geminiCachedTokens, modelTier, deferralResult, mergedCustomTools, deliveredGuides, deps, sessionAdapter, executionCacheRetentionClear, adaptiveRetentionClear, } = params;
+    const { result, session, sm, config, msg, sessionKey, formattedKey, resolverRegisterKey, agentId, executionStartMs, executionId, bridge, unsubscribe, contextEngineRef, ceSetup, streamSetup, getTruncationSummary, getTurnBudgetSummary, executionPlanRef, isOnboarding, geminiCacheHit, geminiCachedTokens, modelTier, provider, providerFamily, deferralResult, mergedCustomTools, deliveredGuides, deps, sessionAdapter, executionCacheRetentionClear, adaptiveRetentionClear, } = params;
+    // Hoist effectiveAgentId normalization to the TOP of the function so all
+    // downstream branches (silent-sentinel gate, memory-store path, drainAt
+    // call site, skip-log debug branches) share the same normalized value.
+    // Multi-agent isolation requires uniformity across all paths.
+    const effectiveAgentId = agentId ?? "default";
     unsubscribe();
     // Clear per-execution cache retention to prevent state leakage
     executionCacheRetentionClear();
@@ -168,7 +232,7 @@ export async function postExecution(params) {
     if (result.errorContext && bridgeResult.lastActiveToolName) {
         result.errorContext.failingTool = bridgeResult.lastActiveToolName;
     }
-    // R-13: Delegate token totals to SDK session stats (single source of truth).
+    // Delegate token totals to SDK session stats (single source of truth).
     // Cost stays from bridge for consistency with per-turn observability events.
     // Per-turn event emission in bridge remains manual (SDK stats are cumulative only).
     mergeSessionStats(result, () => session.getSessionStats());
@@ -184,7 +248,7 @@ export async function postExecution(params) {
         // The context:pipeline event fires pre-LLM with zeros. This event patches actual data.
         if (deps.eventBus) {
             deps.eventBus.emit("context:pipeline:cache", {
-                agentId: agentId ?? "unknown",
+                agentId: effectiveAgentId,
                 sessionKey: formattedKey,
                 cacheHitTokens: cacheReadTokens,
                 cacheWriteTokens,
@@ -207,7 +271,7 @@ export async function postExecution(params) {
             planExtractionTurn: 1,
         };
         deps.eventBus.emit("sep:plan_completed", {
-            agentId: agentId ?? "default",
+            agentId: effectiveAgentId,
             sessionKey: formattedKey,
             stepsPlanned: toolCalls,
             stepsCompleted: toolCalls,
@@ -235,6 +299,10 @@ export async function postExecution(params) {
     // Truncation summary from bouncer + turn budget summary
     const truncSummary = getTruncationSummary();
     const turnBudgetSummary = getTurnBudgetSummary();
+    // Snapshot the scrub counters once before composing the bookend log so both
+    // fields read from the same observation (the getter is cheap but the
+    // read-twice pattern would still be a micro-divergence risk).
+    const scrubCounters = ceSetup.getSignatureScrubCounters();
     deps.logger.info({
         sessionKey: formattedKey,
         durationMs,
@@ -260,7 +328,7 @@ export async function postExecution(params) {
         comisEstimatedTtlSplit: (bridgeResult.cacheWrite5mTokens ?? 0) > 0 || (bridgeResult.cacheWrite1hTokens ?? 0) > 0,
         costUsd: result.cost.total,
         cacheSavedUsd: result.cost.cacheSaved ?? 0,
-        // 1.3: Session-cumulative cost fields (alongside per-turn costUsd/cacheSavedUsd)
+        // Session-cumulative cost fields (alongside per-turn costUsd/cacheSavedUsd)
         sessionCostUsd: bridgeResult.sessionCostUsd ?? 0,
         sessionCacheSavedUsd: bridgeResult.sessionCacheSavedUsd ?? 0,
         // Session cache savings rate
@@ -274,6 +342,8 @@ export async function postExecution(params) {
         geminiCacheHit,
         geminiCachedTokens,
         modelTier,
+        provider,
+        providerFamily,
         deferredCount: deferralResult.deferredCount,
         activeToolCount: mergedCustomTools.length,
         guidesDelivered: deliveredGuides.size,
@@ -282,6 +352,16 @@ export async function postExecution(params) {
         toolFailureRate: (result.stepsExecuted ?? 0) > 0
             ? Math.round(((bridgeResult.failedToolCalls ?? 0) / (result.stepsExecuted ?? 0)) * 100)
             : 0,
+        // Per-execute diagnostic counters rolled up from the two demoted log
+        // sites. Always populated (no `> 0` gate) — `0` is itself meaningful
+        // ("no scrubs/assertions this execute") and gating would lose that
+        // signal. hashAssertions* come from the bridge metrics path;
+        // signatureScrubs* come from ceSetup since the scrubber doesn't write
+        // to bridge state.
+        hashAssertionsRan: bridgeResult.hashAssertionsRan ?? 0,
+        hashAssertionMismatches: bridgeResult.hashAssertionMismatches ?? 0,
+        signatureScrubs: scrubCounters.signatureScrubs,
+        signatureScrubsToolCallsAffected: scrubCounters.signatureScrubsToolCallsAffected,
         ...(bridgeResult.failedTools && bridgeResult.failedTools.length > 0 && { failedTools: bridgeResult.failedTools }),
         truncatedTools: truncSummary.truncatedTools,
         totalTruncatedChars: truncSummary.totalTruncatedChars,
@@ -296,7 +376,7 @@ export async function postExecution(params) {
             postBatchContinuationAttempts: result.continuationMetrics.attempts,
             postBatchContinuationOutcome: result.continuationMetrics.outcome,
         }),
-        // 1.5 + 3.2: Thinking token tracking (conditional -- only when thinking tokens detected)
+        // Thinking token tracking (conditional -- only when thinking tokens detected)
         ...(bridgeResult.thinkingTokens != null && bridgeResult.thinkingTokens > 0 && {
             thinkingTokens: bridgeResult.thinkingTokens,
             totalOutputTokens: result.tokensUsed.output ?? 0,
@@ -323,27 +403,19 @@ export async function postExecution(params) {
             errorKind: "resource",
         }, "Turn budget truncation summary");
     }
-    // Write session metadata companion file with trace correlation
-    // Fire-and-forget: metadata write failure must not affect execution
-    const endReasonMap = {
-        stop: "success", end_turn: "success", error: "error",
-        budget_exceeded: "budget_exceeded", budget_exhausted: "budget_exhausted",
-        circuit_open: "circuit_open",
-        provider_degraded: "provider_degraded", max_steps: "error",
-        context_loop: "error", context_exhausted: "error",
-    };
+    // Write session metadata companion file with trace correlation.
+    // traceId comes from the AsyncLocalStorage request scope so `_session-metadata.json`
+    // can be cross-correlated against daemon.log via grep; runId stays as the
+    // executor-scope UUID. See buildSessionEndMetadata for the contract.
+    // Fire-and-forget: metadata write failure must not affect execution.
     try {
-        sessionAdapter.writeSessionMetadata(sessionKey, {
-            traceId: executionId,
-            runId: executionId,
-            sessionEnd: {
-                type: "session_end",
-                timestamp: new Date().toISOString(),
-                endReason: endReasonMap[result.finishReason] ?? "error",
-                durationMs,
-                totalTokens: result.tokensUsed.total,
-            },
-        });
+        sessionAdapter.writeSessionMetadata(sessionKey, buildSessionEndMetadata({
+            finishReason: result.finishReason,
+            durationMs,
+            totalTokens: result.tokensUsed.total,
+            executionId,
+            traceId: tryGetContext()?.traceId,
+        }));
     }
     catch { /* fire-and-forget */ }
     // Check onboarding completion after execution
@@ -367,14 +439,23 @@ export async function postExecution(params) {
     // Non-blocking, non-fatal -- execution never fails due to memory store errors.
     const operationType = params.executionOverrides?.operationType;
     const skipMemoryForOperation = operationType != null && MEMORY_SKIP_OPERATIONS.has(operationType);
-    if (deps.memoryPort &&
+    // Layer 0: silent sentinels never enter memory. Idempotent under
+    // stripReplyTags + trim per @comis/shared silent-tokens.ts JSDoc
+    // contract. The check happens BEFORE the operationType + content-hash
+    // dedup gates so that even when the response would otherwise pass those
+    // gates, a `NO_REPLY` / `HEARTBEAT_OK` / `[SILENT]` sentinel is rejected
+    // from memory persistence.
+    const isSilent = !!(deps.memoryPort && result.response && msg.text && isSilentResponse(result.response));
+    if (isSilent) {
+        deps.logger.debug({ agentId: effectiveAgentId, sessionKey: formattedKey, hint: "Silent-sentinel response (NO_REPLY / HEARTBEAT_OK / [SILENT]) skipped from paired memory" }, "Paired memory skipped: silent-sentinel response");
+    }
+    else if (deps.memoryPort &&
         result.response &&
         msg.text &&
         !skipMemoryForOperation &&
         shouldStorePairedMemory(msg.text, result.response)) {
         const now = Date.now();
         const pairedContent = buildPairedMemoryContent(msg.text, result.response);
-        const effectiveAgentId = agentId ?? "default";
         if (isDuplicatePairedMemory(pairedContent, effectiveAgentId)) {
             deps.logger.debug({ agentId: effectiveAgentId, sessionKey: formattedKey }, "Paired memory skipped: duplicate content within dedup window");
         }
@@ -417,9 +498,47 @@ export async function postExecution(params) {
             deps.logger.debug({ userLen: msg.text.trim().length, minUserChars: PAIRED_MIN_USER_CHARS, minCombinedChars: PAIRED_MIN_COMBINED_CHARS }, "Paired memory skipped: content below quality threshold");
         }
     }
-    // Deregister active run before dispose
+    // End-of-turn backstop drain.
+    //
+    // The bridge fires `drainAt(...)` on `tool_execution_end` for successful
+    // `message(send|reply|attach)` calls (the primary inline-consumption
+    // call site). The end-of-turn call site below is the BACKSTOP for turns
+    // that produced a response WITHOUT invoking the message tool (NO_REPLY-
+    // only turns, sentinel-passthrough turns, error paths). Both call sites
+    // share the SAME composite-key inflight gate (`drainInflightByKey`) so a
+    // bridge-fired drain in flight collapses any backstop drain for the same
+    // composite key (single-tick gate).
+    //
+    // The drain key is composed from `effectiveAgentId` (multi-agent
+    // isolation) + `msg.channelType` + `msg.channelId`. markRead and
+    // markConsumed inside drainAt read tool context via tryGetContext();
+    // when the executor runs outside an AsyncLocalStorage scope (e.g.,
+    // tests with no runWithContext wrapper) the helpers fall through silently.
+    const drainKey = {
+        agentId: effectiveAgentId,
+        channelType: msg.channelType,
+        channelId: msg.channelId,
+    };
+    // tryGetContext() reads the AsyncLocalStorage scope; markRead/markConsumed
+    // do the same internally, but reading once here lets us correlate the
+    // backstop-drain log line with the request's traceId without re-deriving
+    // it inside the helper. Returns undefined outside any request scope --
+    // markRead/markConsumed handle that path silently.
+    const drainCtx = tryGetContext();
+    if (drainCtx) {
+        deps.logger.debug({
+            submodule: "drain.endOfTurn",
+            agentId: effectiveAgentId,
+            channelType: msg.channelType,
+            channelId: msg.channelId,
+            traceId: drainCtx.traceId,
+        }, "End-of-turn drain backstop firing");
+    }
+    drainAt({ agentId: effectiveAgentId, channelType: drainKey.channelType, channelId: drainKey.channelId }, bridge.getDrainState(), deps.logger);
+    // Deregister active run before dispose. Must use the same resolver-aligned
+    // key formula as the corresponding register call site.
     if (deps.activeRunRegistry) {
-        deps.activeRunRegistry.deregister(formattedKey);
+        deps.activeRunRegistry.deregister(resolverRegisterKey);
     }
     // Strip verbose <functions> blocks from discover_tools results
     // in session history. Runs post-execution so the current turn's model

package/node_modules/@comis/agent/dist/executor/executor-prompt-runner.d.ts

@@ -26,6 +26,7 @@ import type { AuthRotationAdapter } from "../model/auth-rotation-adapter.js";
 import type { ProviderHealthMonitor } from "../safety/provider-health-monitor.js";
 import type { LastKnownModelTracker } from "../model/last-known-model.js";
 import type { EnvelopeConfig } from "@comis/core";
+import type { CapabilityIndexRenderResult } from "./capability-index-context.js";
 /** Bridge interface used by the prompt runner (minimal getResult). */
 export interface PromptRunnerBridge {
     getResult(): {
@@ -60,6 +61,12 @@ export interface RunPromptParams {
     bridge: PromptRunnerBridge;
     dynamicPreamble: string | undefined;
     deferredContext: string | undefined;
+    /**
+     * Per-turn capability-index render result. The .text field is concatenated
+     * into the dynamic preamble via `[...].filter(Boolean).join("\n\n")`; the
+     * count fields feed the Pino debug log below.
+     */
+    capabilityIndexResult: CapabilityIndexRenderResult;
     inlineMemory: string | undefined;
     systemPrompt: string | undefined;
     mergedCustomTools: Array<{

package/node_modules/@comis/agent/dist/executor/executor-prompt-runner.js

@@ -47,7 +47,7 @@ import { getCacheProviderInfo } from "../executor/cache-usage-helpers.js";
  * @returns Prompt execution outcome (success, error, escalation state)
  */
 export async function runPrompt(params) {
-    const { msg, session, config, sessionKey, formattedKey, agentId, result, executionStartMs, effectiveTimeout, executionId, bridge, dynamicPreamble, deferredContext, inlineMemory, systemPrompt, mergedCustomTools, cmdResult, sepEnabled, executionPlanRef, _directives, _prevTimestamp, resolvedModel, deps, onResetTimer, getLastCacheWriteTokens, budgetWarningRef, } = params;
+    const { msg, session, config, sessionKey, formattedKey, agentId, result, executionStartMs, effectiveTimeout, executionId, bridge, dynamicPreamble, deferredContext, capabilityIndexResult, inlineMemory, systemPrompt, mergedCustomTools, cmdResult, sepEnabled, executionPlanRef, _directives, _prevTimestamp, resolvedModel, deps, onResetTimer, getLastCacheWriteTokens, budgetWarningRef, } = params;
     // Wrap message text with envelope
     let messageText = deps.envelopeConfig
         ? wrapInEnvelope(msg, deps.envelopeConfig, _prevTimestamp)
@@ -55,12 +55,33 @@ export async function runPrompt(params) {
     // Prepend dynamic preamble (date/time, inbound metadata)
     // relocated from system prompt for cache stability.
     // Also includes <deferred-tools> context block when deferred tools exist.
-    const fullDynamicPreamble = deferredContext
-        ? (dynamicPreamble ? dynamicPreamble + "\n\n" + deferredContext : deferredContext)
-        : dynamicPreamble;
+    //
+    // Array-concat shape. Each element either contributes a non-empty string
+    // or filters out cleanly. The renderer's EMPTY sentinel (gate-disabled OR
+    // all-zero counts) yields text === "" which .filter(Boolean) drops
+    // automatically.
+    const capabilityIndexContext = capabilityIndexResult.text;
+    const fullDynamicPreamble = [dynamicPreamble, capabilityIndexContext, deferredContext]
+        .filter(Boolean)
+        .join("\n\n");
     if (fullDynamicPreamble) {
         messageText = `[System context]\n${fullDynamicPreamble}\n[End system context]\n\n${messageText}`;
     }
+    // Pino debug log. Submodule binding per AGENTS.md §2.7:
+    // deps.logger.child({ submodule }) attaches the label only at this call
+    // site, not module-scope.
+    const submoduleLogger = deps.logger.child({ submodule: "executor.capability-index" });
+    const fullPreambleTokens = Math.ceil((fullDynamicPreamble ?? "").length / CHARS_PER_TOKEN_RATIO);
+    const deferredContextTokens = Math.ceil((deferredContext ?? "").length / CHARS_PER_TOKEN_RATIO);
+    submoduleLogger.debug({
+        capabilityIndexTokens: capabilityIndexResult.capabilityIndexTokens,
+        deferredContextTokens,
+        fullPreambleTokens,
+        clusterCount: capabilityIndexResult.clusterCount,
+        activeToolCount: capabilityIndexResult.activeToolCount,
+        deferredToolCount: capabilityIndexResult.deferredToolCount,
+        promptSkillCount: capabilityIndexResult.promptSkillCount,
+    }, "Dynamic preamble assembled");
     // Task 229: Inject top-1 RAG memory inline, adjacent to user message
     // for maximum LLM attention. Placed AFTER [End system context] and
     // BEFORE the user's actual question text.
@@ -644,7 +665,7 @@ export async function runPrompt(params) {
         // NOTE: Only evaluate bridge.getResult().textEmitted when needed to avoid
         // incrementing mock call counters (budget tests use callCount on getResult).
         const rawResponse = getVisibleAssistantText(session);
-        const needsRecovery = rawResponse === "" || ["NO_REPLY", "HEARTBEAT_OK"].includes(rawResponse.trim());
+        const needsRecovery = rawResponse === "";
         // Find the last user message index to bound empty-response recovery
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const sessionMessages = session.messages ?? [];

package/node_modules/@comis/agent/dist/executor/executor-response-filter.d.ts

@@ -42,10 +42,15 @@ export declare function scanWithOutputGuard(params: {
     logger: ComisLogger;
 }): OutputGuardScanResult;
 /**
- * When the final assistant message is thinking-only or a
- * silent token (NO_REPLY, HEARTBEAT_OK) but text was emitted in earlier
+ * When the final assistant message is empty but text was emitted in earlier
  * turns, recover a meaningful user-visible response.
  *
+ * Recovery fires only when `extractedResponse === ""`. Silent tokens
+ * (`NO_REPLY`, `HEARTBEAT_OK`) are explicit suppression signals and pass
+ * through unchanged — the channel-layer filter
+ * (`packages/channels/src/shared/response-filter.ts`) detects and suppresses
+ * them downstream.
+ *
  * Two-pass strategy (gated):
  * 1. **Tool-call synthesis** (primary) — if ≥1 prior assistant turn within the
  *    current execution window contains tool-call blocks, synthesize a
@@ -62,10 +67,6 @@ export declare function scanWithOutputGuard(params: {
  * comment below) ensures the standalone walk only fires when no tool calls
  * were observed; this keeps the pass selection mutually exclusive.
  *
- * Suppressed when a delivery tool (`message`, `notify`) was used — the agent
- * already delivered content via side-channel and the silent final token is
- * intentional.
- *
  * Returns the recovered text, or the original response if no recovery needed.
  */
 export declare function recoverEmptyFinalResponse(params: {

package/node_modules/@comis/agent/dist/executor/executor-response-filter.js

@@ -84,16 +84,16 @@ export function scanWithOutputGuard(params) {
 // ---------------------------------------------------------------------------
 /** Silent tokens that indicate the final message has no visible content. */
 const SILENT_FINAL_TOKENS = ["NO_REPLY", "HEARTBEAT_OK"];
-/** Tool names whose successful invocation means the agent already delivered
- *  content to the user through a side-channel. When one of these tools was
- *  called during the execution, a silent final token (NO_REPLY) is intentional
- *  and recovery must be suppressed to avoid leaking internal narration. */
-const DELIVERY_TOOL_NAMES = ["message", "notify"];
 /**
- * When the final assistant message is thinking-only or a
- * silent token (NO_REPLY, HEARTBEAT_OK) but text was emitted in earlier
+ * When the final assistant message is empty but text was emitted in earlier
  * turns, recover a meaningful user-visible response.
  *
+ * Recovery fires only when `extractedResponse === ""`. Silent tokens
+ * (`NO_REPLY`, `HEARTBEAT_OK`) are explicit suppression signals and pass
+ * through unchanged — the channel-layer filter
+ * (`packages/channels/src/shared/response-filter.ts`) detects and suppresses
+ * them downstream.
+ *
  * Two-pass strategy (gated):
  * 1. **Tool-call synthesis** (primary) — if ≥1 prior assistant turn within the
  *    current execution window contains tool-call blocks, synthesize a
@@ -110,29 +110,13 @@ const DELIVERY_TOOL_NAMES = ["message", "notify"];
  * comment below) ensures the standalone walk only fires when no tool calls
  * were observed; this keeps the pass selection mutually exclusive.
  *
- * Suppressed when a delivery tool (`message`, `notify`) was used — the agent
- * already delivered content via side-channel and the silent final token is
- * intentional.
- *
  * Returns the recovered text, or the original response if no recovery needed.
  */
 export function recoverEmptyFinalResponse(params) {
     const { extractedResponse, textEmitted, messages, logger, userMessageIndex } = params;
     const lowerBound = userMessageIndex ?? 0;
-    const isSilentFinalToken = SILENT_FINAL_TOKENS.includes(extractedResponse.trim());
-    if ((extractedResponse === "" || isSilentFinalToken) && textEmitted) {
+    if (extractedResponse === "" && textEmitted) {
         if (Array.isArray(messages)) {
-            // Guard: if the agent already delivered content via a delivery tool
-            // (message, notify), the silent final token is intentional — skip
-            // recovery to avoid leaking internal narration (e.g. "Now let me
-            // generate the chart:" surfaced as a user-visible message).
-            if (isSilentFinalToken && hasDeliveryToolCall(messages, lowerBound)) {
-                logger.debug({
-                    hint: "Silent final token after delivery tool call — recovery suppressed",
-                    extractedResponse,
-                }, "Skipping empty-response recovery (delivery tool used)");
-                return extractedResponse;
-            }
             /* eslint-disable @typescript-eslint/no-explicit-any */
             // Collect tool-call summaries from prior assistant turns within the
             // current execution window (lowerBound .. messages.length).
@@ -170,7 +154,7 @@ export function recoverEmptyFinalResponse(params) {
                     `${bullets}\n` +
                     `The work was done; the assistant did not summarize. Please ask "what did you do?" if details are needed.`;
                 logger.info({
-                    module: "agent.executor.empty-turn-recovery",
+                    submodule: "executor.empty-turn-recovery",
                     recoveryPass: "tool-call-synthesis",
                     toolCallCount: toolCallSummaries.length,
                     toolNames: [...toolNamesSet],
@@ -226,23 +210,6 @@ function extractVisibleText(content) {
     return undefined;
 }
 /* eslint-enable @typescript-eslint/no-explicit-any */
-/** Check whether any assistant turn (from lowerBound onward) contains a tool
- *  call to a delivery tool (message, notify). These tools send content to the
- *  user through a side-channel, so a subsequent NO_REPLY is intentional. */
-/* eslint-disable @typescript-eslint/no-explicit-any */
-function hasDeliveryToolCall(messages, lowerBound) {
-    for (let i = lowerBound; i < messages.length; i++) {
-        const msg = messages[i]; // eslint-disable-line security/detect-object-injection
-        if (msg?.role === "assistant" && Array.isArray(msg.content)) {
-            const hasDelivery = msg.content.some((b) => (b?.type === "toolCall" || b?.type === "tool_use") &&
-                DELIVERY_TOOL_NAMES.includes(b?.name));
-            if (hasDelivery)
-                return true;
-        }
-    }
-    return false;
-}
-/* eslint-enable @typescript-eslint/no-explicit-any */
 /** Summarize a single tool-call content block as `toolName({primary_arg: "value"})`.
  *  Reads `name` from the block, and `input` (Anthropic native) or `arguments`
  *  (internal mapped convention) for args. Returns bare tool name on malformed

package/node_modules/@comis/agent/dist/executor/executor-tool-assembly.d.ts

@@ -15,9 +15,10 @@
 import { SettingsManager, DefaultResourceLoader } from "@mariozechner/pi-coding-agent";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
 import type { AgentTool } from "@mariozechner/pi-agent-core";
-import { type SessionKey, type NormalizedMessage, type PerAgentConfig, type TypedEventBus, type MemoryPort, type HookRunner, type SecretManager, type EnvelopeConfig, type SenderTrustDisplayConfig } from "@comis/core";
+import { type SessionKey, type NormalizedMessage, type PerAgentConfig, type TypedEventBus, type MemoryPort, type HookRunner, type SecretManager, type EnvelopeConfig, type SenderTrustDisplayConfig, type ToolCapabilityPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { ExcludeDeferralResult } from "./tool-deferral.js";
+import type { CapabilityIndexRenderResult } from "./capability-index-context.js";
 import type { DiscoveryTracker } from "./discovery-tracker.js";
 import type { ExecutionPromptResult } from "./prompt-assembly.js";
 import type { ExecutionOverrides } from "./types.js";
@@ -48,6 +49,13 @@ export interface ToolAssemblyDeps {
         maxCharsPerInjection: number;
     };
     embeddingPort?: EmbeddingPort;
+    /**
+     * Tool-capability port for the per-turn capability-index renderer.
+     * Daemon wiring injects createNoOpCapabilityPort() from @comis/core; the
+     * live adapter is swapped in elsewhere. The no-op is a real production
+     * code path — NOT a transitional shim.
+     */
+    toolCapabilityPort: ToolCapabilityPort;
     skillRegistry?: {
         getEligibleSkillNames(): Set<string>;
         initFromSdkSkills(sdkSkills: Array<{
@@ -70,6 +78,15 @@ export interface ToolAssemblyResult {
     deferralResult: ExcludeDeferralResult;
     /** Formatted deferred tools context for dynamic preamble injection. */
     deferredContext: string;
+    /**
+     * Per-turn capability-index render result.
+     * `text` is concatenated into the dynamic preamble; the count fields feed
+     * the Pino debug log emitted in `executor-prompt-runner.ts`.
+     * When the port returns gate-disabled or all counts are zero, the renderer
+     * returns the EMPTY sentinel and `text === ""` filters out via
+     * `[...].filter(Boolean)` in the runner.
+     */
+    capabilityIndexResult: CapabilityIndexRenderResult;
     /** Session-scoped guide delivery tracking set. */
     deliveredGuides: Set<string>;
     /** Model tier derived from context window: "small" | "medium" | "large". */

package/node_modules/@comis/agent/dist/executor/executor-tool-assembly.js

@@ -15,7 +15,8 @@
  */
 import { SettingsManager, } from "@mariozechner/pi-coding-agent";
 import { formatSessionKey, } from "@comis/core";
-import { applyToolDeferral, buildDeferredToolsContext, createDiscoverTool, createAutoDiscoveryStubs, extractRecentlyUsedToolNames, resolveModelTier, supportsToolSearch, CORE_TOOLS } from "./tool-deferral.js";
+import { applyToolDeferral, buildDeferredToolsContext, createDiscoverTool, createAutoDiscoveryStubs, extractRecentlyUsedToolNames, resolveModelTier, CORE_TOOLS } from "./tool-deferral.js";
+import { buildCapabilityIndexContext } from "./capability-index-context.js";
 import { getOrCreateDiscoveryTracker } from "./discovery-tracker.js";
 import { getOrCreateTracker, DEFAULT_LIFECYCLE_CONFIG } from "./tool-lifecycle.js";
 import { isAnthropicFamily, isGoogleFamily } from "../provider/capabilities.js";
@@ -159,6 +160,9 @@ export async function assembleTools(params) {
             deliveryMirror: deps.deliveryMirror,
             deliveryMirrorConfig: deps.deliveryMirrorConfig,
             channelMaxChars: deps.getChannelMaxChars?.(msg.channelType),
+            // Forward the tool-capability port so prompt-assembly.ts can read
+            // `port.isCapabilityIndexEnabled()` for the static-prompt swap gate.
+            toolCapabilityPort: deps.toolCapabilityPort,
         },
         msg,
         sessionKey,
@@ -297,8 +301,7 @@ export async function assembleTools(params) {
     // discovered) is the only factually-accurate set -- using mergedCustomTools
     // (pre-deferral) would false-positive on currently-deferred tools and tell
     // the agent "call directly, no discovery needed" for tools that aren't
-    // actually loaded. See design §4.2, §5.5, decision log row 4:
-    // .planning/design/discover-tools-bm25-fallback-fix.md
+    // actually loaded.
     if (deferralResult.discoverTool) {
         const activeAfterDeferral = new Set([
             ...deferralResult.activeTools.map(t => t.name),
@@ -322,24 +325,22 @@ export async function assembleTools(params) {
         const stubs = createAutoDiscoveryStubs(deferralResult.deferredEntries, discoveryTracker, deps.logger);
         mergedCustomTools.push(...stubs);
     }
-    // Build deferred context for dynamic preamble injection.
-    //
-    // 260428-oyc: under Anthropic Sonnet/Opus 4.x, request-body-injector.ts
-    // strips client-side `discover_tools` from the API payload and replaces it
-    // with the server-side `tool_search_tool_regex` + per-tool `defer_loading`
-    // flag. Pass `useToolSearch=true` so the preamble teaches the model that
-    // deferred tools auto-load on first direct invocation, rather than telling
-    // it to call a tool the model can no longer see.
-    //
-    // resolvedModel is in scope here (param of assembleToolsForAgent, see
-    // function signature ~line 143). When undefined (test paths / fallback),
-    // useToolSearch defaults to false, preserving backward-compatible
-    // discover_tools wording.
+    // Build deferred-tools context for dynamic preamble injection (mechanism-neutral).
+    // Provider-specific payload reshaping (stripping the client-side discovery
+    // tool, appending the server-side tool-search regex tool for Anthropic
+    // Sonnet/Opus 4.x) lives entirely in `request-body-injector.ts` and is
+    // gated there by a model-id capability check. See tool-deferral.ts JSDoc
+    // on `buildDeferredToolsContext` for the rationale.
     let deferredContext = "";
     if (deferralResult.deferredEntries.length > 0) {
-        const useToolSearch = supportsToolSearch(resolvedModel?.id ?? "");
-        deferredContext = buildDeferredToolsContext(deferralResult.deferredEntries, { useToolSearch });
+        deferredContext = buildDeferredToolsContext(deferralResult.deferredEntries);
     }
+    // Per-turn capability index.
+    // Lives AFTER applyToolDeferral so the renderer sees the post-partition
+    // state (active vs deferred entries). When the port is the no-op, the
+    // renderer's gate check still respects port.isCapabilityIndexEnabled();
+    // if false, returns EMPTY which the runner filters via .filter(Boolean).
+    const capabilityIndexResult = buildCapabilityIndexContext(deferralResult, deps.toolCapabilityPort);
     // -------------------------------------------------------------------
     // 8. JIT guide wrapping, schema pruning, snapshot, normalization, serializer
     // -------------------------------------------------------------------
@@ -369,6 +370,7 @@ export async function assembleTools(params) {
         mergedCustomTools,
         deferralResult,
         deferredContext,
+        capabilityIndexResult,
         deliveredGuides,
         modelTier,
         discoveryTracker,

package/node_modules/@comis/agent/dist/executor/gemini-cache-injector.d.ts

@@ -3,7 +3,7 @@
  *
  * Injects CachedContent name into Gemini API payloads and atomically strips
  * the three inherited fields (systemInstruction, tools, toolConfig) to avoid
- * double-billing. Operates inside the onPayload hook (post-buildParams) per D-04.
+ * double-billing. Operates inside the onPayload hook (post-buildParams).
  *
  * Handles cache injection, inherited field stripping, and staleness recovery.
  *
@@ -24,7 +24,7 @@ export interface GeminiCacheInjectorConfig {
     /** Callback when a Gemini CachedContent entry is successfully injected.
      *  Called with the CacheEntry so the caller can capture cache hit stats for logging. */
     onCacheHit?: (entry: CacheEntry) => void;
-    /** Callback for cache break detection Phase 1.
+    /** Callback for cache break detection.
      *  Called with the API-ready payload AFTER any cache injection. */
     onPayloadForCacheDetection?: (params: Record<string, unknown>, model: {
         id: string;