comisai 1.0.14 → 1.0.16

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

@@ -19,7 +19,7 @@ import { mergeSessionStats } from "./pi-executor.js";
 import { recordLastResponseTs } from "./ttl-guard.js";
 import { stripDiscoverySchemas } from "./schema-stripping.js";
 import { getWorkspaceStatus } from "../workspace/index.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -61,6 +61,69 @@ export function shouldStorePairedMemory(userText, agentResponse) {
         return false;
     return true;
 }
+/**
+ * Operation types that must NOT create paired memories.
+ *
+ * Cron and heartbeat executions are stateless and repetitive -- storing their
+ * prompts pollutes the vector space and degrades RAG recall for interactive
+ * conversations. Compaction / taskExtraction / condensation are system-internal
+ * operations that have their own dedicated memory paths (compaction summaries,
+ * extracted tasks) and should not additionally create paired conversation
+ * entries. Interactive and subagent are deliberately excluded.
+ */
+const MEMORY_SKIP_OPERATIONS = new Set([
+    "cron",
+    "heartbeat",
+    "compaction",
+    "taskExtraction",
+    "condensation",
+]);
+/**
+ * In-memory dedup cache for paired memory content.
+ *
+ * Defense-in-depth for interactive conversations where the user sends the same
+ * message multiple times (retries, reconnects). The Layer-1 operationType gate
+ * is the primary defense against cron/heartbeat duplication; this Layer-2 hash
+ * dedup catches residual duplicates that slip through.
+ *
+ * Keyed by a 64-bit truncation of sha256(agentId || content). Single-process
+ * daemon deployment (pm2, no cluster) means this cache is always complete.
+ */
+const DEDUP_TTL_MS = 10 * 60 * 1000;
+const DEDUP_MAX_ENTRIES = 500;
+const pairedMemoryDedup = new Map();
+/**
+ * Check whether paired memory content was stored recently for this agent.
+ *
+ * Exact-content hashing (not semantic similarity) -- targets the cron pattern
+ * of identical prompt + identical NO_REPLY response. Lazy eviction keeps the
+ * cache bounded without a timer.
+ *
+ * Exported for unit tests.
+ */
+export function isDuplicatePairedMemory(content, agentId) {
+    const now = Date.now();
+    if (pairedMemoryDedup.size > DEDUP_MAX_ENTRIES) {
+        for (const [key, ts] of pairedMemoryDedup) {
+            if (now - ts > DEDUP_TTL_MS)
+                pairedMemoryDedup.delete(key);
+        }
+    }
+    const hash = createHash("sha256")
+        .update(agentId)
+        .update(content)
+        .digest("hex")
+        .slice(0, 16);
+    const existing = pairedMemoryDedup.get(hash);
+    if (existing != null && now - existing <= DEDUP_TTL_MS)
+        return true;
+    pairedMemoryDedup.set(hash, now);
+    return false;
+}
+/** Reset the paired-memory dedup cache. Exported for unit tests. */
+export function resetPairedMemoryDedupForTests() {
+    pairedMemoryDedup.clear();
+}
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
@@ -292,38 +355,65 @@ export async function postExecution(params) {
     // Pairing user message with agent response creates entries that carry enough
     // context for meaningful RAG retrieval. Standalone user messages like "Hello"
     // or "you choose" have no semantic value without the agent's response.
-    // Runs for ALL execution paths: gateway, channels, cron.
+    //
+    // Two-layer dedup defense:
+    //   Layer 1: operationType gate -- skip cron/heartbeat/system-internal ops
+    //            which are stateless/repetitive and would pollute the vector
+    //            space with near-identical entries.
+    //   Layer 2: content-hash dedup -- safety net for interactive retries.
+    //
     // Non-blocking, non-fatal -- execution never fails due to memory store errors.
-    if (deps.memoryPort && result.response && msg.text && shouldStorePairedMemory(msg.text, result.response)) {
-        try {
-            const now = Date.now();
-            const userEntryId = randomUUID();
-            const pairedContent = buildPairedMemoryContent(msg.text, result.response);
-            const userStoreResult = await deps.memoryPort.store({
-                id: userEntryId,
-                tenantId: sessionKey.tenantId,
-                agentId: agentId ?? "default",
-                userId: sessionKey.userId,
-                content: pairedContent,
-                trustLevel: "learned",
-                source: { who: sessionKey.userId, channel: msg.channelType ?? "unknown" },
-                tags: ["conversation", "paired"],
-                createdAt: now,
-            });
-            if (!userStoreResult.ok) {
-                deps.logger.warn({ err: userStoreResult.error.message, hint: "Check database connectivity and disk space", errorKind: "dependency" }, "Memory store failed for user message");
+    const operationType = params.executionOverrides?.operationType;
+    const skipMemoryForOperation = operationType != null && MEMORY_SKIP_OPERATIONS.has(operationType);
+    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");
+        }
+        else {
+            try {
+                const userEntryId = randomUUID();
+                const userStoreResult = await deps.memoryPort.store({
+                    id: userEntryId,
+                    tenantId: sessionKey.tenantId,
+                    agentId: effectiveAgentId,
+                    userId: sessionKey.userId,
+                    content: pairedContent,
+                    trustLevel: "learned",
+                    source: {
+                        who: sessionKey.userId,
+                        channel: msg.channelType ?? "unknown",
+                        sessionKey: formattedKey,
+                    },
+                    tags: ["conversation", "paired"],
+                    createdAt: now,
+                });
+                if (!userStoreResult.ok) {
+                    deps.logger.warn({ err: userStoreResult.error.message, hint: "Check database connectivity and disk space", errorKind: "dependency" }, "Memory store failed for user message");
+                }
+                else if (deps.embeddingEnqueue) {
+                    deps.embeddingEnqueue(userEntryId, pairedContent);
+                }
             }
-            else if (deps.embeddingEnqueue) {
-                deps.embeddingEnqueue(userEntryId, pairedContent);
+            catch {
+                // Memory storage failure is non-fatal -- errors already logged per-entry
             }
         }
-        catch {
-            // Memory storage failure is non-fatal -- errors already logged per-entry
-        }
     }
     else if (deps.memoryPort && result.response && msg.text) {
-        // Quality gate filtered this turn -- log for observability
-        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");
+        // Memory not stored -- distinguish the two skip reasons for observability.
+        if (skipMemoryForOperation) {
+            deps.logger.debug({ operationType, sessionKey: formattedKey }, "Paired memory skipped: non-interactive operation type");
+        }
+        else {
+            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
     if (deps.activeRunRegistry) {

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

@@ -37,6 +37,7 @@ export interface PromptRunnerBridge {
             output?: number;
         };
         stepsExecuted?: number;
+        toolCallHistory?: string[];
     };
 }
 /** Parameters for runPrompt(). */

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

@@ -515,6 +515,17 @@ export async function runPrompt(params) {
             if (plan) {
                 executionPlanRef.current = plan;
                 deps.logger.debug({ agentId }, "SEP plan extracted (post-loop fallback)");
+                // Inline backfill: post-loop extraction means no mid-loop step tracking
+                // ran, so completedCount is stuck at 0 and the nudge cannot fire. Use
+                // the bridge's recorded tool history as a proxy for work done and mark
+                // the first N steps as "done" (N = min(toolHistoryLen, stepCount)).
+                // Tool-to-step attribution is advisory/observability only; over-counting
+                // is strictly better than the 0/N deadlock.
+                const toolHistoryLen = bridge.getResult().toolCallHistory?.length ?? 0;
+                const doneCount = Math.min(toolHistoryLen, plan.steps.length);
+                for (let i = 0; i < doneCount; i++)
+                    plan.steps[i].status = "done";
+                plan.completedCount = doneCount;
             }
         }
         if (sepEnabled && !executionPlanRef.current && extractedResponse && toolCallCount === 0) {
@@ -676,11 +687,12 @@ export async function runPrompt(params) {
                 // Estimated cache write cost for the system prompt portion.
                 // System prompt is sent as cacheable prefix; on first request it incurs cache write cost.
                 const estimatedCacheWriteTokens = Math.ceil(sysPromptChars / CHARS_PER_TOKEN_RATIO);
-                const pricing = resolveModelPricing(config.provider, config.model);
+                const effectiveModelId = resolvedModel?.id ?? config.model;
+                const pricing = resolveModelPricing(config.provider, effectiveModelId);
                 if (pricing.input === 0) {
                     deps.logger.warn({
                         provider: config.provider,
-                        model: config.model,
+                        model: effectiveModelId,
                         hint: "Model not found in pricing catalog; timeout cost estimate is $0 -- actual provider billing may differ",
                         errorKind: "config",
                     }, "Unknown model for timeout cost estimation");
@@ -699,7 +711,7 @@ export async function runPrompt(params) {
                     channelId: msg.channelId,
                     executionId,
                     provider: config.provider,
-                    model: config.model,
+                    model: effectiveModelId,
                     tokens: {
                         prompt: estimatedPromptTokens,
                         completion: 0,
@@ -717,7 +729,7 @@ export async function runPrompt(params) {
                     cacheWriteTokens: estimatedCacheWriteTokens,
                     sessionKey: formatSessionKey(sessionKey),
                     savedVsUncached: 0,
-                    cacheEligible: getCacheProviderInfo(config.provider).cacheEligible,
+                    cacheEligible: getCacheProviderInfo(config.provider, effectiveModelId).cacheEligible,
                 });
                 // Include ghost cost estimate in result for bridge accumulation
                 ghostCost = pricing.input > 0 ? {

package/node_modules/@comis/agent/dist/executor/executor-stream-setup.js

@@ -29,8 +29,9 @@
 import { safePath, } from "@comis/core";
 import { createToolResultSizeBouncer, createTurnResultBudgetWrapper, createConfigResolver, createCacheTraceWriter, createApiPayloadTraceWriter, createRequestBodyInjector, createValidationErrorFormatter, } from "./stream-wrappers/index.js";
 import { resolveToolCallingTemperature } from "./tool-deferral.js";
+import { createStubFilterInjector } from "./stream-wrappers/stub-filter-injector.js";
 import { computeFeatureFlagHash } from "./prompt-assembly.js";
-import { createTtlGuard, getElapsedSinceLastResponse } from "./ttl-guard.js";
+import { createTtlGuard, getElapsedSinceLastResponse, getLastResponseTs } from "./ttl-guard.js";
 import { isAnthropicFamily, isGoogleFamily } from "../provider/capabilities.js";
 import { createGeminiCacheInjector } from "./gemini-cache-injector.js";
 import { extractAnthropicPromptState, extractGeminiPromptState } from "./cache-break-detection.js";
@@ -142,6 +143,8 @@ export function setupStreamWrappers(params) {
         parentCacheRetention: executionOverrides?.spawnPacket?.cacheSafeParams?.cacheRetention,
         getCacheFenceIndex: () => getBreakpointIndex(formattedKey) ?? -1,
         getElapsedSinceLastResponse: () => getElapsedSinceLastResponse(formattedKey),
+        getLastResponseTs: () => getLastResponseTs(formattedKey),
+        promoteRecentZoneOnSlowCadence: config.advancedCacheOptimization?.enableRecentZonePromotion ?? true,
         observationKeepWindow: 25,
         microcompactTokenCeiling: 180_000,
         onContentModification: () => cacheBreakDetector.notifyContentModification(formattedKey),
@@ -231,6 +234,19 @@ export function setupStreamWrappers(params) {
             deps.logger.info({ outputDir, cacheTracePath, apiPayloadPath }, "JSONL tracing enabled");
         }
     }
+    // MUST be the last wrapper pushed (innermost). Runs its onPayload FIRST in
+    // the chain so all downstream wrappers operate on stub-free tools. Violating
+    // this ordering would (a) include stub schemas in the Anthropic rendered-tool
+    // cache hash, (b) persist stubs into the Gemini CachedContent entry for its
+    // whole lifetime, and (c) cause deferCount > 0 in the DEFER-TOOL block,
+    // unintentionally flipping Anthropic sessions to server-side tool_search.
+    wrappers.push(createStubFilterInjector({
+        getStubToolNames: () => {
+            if (!deferralResult?.deferredEntries.length)
+                return new Set();
+            return new Set(deferralResult.deferredEntries.map(e => e.name));
+        },
+    }, deps.logger));
     return {
         wrappers,
         contextEngineRef,

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

@@ -15,7 +15,7 @@
  */
 import { SettingsManager, } from "@mariozechner/pi-coding-agent";
 import { formatSessionKey, } from "@comis/core";
-import { applyToolDeferral, buildDeferredToolsContext, extractRecentlyUsedToolNames, resolveModelTier, CORE_TOOLS } from "./tool-deferral.js";
+import { applyToolDeferral, buildDeferredToolsContext, createDiscoverTool, createAutoDiscoveryStubs, extractRecentlyUsedToolNames, resolveModelTier, CORE_TOOLS } from "./tool-deferral.js";
 import { getOrCreateDiscoveryTracker } from "./discovery-tracker.js";
 import { getOrCreateTracker, DEFAULT_LIFECYCLE_CONFIG } from "./tool-lifecycle.js";
 import { isAnthropicFamily, isGoogleFamily } from "../provider/capabilities.js";
@@ -169,6 +169,8 @@ export async function assembleTools(params) {
         resolvedModelId: resolvedModel?.id,
         resolvedModelProvider: resolvedModel?.provider,
         resolvedModelReasoning: resolvedModel?.reasoning,
+        // "interactive" default guards the optional overrides; mirrors pi-executor.ts:1077.
+        operationType: executionOverrides?.operationType ?? "interactive",
     });
     // -------------------------------------------------------------------
     // 5. System token estimate
@@ -287,10 +289,36 @@ export async function assembleTools(params) {
             : undefined,
     };
     const deferralResult = applyToolDeferral(mergedCustomTools, contextWindow, deferralCtx, deps.logger, deps.embeddingPort, config.skills?.toolDiscovery);
+    // Rebuild discover_tools with the now-known active set so it can answer
+    // "already active" queries correctly. Post-deferral set (active +
+    // 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
+    if (deferralResult.discoverTool) {
+        const activeAfterDeferral = new Set([
+            ...deferralResult.activeTools.map(t => t.name),
+            ...deferralResult.discoveredTools.map(t => t.name),
+        ]);
+        deferralResult.discoverTool = createDiscoverTool(deferralResult.deferredEntries, deps.logger, deps.embeddingPort, config.skills?.toolDiscovery, activeAfterDeferral);
+    }
     mergedCustomTools = [...deferralResult.activeTools, ...deferralResult.discoveredTools];
     if (deferralResult.discoverTool) {
         mergedCustomTools.push(deferralResult.discoverTool);
     }
+    // 7b. Auto-discovery stubs for deferred tools.
+    // Lightweight stubs so the SDK's agent-loop finds deferred tools during
+    // tool resolution. Prevents "Tool X not found" errors when skills
+    // reference deferred MCP tools directly. Stubs are filtered from the
+    // API request by createStubFilterInjector (see stream-wrappers/
+    // stub-filter-injector.ts) -- zero token cost guarantee.
+    // Position: BEFORE JIT guide wrapping / schema pruning / sideEffects
+    // wrapping -- stubs receive all downstream wrappers automatically.
+    if (deferralResult.deferredEntries.length > 0) {
+        const stubs = createAutoDiscoveryStubs(deferralResult.deferredEntries, discoveryTracker, deps.logger);
+        mergedCustomTools.push(...stubs);
+    }
     // Build deferred context for dynamic preamble injection
     let deferredContext = "";
     if (deferralResult.deferredEntries.length > 0) {

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

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { SessionKey, NormalizedMessage, PerAgentConfig, MemoryPort, HookRunner, SecretManager, EnvelopeConfig, WrapExternalContentOptions, TypedEventBus, SenderTrustDisplayConfig, SpawnPacket, DeliveryMirrorPort } from "@comis/core";
+import type { SessionKey, NormalizedMessage, PerAgentConfig, MemoryPort, HookRunner, SecretManager, EnvelopeConfig, WrapExternalContentOptions, TypedEventBus, SenderTrustDisplayConfig, SpawnPacket, DeliveryMirrorPort, ModelOperationType } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
 import type { BootstrapContextFile } from "../bootstrap/types.js";
@@ -151,6 +151,13 @@ export interface PromptAssemblyParams {
     /** Whether the resolved model has native reasoning support (e.g. encrypted thinking blocks).
      *  When true, the `<think>`/`<final>` tag hint is suppressed to avoid double-reasoning. */
     resolvedModelReasoning?: boolean;
+    /** Operation type from ExecutionOverrides. Resolves promptMode and bootstrap filter.
+     *  When omitted by callers at the TypeScript level, executor-tool-assembly supplies
+     *  "interactive" as the default before invoking this function, so this is required
+     *  at the call-site contract level. Values of "cron" or "heartbeat" auto-upgrade
+     *  the promptMode from "full" to "operational" and dispatch operation-specific
+     *  bootstrap filters. */
+    operationType: ModelOperationType;
 }
 /**
  * Assemble the full system prompt for a PiExecutor execution cycle.

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

@@ -12,7 +12,7 @@
 import * as fs from "node:fs/promises";
 import { wrapExternalContent, safePath, formatSessionKey, generateCanaryToken } from "@comis/core";
 import { suppressError } from "@comis/shared";
-import { loadWorkspaceBootstrapFiles, buildBootstrapContextFiles, assembleRichSystemPrompt, assembleRichSystemPromptBlocks, filterBootstrapFilesForLightContext, filterBootstrapFilesForGroupChat, resolveSenderDisplay, buildDateTimeSection, buildInboundMetadataSection, buildSenderTrustSection, buildSubagentRoleSection, // for dynamic preamble injection
+import { loadWorkspaceBootstrapFiles, buildBootstrapContextFiles, assembleRichSystemPrompt, assembleRichSystemPromptBlocks, filterBootstrapFilesForLightContext, filterBootstrapFilesForCron, filterBootstrapFilesForGroupChat, resolveSenderDisplay, buildDateTimeSection, buildInboundMetadataSection, buildSenderTrustSection, buildSubagentRoleSection, // for dynamic preamble injection
 buildVerbosityHintSection, resolveVerbosityProfile, } from "../bootstrap/index.js";
 import { deduplicateResults } from "../rag/rag-retriever.js";
 import { createHybridMemoryInjector } from "../rag/hybrid-memory-injector.js";
@@ -320,7 +320,19 @@ export async function assembleExecutionPrompt(params) {
         return { systemPrompt: parentCache.frozenSystemPrompt, systemPromptBlocks: parentCache.frozenSystemPromptBlocks, dynamicPreamble, inlineMemory: undefined };
     }
     // 1. Resolve promptMode
-    const promptMode = config.bootstrap?.promptMode ?? "full";
+    // Cron and heartbeat auto-upgrade from "full" -> "operational" to trim
+    // interactive-only sections (compaction recovery, silent replies, reactions,
+    // media, SEP, sender trust). An explicit `config.bootstrap?.promptMode` wins
+    // -- operators can still force "minimal"/"none"/"full" if they have reason.
+    const baseMode = config.bootstrap?.promptMode ?? "full";
+    const promptMode = (params.operationType === "cron" || params.operationType === "heartbeat") && baseMode === "full"
+        ? "operational"
+        : baseMode;
+    // Consolidated lightContext flag: heartbeat implies light-context regardless
+    // of the explicit msg.metadata.lightContext flag. Callers that only set the
+    // metadata flag OR only set operationType="heartbeat" produce identical
+    // prompt output (design-doc §Risks: "Heartbeat lightContext and operationType drift").
+    const effectiveLightContext = msg.metadata?.lightContext === true || params.operationType === "heartbeat";
     // 2. Load workspace bootstrap files (skip for "none" mode)
     let bootstrapContextFiles = [];
     if (promptMode !== "none") {
@@ -337,11 +349,16 @@ export async function assembleExecutionPrompt(params) {
             bootstrapFiles = await loadWorkspaceBootstrapFiles(deps.workspaceDir, bootstrapMaxChars);
             sessionBootstrapFileSnapshots.set(bsSnapKey, bootstrapFiles);
         }
-        // Heartbeat light context -- keep only HEARTBEAT.md
-        if (msg.metadata?.lightContext === true) {
+        // Bootstrap filter dispatch:
+        //  - effectiveLightContext (heartbeat / explicit flag) -> HEARTBEAT.md only
+        //  - operationType === "cron" -> SOUL.md + ROLE.md only
+        //  - group chat context -> strip USER.md for privacy
+        if (effectiveLightContext) {
             bootstrapFiles = filterBootstrapFilesForLightContext(bootstrapFiles);
         }
-        // Group chat privacy -- exclude USER.md
+        else if (params.operationType === "cron") {
+            bootstrapFiles = filterBootstrapFilesForCron(bootstrapFiles);
+        }
         else if (config.bootstrap?.groupChatFiltering !== false &&
             isGroupContext(msg)) {
             bootstrapFiles = filterBootstrapFilesForGroupChat(bootstrapFiles);

package/node_modules/@comis/agent/dist/executor/session-snapshot-cleanup.js

@@ -20,7 +20,7 @@ import { clearSessionTracker } from "./tool-lifecycle.js";
 import { clearDiscoveryTracker } from "./discovery-tracker.js";
 import { clearCacheBreakDetectorSession } from "./cache-break-detection.js";
 import { clearSessionLastResponseTs } from "./ttl-guard.js";
-import { clearSessionBetaHeaderLatches } from "./stream-wrappers/request-body-injector.js";
+import { clearSessionBetaHeaderLatches, clearSessionPrefixStability, clearSessionCadenceTracker } from "./stream-wrappers/request-body-injector.js";
 import { clearSessionRenderedToolCache, clearSessionPerToolCache } from "./stream-wrappers/tool-schema-cache.js";
 import { clearSessionBlockStability } from "./block-stability-tracker.js";
 /**
@@ -49,6 +49,8 @@ export function clearSessionState(formattedKey) {
     clearSessionBlockStability(formattedKey);
     clearSessionEvictionCooldown(formattedKey);
     clearSessionCacheSavings(formattedKey);
+    clearSessionPrefixStability(formattedKey);
+    clearSessionCadenceTracker(formattedKey);
 }
 /**
  * Subscribe to `session:expired` on the provided event bus and clean up

package/node_modules/@comis/agent/dist/executor/stream-wrappers/index.d.ts

@@ -24,3 +24,5 @@ export { createRequestBodyInjector, addCacheControlToLastBlock, CACHEABLE_BLOCK_
 export type { RequestBodyInjectorConfig } from "./request-body-injector.js";
 export { sessionRenderedToolCache, getOrCacheRenderedTool, clearSessionRenderedToolCache, clearSessionPerToolCache, } from "./tool-schema-cache.js";
 export type { RenderedToolCacheEntry, PerToolCacheEntry } from "./tool-schema-cache.js";
+export { createStubFilterInjector } from "./stub-filter-injector.js";
+export type { StubFilterInjectorConfig } from "./stub-filter-injector.js";

package/node_modules/@comis/agent/dist/executor/stream-wrappers/index.js

@@ -20,3 +20,5 @@ export { createApiPayloadTraceWriter } from "./api-payload-trace-writer.js";
 export { createRequestBodyInjector, addCacheControlToLastBlock, CACHEABLE_BLOCK_TYPES, getMinCacheableTokens, resolveCacheRetention, clearSessionBetaHeaderLatches, } from "./request-body-injector.js";
 // Tool schema cache extracted to leaf module
 export { sessionRenderedToolCache, getOrCacheRenderedTool, clearSessionRenderedToolCache, clearSessionPerToolCache, } from "./tool-schema-cache.js";
+// Stub filter injector (auto-discovery stubs)
+export { createStubFilterInjector } from "./stub-filter-injector.js";

package/node_modules/@comis/agent/dist/executor/stream-wrappers/request-body-injector.d.ts

@@ -105,6 +105,14 @@ export interface RequestBodyInjectorConfig {
     /** Getter for elapsed ms since last assistant response.
      *  Used for time-based microcompact to detect cold-start scenarios. */
     getElapsedSinceLastResponse?: () => number | undefined;
+    /** When true, the recent-zone message breakpoint may be promoted from
+     *  "short" to "long" TTL based on observed inter-turn timing.
+     *  Requires sessionKey, getElapsedSinceLastResponse, AND getLastResponseTs. */
+    promoteRecentZoneOnSlowCadence?: boolean;
+    /** Getter for the raw `sessionLastResponseTs.ts` value (ms since epoch)
+     *  for this session, or undefined on cold-start. Used by the cadence
+     *  tracker to detect turn boundaries within a single execute(). */
+    getLastResponseTs?: () => number | undefined;
     /** Number of recent tool results to preserve during microcompact.
      *  Defaults to 25 (matches observation masker keep window). */
     observationKeepWindow?: number;
@@ -141,6 +149,7 @@ export { clearSessionRenderedToolCache, getOrCacheRenderedTool, clearSessionPerT
 export type { RenderedToolCacheEntry } from "./tool-schema-cache.js";
 export declare function clearSessionPrefixStability(sessionKey: string): void;
 export declare function clearSessionBetaHeaderLatches(sessionKey: string): void;
+export declare function clearSessionCadenceTracker(sessionKey: string): void;
 /**
  * Resolve effective cache retention for a model, considering per-model overrides.
  * Uses longest-prefix-first matching: "claude-sonnet-4-6" wins over "claude-sonnet".

package/node_modules/@comis/agent/dist/executor/stream-wrappers/request-body-injector.js

@@ -43,6 +43,13 @@ export function clearSessionPrefixStability(sessionKey) {
 export function clearSessionBetaHeaderLatches(sessionKey) {
     sessionBetaHeaderLatches.delete(sessionKey);
 }
+const sessionCadenceTracker = new Map();
+export function clearSessionCadenceTracker(sessionKey) {
+    sessionCadenceTracker.delete(sessionKey);
+}
+const SLOW_CADENCE_PROMOTION_THRESHOLD = 3;
+const FAST_CADENCE_DEMOTION_THRESHOLD = 5;
+const SLOW_CADENCE_MS = 5 * 60 * 1000; // 5 minutes
 // ---------------------------------------------------------------------------
 // Per-model cache retention override resolution.
 // Enables selectively disabling or changing prompt caching for specific model
@@ -402,7 +409,17 @@ function placeCacheBreakpoints(messages, options) {
         const startFrom = semiStableIdx >= 0 ? semiStableIdx + 1 : 0;
         const tokensInRange = estimateTokensInRange(startFrom, secondToLastUserIdx);
         if (tokensInRange >= minTokens) {
-            addCacheControlToLastBlock(messages[secondToLastUserIdx], retention);
+            // Promote recent-zone to "long" when cadence indicates user pauses exceed 5m.
+            // Monotonicity guard: recent zone can only be promoted when
+            // resolvedRetention (tool/system) is already "long".
+            let recentRetention = retention;
+            if (options.promoteRecentZoneOnSlowCadence && options.sessionKey) {
+                const cadence = sessionCadenceTracker.get(options.sessionKey);
+                if (cadence?.promoted && resolvedRetention === "long") {
+                    recentRetention = "long";
+                }
+            }
+            addCacheControlToLastBlock(messages[secondToLastUserIdx], recentRetention);
             placed++;
         }
     }
@@ -434,7 +451,7 @@ function placeCacheBreakpoints(messages, options) {
     // The Anthropic API uses a 20-block lookback window for cache prefix matching.
     // If any gap exceeds the window and slots remain, place a bridging breakpoint
     // at the midpoint of the gap to prevent silent cache misses.
-    if (placed > 0 && placed < Math.min(maxBreakpoints, 3)) {
+    if (placed > 0 && placed < maxBreakpoints) {
         const breakpointPositions = [];
         for (let i = 0; i < messages.length; i++) {
             const content = messages[i].content;
@@ -448,7 +465,7 @@ function placeCacheBreakpoints(messages, options) {
             }
         }
         // Check gaps between consecutive breakpoints
-        for (let g = 1; g < breakpointPositions.length && placed < Math.min(maxBreakpoints, 3); g++) {
+        for (let g = 1; g < breakpointPositions.length && placed < maxBreakpoints; g++) {
             const gap = breakpointPositions[g] - breakpointPositions[g - 1];
             if (gap > CACHE_LOOKBACK_WINDOW) {
                 // Find a user message near the midpoint of the gap
@@ -1338,6 +1355,8 @@ export function createRequestBodyInjector(config, logger) {
                                 resolvedRetention: inCooldown ? "short" : messageRetention, // Force "short" during cooldown
                                 strategy: resolveBreakpointStrategy(config.cacheBreakpointStrategy, model.provider),
                                 skipCacheWrite: effectiveSkipCacheWrite,
+                                promoteRecentZoneOnSlowCadence: config.promoteRecentZoneOnSlowCadence,
+                                sessionKey: config.sessionKey,
                             });
                             if (placed > 0) {
                                 logger.debug({
@@ -1478,6 +1497,49 @@ export function createRequestBodyInjector(config, logger) {
                     if (config.onPayloadForCacheDetection) {
                         config.onPayloadForCacheDetection(result, model, mergedHeaders);
                     }
+                    // Track cadence for recent-zone promotion (symmetric: promote slow, demote on fast).
+                    // Runs after onPayloadForCacheDetection so the detection snapshot reflects the
+                    // pre-mutation state. Mutation takes effect on the next turn's placeCacheBreakpoints().
+                    if (config.promoteRecentZoneOnSlowCadence && config.sessionKey
+                        && config.getElapsedSinceLastResponse && config.getLastResponseTs) {
+                        const lastResponseTs = config.getLastResponseTs();
+                        if (lastResponseTs !== undefined) {
+                            let tracker = sessionCadenceTracker.get(config.sessionKey);
+                            if (!tracker) {
+                                tracker = {
+                                    consecutiveSlowTurns: 0,
+                                    consecutiveFastTurns: 0,
+                                    promoted: false,
+                                    lastObservedResponseTs: undefined,
+                                };
+                                sessionCadenceTracker.set(config.sessionKey, tracker);
+                            }
+                            // Same-turn guard: successive onPayload calls inside one execute() all
+                            // observe the same lastResponseTs. Only count once per turn boundary.
+                            if (lastResponseTs !== tracker.lastObservedResponseTs) {
+                                tracker.lastObservedResponseTs = lastResponseTs;
+                                const elapsed = config.getElapsedSinceLastResponse();
+                                if (elapsed !== undefined) {
+                                    if (elapsed > SLOW_CADENCE_MS) {
+                                        tracker.consecutiveSlowTurns++;
+                                        tracker.consecutiveFastTurns = 0;
+                                        if (!tracker.promoted && tracker.consecutiveSlowTurns >= SLOW_CADENCE_PROMOTION_THRESHOLD) {
+                                            tracker.promoted = true;
+                                            logger.info({ sessionKey: config.sessionKey, consecutiveSlowTurns: tracker.consecutiveSlowTurns }, "Recent-zone TTL promoted to long: slow cadence detected");
+                                        }
+                                    }
+                                    else {
+                                        tracker.consecutiveFastTurns++;
+                                        tracker.consecutiveSlowTurns = 0;
+                                        if (tracker.promoted && tracker.consecutiveFastTurns >= FAST_CADENCE_DEMOTION_THRESHOLD) {
+                                            tracker.promoted = false;
+                                            logger.info({ sessionKey: config.sessionKey, consecutiveFastTurns: tracker.consecutiveFastTurns }, "Recent-zone TTL demoted to short: fast cadence resumed");
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
                     // SDK-UPGRADE: Upgrade SDK auto-placed 5m markers to 1h when retention is long.
                     // The pi-ai SDK places cache_control: { type: "ephemeral" } (5m TTL) on the last
                     // user message. When the session uses "long" retention, these 5m writes waste money

package/node_modules/@comis/agent/dist/executor/stream-wrappers/stub-filter-injector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stub-filter injector stream wrapper.
+ *
+ * Removes auto-discovery stub tools (see tool-deferral.ts createAutoDiscoveryStubs)
+ * from the API-ready payload. Stubs are present in the SDK's tools array so
+ * agent-loop.js tool lookup succeeds, but must not reach the API:
+ *  - They consume input tokens (~100 tokens per stub schema).
+ *  - For Anthropic models where supportsToolSearch() is true, unfiltered stub
+ *    names would match in the DEFER-TOOL block (request-body-injector.ts
+ *    lines 1599-1643), causing deferCount > 0 which REMOVES client-side
+ *    discover_tools and APPENDS server-side tool_search_tool_regex —
+ *    flipping the session to a different control path unintentionally.
+ *  - For Google AI Studio, unfiltered stubs would be persisted into the
+ *    Gemini CachedContent entry (gemini-cache-injector.ts line 191-195),
+ *    bloating the cache for its entire lifetime.
+ *
+ * Provider-agnostic: filters both top-level `params.tools` (Anthropic,
+ * OpenAI, xAI) and nested `params.config.tools` (Google AI Studio).
+ *
+ * @module
+ */
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./types.js";
+export interface StubFilterInjectorConfig {
+    /** Getter for stub tool names. Filtered from the rendered API payload. */
+    getStubToolNames: () => ReadonlySet<string>;
+}
+export declare function createStubFilterInjector(config: StubFilterInjectorConfig, logger: ComisLogger): StreamFnWrapper;