comisai 1.0.4

package/node_modules/@comis/agent/dist/executor/stream-wrappers/tool-result-size-bouncer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Tool result size bouncer stream wrapper.
+ *
+ * Truncates oversized tool results before passing context to the LLM.
+ * Prevents oversized tool results from entering the context window, which
+ * causes compaction spirals and wasted tokens.
+ *
+ * @module
+ */
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./types.js";
+/** Truncation summary accumulated across all LLM calls in one execution. */
+export interface TruncationSummary {
+    /** Number of unique tools that had results truncated. */
+    truncatedTools: number;
+    /** Total characters removed by truncation. */
+    totalTruncatedChars: number;
+}
+/** Return type for createToolResultSizeBouncer: wrapper + summary getter. */
+export interface ToolResultSizeBouncerResult {
+    /** The StreamFnWrapper to push into the wrappers array. */
+    wrapper: StreamFnWrapper;
+    /** Retrieve the accumulated truncation summary for the execution bookend. */
+    getTruncationSummary: () => TruncationSummary;
+}
+/**
+ * Create a wrapper that truncates oversized toolResult messages before
+ * passing context to the LLM.
+ *
+ * Prevents oversized tool results from entering the context window, which
+ * causes compaction spirals and wasted tokens. Uses the existing
+ * createToolResultSizeGuard for proportional truncation.
+ *
+ * Accepts a truncationHints map for tool-specific recovery guidance.
+ * Deduplicates WARN logs per (toolName, toolCallId) within one execution.
+ * Accumulates truncation summary (truncatedTools + totalTruncatedChars).
+ *
+ * @param maxChars - Maximum allowed text characters per tool result
+ * @param logger - Logger for WARN output when truncation occurs
+ * @param truncationHints - Optional map of toolName -> hint text for tool-specific guidance
+ * @returns Object with wrapper and getTruncationSummary getter
+ */
+export declare function createToolResultSizeBouncer(maxChars: number, logger: ComisLogger, truncationHints?: ReadonlyMap<string, string>, onTruncation?: (toolCallId: string, meta: {
+    fullChars: number;
+    returnedChars: number;
+}) => void): ToolResultSizeBouncerResult;

package/node_modules/@comis/agent/dist/executor/stream-wrappers/tool-result-size-bouncer.js

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tool result size bouncer stream wrapper.
+ *
+ * Truncates oversized tool results before passing context to the LLM.
+ * Prevents oversized tool results from entering the context window, which
+ * causes compaction spirals and wasted tokens.
+ *
+ * @module
+ */
+import { createToolResultSizeGuard } from "../../safety/tool-result-size-guard.js";
+/**
+ * Create a wrapper that truncates oversized toolResult messages before
+ * passing context to the LLM.
+ *
+ * Prevents oversized tool results from entering the context window, which
+ * causes compaction spirals and wasted tokens. Uses the existing
+ * createToolResultSizeGuard for proportional truncation.
+ *
+ * Accepts a truncationHints map for tool-specific recovery guidance.
+ * Deduplicates WARN logs per (toolName, toolCallId) within one execution.
+ * Accumulates truncation summary (truncatedTools + totalTruncatedChars).
+ *
+ * @param maxChars - Maximum allowed text characters per tool result
+ * @param logger - Logger for WARN output when truncation occurs
+ * @param truncationHints - Optional map of toolName -> hint text for tool-specific guidance
+ * @returns Object with wrapper and getTruncationSummary getter
+ */
+export function createToolResultSizeBouncer(maxChars, logger, truncationHints, onTruncation) {
+    const guard = createToolResultSizeGuard();
+    // Dedup set keyed by "toolName:toolCallId" -- persists across all LLM calls
+    const truncationDedup = new Set();
+    // Accumulator for execution-level summary
+    let truncatedToolsCount = 0;
+    let totalTruncatedChars = 0;
+    const wrapper = function toolResultSizeBouncer(next) {
+        return (model, context, options) => {
+            let anyTruncated = false;
+            const bouncedMessages = context.messages.map((msg) => {
+                if (msg.role !== "toolResult") {
+                    return msg;
+                }
+                // Look up tool-specific hint
+                const toolHint = truncationHints?.get(msg.toolName);
+                // Cast SDK (TextContent | ImageContent)[] to guard's ContentBlock[] --
+                // structurally compatible, but TS can't prove it due to index signature.
+                const result = guard.truncateIfNeeded(msg.content, maxChars, toolHint);
+                if (!result.truncated) {
+                    return msg;
+                }
+                anyTruncated = true;
+                // Build dedup key and only log WARN on first occurrence
+                const dedupKey = `${msg.toolName}:${msg.toolCallId}`;
+                if (!truncationDedup.has(dedupKey)) {
+                    truncationDedup.add(dedupKey);
+                    truncatedToolsCount++;
+                    logger.warn({
+                        toolName: msg.toolName,
+                        originalChars: result.metadata.originalChars,
+                        truncatedChars: result.metadata.truncatedChars,
+                        hint: `Tool result from '${msg.toolName}' exceeded ${maxChars} chars and was truncated; increase agents.<name>.maxToolResultChars if this tool legitimately produces large output`,
+                        errorKind: "resource",
+                    }, "Tool result truncated");
+                }
+                // Always accumulate chars regardless of dedup
+                totalTruncatedChars += result.metadata.originalChars - result.metadata.truncatedChars;
+                // Notify truncation registry for audit event metadata
+                onTruncation?.(msg.toolCallId, {
+                    fullChars: result.metadata.originalChars,
+                    returnedChars: result.metadata.truncatedChars,
+                });
+                return { ...msg, content: result.content };
+            });
+            if (anyTruncated) {
+                const bouncedContext = {
+                    ...context,
+                    messages: bouncedMessages,
+                };
+                return next(model, bouncedContext, options);
+            }
+            // No truncation needed -- pass through unchanged
+            return next(model, context, options);
+        };
+    };
+    return {
+        wrapper,
+        getTruncationSummary: () => ({
+            truncatedTools: truncatedToolsCount,
+            totalTruncatedChars,
+        }),
+    };
+}

