comisai 1.0.15 → 1.0.17

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;

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

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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
+ */
+export function createStubFilterInjector(config, logger) {
+    return function stubFilterInjector(next) {
+        return (model, context, options) => {
+            const existingOnPayload = options?.onPayload;
+            const enhancedOptions = {
+                ...options,
+                onPayload: async (payload, payloadModel) => {
+                    // Let any upstream onPayload run first (we are the innermost wrapper,
+                    // so upstream here is the SDK's own or a user-provided one).
+                    const resolvedParams = (existingOnPayload
+                        ? await Promise.resolve(existingOnPayload(payload, payloadModel))
+                        : payload);
+                    const stubNames = config.getStubToolNames();
+                    if (stubNames.size === 0)
+                        return resolvedParams;
+                    let removed = 0;
+                    // Top-level tools (Anthropic, OpenAI, xAI)
+                    if (Array.isArray(resolvedParams.tools)) {
+                        const before = resolvedParams.tools.length;
+                        resolvedParams.tools = resolvedParams.tools
+                            .filter(t => !stubNames.has(t.name));
+                        removed += before - resolvedParams.tools.length;
+                    }
+                    // Nested config.tools (Google AI Studio / Gemini)
+                    const cfg = resolvedParams.config;
+                    if (cfg && Array.isArray(cfg.tools)) {
+                        const before = cfg.tools.length;
+                        cfg.tools = cfg.tools
+                            .filter(t => !stubNames.has(t.name));
+                        removed += before - cfg.tools.length;
+                    }
+                    if (removed > 0) {
+                        logger.debug({ removed, provider: payloadModel?.provider }, "Stub filter removed auto-discovery stubs from payload");
+                    }
+                    return resolvedParams;
+                },
+            };
+            return next(model, context, enhancedOptions);
+        };
+    };
+}

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

@@ -50,6 +50,11 @@ export interface DeferralContext {
      *  "default") do not inject mid-turn, so MCP tools must be active from the
      *  start. When undefined, defaults to deferring (backward compat). */
     providerFamily?: string;
+    /** Names of tools currently ACTIVE in this session (post-deferral).
+     *  Consumed by discover_tools to return "already active" guidance when
+     *  queries re-ask for loaded MCPs. Must NOT include names that were
+     *  deferred -- pass the post-deferral set, not mergedCustomTools. */
+    activeToolNames?: ReadonlySet<string>;
 }
 /** Entry describing a deferred tool with its display description and original definition. */
 export interface DeferredToolEntry {
@@ -153,7 +158,19 @@ export interface ToolDiscoveryScoreConfig {
  * Receives DeferredToolEntry[] (with original schemas and display descriptions)
  * so it can serve full schemas and lean descriptions when queried.
  *
+ * BM25 scores are normalized to [0, 1] (fraction of top match) BEFORE the
+ * score-floor filter applies, matching the semantics of hybrid-mode scoring.
+ * This ensures the top match always clears any floor <= 1.0 whenever any
+ * positive signal exists (fixes the srv1593437 08:06:39Z "install MCP"
+ * regression where raw BM25 ~0.74 was dropped by the 0.8 raw-score floor).
+ *
  * @param scoreConfig Optional score-floor override (defaults to 0.8 BM25 /
  *   0.35 hybrid). Zero or negative floors disable the filter.
+ * @param activeToolNames Names of tools currently ACTIVE in this session
+ *   (post-deferral: active + discovered). Used to return "already active"
+ *   guidance when queries re-ask for loaded MCPs. Must NOT include names
+ *   that were deferred. Default empty set keeps callers backward-compatible.
  */
-export declare function createDiscoverTool(deferredEntries: DeferredToolEntry[], logger: ComisLogger, embeddingPort?: EmbeddingPort, scoreConfig?: ToolDiscoveryScoreConfig): ToolDefinition;
+export declare function createDiscoverTool(deferredEntries: DeferredToolEntry[], logger: ComisLogger, embeddingPort?: EmbeddingPort, scoreConfig?: ToolDiscoveryScoreConfig, activeToolNames?: ReadonlySet<string>): ToolDefinition;
+export declare const DEFERRAL_STUB_MARKER: "__comis_deferral_stub__";
+export declare function createAutoDiscoveryStubs(deferredEntries: DeferredToolEntry[], discoveryTracker: DiscoveryTracker, logger: ComisLogger): ToolDefinition[];