@cognipeer/agent-sdk 0.8.3 → 0.8.5

package/dist/index.d.cts

@@ -240,18 +240,36 @@ declare const DEFAULT_SUBAGENT_TOOL_NAMES: SubagentToolNames;
 /**
  * Skill primitive — progressive capability disclosure for the smart agent.
  *
- * A Skill is a lazy, self-contained capability bundle. The model always sees a
- * cheap one-line `header`; it calls `open_skill(key)` to load the skill's prompt
- * and (for small skills) bind its tools, or `bind_skill_tools(key, names)` to
- * bind a chosen subset of a fat skill. This keeps the number of bound tools per
- * step small — the property small models need — and replaces an up-front
- * tool-selector pass with on-demand disclosure.
+ * A Skill is a lazy, self-contained capability bundle. The model discovers a
+ * skill by its cheap one-line `header`, then calls `open_skill(key)` to load the
+ * skill's prompt and (for small skills) bind its tools, or
+ * `bind_skill_tools(key, names)` to bind a chosen subset of a fat skill. This
+ * keeps the number of bound tools per step small — the property small models
+ * need — and replaces an up-front tool-selector pass with on-demand disclosure.
+ *
+ * Discovery itself comes in two flavors, see `SkillPolicy.disclosure`: the
+ * headers can be listed in the system prompt, or looked up with `search_skills`.
  */
 type SkillToolHeader = {
     name: string;
     description?: string;
 };
 type SkillModelTier = "small" | "large";
