comisai 1.0.14 → 1.0.16

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[];

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

@@ -302,9 +302,14 @@ export function applyToolDeferral(tools, _contextWindow, deferralContext, logger
             remainingDeferred.push(entry);
         }
     }
-    // Create discover_tools only when remaining deferred entries exist
+    // Create discover_tools only when remaining deferred entries exist.
+    // Thread active-tool names through so "already active" guidance works.
+    // NOTE: executor-tool-assembly.ts rebuilds this tool a second time with the
+    // post-deferral active set (active + discovered) since the final active set
+    // isn't known until after this function returns.
+    const activeNamesForDiscover = deferralContext.activeToolNames ?? new Set();
     const discoverTool = remainingDeferred.length > 0
-        ? createDiscoverTool(remainingDeferred, logger, embeddingPort, scoreConfig)
+        ? createDiscoverTool(remainingDeferred, logger, embeddingPort, scoreConfig, activeNamesForDiscover)
         : null;
     const deferredNames = [...deferredSet];
     // Log deferral
@@ -400,10 +405,20 @@ const DEFAULT_TOOL_DISCOVERY_SCORES = {
  * 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 function createDiscoverTool(deferredEntries, logger, embeddingPort, scoreConfig = DEFAULT_TOOL_DISCOVERY_SCORES) {
+export function createDiscoverTool(deferredEntries, logger, embeddingPort, scoreConfig = DEFAULT_TOOL_DISCOVERY_SCORES, activeToolNames = new Set()) {
     // Build ToolDefinition[] view for structuredSearch compatibility
     const deferredTools = deferredEntries.map(e => e.original);
     /**
@@ -436,14 +451,10 @@ export function createDiscoverTool(deferredEntries, logger, embeddingPort, score
         async execute(_toolCallId, params) {
             const p = params;
             const query = String(p.query ?? "");
-            // Try structured search first (deterministic modes)
+            // ---------- Path 1: structured deterministic modes ----------
             const structuredResults = structuredSearch(deferredTools, query, 10);
-            let matches;
-            let searchMode;
             if (structuredResults.length > 0) {
-                // Structured search matched -- skip BM25/embedding entirely
-                matches = structuredResults;
-                searchMode = query.toLowerCase().trim().startsWith("select:")
+                const searchMode = query.toLowerCase().trim().startsWith("select:")
                     ? "select"
                     : query.toLowerCase().trim().startsWith("mcp__") || query.toLowerCase().trim().startsWith("mcp:")
                         ? "prefix"
@@ -453,151 +464,248 @@ export function createDiscoverTool(deferredEntries, logger, embeddingPort, score
                     query,
                     searchMode,
                     candidateCount: deferredEntries.length,
-                    structuredMatchCount: matches.length,
-                    topMatch: matches[0]?.name ?? "none",
+                    structuredMatchCount: structuredResults.length,
+                    topMatch: structuredResults[0]?.name ?? "none",
                 }, "discover_tools search completed");
+                return formatDiscoveryResponse(structuredResults, deferredEntries);
             }
-            else {
-                // No structured match -- fall through to BM25 + optional embedding
-                const documents = deferredTools.map(t => ({
-                    name: t.name,
-                    text: resolveBM25Text(t),
-                }));
-                let ranked = bm25Score(query, documents);
-                // Optional: semantic re-ranking via EmbeddingPort
-                let embeddingUsed = false;
-                if (embeddingPort && ranked.length > 0) {
-                    try {
-                        const queryResult = await embeddingPort.embed(query);
-                        if (queryResult.ok) {
-                            const queryVec = queryResult.value;
-                            const textsToEmbed = ranked.map(r => {
-                                const doc = documents.find(d => d.name === r.name);
-                                return doc?.text ?? r.name;
-                            });
-                            const batchResult = await embeddingPort.embedBatch(textsToEmbed);
-                            if (batchResult.ok) {
-                                const docVecs = batchResult.value;
-                                const maxBm25 = ranked[0].score;
-                                const combined = ranked.map((r, i) => {
-                                    const bm25Norm = maxBm25 > 0 ? r.score / maxBm25 : 0;
-                                    const cosineSim = cosine(queryVec, docVecs[i]);
-                                    return { name: r.name, score: 0.5 * bm25Norm + 0.5 * cosineSim };
-                                });
-                                combined.sort((a, b) => b.score - a.score);
-                                ranked = combined;
-                                embeddingUsed = true;
-                            }
+            // ---------- Path 2: BM25 (+ optional hybrid) fallback ----------
+            const documents = deferredTools.map(t => ({
+                name: t.name,
+                text: resolveBM25Text(t),
+            }));
+            const rankedRaw = bm25Score(query, documents);
+            const rawTopScore = rankedRaw[0]?.score ?? 0;
+            // NORMALIZE UP FRONT -- both modes now operate in [0, 1] space.
+            // This makes `minBm25Score` semantically equivalent to `minHybridScore`:
+            // a fraction of the top match. After this step, ranked[0].score === 1.0
+            // whenever rawTopScore > 0, so the top match always clears any floor <= 1.0.
+            let ranked = rawTopScore > 0
+                ? rankedRaw.map(r => ({ name: r.name, score: r.score / rawTopScore }))
+                : rankedRaw.map(r => ({ name: r.name, score: 0 }));
+            // Optional: semantic re-ranking via EmbeddingPort
+            let embeddingUsed = false;
+            if (embeddingPort && ranked.length > 0) {
+                try {
+                    const queryResult = await embeddingPort.embed(query);
+                    if (queryResult.ok) {
+                        const queryVec = queryResult.value;
+                        const textsToEmbed = ranked.map(r => {
+                            const doc = documents.find(d => d.name === r.name);
+                            return doc?.text ?? r.name;
+                        });
+                        const batchResult = await embeddingPort.embedBatch(textsToEmbed);
+                        if (batchResult.ok) {
+                            const docVecs = batchResult.value;
+                            // `ranked` is already BM25-normalized; combine with cosine.
+                            // NO second normalization -- that would double-normalize and
+                            // change the scoring contract.
+                            const combined = ranked.map((r, i) => ({
+                                name: r.name,
+                                score: 0.5 * r.score + 0.5 * cosine(queryVec, docVecs[i]),
+                            }));
+                            combined.sort((a, b) => b.score - a.score);
+                            ranked = combined;
+                            embeddingUsed = true;
                         }
                     }
-                    catch (embeddingErr) {
-                        logger.warn({
-                            err: embeddingErr,
-                            hint: "discover_tools falling back to BM25-only search; check embedding provider",
-                            errorKind: "dependency",
-                        }, "discover_tools embedding re-ranking failed");
-                    }
                 }
-                // Score-floor filter: zero-signal queries produce spurious BM25
-                // matches (token overlap on common words) and cosine-noise in hybrid
-                // mode. Filter below the floor before slicing so "no matches" is
-                // reported honestly instead of surfacing misleading top-10 noise.
-                const floor = embeddingUsed ? scoreConfig.minHybridScore : scoreConfig.minBm25Score;
-                const rawTop = ranked[0];
-                const filtered = ranked.filter(r => r.score >= floor);
-                const topResults = filtered.slice(0, 10);
-                searchMode = embeddingUsed ? "hybrid" : "bm25";
-                logger.debug({
-                    toolName: "discover_tools",
-                    query,
-                    searchMode,
-                    candidateCount: deferredEntries.length,
-                    resultCount: topResults.length,
-                    topScore: topResults[0]?.score ?? 0,
-                    topMatch: topResults[0]?.name ?? "none",
-                    floor,
-                    filteredOut: ranked.length - filtered.length,
-                }, "discover_tools search completed");
-                if (topResults.length === 0) {
+                catch (embeddingErr) {
                     logger.warn({
+                        err: embeddingErr,
+                        hint: "discover_tools falling back to BM25-only search; check embedding provider health",
+                        errorKind: "dependency",
+                    }, "discover_tools embedding re-ranking failed");
+                }
+            }
+            // ---------- Floor check ----------
+            const floor = embeddingUsed ? scoreConfig.minHybridScore : scoreConfig.minBm25Score;
+            const normalizedTopScore = ranked[0]?.score ?? 0;
+            const filtered = ranked.filter(r => r.score >= floor);
+            const topResults = filtered.slice(0, 10);
+            const searchMode = embeddingUsed ? "hybrid" : "bm25";
+            logger.debug({
+                toolName: "discover_tools",
+                query,
+                searchMode,
+                candidateCount: deferredEntries.length,
+                resultCount: topResults.length,
+                normalizedTopScore,
+                rawTopScore,
+                topMatch: topResults[0]?.name ?? "none",
+                floor,
+                filteredOut: ranked.length - filtered.length,
+            }, "discover_tools search completed");
+            // ---------- No BM25 match -- check active tools before giving up ----------
+            if (topResults.length === 0) {
+                const activeMatches = findActiveToolMatches(query, activeToolNames);
+                if (activeMatches.length > 0) {
+                    logger.info({
+                        toolName: "discover_tools",
                         query,
-                        searchMode,
-                        floor,
-                        topScore: rawTop?.score ?? 0,
-                        topCandidate: rawTop?.name ?? "none",
-                        filteredOut: ranked.length - filtered.length,
-                        hint: "No tool scored above the discover_tools floor; lower skills.toolDiscovery.minBm25Score / minHybridScore if this query should have matched, or retry with an exact tool name or 'select:...' syntax",
-                        errorKind: "validation",
-                    }, "discover_tools: no good matches found");
+                        activeMatchCount: activeMatches.length,
+                        topActiveMatch: activeMatches[0],
+                    }, "discover_tools: query matches already-active tools");
                     return {
                         content: [{
                                 type: "text",
-                                text: "No matching tools found. Try an exact tool name, MCP server name (e.g. 'yfinance'), or select:tool1,tool2 syntax.",
+                                text: `Tool(s) already active -- call directly, no discovery needed:\n${activeMatches.slice(0, 20).map(n => `  - ${n}`).join("\n")}${activeMatches.length > 20 ? `\n  ... (${activeMatches.length} total)` : ""}`,
                             }],
                         isError: false,
                         details: undefined,
                         sideEffects: { discoveredTools: [] },
                     };
                 }
-                // Resolve BM25 results back to ToolDefinition objects
-                matches = topResults
-                    .map(r => deferredTools.find(t => t.name === r.name))
-                    .filter((t) => t !== undefined);
-            }
-            const discoveredNames = matches.map(m => m.name);
-            // Server-level activation: expand to all tools from same MCP server(s)
-            const serverNames = new Set();
-            for (const name of discoveredNames) {
-                const server = extractMcpServerName(name);
-                if (server)
-                    serverNames.add(server);
+                // Distinguish "corpus has signal but filtered" vs "query terms absent from corpus".
+                // After normalization, the former is only reachable in hybrid mode with adversarial
+                // cosine (combined < floor). In BM25-only mode it's unreachable because the top
+                // match always normalizes to 1.0 >= any floor <= 1.0.
+                const warnMsg = rawTopScore > 0
+                    ? "discover_tools: no matches above floor"
+                    : "discover_tools: query tokens absent from deferred corpus";
+                logger.warn({
+                    query,
+                    searchMode,
+                    floor,
+                    rawTopScore,
+                    normalizedTopScore,
+                    topCandidate: ranked[0]?.name ?? "none",
+                    filteredOut: ranked.length - filtered.length,
+                    activeCorpusSize: activeToolNames.size,
+                    hint: rawTopScore > 0
+                        ? "No tool scored above the discover_tools floor. Lower skills.toolDiscovery.minHybridScore, retry with an exact tool name, or use 'select:<name>' syntax."
+                        : "Query tokens do not appear in any deferred tool description. Use 'select:<name>' for exact match, or reconsider whether the tool you want is already active.",
+                    errorKind: "validation",
+                }, warnMsg);
+                return {
+                    content: [{
+                            type: "text",
+                            text: "No matching tools found. Try an exact tool name, MCP server name (e.g. 'yfinance'), or select:tool1,tool2 syntax.",
+                        }],
+                    isError: false,
+                    details: undefined,
+                    sideEffects: { discoveredTools: [] },
+                };
             }
-            if (serverNames.size > 0) {
-                for (const entry of deferredEntries) {
-                    const server = extractMcpServerName(entry.name);
-                    if (server && serverNames.has(server) && !discoveredNames.includes(entry.name)) {
-                        discoveredNames.push(entry.name);
-                    }
-                }
+            // ---------- Resolve matches, expand, format ----------
+            const matches = topResults
+                .map(r => deferredTools.find(t => t.name === r.name))
+                .filter((t) => t !== undefined);
+            return formatDiscoveryResponse(matches, deferredEntries);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers: active-tool match + output formatting
+// ---------------------------------------------------------------------------
+/**
+ * Check whether `query` refers to any already-active tool.
+ * Used to return "already active" guidance instead of "no matches" when
+ * the agent re-discovers a previously-installed MCP or active builtin.
+ *
+ * Match modes (checked in order, first non-empty wins):
+ * 1. Exact name match (case-insensitive) against the full query.
+ * 2. `mcp__` / `mcp:` prefix match against the full query.
+ * 3. Bare server-name match on full query (`"yfinance"` -> all `mcp__yfinance--*`).
+ * 4. Per-token server-name fallback: for multi-word queries like
+ *    `"yfinance get_stock"`, check each whitespace-separated token as a
+ *    potential MCP server name. Catches the srv1593437 08:06:39Z scenario
+ *    where the agent emits `{query: "yfinance get_stock"}` rather than just
+ *    `{query: "yfinance"}`.
+ */
+function findActiveToolMatches(query, activeToolNames) {
+    const q = query.toLowerCase().trim();
+    if (!q || activeToolNames.size === 0)
+        return [];
+    const names = [...activeToolNames];
+    const lowerMap = new Map(names.map(n => [n.toLowerCase(), n]));
+    // Mode 1: exact match
+    const exact = lowerMap.get(q);
+    if (exact)
+        return [exact];
+    // Mode 2: prefix match (mcp__ or mcp:)
+    if ((q.startsWith("mcp__") || q.startsWith("mcp:")) && q.length > 5) {
+        const prefix = names.filter(n => n.toLowerCase().startsWith(q));
+        if (prefix.length > 0)
+            return prefix;
+    }
+    // Mode 3: bare server name -> mcp__<server>--*
+    const serverPrefix = `mcp__${q}--`;
+    const server = names.filter(n => n.toLowerCase().startsWith(serverPrefix));
+    if (server.length > 0)
+        return server;
+    // Mode 4: per-token server fallback for multi-word queries.
+    // Each whitespace-separated token is probed as a server name. The first
+    // token that resolves to >= 1 active tool wins. This handles the common
+    // "{server} {verb}" pattern like "yfinance get_stock".
+    const tokens = q.split(/\s+/).filter(t => /^[a-z0-9_-]+$/.test(t));
+    for (const token of tokens) {
+        const tokenServerPrefix = `mcp__${token}--`;
+        const tokenMatches = names.filter(n => n.toLowerCase().startsWith(tokenServerPrefix));
+        if (tokenMatches.length > 0)
+            return tokenMatches;
+    }
+    return [];
+}
+/**
+ * Format matched tool definitions as a `<functions>` block with full JSON schemas,
+ * applying server-expansion and co-discovery.
+ *
+ * Extracted from the inline block in `createDiscoverTool.execute()` so the two
+ * return paths (structured + BM25) share one formatter.
+ */
+function formatDiscoveryResponse(matches, deferredEntries) {
+    const discoveredNames = matches.map(m => m.name);
+    // Server-level activation: expand to all tools from same MCP server(s)
+    const serverNames = new Set();
+    for (const name of discoveredNames) {
+        const server = extractMcpServerName(name);
+        if (server)
+            serverNames.add(server);
+    }
+    if (serverNames.size > 0) {
+        for (const entry of deferredEntries) {
+            const server = extractMcpServerName(entry.name);
+            if (server && serverNames.has(server) && !discoveredNames.includes(entry.name)) {
+                discoveredNames.push(entry.name);
             }
-            // Co-discovery: expand to related tools via ComisToolMetadata.coDiscoverWith
-            const coDiscoveryNames = [];
-            for (const name of discoveredNames) {
-                const meta = getToolMetadata(name);
-                if (meta?.coDiscoverWith) {
-                    for (const coName of meta.coDiscoverWith) {
-                        if (!discoveredNames.includes(coName) && !coDiscoveryNames.includes(coName)) {
-                            // Only add if the tool exists in the deferred set
-                            if (deferredEntries.some(e => e.name === coName)) {
-                                coDiscoveryNames.push(coName);
-                            }
-                        }
+        }
+    }
+    // Co-discovery: expand to related tools via ComisToolMetadata.coDiscoverWith
+    const coDiscoveryNames = [];
+    for (const name of discoveredNames) {
+        const meta = getToolMetadata(name);
+        if (meta?.coDiscoverWith) {
+            for (const coName of meta.coDiscoverWith) {
+                if (!discoveredNames.includes(coName) && !coDiscoveryNames.includes(coName)) {
+                    // Only add if the tool exists in the deferred set
+                    if (deferredEntries.some(e => e.name === coName)) {
+                        coDiscoveryNames.push(coName);
                     }
                 }
             }
-            discoveredNames.push(...coDiscoveryNames);
-            // Add co-discovered tool schemas to the display output
-            for (const coName of coDiscoveryNames) {
-                const coEntry = deferredEntries.find(e => e.name === coName);
-                if (coEntry && !matches.some(m => m.name === coName)) {
-                    matches.push(coEntry.original);
-                }
-            }
-            // Format output as <functions> block with full JSON schemas (after all expansions)
-            const functionsBlock = matches.map(m => {
-                return `<function>${JSON.stringify({
-                    name: m.name,
-                    description: resolveToolDescription(m),
-                    parameters: m.parameters,
-                })}</function>`;
-            }).join("\n");
-            return {
-                content: [{ type: "text", text: `<functions>\n${functionsBlock}\n</functions>` }],
-                isError: false,
-                details: undefined,
-                sideEffects: { discoveredTools: discoveredNames },
-            };
-        },
+        }
+    }
+    discoveredNames.push(...coDiscoveryNames);
+    // Add co-discovered tool schemas to the display output
+    const expandedMatches = [...matches];
+    for (const coName of coDiscoveryNames) {
+        const coEntry = deferredEntries.find(e => e.name === coName);
+        if (coEntry && !expandedMatches.some(m => m.name === coName)) {
+            expandedMatches.push(coEntry.original);
+        }
+    }
+    // Format output as <functions> block with full JSON schemas (after all expansions)
+    const functionsBlock = expandedMatches.map(m => `<function>${JSON.stringify({
+        name: m.name,
+        description: resolveToolDescription(m),
+        parameters: m.parameters,
+    })}</function>`).join("\n");
+    return {
+        content: [{ type: "text", text: `<functions>\n${functionsBlock}\n</functions>` }],
+        isError: false,
+        details: undefined,
+        sideEffects: { discoveredTools: discoveredNames },
     };
 }
 // ---------------------------------------------------------------------------
@@ -615,3 +723,37 @@ function cosine(a, b) {
     const denom = Math.sqrt(magA) * Math.sqrt(magB);
     return denom === 0 ? 0 : dot / denom;
 }
+// ---------------------------------------------------------------------------
+// Auto-discovery stubs
+// ---------------------------------------------------------------------------
+export const DEFERRAL_STUB_MARKER = "__comis_deferral_stub__";
+export function createAutoDiscoveryStubs(deferredEntries, discoveryTracker, logger) {
+    return deferredEntries.map(entry => {
+        // `label` is a required field on ToolDefinition
+        // (pi-coding-agent/core/extensions/types.d.ts). Some existing code paths
+        // dereference it (pi-executor.ts mid-turn injection at line ~826), so
+        // copy from the original rather than leave undefined.
+        const originalLabel = entry.original.label;
+        const stub = {
+            name: entry.name,
+            label: originalLabel ?? entry.name,
+            description: entry.description,
+            parameters: entry.original.parameters,
+            [DEFERRAL_STUB_MARKER]: true,
+            async execute(toolCallId, params, signal, onUpdate, ctx) {
+                const result = await entry.original.execute(toolCallId, params, signal, onUpdate, ctx);
+                // Mark discovered only after a SUCCESSFUL execution. An MCP tool can
+                // return `{ isError: true, content: [...] }` without throwing -- those
+                // results must not promote the tool to the active set, or a broken tool
+                // would persist across turns and keep wasting discovery budget.
+                const isError = result?.isError === true;
+                if (!isError) {
+                    discoveryTracker.markDiscovered([entry.name]);
+                }
+                logger.info({ toolName: entry.name, toolCallId, isError }, "Auto-discovery stub triggered — forwarding to real tool");
+                return result;
+            },
+        };
+        return stub;
+    });
+}

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

@@ -48,6 +48,12 @@ export declare function clearSessionLastResponseTs(sessionKey: string): void;
  * Used by the idle-based thinking clear to determine if cache is cold.
  */
 export declare function getElapsedSinceLastResponse(sessionKey: string): number | undefined;
+/**
+ * Get the raw timestamp of the last recorded response for a session.
+ * Returns undefined if no response has been recorded (cold-start).
+ * Used by the cadence tracker to detect turn boundaries.
+ */
+export declare function getLastResponseTs(sessionKey: string): number | undefined;
 /** Expose the internal Map for test assertions. Underscore prefix per project convention. */
 export declare function _getSessionLastResponseTsForTest(): Map<string, {
     ts: number;

package/node_modules/@comis/agent/dist/executor/ttl-guard.js

@@ -94,6 +94,14 @@ export function getElapsedSinceLastResponse(sessionKey) {
         return undefined;
     return Date.now() - entry.ts;
 }
+/**
+ * Get the raw timestamp of the last recorded response for a session.
+ * Returns undefined if no response has been recorded (cold-start).
+ * Used by the cadence tracker to detect turn boundaries.
+ */
+export function getLastResponseTs(sessionKey) {
+    return sessionLastResponseTs.get(sessionKey)?.ts;
+}
 // ---------------------------------------------------------------------------
 // Test-only export
 // ---------------------------------------------------------------------------

package/node_modules/@comis/agent/dist/session/comis-session-manager.js

@@ -18,7 +18,7 @@
 import { SessionManager as SdkSessionManager } from "@mariozechner/pi-coding-agent";
 import { formatSessionKey, safePath } from "@comis/core";
 import { suppressError } from "@comis/shared";
-import { mkdir, unlink, rm } from "node:fs/promises";
+import { mkdir, unlink, rm, rmdir } from "node:fs/promises";
 import { existsSync, writeFileSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { sessionKeyToPath } from "./session-key-mapper.js";
@@ -61,8 +61,13 @@ export function createComisSessionManager(deps) {
                     await unlink(sessionPath);
                 }
                 catch { /* ENOENT ok */ }
-                const toolResultsDir = safePath(dirname(sessionPath), "tool-results");
+                const sessionDir = dirname(sessionPath);
+                const toolResultsDir = safePath(sessionDir, "tool-results");
                 await suppressError(rm(toolResultsDir, { recursive: true, force: true }), "tool-results dir may not exist");
+                try {
+                    await rmdir(sessionDir);
+                }
+                catch { /* non-empty or already gone */ }
             }, { retries: 10, retryMinTimeout: 500 });
         },
         writeSessionMetadata(sessionKey, metadata) {

package/node_modules/@comis/agent/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/agent",
   "private": true,
-  "version": "1.0.14",
+  "version": "1.0.16",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "AI agent executor, budget control, and session management for Comis",