comisai 1.0.36 → 1.0.37

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

@@ -16,8 +16,9 @@ import type { AgentSession } from "@mariozechner/pi-coding-agent";
 import type { CacheRetention } from "@mariozechner/pi-ai";
 import { type SessionKey, type NormalizedMessage, type PerAgentConfig, type TypedEventBus, type MemoryPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
+import { drainAt, markRead, markConsumed, formatDrainKey, type DrainKey, type DrainInflightState } from "./drain-helper.js";
 import type { ActiveRunRegistry } from "./active-run-registry.js";
-import type { ComisSessionManager } from "../session/comis-session-manager.js";
+import type { ComisSessionManager, SessionMetadata } from "../session/comis-session-manager.js";
 import type { ExecutionResult, ExecutionOverrides } from "./types.js";
 import type { ExecutionPlan } from "../planner/types.js";
 import type { ContextEngine } from "../context-engine/index.js";
@@ -53,11 +54,11 @@ export interface PostExecutionBridgeResult {
     cacheWrite5mTokens?: number;
     /** Estimated 1h TTL cache write tokens from TTL split data. */
     cacheWrite1hTokens?: number;
-    /** 1.3: Session-cumulative total cost across all turns (USD). */
+    /** Session-cumulative total cost across all turns (USD). */
     sessionCostUsd?: number;
-    /** 1.3: Session-cumulative cache savings across all turns (USD). */
+    /** Session-cumulative cache savings across all turns (USD). */
     sessionCacheSavedUsd?: number;
-    /** 1.5: Thinking tokens from SDK reasoningTokens field. */
+    /** Thinking tokens from SDK reasoningTokens field. */
     thinkingTokens?: number;
     /** Number of pre-LLM-call hash-assertion walks performed (one per turn_start). */
     hashAssertionsRan?: number;
@@ -74,6 +75,19 @@ export interface PostExecutionBridgeResult {
 /** Bridge interface used by post-execution. */
 export interface PostExecutionBridge {
     getResult(): PostExecutionBridgeResult;
+    /**
+     * Expose the bridge-owned drain inflight gate so postExecution can fire
+     * an end-of-turn backstop `drainAt(...)`. The bridge already drains on
+     * `tool_execution_end` for `message` actions (inline-consumption); the
+     * end-of-turn backstop closes the residual race for turns that never
+     * invoked the `message` tool but still need the inline-consumption
+     * queue flipped (NO_REPLY-only turns, sentinel passes, etc.).
+     *
+     * Both call sites share the SAME composite key gate map so concurrent
+     * drains for the same `(agentId, channelType, channelId)` triple
+     * collapse to a single in-flight Promise.
+     */
+    getDrainState(): DrainInflightState;
 }
 /** Parameters for postExecution(). */
 export interface PostExecutionParams {
@@ -86,6 +100,9 @@ export interface PostExecutionParams {
     msg: NormalizedMessage;
     sessionKey: SessionKey;
     formattedKey: string;
+    /** Resolver-aligned key for activeRunRegistry.deregister. Must match the
+     *  formula used at the corresponding register call site. */
+    resolverRegisterKey: string;
     agentId: string | undefined;
     executionStartMs: number;
     executionId: string;
@@ -182,6 +199,33 @@ export declare function shouldStorePairedMemory(userText: string, agentResponse:
 export declare function isDuplicatePairedMemory(content: string, agentId: string): boolean;
 /** Reset the paired-memory dedup cache. Exported for unit tests. */
 export declare function resetPairedMemoryDedupForTests(): void;
+/**
+ * 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 declare function buildSessionEndMetadata(args: {
+    finishReason: string;
+    durationMs: number;
+    totalTokens: number;
+    executionId: string;
+    traceId: string | undefined;
+}): SessionMetadata;
+export { drainAt, markRead, markConsumed, formatDrainKey, type DrainKey, type DrainInflightState, };
 /**
  * Run post-execution cleanup for a PiExecutor turn.
  *

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, provider, providerFamily, 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,
@@ -264,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
@@ -312,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,
@@ -339,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
@@ -383,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");
         }
@@ -433,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.

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,
@@ -321,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.
-    //
-    // 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
     // -------------------------------------------------------------------
@@ -368,6 +370,7 @@ export async function assembleTools(params) {
         mergedCustomTools,
         deferralResult,
         deferredContext,
+        capabilityIndexResult,
         deliveredGuides,
         modelTier,
         discoveryTracker,

package/node_modules/@comis/agent/dist/executor/jit-guide-injector.d.ts

@@ -35,10 +35,19 @@ import type { AgentToolResult } from "@mariozechner/pi-agent-core";
  *
  * - If no guide exists for the tool, returns result unchanged.
  * - If guide was already delivered in this session, returns result unchanged.
- * - Always marks the tool as delivered (even on error).
- * - Skips injection when result has isError: true (but still marks delivered).
+ * - Skips injection when result has isError: true and does NOT mark delivered
+ *   (so a retry can fire — see regression coverage in `jit-guide-injector.test.ts`).
  * - Logs at INFO level when guide is injected.
  *
+ * **Re-injection de-dup contract.** The `deliveredGuides` Set is the single
+ * source of truth for which guide ids have been injected within the current
+ * scope (per-session by default; cleared on session reset by pi-executor).
+ * Within a single turn — even when the same tool fires multiple times via
+ * mid-turn discovery / retries — the same guide id is not re-injected
+ * because the early-return on `deliveredGuides.has(...)` fires on the
+ * second-and-later check. The existing Set IS the per-turn (and per-session)
+ * tracker; no second data structure is needed.
+ *
  * Note: AgentToolResult does not formally include isError (it is set by
  * the agent-loop on the message level), but some tools (MCP, discovery)
  * include it at runtime. We check for it defensively.

package/node_modules/@comis/agent/dist/executor/jit-guide-injector.js

@@ -42,10 +42,19 @@ const PRIVILEGED_SECTION_KEY = "section:privileged";
  *
  * - If no guide exists for the tool, returns result unchanged.
  * - If guide was already delivered in this session, returns result unchanged.
- * - Always marks the tool as delivered (even on error).
- * - Skips injection when result has isError: true (but still marks delivered).
+ * - Skips injection when result has isError: true and does NOT mark delivered
+ *   (so a retry can fire — see regression coverage in `jit-guide-injector.test.ts`).
  * - Logs at INFO level when guide is injected.
  *
+ * **Re-injection de-dup contract.** The `deliveredGuides` Set is the single
+ * source of truth for which guide ids have been injected within the current
+ * scope (per-session by default; cleared on session reset by pi-executor).
+ * Within a single turn — even when the same tool fires multiple times via
+ * mid-turn discovery / retries — the same guide id is not re-injected
+ * because the early-return on `deliveredGuides.has(...)` fires on the
+ * second-and-later check. The existing Set IS the per-turn (and per-session)
+ * tracker; no second data structure is needed.
+ *
  * Note: AgentToolResult does not formally include isError (it is set by
  * the agent-loop on the message level), but some tools (MCP, discovery)
  * include it at runtime. We check for it defensively.
@@ -67,6 +76,11 @@ export function wrapToolResultWithGuide(toolName, result, deliveredGuides, logge
     const wantsPrivileged = PRIVILEGED_TOOL_SET.has(toolName) &&
         !deliveredGuides.has(PRIVILEGED_SECTION_KEY) &&
         !!SYSTEM_PROMPT_GUIDES["__privileged_tools__"];
+    // Re-injection de-dup: when every candidate guide id is already in
+    // `deliveredGuides`, none of `wantsTool`/`wantsSection`/`wantsPrivileged`
+    // is true and we early-return without appending. This single check is the
+    // per-turn (and per-session) de-dup gate — the same `deliveredGuides` Set
+    // passed across calls within a turn IS the injectedGuideIds tracker.
     if (!wantsTool && !wantsSection && !wantsPrivileged)
         return result;
     // Skip on error — but DO NOT consume delivery slots so a retry can fire.

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

@@ -21,7 +21,7 @@
  */
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
 import type { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
-import { type PerAgentConfig, type TypedEventBus, type MemoryPort, type HookRunner, type SecretManager, type EnvelopeConfig, type OutputGuardPort, type InputValidationResult, type InputSecurityGuard, type InjectionRateLimiter, type SenderTrustDisplayConfig } from "@comis/core";
+import { type PerAgentConfig, type TypedEventBus, type MemoryPort, type HookRunner, type SecretManager, type EnvelopeConfig, type OutputGuardPort, type InputValidationResult, type InputSecurityGuard, type InjectionRateLimiter, type SenderTrustDisplayConfig, type ToolCapabilityPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { AgentTool } from "@mariozechner/pi-agent-core";
 import type { BudgetGuard } from "../budget/budget-guard.js";
@@ -53,7 +53,7 @@ import type { AgentExecutor } from "./types.js";
  */
 export declare function createBeforeToolCallGuard(stepCounter: StepCounter, budgetGuard: BudgetGuard, circuitBreaker: CircuitBreaker, toolRetryBreaker?: ToolRetryBreaker, messageSendLimiter?: MessageSendLimiter): (context: unknown, _signal?: AbortSignal) => Promise<import("../safety/message-send-limiter.js").MessageSendVerdict | undefined>;
 /**
- * Merge SDK session stats into execution result for token totals (R-13).
+ * Merge SDK session stats into execution result for token totals.
  *
  * Token counts (input, output, cacheRead, cacheWrite, total) are sourced
  * from the SDK's cumulative session stats -- single source of truth.
@@ -169,6 +169,12 @@ export interface PiExecutorDeps {
     embeddingEnqueue?: (entryId: string, content: string) => void;
     /** Optional embedding port for semantic search in discover_tools. */
     embeddingPort?: import("@comis/core").EmbeddingPort;
+    /**
+     * Tool-capability port for the per-turn capability-index renderer.
+     * Daemon wiring injects createNoOpCapabilityPort() from @comis/core
+     * until the live adapter ships.
+     */
+    toolCapabilityPort: ToolCapabilityPort;
     /** Sender trust display config from AppConfig. */
     senderTrustDisplayConfig?: SenderTrustDisplayConfig;
     /** Documentation config from AppConfig. */