+/**
+ * How the model finds out which skills exist.
+ *
+ *  - `"catalog"` (default): every available skill's header is rendered into the
+ *    system prompt as `<available_skills>`. Cheapest possible discovery — the
+ *    model needs no tool call — but the prompt grows with the catalog, and the
+ *    whole catalog is paid for on every single turn of every conversation.
+ *  - `"search"`: nothing goes into the prompt. The model finds skills through
+ *    the `search_skills` tool, whose description is the only always-on cost.
+ *    Prompt cost is constant, so this is the mode for a catalog that is large,
+ *    workspace-supplied, or mostly irrelevant to any one conversation. The
+ *    trade-off is real: a model that never calls `search_skills` never learns
+ *    the skills exist, so keep the tool description explicit about when to call.
+ */
+type SkillDisclosure = "catalog" | "search";
 type Skill = {
     /** Stable key, e.g. "mcp:atlassian" | "integration:google" | "builtin:drawio". */
     key: string;
@@ -284,6 +302,8 @@ type SkillPolicy = {
     maxBoundToolsTotal: number;
     /** Current model tier; gates `minModelTier`. */
     modelTier?: SkillModelTier;
+    /** How the model discovers skills. Defaults to `"catalog"`. */
+    disclosure?: SkillDisclosure;
 };
 declare const DEFAULT_SKILL_POLICY: SkillPolicy;
 declare const SMALL_TIER_SKILL_POLICY: SkillPolicy;
@@ -906,13 +926,19 @@ type SmartAgentOptions = {
     /** See AgentOptions.humanInTheLoop. */
     humanInTheLoop?: HumanInTheLoopOptions;
     /**
-     * Progressive capability disclosure. When provided, the agent exposes cheap
-     * skill headers in its system prompt and binds a skill's tools on demand via
-     * the built-in open_skill / bind_skill_tools tools. Keeps the bound-tool count
-     * per step small. An empty array is a no-op.
+     * Progressive capability disclosure. When provided, the agent binds a skill's
+     * tools on demand via the built-in open_skill / bind_skill_tools tools, which
+     * keeps the bound-tool count per step small. An empty array is a no-op.
+     *
+     * How the model discovers the catalog is set by `skillPolicy.disclosure`:
+     * cheap skill headers in the system prompt (`"catalog"`, the default), or a
+     * `search_skills` tool with nothing in the prompt (`"search"`).
      */
     skills?: Skill[];
-    /** Caps/tiering for skill disclosure. Defaults to DEFAULT_SKILL_POLICY. */
+    /**
+     * Caps, tiering and discovery mode for skills. Defaults to
+     * DEFAULT_SKILL_POLICY (i.e. `disclosure: "catalog"`).
+     */
     skillPolicy?: SkillPolicy;
     /**
      * Sub-agents for dynamic problem decomposition. When provided (or when
@@ -1907,6 +1933,20 @@ declare function canOpenSkill(ref: SkillRegistryRef, policy: SkillPolicy): {
 declare function resolveAvailableSkills(skills: Skill[], opts?: {
     modelTier?: SkillPolicy["modelTier"];
 }): Promise<Skill[]>;
+/**
+ * Rank a catalog against a free-text task description. Pure, deterministic and
+ * dependency-free: no embeddings, no I/O, so it costs nothing and behaves the
+ * same on every run. Backs the `search_skills` tool.
+ *
+ * Skills covering MORE of the query rank first, and only then by field weight
+ * (key > title > header) — matching two of the user's words in a header beats
+ * matching one of them in a title. Ties keep catalog order so a repeated query
+ * always returns the same list.
+ *
+ * An empty (or all-noise) query is a browse request and returns the head of the
+ * catalog rather than nothing.
+ */
+declare function searchSkills(skills: Skill[], query?: string, limit?: number): Skill[];
 /** The cheap header block the model always sees in its system prompt. */
 declare function buildSkillHeaderBlock(skills: Skill[]): string;
 declare function dedupeToolsByName(tools: ToolInterface[]): ToolInterface[];
@@ -1916,9 +1956,23 @@ type SkillToolDeps = {
     skills: Skill[];
     policy: SkillPolicy;
 };
+/**
+ * Discovery for `disclosure: "search"`: the catalog stays out of the prompt and
+ * the model looks it up instead, so prompt cost is constant no matter how many
+ * skills a workspace has.
+ *
+ * Availability (`isAvailable` / `minModelTier`) is resolved HERE rather than at
+ * prompt-assembly time, which means an integration that connects mid-run shows
+ * up on the next search instead of being frozen out for the whole invoke.
+ */
+declare function createSearchSkillsTool(deps: SkillToolDeps): ToolInterface;
 declare function createOpenSkillTool(deps: SkillToolDeps): ToolInterface;
 declare function createBindSkillToolsTool(deps: SkillToolDeps): ToolInterface;
-/** Both skill tools for an invoke, sharing one registry ref. */
+/**
+ * The skill meta-tools for an invoke, sharing one registry ref. `search_skills`
+ * is only wired under `disclosure: "search"` — in catalog mode the headers are
+ * already in the prompt and a search tool would be pure overhead.
+ */
 declare function createSkillTools(deps: SkillToolDeps): ToolInterface[];
 
 /**
@@ -2468,6 +2522,12 @@ declare function resolveToolApprovalState(state: SmartState, resolution: ToolApp
 
 declare function resolveUserQuestionState(state: SmartState, resolution: UserQuestionResolution): SmartState;
 
+/**
+ * The built-in ask-user tool's name. Exported because more than one layer has to
+ * recognise it: `createSmartAgent` builds the tool into the list it hands to
+ * `createAgent`, which must then not attach a second one of its own.
+ */
+declare const ASK_USER_TOOL_NAME = "ask_user_question";
 type AskUserStateRef = {
     pendingUserQuestions?: PendingUserQuestion[];
     ctx?: Record<string, any>;
@@ -3010,4 +3070,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, tokenize, traceSessionToOtlp, validateReasoningConfig, withTools, withinDepth, writeSummaryFactsToMemory };
+export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, tokenize, traceSessionToOtlp, validateReasoningConfig, withTools, withinDepth, writeSummaryFactsToMemory };

package/dist/index.d.ts

@@ -240,18 +240,36 @@ declare const DEFAULT_SUBAGENT_TOOL_NAMES: SubagentToolNames;
 /**
  * Skill primitive — progressive capability disclosure for the smart agent.
  *
- * A Skill is a lazy, self-contained capability bundle. The model always sees a
- * cheap one-line `header`; it calls `open_skill(key)` to load the skill's prompt
- * and (for small skills) bind its tools, or `bind_skill_tools(key, names)` to
- * bind a chosen subset of a fat skill. This keeps the number of bound tools per
- * step small — the property small models need — and replaces an up-front
- * tool-selector pass with on-demand disclosure.
+ * A Skill is a lazy, self-contained capability bundle. The model discovers a
+ * skill by its cheap one-line `header`, then calls `open_skill(key)` to load the
+ * skill's prompt and (for small skills) bind its tools, or
+ * `bind_skill_tools(key, names)` to bind a chosen subset of a fat skill. This
+ * keeps the number of bound tools per step small — the property small models
+ * need — and replaces an up-front tool-selector pass with on-demand disclosure.
+ *
+ * Discovery itself comes in two flavors, see `SkillPolicy.disclosure`: the
+ * headers can be listed in the system prompt, or looked up with `search_skills`.
  */
 type SkillToolHeader = {
     name: string;
     description?: string;
 };
 type SkillModelTier = "small" | "large";
+/**
+ * How the model finds out which skills exist.
+ *
+ *  - `"catalog"` (default): every available skill's header is rendered into the
+ *    system prompt as `<available_skills>`. Cheapest possible discovery — the
+ *    model needs no tool call — but the prompt grows with the catalog, and the
+ *    whole catalog is paid for on every single turn of every conversation.
+ *  - `"search"`: nothing goes into the prompt. The model finds skills through
+ *    the `search_skills` tool, whose description is the only always-on cost.
+ *    Prompt cost is constant, so this is the mode for a catalog that is large,
+ *    workspace-supplied, or mostly irrelevant to any one conversation. The
+ *    trade-off is real: a model that never calls `search_skills` never learns
+ *    the skills exist, so keep the tool description explicit about when to call.
+ */
+type SkillDisclosure = "catalog" | "search";
 type Skill = {
     /** Stable key, e.g. "mcp:atlassian" | "integration:google" | "builtin:drawio". */
     key: string;
@@ -284,6 +302,8 @@ type SkillPolicy = {
     maxBoundToolsTotal: number;
     /** Current model tier; gates `minModelTier`. */
     modelTier?: SkillModelTier;
+    /** How the model discovers skills. Defaults to `"catalog"`. */
+    disclosure?: SkillDisclosure;
 };
 declare const DEFAULT_SKILL_POLICY: SkillPolicy;
 declare const SMALL_TIER_SKILL_POLICY: SkillPolicy;
@@ -906,13 +926,19 @@ type SmartAgentOptions = {
     /** See AgentOptions.humanInTheLoop. */
     humanInTheLoop?: HumanInTheLoopOptions;
     /**
-     * Progressive capability disclosure. When provided, the agent exposes cheap
-     * skill headers in its system prompt and binds a skill's tools on demand via
-     * the built-in open_skill / bind_skill_tools tools. Keeps the bound-tool count
-     * per step small. An empty array is a no-op.
+     * Progressive capability disclosure. When provided, the agent binds a skill's
+     * tools on demand via the built-in open_skill / bind_skill_tools tools, which
+     * keeps the bound-tool count per step small. An empty array is a no-op.
+     *
+     * How the model discovers the catalog is set by `skillPolicy.disclosure`:
+     * cheap skill headers in the system prompt (`"catalog"`, the default), or a
+     * `search_skills` tool with nothing in the prompt (`"search"`).
      */
     skills?: Skill[];
-    /** Caps/tiering for skill disclosure. Defaults to DEFAULT_SKILL_POLICY. */
+    /**
+     * Caps, tiering and discovery mode for skills. Defaults to
+     * DEFAULT_SKILL_POLICY (i.e. `disclosure: "catalog"`).
+     */
     skillPolicy?: SkillPolicy;
     /**
      * Sub-agents for dynamic problem decomposition. When provided (or when
@@ -1907,6 +1933,20 @@ declare function canOpenSkill(ref: SkillRegistryRef, policy: SkillPolicy): {
 declare function resolveAvailableSkills(skills: Skill[], opts?: {
     modelTier?: SkillPolicy["modelTier"];
 }): Promise<Skill[]>;
+/**
+ * Rank a catalog against a free-text task description. Pure, deterministic and
+ * dependency-free: no embeddings, no I/O, so it costs nothing and behaves the
+ * same on every run. Backs the `search_skills` tool.
+ *
+ * Skills covering MORE of the query rank first, and only then by field weight
+ * (key > title > header) — matching two of the user's words in a header beats
+ * matching one of them in a title. Ties keep catalog order so a repeated query
+ * always returns the same list.
+ *
+ * An empty (or all-noise) query is a browse request and returns the head of the
+ * catalog rather than nothing.
+ */
+declare function searchSkills(skills: Skill[], query?: string, limit?: number): Skill[];
 /** The cheap header block the model always sees in its system prompt. */
 declare function buildSkillHeaderBlock(skills: Skill[]): string;
 declare function dedupeToolsByName(tools: ToolInterface[]): ToolInterface[];
@@ -1916,9 +1956,23 @@ type SkillToolDeps = {
     skills: Skill[];
     policy: SkillPolicy;
 };
+/**
+ * Discovery for `disclosure: "search"`: the catalog stays out of the prompt and
+ * the model looks it up instead, so prompt cost is constant no matter how many
+ * skills a workspace has.
+ *
+ * Availability (`isAvailable` / `minModelTier`) is resolved HERE rather than at
+ * prompt-assembly time, which means an integration that connects mid-run shows
+ * up on the next search instead of being frozen out for the whole invoke.
+ */
+declare function createSearchSkillsTool(deps: SkillToolDeps): ToolInterface;
 declare function createOpenSkillTool(deps: SkillToolDeps): ToolInterface;
 declare function createBindSkillToolsTool(deps: SkillToolDeps): ToolInterface;
-/** Both skill tools for an invoke, sharing one registry ref. */
+/**
+ * The skill meta-tools for an invoke, sharing one registry ref. `search_skills`
+ * is only wired under `disclosure: "search"` — in catalog mode the headers are
+ * already in the prompt and a search tool would be pure overhead.
+ */
 declare function createSkillTools(deps: SkillToolDeps): ToolInterface[];
 
 /**
@@ -2468,6 +2522,12 @@ declare function resolveToolApprovalState(state: SmartState, resolution: ToolApp
 
 declare function resolveUserQuestionState(state: SmartState, resolution: UserQuestionResolution): SmartState;
 
+/**
+ * The built-in ask-user tool's name. Exported because more than one layer has to
+ * recognise it: `createSmartAgent` builds the tool into the list it hands to
+ * `createAgent`, which must then not attach a second one of its own.
+ */
+declare const ASK_USER_TOOL_NAME = "ask_user_question";
 type AskUserStateRef = {
     pendingUserQuestions?: PendingUserQuestion[];
     ctx?: Record<string, any>;
@@ -3010,4 +3070,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, tokenize, traceSessionToOtlp, validateReasoningConfig, withTools, withinDepth, writeSummaryFactsToMemory };
+export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, tokenize, traceSessionToOtlp, validateReasoningConfig, withTools, withinDepth, writeSummaryFactsToMemory };

package/dist/index.mjs

@@ -4563,6 +4563,7 @@ function resolveUserQuestionState(state, resolution) {
     ctx
   };
 }
+var ASK_USER_TOOL_NAME = "ask_user_question";
 var DEFAULT_DESCRIPTION_WITH_FREETEXT = "Pause the agent and surface a structured prompt to the human user when you genuinely cannot proceed without their input. Group up to 4 closely related questions into a single call. Prefer concrete options the user can pick over open-ended free-text \u2014 list `options` whenever you can anticipate the choices. The user may type a custom answer for any question. Do not use this tool for things you can deduce from the conversation, the system prompt, or another tool. After the user answers, their selections come back as the tool result.";
 var DEFAULT_DESCRIPTION_NO_FREETEXT = "Pause the agent and surface a structured multi-choice prompt to the human user when you genuinely cannot proceed without their input. Group up to 4 closely related questions into a single call. Every question MUST include at least two `options` \u2014 free-text answers are disabled for this agent. Do not use this tool for things you can deduce from the conversation, the system prompt, or another tool. After the user picks, their selections come back as the tool result.";
 function buildOptionSchema() {
@@ -4598,7 +4599,7 @@ function createAskUserQuestionTool(stateRef, config) {
   const description = config.promptOverride ?? (allowFreeText ? DEFAULT_DESCRIPTION_WITH_FREETEXT : DEFAULT_DESCRIPTION_NO_FREETEXT);
   const questionSchema = buildQuestionSchema(allowFreeText);
   const askUser = createTool({
-    name: "ask_user_question",
+    name: ASK_USER_TOOL_NAME,
     description,
     schema: z.object({
       questions: z.array(questionSchema).min(1).max(4).describe("1-4 related questions to ask in a single pause.")
@@ -4614,7 +4615,7 @@ function createAskUserQuestionTool(stateRef, config) {
       const entry = {
         id: nanoid(),
         toolCallId,
-        toolName: "ask_user_question",
+        toolName: ASK_USER_TOOL_NAME,
         questions,
         status: "pending",
         requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -4970,14 +4971,15 @@ function createAgent(opts) {
   })();
   const askUserOnQuestion = typeof opts.humanInTheLoop?.askUser === "object" ? opts.humanInTheLoop?.askUser?.onQuestion : void 0;
   const askUserStateRef = askUserConfig ? { pendingUserQuestions: void 0, ctx: void 0, __onEvent: void 0, __currentToolCallId: void 0 } : void 0;
-  if (askUserConfig && askUserStateRef) {
+  const hasTool = (name) => toolsBase.some((tool) => tool?.name === name);
+  if (askUserConfig && askUserStateRef && !hasTool(ASK_USER_TOOL_NAME)) {
     toolsBase.push(createAskUserQuestionTool(askUserStateRef, askUserConfig));
   }
   const soManager = opts.outputSchema ? new StructuredOutputManager(opts.outputSchema, resolveStrategy(opts.model)) : void 0;
   if (soManager) {
     const modelCapabilities = getModelCapabilities(opts.model);
     const responseTool = soManager.getResponseTool();
-    if (responseTool && modelCapabilities.structuredOutput !== "native") {
+    if (responseTool && modelCapabilities.structuredOutput !== "native" && !hasTool(responseTool.name)) {
       toolsBase.push(responseTool);
     }
   }
@@ -6910,6 +6912,42 @@ async function resolveAvailableSkills(skills, opts = {}) {
   }
   return out;
 }
+var WORD_SPLIT = /[^\p{L}\p{N}]+/u;
+var MIN_TERM_LENGTH = 3;
+var FIELD_WEIGHTS = { key: 4, title: 3, header: 2 };
+var wordsOf = (text) => text.toLowerCase().split(WORD_SPLIT).filter((word) => word.length >= 2);
+var termHitsWord = (term, word) => word === term || word.startsWith(term) || word.length >= 3 && term.startsWith(word) || term.length >= 5 && word.length >= 5 && word.slice(0, 4) === term.slice(0, 4);
+function searchSkills(skills, query, limit = 10) {
+  const cap = Math.max(1, limit);
+  const normalized = (query || "").trim().toLowerCase();
+  const terms = [
+    ...new Set(normalized.split(WORD_SPLIT).filter((term) => term.length >= MIN_TERM_LENGTH))
+  ];
+  if (terms.length === 0) return skills.slice(0, cap);
+  const scored = skills.map((skill, index) => {
+    const fields = {
+      key: wordsOf(skill.key),
+      title: wordsOf(skill.title || ""),
+      header: wordsOf(skill.header || "")
+    };
+    const exact = skill.key.toLowerCase() === normalized || (skill.title || "").toLowerCase() === normalized;
+    let score = exact ? 100 : 0;
+    let coverage = 0;
+    for (const term of terms) {
+      let hit = false;
+      for (const [field, weight] of Object.entries(FIELD_WEIGHTS)) {
+        if (fields[field].some((word) => termHitsWord(term, word))) {
+          score += weight;
+          hit = true;
+        }
+      }
+      if (hit) coverage += 1;
+    }
+    return { skill, score, coverage, index };
+  }).filter((entry) => entry.score > 0);
+  scored.sort((a, b) => b.coverage - a.coverage || b.score - a.score || a.index - b.index);
+  return scored.slice(0, cap).map((entry) => entry.skill);
+}
 function buildSkillHeaderBlock(skills) {
   if (skills.length === 0) return "";
   const lines = skills.map((skill) => `- ${skill.key}: ${skill.header}`);
@@ -6933,24 +6971,65 @@ function dedupeToolsByName(tools) {
 
 // src/smart/skills/skillTools.ts
 var MAX_RETURNED_INDEX = 40;
-var OPEN_SKILL_DESCRIPTION = "Load a capability on demand. Pass a skillKey from <available_skills>. A small skill binds all its tools immediately; a large one returns a tool index \u2014 then call bind_skill_tools with only the tools you need. Open only what the task needs.";
+var DEFAULT_SEARCH_LIMIT = 10;
+var MAX_SEARCH_LIMIT = 25;
+var isSearchDisclosure = (policy) => policy.disclosure === "search";
+var keySource = (policy) => isSearchDisclosure(policy) ? "search_skills" : "<available_skills>";
+var openSkillDescription = (policy) => `Load a capability on demand. Pass a skillKey from ${keySource(policy)}. A small skill binds all its tools immediately; a large one returns a tool index \u2014 then call bind_skill_tools with only the tools you need. Open only what the task needs.`;
 var BIND_SKILL_TOOLS_DESCRIPTION = "After open_skill on a large skill, bind a chosen subset of its tools by name. Pick the few tools the task actually needs.";
+var SEARCH_SKILLS_DESCRIPTION = 'Find a reusable playbook (a "skill") for the task at hand. Skills are proven, pre-written procedures for specific kinds of work \u2014 each with its own tools, which are NOT in your tool list until you open the skill. Call this early whenever a request looks like an established procedure, or when you seem to be missing a capability you would expect to have: describe the task in `query`. Returns matching skill keys; pass one to open_skill to load its instructions and tools. An empty query lists what exists.';
 function findSkill(deps, key) {
   return deps.skills.find((skill) => skill.key === key);
 }
+function createSearchSkillsTool(deps) {
+  const tool = createTool({
+    name: "search_skills",
+    description: SEARCH_SKILLS_DESCRIPTION,
+    schema: z.object({
+      query: z.string().optional().describe("What you are trying to do, in a few words. Omit to list available skills."),
+      limit: z.number().int().positive().optional().describe(`Max results to return (default ${DEFAULT_SEARCH_LIMIT}).`)
+    }).strict(),
+    func: async ({ query, limit }) => {
+      const { skills, policy, registryRef: ref } = tool._deps;
+      const available = await resolveAvailableSkills(skills, { modelTier: policy.modelTier });
+      if (available.length === 0) {
+        return { skills: [], total: 0, hint: "No skills are available in this workspace." };
+      }
+      const capped = Math.min(limit || DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
+      const matches = searchSkills(available, query, capped);
+      const missed = matches.length === 0;
+      const shown = missed ? available.slice(0, capped) : matches;
+      return {
+        skills: shown.map((skill) => ({
+          skillKey: skill.key,
+          title: skill.title,
+          header: skill.header,
+          ...ref.openedSkillKeys.includes(skill.key) ? { alreadyOpen: true } : {}
+        })),
+        total: available.length,
+        hint: missed ? `Nothing matched "${query}" literally \u2014 listing ${shown.length} of ${available.length} instead. Judge them by their headers; call open_skill(skillKey) if one fits, otherwise carry on without a skill.` : "Call open_skill(skillKey) to load the one that fits."
+      };
+    }
+  });
+  tool._deps = deps;
+  tool.__source = "smart-skills";
+  return tool;
+}
 function createOpenSkillTool(deps) {
   const tool = createTool({
     name: "open_skill",
-    description: OPEN_SKILL_DESCRIPTION,
+    description: openSkillDescription(deps.policy),
     schema: z.object({
-      skillKey: z.string().min(1).describe("A key from <available_skills>."),
+      skillKey: z.string().min(1).describe(`A key from ${keySource(deps.policy)}.`),
       query: z.string().optional().describe("What you need from the skill \u2014 used to rank a large skill's tools.")
     }).strict(),
     func: async ({ skillKey, query }) => {
       const { registryRef: ref, policy } = tool._deps;
       const skill = findSkill(tool._deps, skillKey);
       if (!skill) {
-        return { error: `Unknown skill: ${skillKey}. Choose a key listed in <available_skills>.` };
+        return {
+          error: `Unknown skill: ${skillKey}. ${isSearchDisclosure(policy) ? "Call search_skills to get a valid key." : "Choose a key listed in <available_skills>."}`
+        };
       }
       if (skill.isAvailable && !await skill.isAvailable()) {
         return { error: `Skill ${skillKey} is not available in this workspace.` };
@@ -7039,7 +7118,9 @@ function createBindSkillToolsTool(deps) {
   return tool;
 }
 function createSkillTools(deps) {
-  return [createOpenSkillTool(deps), createBindSkillToolsTool(deps)];
+  const tools = [createOpenSkillTool(deps), createBindSkillToolsTool(deps)];
+  if (isSearchDisclosure(deps.policy)) tools.unshift(createSearchSkillsTool(deps));
+  return tools;
 }
 
 // src/smart/subagents/types.ts
@@ -7719,7 +7800,8 @@ function createSmartAgent(opts) {
         if (changed) toolSet.skillRegistryRef.__onToolsChanged?.();
       }
       const syncPlanFromRef = (state2) => syncPlanStateWith(stateRef, state2);
-      const availableSkills = skillsEnabled ? await resolveAvailableSkills(skills, { modelTier: skillPolicy.modelTier }) : [];
+      const catalogDisclosure = skillPolicy.disclosure !== "search";
+      const availableSkills = skillsEnabled && catalogDisclosure ? await resolveAvailableSkills(skills, { modelTier: skillPolicy.modelTier }) : [];
       const skillBlock = availableSkills.length > 0 ? buildSkillHeaderBlock(availableSkills) : void 0;
       let subagentBlock;
       if (subagentsEnabled) {
@@ -10937,6 +11019,6 @@ function createProvider(config) {
   }
 }
 
-export { AnthropicProvider, AzureProvider, BaseProvider, BedrockProvider, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DedupTracker, GuardrailPhase, InMemoryMemoryStore, NativeJsonSchemaStrategy, OpenAICompatibleProvider, OpenAIProvider, ProviderError, SMALL_TIER_SKILL_POLICY, StructuredOutputManager, ToolBasedStrategy, VertexProvider, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, tokenize, traceSessionToOtlp, validateReasoningConfig, withTools, withinDepth, writeSummaryFactsToMemory };
+export { ASK_USER_TOOL_NAME, AnthropicProvider, AzureProvider, BaseProvider, BedrockProvider, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DedupTracker, GuardrailPhase, InMemoryMemoryStore, NativeJsonSchemaStrategy, OpenAICompatibleProvider, OpenAIProvider, ProviderError, SMALL_TIER_SKILL_POLICY, StructuredOutputManager, ToolBasedStrategy, VertexProvider, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, tokenize, traceSessionToOtlp, validateReasoningConfig, withTools, withinDepth, writeSummaryFactsToMemory };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map