package/node_modules/@comis/agent/dist/executor/stream-wrappers/tool-schema-cache.d.ts

@@ -0,0 +1,28 @@
+export interface RenderedToolCacheEntry {
+    hash: number;
+    featureFlagHash: string;
+    tools: Array<Record<string, unknown>>;
+}
+export declare const sessionRenderedToolCache: Map<string, RenderedToolCacheEntry>;
+export declare function clearSessionRenderedToolCache(sessionKey: string): void;
+export type PerToolCacheEntry = {
+    key: string;
+    tool: Record<string, unknown>;
+};
+export declare const sessionPerToolCache: Map<string, Map<string, PerToolCacheEntry>>;
+/**
+ * Get or cache a single rendered tool object by content-addressed key.
+ * Returns byte-identical reference when name+description+input_schema is unchanged.
+ * When any field changes, a new structuredClone snapshot replaces the old entry.
+ *
+ * @param sessionKey - Session key for cache scoping
+ * @param tool - Rendered tool object with name, description, input_schema
+ * @returns Cached or freshly cloned tool object
+ */
+export declare function getOrCacheRenderedTool(sessionKey: string, tool: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Clear the per-tool content-addressed cache for a session.
+ *
+ * @param sessionKey - Session key to clear
+ */
+export declare function clearSessionPerToolCache(sessionKey: string): void;

package/node_modules/@comis/agent/dist/executor/stream-wrappers/tool-schema-cache.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Extracted tool schema cache module.
+ *
+ * Pure data structures for session-scoped rendered tool caching.
+ * Leaf module: imports only from cache-break-detection.ts (computeHash).
+ * Zero imports from request-body-injector.ts.
+ *
+ * @module
+ */
+import { computeHash } from "../cache-break-detection.js";
+export const sessionRenderedToolCache = new Map();
+export function clearSessionRenderedToolCache(sessionKey) {
+    sessionRenderedToolCache.delete(sessionKey);
+}
+export const sessionPerToolCache = new Map();
+/**
+ * Get or cache a single rendered tool object by content-addressed key.
+ * Returns byte-identical reference when name+description+input_schema is unchanged.
+ * When any field changes, a new structuredClone snapshot replaces the old entry.
+ *
+ * @param sessionKey - Session key for cache scoping
+ * @param tool - Rendered tool object with name, description, input_schema
+ * @returns Cached or freshly cloned tool object
+ */
+export function getOrCacheRenderedTool(sessionKey, tool) {
+    const name = tool.name;
+    const cacheKey = `${name}:${computeHash({ name: tool.name, description: tool.description, input_schema: tool.input_schema })}`;
+    let sessionTools = sessionPerToolCache.get(sessionKey);
+    if (!sessionTools) {
+        sessionTools = new Map();
+        sessionPerToolCache.set(sessionKey, sessionTools);
+    }
+    const cached = sessionTools.get(name);
+    if (cached && cached.key === cacheKey) {
+        return cached.tool; // byte-identical reference
+    }
+    // Create a new snapshot
+    const snapshot = structuredClone({ name: tool.name, description: tool.description, input_schema: tool.input_schema });
+    sessionTools.set(name, { key: cacheKey, tool: snapshot });
+    return snapshot;
+}
+/**
+ * Clear the per-tool content-addressed cache for a session.
+ *
+ * @param sessionKey - Session key to clear
+ */
+export function clearSessionPerToolCache(sessionKey) {
+    sessionPerToolCache.delete(sessionKey);
+}

package/node_modules/@comis/agent/dist/executor/stream-wrappers/turn-result-budget-wrapper.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-turn result budget stream wrapper.
+ *
+ * Enforces a per-turn aggregate character budget across all tool results
+ * before passing context to the LLM.
+ *
+ * @module
+ */
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./types.js";
+/** Summary of per-turn budget enforcement accumulated across all LLM calls. */
+export interface TurnBudgetSummary {
+    /** Number of turns where the aggregate budget was exceeded. */
+    turnsExceeded: number;
+    /** Total characters removed by per-turn budget truncation. */
+    totalBudgetTruncatedChars: number;
+}
+/** Return type for createTurnResultBudgetWrapper: wrapper + summary getter. */
+export interface TurnResultBudgetWrapperResult {
+    /** The StreamFnWrapper to push into the wrappers array. */
+    wrapper: StreamFnWrapper;
+    /** Retrieve the accumulated turn budget summary for the execution bookend. */
+    getTurnBudgetSummary: () => TurnBudgetSummary;
+}
+/**
+ * Create a wrapper that enforces a per-turn aggregate character budget across
+ * all tool results before passing context to the LLM.
+ *
+ * Uses the pure `applyTurnResultBudget` function from .
+ * When the budget is exceeded, tool results are proportionally truncated
+ * with each tool guaranteed at least `minCharsPerTool` characters.
+ *
+ * @param maxTurnChars - Maximum aggregate text chars across all tool results per turn
+ * @param minCharsPerTool - Minimum chars each tool result is guaranteed
+ * @param logger - Logger for WARN output when budget is exceeded
+ * @param onTruncation - Optional callback for per-tool truncation metadata ( audit)
+ * @returns Object with wrapper and getTurnBudgetSummary getter
+ */
+export declare function createTurnResultBudgetWrapper(maxTurnChars: number, minCharsPerTool: number, logger: ComisLogger, onTruncation?: (toolCallId: string, meta: {
+    fullChars: number;
+    returnedChars: number;
+}) => void): TurnResultBudgetWrapperResult;

package/node_modules/@comis/agent/dist/executor/stream-wrappers/turn-result-budget-wrapper.js

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Per-turn result budget stream wrapper.
+ *
+ * Enforces a per-turn aggregate character budget across all tool results
+ * before passing context to the LLM.
+ *
+ * @module
+ */
+import { applyTurnResultBudget } from "../../safety/turn-result-budget.js";
+/**
+ * Create a wrapper that enforces a per-turn aggregate character budget across
+ * all tool results before passing context to the LLM.
+ *
+ * Uses the pure `applyTurnResultBudget` function from .
+ * When the budget is exceeded, tool results are proportionally truncated
+ * with each tool guaranteed at least `minCharsPerTool` characters.
+ *
+ * @param maxTurnChars - Maximum aggregate text chars across all tool results per turn
+ * @param minCharsPerTool - Minimum chars each tool result is guaranteed
+ * @param logger - Logger for WARN output when budget is exceeded
+ * @param onTruncation - Optional callback for per-tool truncation metadata ( audit)
+ * @returns Object with wrapper and getTurnBudgetSummary getter
+ */
+export function createTurnResultBudgetWrapper(maxTurnChars, minCharsPerTool, logger, onTruncation) {
+    let turnsExceeded = 0;
+    let totalBudgetTruncatedChars = 0;
+    const wrapper = function turnResultBudget(next) {
+        return (model, context, options) => {
+            const result = applyTurnResultBudget(context.messages, { maxTurnChars, minCharsPerTool });
+            if (!result.budgetExceeded) {
+                return next(model, context, options);
+            }
+            // Budget exceeded -- accumulate summary stats
+            turnsExceeded++;
+            let turnTruncatedChars = 0;
+            for (const meta of result.toolMetas) {
+                if (meta.truncated) {
+                    turnTruncatedChars += meta.fullChars - meta.returnedChars;
+                    // Notify truncation registry for audit event metadata
+                    onTruncation?.(meta.toolCallId, {
+                        fullChars: meta.fullChars,
+                        returnedChars: meta.returnedChars,
+                    });
+                }
+            }
+            totalBudgetTruncatedChars += turnTruncatedChars;
+            logger.warn({
+                turnsExceeded,
+                totalBudgetTruncatedChars,
+                maxTurnChars,
+                toolsInTurn: result.toolMetas.length,
+                truncatedInTurn: result.toolMetas.filter(m => m.truncated).length,
+                hint: "Per-turn aggregate tool result budget exceeded; reduce tool output size or increase budget",
+                errorKind: "resource",
+            }, "Turn result budget exceeded");
+            const budgetedContext = { ...context, messages: result.messages };
+            return next(model, budgetedContext, options);
+        };
+    };
+    return {
+        wrapper,
+        getTurnBudgetSummary: () => ({
+            turnsExceeded,
+            totalBudgetTruncatedChars,
+        }),
+    };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Shared types for the stream wrapper chain infrastructure.
+ *
+ * @module
+ */
+import type { StreamFn } from "@mariozechner/pi-agent-core";
+/**
+ * A StreamFn wrapper intercepts and decorates a StreamFn.
+ * Takes the "next" function in the chain and returns a new StreamFn.
+ * Standard decorator/middleware pattern.
+ */
+export type StreamFnWrapper = (next: StreamFn) => StreamFn;

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

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared types for the stream wrapper chain infrastructure.
+ *
+ * @module
+ */
+export {};

package/node_modules/@comis/agent/dist/executor/stream-wrappers/validation-error-formatter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Validation error formatter stream wrapper.
+ *
+ * Reformats AJV validation errors in toolResult messages before the LLM
+ * sees them on the next turn, providing concise, actionable messages.
+ *
+ * @module
+ */
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./types.js";
+/**
+ * Create a wrapper that reformats AJV validation errors in toolResult messages
+ * before the LLM sees them on the next turn.
+ *
+ * pi-ai's validateToolArguments() produces verbose error text containing
+ * AJV's generic messages plus a full JSON dump of the received arguments.
+ * This wrapper intercepts those tool results and rewrites them into concise,
+ * actionable messages that help the LLM self-correct.
+ *
+ * Only modifies toolResult messages where `isError === true` and the text
+ * matches the pi-ai validation error pattern. All other messages pass through
+ * unchanged.
+ *
+ * @param logger - Logger for debug output when a validation error is reformatted
+ * @returns A named StreamFnWrapper ("validationErrorFormatter")
+ */
+export declare function createValidationErrorFormatter(logger: ComisLogger): StreamFnWrapper;

package/node_modules/@comis/agent/dist/executor/stream-wrappers/validation-error-formatter.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Validation error formatter stream wrapper.
+ *
+ * Reformats AJV validation errors in toolResult messages before the LLM
+ * sees them on the next turn, providing concise, actionable messages.
+ *
+ * @module
+ */
+import { formatValidationError } from "../../safety/validation-error-formatter.js";
+/**
+ * Create a wrapper that reformats AJV validation errors in toolResult messages
+ * before the LLM sees them on the next turn.
+ *
+ * pi-ai's validateToolArguments() produces verbose error text containing
+ * AJV's generic messages plus a full JSON dump of the received arguments.
+ * This wrapper intercepts those tool results and rewrites them into concise,
+ * actionable messages that help the LLM self-correct.
+ *
+ * Only modifies toolResult messages where `isError === true` and the text
+ * matches the pi-ai validation error pattern. All other messages pass through
+ * unchanged.
+ *
+ * @param logger - Logger for debug output when a validation error is reformatted
+ * @returns A named StreamFnWrapper ("validationErrorFormatter")
+ */
+export function createValidationErrorFormatter(logger) {
+    return function validationErrorFormatter(next) {
+        return (model, context, options) => {
+            const mappedMessages = context.messages.map((msg) => {
+                if (msg.role !== "toolResult" || !msg.isError) {
+                    return msg;
+                }
+                // Find first text content block
+                const textBlock = msg.content.find((block) => block.type === "text");
+                if (!textBlock || typeof textBlock.text !== "string") {
+                    return msg;
+                }
+                const formatted = formatValidationError(textBlock.text);
+                if (formatted === null) {
+                    return msg;
+                }
+                logger.debug({ toolName: msg.toolName }, "Validation error reformatted");
+                // Replace text in the matching content block
+                const updatedContent = msg.content.map((block) => block === textBlock ? { ...block, text: formatted } : block);
+                return { ...msg, content: updatedContent };
+            });
+            return next(model, { ...context, messages: mappedMessages }, options);
+        };
+    };
+}

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

@@ -0,0 +1,159 @@
+/**
+ * Unified tool deferral engine: replaces the MCP-only applyMcpToolDeferral()
+ * with rule-based, budget-based, and small-model deferral, plus BM25-scored
+ * discover_tools for searching deferred tools.
+ *
+ * Deferral model (exclude model): Deferred tools are removed from the tools
+ * parameter entirely and partitioned into a DeferredToolEntry list. A
+ * discover_tools tool is appended when deferred entries exist, allowing the
+ * LLM to search and fetch full schemas on demand. Discovered tools (tracked
+ * via DiscoveryTracker) are re-included in the active context with their
+ * original schemas. This achieves ~81% token savings for 100 tools compared
+ * to the previous description-swap (pre-register) model.
+ *
+ * @module
+ */
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { ComisLogger } from "@comis/infra";
+import type { EmbeddingPort } from "@comis/core";
+import type { DiscoveryTracker } from "./discovery-tracker.js";
+import type { ModelTier } from "../bootstrap/sections/tooling-sections.js";
+export interface DeferralRule {
+    /** Tool names that can be deferred under this rule. */
+    tools: string[];
+    /** Condition that KEEPS the tool active (not deferred). When false, tool is deferred. */
+    activeWhen: (ctx: DeferralContext) => boolean;
+    /** Namespace label for the discovery tool listing. */
+    namespace: string;
+    /** Brief description for the discovery tool. */
+    namespaceDescription: string;
+}
+export interface DeferralContext {
+    trustLevel: string;
+    channelType?: string;
+    modelTier: ModelTier;
+    recentlyUsedToolNames: Set<string>;
+    toolNames: string[];
+    contextEngineVersion?: string;
+    /** Tool names demoted by lifecycle management. When provided, these tools
+     *  are treated as an additional deferral source so discover_tools covers them. */
+    lifecycleDemotedNames?: Set<string>;
+    /** Session-scoped discovery tracker for re-including discovered tools. */
+    discoveryTracker: DiscoveryTracker;
+    /** Operator override: tools that should never be deferred (from config.deferredTools.neverDefer). */
+    neverDefer?: string[];
+    /** Operator override: tools that should always be deferred (from config.deferredTools.alwaysDefer). */
+    alwaysDefer?: string[];
+    /** Provider family for mid-turn injection awareness.
+     *  "anthropic" and "google" support mid-turn tool injection, so MCP tools
+     *  can be deferred behind discover_tools. Other providers (e.g., "openai",
+     *  "default") do not inject mid-turn, so MCP tools must be active from the
+     *  start. When undefined, defaults to deferring (backward compat). */
+    providerFamily?: string;
+}
+/** Entry describing a deferred tool with its display description and original definition. */
+export interface DeferredToolEntry {
+    name: string;
+    description: string;
+    original: ToolDefinition;
+}
+/** Result of the exclude-model deferral: tools partitioned into active, deferred, and discovered. */
+export interface ExcludeDeferralResult {
+    /** Tools to include in the LLM tools parameter (non-deferred). */
+    activeTools: ToolDefinition[];
+    /** Deferred tools not yet discovered (excluded from tools parameter). */
+    deferredEntries: DeferredToolEntry[];
+    /** Previously discovered tools re-included with full original schemas. */
+    discoveredTools: ToolDefinition[];
+    /** The discover_tools tool definition, or null when nothing is deferred. */
+    discoverTool: ToolDefinition | null;
+    /** Total number of tools in the deferral set (before discovery re-inclusion). */
+    deferredCount: number;
+    /** Names of all tools in the deferral set (before discovery re-inclusion). */
+    deferredNames: string[];
+}
+/**
+ * Declarative deferral rules. Each rule specifies tools to defer and the
+ * condition under which they remain active.
+ */
+export declare const DEFERRAL_RULES: DeferralRule[];
+/**
+ * Core tools that remain active even under aggressive small-model deferral.
+ * These are the essential tools for basic file/exec/memory/web operations.
+ */
+export declare const CORE_TOOLS: Set<string>;
+/**
+ * Classify a model by its context window size into small/medium/large tiers.
+ *
+ * - small (<= 32K): Aggressive deferral, 0.0 temperature
+ * - medium (<= 64K): Standard deferral, 0.1 temperature
+ * - large (> 64K): Standard deferral, 0.1 temperature
+ */
+export declare function resolveModelTier(contextWindow: number): ModelTier;
+/**
+ * Resolve the optimal tool-calling temperature for a given model tier.
+ * Small models benefit from deterministic tool selection (0.0).
+ */
+export declare function resolveToolCallingTemperature(modelTier: ModelTier): number;
+/**
+ * Extract recently-used tool names from session history messages.
+ * Looks at the most recent N assistant messages for tool_use blocks.
+ *
+ * @param messages - Session context messages (AgentMessage[] or SDK Message[])
+ * @param lookbackCount - Number of recent messages to scan (default: 20)
+ * @returns Set of tool names used recently
+ */
+export declare function extractRecentlyUsedToolNames(messages: Array<Record<string, unknown>>, lookbackCount?: number): Set<string>;
+/**
+ * Resolve the lean display description for a tool.
+ * Lookup chain: dynamic builder -> static lean -> original description -> tool name.
+ * Used for both DeferredToolEntry.description and discover_tools output.
+ * Does NOT include searchHint (display-only).
+ */
+export declare function resolveToolDescription(tool: ToolDefinition): string;
+/**
+ * Build a `<deferred-tools>` XML block for dynamic preamble injection.
+ * Lists deferred tool names and descriptions so the LLM knows what's
+ * available behind discover_tools.
+ *
+ * @param entries - Deferred tool entries (remaining after discovery re-inclusion)
+ * @returns XML block string, or empty string when no entries
+ */
+export declare function buildDeferredToolsContext(entries: DeferredToolEntry[]): string;
+/**
+ * Apply unified tool deferral: rule-based, budget-based, small-model,
+ * lifecycle merge, and operator overrides.
+ *
+ * Exclude model: deferred tools are removed from the tools parameter entirely
+ * and partitioned into DeferredToolEntry[]. Discovered tools (via
+ * DiscoveryTracker) are re-included with their full original schemas.
+ * A discover_tools tool is created when remaining deferred entries exist.
+ *
+ * @param tools - Full list of custom tools (may include MCP tools)
+ * @param contextWindow - Model context window in tokens
+ * @param deferralContext - Session context for deferral decisions
+ * @param logger - Logger for INFO/WARN output
+ * @param embeddingPort - Optional embedding port for semantic search in discover_tools
+ * @returns Partitioned tools and deferral metadata
+ */
+export declare function applyToolDeferral(tools: ToolDefinition[], _contextWindow: number, deferralContext: DeferralContext, logger: ComisLogger, embeddingPort?: EmbeddingPort, scoreConfig?: ToolDiscoveryScoreConfig): ExcludeDeferralResult;
+/**
+ * Score-floor thresholds for discover_tools ranking. Applied to the filtered
+ * ranked list before slice(0, 10) to prevent zero-signal queries from
+ * surfacing incidental BM25 hits or cosine-noise matches.
+ */
+export interface ToolDiscoveryScoreConfig {
+    minBm25Score: number;
+    minHybridScore: number;
+}
+/**
+ * Create a discovery tool that lets the agent search deferred tools by query.
+ * Uses BM25 keyword scoring with optional EmbeddingPort semantic re-ranking.
+ *
+ * Receives DeferredToolEntry[] (with original schemas and display descriptions)
+ * so it can serve full schemas and lean descriptions when queried.
+ *
+ * @param scoreConfig Optional score-floor override (defaults to 0.8 BM25 /
+ *   0.35 hybrid). Zero or negative floors disable the filter.
+ */
+export declare function createDiscoverTool(deferredEntries: DeferredToolEntry[], logger: ComisLogger, embeddingPort?: EmbeddingPort, scoreConfig?: ToolDiscoveryScoreConfig): ToolDefinition;