@cognipeer/agent-sdk 0.7.1 → 0.7.2

package/dist/index.d.cts

@@ -107,6 +107,71 @@ declare function withTools(model: SmartModel, tools: any[], options?: {
 }): BaseChatModel;
 declare function fromLangchainModel(lcModel: any): BaseChatModel;
 
+/**
+ * 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.
+ */
+type SkillToolHeader = {
+    name: string;
+    description?: string;
+};
+type SkillModelTier = "small" | "large";
+type Skill = {
+    /** Stable key, e.g. "mcp:atlassian" | "integration:google" | "builtin:drawio". */
+    key: string;
+    title: string;
+    /** One-line "what + when to use" the model always sees in the catalog. */
+    header: string;
+    /** Injected (as the open_skill result) only after the skill is opened. */
+    prompt: string | (() => Promise<string> | string);
+    /** When true, opening this skill should trigger sandbox bootstrap. */
+    needsSandbox?: boolean;
+    /** Gate: a "large"-only skill is hidden from a small-tier model. */
+    minModelTier?: SkillModelTier;
+    /** Whether the skill is usable in the current workspace (integration connected, etc.). */
+    isAvailable?: () => boolean | Promise<boolean>;
+    /** Cheap list of the skill's tool headers (names + one-liners). */
+    listToolIndex: () => Promise<SkillToolHeader[]> | SkillToolHeader[];
+    /** Bind concrete tools. With no names, bind the whole (small) skill. */
+    bindTools: (names?: string[]) => Promise<ToolInterface[]> | ToolInterface[];
+    /** Optional embedding/heuristic ranking of tool headers for a fat skill. */
+    rankToolHeaders?: (query: string, headers: SkillToolHeader[]) => Promise<SkillToolHeader[]> | SkillToolHeader[];
+    /** Deterministic floor: tools to bind when a weak model gives no usable query. */
+    defaultBindNames?: string[];
+};
+type SkillPolicy = {
+    /** Max distinct skills open at once (small tier should be 1). */
+    maxOpenSkills: number;
+    /** Max tools bound from a single skill in one bind call. */
+    maxBoundToolsPerSkill: number;
+    /** Overall cap on skill-bound tools across the whole run. */
+    maxBoundToolsTotal: number;
+    /** Current model tier; gates `minModelTier`. */
+    modelTier?: SkillModelTier;
+};
+declare const DEFAULT_SKILL_POLICY: SkillPolicy;
+declare const SMALL_TIER_SKILL_POLICY: SkillPolicy;
+/**
+ * Mutable per-invoke registry. The skill tools mutate this ref (append-only) and
+ * call `__onToolsChanged` so the runtime can rebuild its tool sets. Mirrors the
+ * stateRef pattern used by createAskUserQuestionTool.
+ */
+type SkillRegistryRef = {
+    /** Append-only: skills the model has opened this run. */
+    openedSkillKeys: string[];
+    /** Append-only, deduped by tool name: tools bound from opened skills. */
+    boundSkillTools: ToolInterface[];
+    /** Rebuild hook wired by createSmartAgent; rebuilds both recovery variants. */
+    __onToolsChanged?: () => void;
+};
+declare function createSkillRegistryRef(): SkillRegistryRef;
+
 type ImageURL = {
     url: string;
     detail?: 'auto' | 'low' | 'high';
@@ -577,6 +642,15 @@ type SmartAgentOptions = {
     costEstimator?: AgentOptions["costEstimator"];
     /** 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.
+     */
+    skills?: Skill[];
+    /** Caps/tiering for skill disclosure. Defaults to DEFAULT_SKILL_POLICY. */
+    skillPolicy?: SkillPolicy;
 };
 type AgentRuntimeConfig = {
     name?: string;
@@ -1449,6 +1523,58 @@ declare function createSmartAgent<TOutput = unknown>(opts: SmartAgentOptions & {
     outputSchema?: ZodSchema<TOutput>;
 }): SmartAgentInstance<TOutput>;
 
+/**
+ * Pure registry helpers for the skill primitive. No I/O, no agent loop — these
+ * are the deterministic core, fully unit-testable on their own.
+ */
+/**
+ * Rebuild BOTH runtime tool-set variants with fresh array references.
+ *
+ * This is the heart of mid-run skill binding. `syncRuntimeTools` swaps between
+ * two PRE-COMPUTED arrays and short-circuits on `currentRuntime.tools ===
+ * nextTools`. So to make newly-bound skill tools take effect we must hand back
+ * NEW array references (breaking the `===` short-circuit) AND include the skill
+ * tools in the recovery variant too (otherwise a recovery-swap iteration would
+ * silently drop them).
+ */
+declare function composeToolSets(input: {
+    base: ToolInterface[];
+    boundSkillTools: ToolInterface[];
+    recoveryTool?: ToolInterface;
+}): {
+    toolsWithoutRecovery: ToolInterface[];
+    toolsWithRecovery: ToolInterface[];
+};
+/**
+ * Append tools to the registry, append-only and deduped by name, honoring the
+ * overall total cap. Returns the tools actually added (may be fewer than asked).
+ */
+declare function appendBoundTools(ref: SkillRegistryRef, newTools: ToolInterface[], policy: Pick<SkillPolicy, "maxBoundToolsTotal">): ToolInterface[];
+/** Precedence guard: may the model open another (not-yet-open) skill? */
+declare function canOpenSkill(ref: SkillRegistryRef, policy: SkillPolicy): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Filter the catalog to skills usable now: available + tier-gated. */
+declare function resolveAvailableSkills(skills: Skill[], opts?: {
+    modelTier?: SkillPolicy["modelTier"];
+}): Promise<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[];
+
+type SkillToolDeps = {
+    registryRef: SkillRegistryRef;
+    skills: Skill[];
+    policy: SkillPolicy;
+};
+declare function createOpenSkillTool(deps: SkillToolDeps): ToolInterface;
+declare function createBindSkillToolsTool(deps: SkillToolDeps): ToolInterface;
+/** Both skill tools for an invoke, sharing one registry ref. */
+declare function createSkillTools(deps: SkillToolDeps): ToolInterface[];
+
 type EvalHarnessParams = {
     profiles: EvalProfileTarget[];
     cases: EvalCase[];
@@ -2228,4 +2354,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, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, 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, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, 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 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 ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, 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 SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, 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, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, validateReasoningConfig, withTools, writeSummaryFactsToMemory };
+export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, 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, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, 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 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 ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, 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 SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, 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, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSystemPrompt, canOpenSkill, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createProvider, createRegexGuardrail, createResolverNode, createSkillRegistryRef, createSkillTools, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveAvailableSkills, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, validateReasoningConfig, withTools, writeSummaryFactsToMemory };

package/dist/index.d.ts

@@ -107,6 +107,71 @@ declare function withTools(model: SmartModel, tools: any[], options?: {
 }): BaseChatModel;
 declare function fromLangchainModel(lcModel: any): BaseChatModel;
 
+/**
+ * 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.
+ */
+type SkillToolHeader = {
+    name: string;
+    description?: string;
+};
+type SkillModelTier = "small" | "large";
+type Skill = {
+    /** Stable key, e.g. "mcp:atlassian" | "integration:google" | "builtin:drawio". */
+    key: string;
+    title: string;
+    /** One-line "what + when to use" the model always sees in the catalog. */
+    header: string;
+    /** Injected (as the open_skill result) only after the skill is opened. */
+    prompt: string | (() => Promise<string> | string);
+    /** When true, opening this skill should trigger sandbox bootstrap. */
+    needsSandbox?: boolean;
+    /** Gate: a "large"-only skill is hidden from a small-tier model. */
+    minModelTier?: SkillModelTier;
+    /** Whether the skill is usable in the current workspace (integration connected, etc.). */
+    isAvailable?: () => boolean | Promise<boolean>;
+    /** Cheap list of the skill's tool headers (names + one-liners). */
+    listToolIndex: () => Promise<SkillToolHeader[]> | SkillToolHeader[];
+    /** Bind concrete tools. With no names, bind the whole (small) skill. */
+    bindTools: (names?: string[]) => Promise<ToolInterface[]> | ToolInterface[];
+    /** Optional embedding/heuristic ranking of tool headers for a fat skill. */
+    rankToolHeaders?: (query: string, headers: SkillToolHeader[]) => Promise<SkillToolHeader[]> | SkillToolHeader[];
+    /** Deterministic floor: tools to bind when a weak model gives no usable query. */
+    defaultBindNames?: string[];
+};
+type SkillPolicy = {
+    /** Max distinct skills open at once (small tier should be 1). */
+    maxOpenSkills: number;
+    /** Max tools bound from a single skill in one bind call. */
+    maxBoundToolsPerSkill: number;
+    /** Overall cap on skill-bound tools across the whole run. */
+    maxBoundToolsTotal: number;
+    /** Current model tier; gates `minModelTier`. */
+    modelTier?: SkillModelTier;
+};
+declare const DEFAULT_SKILL_POLICY: SkillPolicy;
+declare const SMALL_TIER_SKILL_POLICY: SkillPolicy;
+/**
+ * Mutable per-invoke registry. The skill tools mutate this ref (append-only) and
+ * call `__onToolsChanged` so the runtime can rebuild its tool sets. Mirrors the
+ * stateRef pattern used by createAskUserQuestionTool.
+ */
+type SkillRegistryRef = {
+    /** Append-only: skills the model has opened this run. */
+    openedSkillKeys: string[];
+    /** Append-only, deduped by tool name: tools bound from opened skills. */
+    boundSkillTools: ToolInterface[];
+    /** Rebuild hook wired by createSmartAgent; rebuilds both recovery variants. */
+    __onToolsChanged?: () => void;
+};
+declare function createSkillRegistryRef(): SkillRegistryRef;
+
 type ImageURL = {
     url: string;
     detail?: 'auto' | 'low' | 'high';
@@ -577,6 +642,15 @@ type SmartAgentOptions = {
     costEstimator?: AgentOptions["costEstimator"];
     /** 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.
+     */
+    skills?: Skill[];
+    /** Caps/tiering for skill disclosure. Defaults to DEFAULT_SKILL_POLICY. */
+    skillPolicy?: SkillPolicy;
 };
 type AgentRuntimeConfig = {
     name?: string;
@@ -1449,6 +1523,58 @@ declare function createSmartAgent<TOutput = unknown>(opts: SmartAgentOptions & {
     outputSchema?: ZodSchema<TOutput>;
 }): SmartAgentInstance<TOutput>;
 
+/**
+ * Pure registry helpers for the skill primitive. No I/O, no agent loop — these
+ * are the deterministic core, fully unit-testable on their own.
+ */
+/**
+ * Rebuild BOTH runtime tool-set variants with fresh array references.
+ *
+ * This is the heart of mid-run skill binding. `syncRuntimeTools` swaps between
+ * two PRE-COMPUTED arrays and short-circuits on `currentRuntime.tools ===
+ * nextTools`. So to make newly-bound skill tools take effect we must hand back
+ * NEW array references (breaking the `===` short-circuit) AND include the skill
+ * tools in the recovery variant too (otherwise a recovery-swap iteration would
+ * silently drop them).
+ */
+declare function composeToolSets(input: {
+    base: ToolInterface[];
+    boundSkillTools: ToolInterface[];
+    recoveryTool?: ToolInterface;
+}): {
+    toolsWithoutRecovery: ToolInterface[];
+    toolsWithRecovery: ToolInterface[];
+};
+/**
+ * Append tools to the registry, append-only and deduped by name, honoring the
+ * overall total cap. Returns the tools actually added (may be fewer than asked).
+ */
+declare function appendBoundTools(ref: SkillRegistryRef, newTools: ToolInterface[], policy: Pick<SkillPolicy, "maxBoundToolsTotal">): ToolInterface[];
+/** Precedence guard: may the model open another (not-yet-open) skill? */
+declare function canOpenSkill(ref: SkillRegistryRef, policy: SkillPolicy): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Filter the catalog to skills usable now: available + tier-gated. */
+declare function resolveAvailableSkills(skills: Skill[], opts?: {
+    modelTier?: SkillPolicy["modelTier"];
+}): Promise<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[];
+
+type SkillToolDeps = {
+    registryRef: SkillRegistryRef;
+    skills: Skill[];
+    policy: SkillPolicy;
+};
+declare function createOpenSkillTool(deps: SkillToolDeps): ToolInterface;
+declare function createBindSkillToolsTool(deps: SkillToolDeps): ToolInterface;
+/** Both skill tools for an invoke, sharing one registry ref. */
+declare function createSkillTools(deps: SkillToolDeps): ToolInterface[];
+
 type EvalHarnessParams = {
     profiles: EvalProfileTarget[];
     cases: EvalCase[];
@@ -2228,4 +2354,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, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, 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, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, 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 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 ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, 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 SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, 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, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, validateReasoningConfig, withTools, writeSummaryFactsToMemory };
+export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, 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, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, 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 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 ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, 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 SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, 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, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSystemPrompt, canOpenSkill, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createProvider, createRegexGuardrail, createResolverNode, createSkillRegistryRef, createSkillTools, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveAvailableSkills, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, validateReasoningConfig, withTools, writeSummaryFactsToMemory };

package/dist/index.mjs

@@ -3026,6 +3026,17 @@ function createToolsNode(initialTools, opts) {
         }
         const durationMs = Date.now() - start;
         const executionId = nanoid();
+        if (output && typeof output === "object" && Array.isArray(output.__runtimeToolsDelta)) {
+          const delta = output.__runtimeToolsDelta;
+          delete output.__runtimeToolsDelta;
+          const currentRuntime = state.agent || runtime;
+          const currentTools = currentRuntime?.tools ?? [];
+          const present = new Set(currentTools.map((tool2) => tool2?.name));
+          const additions = delta.filter((tool2) => tool2 && tool2.name && !present.has(tool2.name));
+          if (additions.length > 0 && currentRuntime) {
+            state.agent = { ...currentRuntime, tools: [...currentTools, ...additions] };
+          }
+        }
         if (output && typeof output === "object" && output.__handoff && output.__handoff.runtime) {
           toolHistory.push({ executionId, toolName, args, output: "handoff:ok", rawOutput: output, timestamp: (/* @__PURE__ */ new Date()).toISOString(), tool_call_id: tc.id, status: "handoff" });
           push({ role: "tool", content: "ok", tool_call_id: tc.id || `${tc.name}_${toolCount}`, name: tc.name });
@@ -6183,6 +6194,190 @@ async function writeSummaryFactsToMemory(store, config, summary, sourceTurn) {
   return store.get(config.memory.scope, { limit: config.context.lastTurnsToKeep + summary.stable_facts.length });
 }
 
+// src/smart/skills/types.ts
+var DEFAULT_SKILL_POLICY = {
+  maxOpenSkills: 4,
+  maxBoundToolsPerSkill: 12,
+  maxBoundToolsTotal: 40
+};
+var SMALL_TIER_SKILL_POLICY = {
+  maxOpenSkills: 1,
+  maxBoundToolsPerSkill: 6,
+  maxBoundToolsTotal: 18,
+  modelTier: "small"
+};
+function createSkillRegistryRef() {
+  return { openedSkillKeys: [], boundSkillTools: [] };
+}
+
+// src/smart/skills/registry.ts
+function composeToolSets(input) {
+  const without = [...input.base, ...input.boundSkillTools];
+  const withRec = input.recoveryTool ? [...without, input.recoveryTool] : [...without];
+  return { toolsWithoutRecovery: without, toolsWithRecovery: withRec };
+}
+function appendBoundTools(ref, newTools, policy) {
+  const present = new Set(ref.boundSkillTools.map((tool) => tool.name));
+  const added = [];
+  for (const tool of newTools) {
+    if (ref.boundSkillTools.length >= policy.maxBoundToolsTotal) break;
+    if (present.has(tool.name)) continue;
+    present.add(tool.name);
+    ref.boundSkillTools.push(tool);
+    added.push(tool);
+  }
+  return added;
+}
+function canOpenSkill(ref, policy) {
+  if (ref.openedSkillKeys.length >= policy.maxOpenSkills) {
+    return { ok: false, reason: `max ${policy.maxOpenSkills} skill(s) already open` };
+  }
+  if (ref.boundSkillTools.length >= policy.maxBoundToolsTotal) {
+    return { ok: false, reason: "skill tool budget exhausted" };
+  }
+  return { ok: true };
+}
+async function resolveAvailableSkills(skills, opts = {}) {
+  const out = [];
+  for (const skill of skills) {
+    if (skill.minModelTier === "large" && opts.modelTier === "small") continue;
+    const available = skill.isAvailable ? await skill.isAvailable() : true;
+    if (available) out.push(skill);
+  }
+  return out;
+}
+function buildSkillHeaderBlock(skills) {
+  if (skills.length === 0) return "";
+  const lines = skills.map((skill) => `- ${skill.key}: ${skill.header}`);
+  return [
+    "<available_skills>",
+    "Open a skill with open_skill(skillKey) to load its tools on demand. Only open what the task needs; close nothing \u2014 opened skills stay available for the rest of the run.",
+    ...lines,
+    "</available_skills>"
+  ].join("\n");
+}
+function dedupeToolsByName(tools) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const tool of tools) {
+    if (seen.has(tool.name)) continue;
+    seen.add(tool.name);
+    out.push(tool);
+  }
+  return out;
+}
+
+// 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 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.";
+function findSkill(deps, key) {
+  return deps.skills.find((skill) => skill.key === key);
+}
+function createOpenSkillTool(deps) {
+  const tool = createTool({
+    name: "open_skill",
+    description: OPEN_SKILL_DESCRIPTION,
+    schema: z.object({
+      skillKey: z.string().min(1).describe("A key from <available_skills>."),
+      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>.` };
+      }
+      if (skill.isAvailable && !await skill.isAvailable()) {
+        return { error: `Skill ${skillKey} is not available in this workspace.` };
+      }
+      const alreadyOpen = ref.openedSkillKeys.includes(skillKey);
+      if (!alreadyOpen) {
+        const guard = canOpenSkill(ref, policy);
+        if (!guard.ok) {
+          return {
+            error: `Cannot open ${skillKey}: ${guard.reason}. Work with the skills already open.`
+          };
+        }
+        ref.openedSkillKeys.push(skillKey);
+      }
+      const prompt = typeof skill.prompt === "function" ? await skill.prompt() : skill.prompt;
+      const index = await skill.listToolIndex();
+      if (index.length <= policy.maxBoundToolsPerSkill) {
+        const bound = await skill.bindTools();
+        const added = appendBoundTools(ref, bound, policy);
+        if (added.length > 0) ref.__onToolsChanged?.();
+        return {
+          skillKey,
+          prompt,
+          needsSandbox: Boolean(skill.needsSandbox),
+          boundTools: added.map((t) => t.name),
+          // Inject the bound tools into the live runtime for this loop.
+          __runtimeToolsDelta: added
+        };
+      }
+      let defaultBound = [];
+      let defaultAdded = [];
+      if ((!query || query.trim().length < 3) && skill.defaultBindNames?.length) {
+        const bound = await skill.bindTools(skill.defaultBindNames.slice(0, policy.maxBoundToolsPerSkill));
+        defaultAdded = appendBoundTools(ref, bound, policy);
+        if (defaultAdded.length > 0) ref.__onToolsChanged?.();
+        defaultBound = defaultAdded.map((t) => t.name);
+      }
+      const headers = query && query.trim().length >= 3 && skill.rankToolHeaders ? await skill.rankToolHeaders(query, index) : index;
+      return {
+        skillKey,
+        prompt,
+        needsSandbox: Boolean(skill.needsSandbox),
+        boundTools: defaultBound,
+        toolIndex: headers.slice(0, MAX_RETURNED_INDEX).map((h) => ({ name: h.name, description: h.description })),
+        hint: "Call bind_skill_tools(skillKey, toolNames) with only the tools you need.",
+        ...defaultAdded.length > 0 ? { __runtimeToolsDelta: defaultAdded } : {}
+      };
+    }
+  });
+  tool._deps = deps;
+  tool.__source = "smart-skills";
+  return tool;
+}
+function createBindSkillToolsTool(deps) {
+  const tool = createTool({
+    name: "bind_skill_tools",
+    description: BIND_SKILL_TOOLS_DESCRIPTION,
+    schema: z.object({
+      skillKey: z.string().min(1),
+      toolNames: z.array(z.string().min(1)).min(1).describe("Tool names from the skill's index.")
+    }).strict(),
+    func: async ({ skillKey, toolNames }) => {
+      const { registryRef: ref, policy } = tool._deps;
+      const skill = findSkill(tool._deps, skillKey);
+      if (!skill) {
+        return { error: `Unknown skill: ${skillKey}.` };
+      }
+      if (!ref.openedSkillKeys.includes(skillKey)) {
+        return { error: `Call open_skill("${skillKey}") before binding its tools.` };
+      }
+      const capped = toolNames.slice(0, policy.maxBoundToolsPerSkill);
+      const bound = await skill.bindTools(capped);
+      const added = appendBoundTools(ref, bound, policy);
+      if (added.length > 0) ref.__onToolsChanged?.();
+      return {
+        skillKey,
+        boundTools: added.map((t) => t.name),
+        requested: capped.length,
+        truncated: toolNames.length > capped.length,
+        ...added.length > 0 ? { __runtimeToolsDelta: added } : {}
+      };
+    }
+  });
+  tool._deps = deps;
+  tool.__source = "smart-skills";
+  return tool;
+}
+function createSkillTools(deps) {
+  return [createOpenSkillTool(deps), createBindSkillToolsTool(deps)];
+}
+
 // src/smart/index.ts
 function createSmartAgent(opts) {
   const resolved = normalizeSmartAgentOptions(opts);
@@ -6217,6 +6412,9 @@ function createSmartAgent(opts) {
   if (askUserConfig) {
     factoryToolsWithoutRecovery.push(createAskUserQuestionTool(factoryStateRef, askUserConfig));
   }
+  const skills = opts.skills ?? [];
+  const skillPolicy = opts.skillPolicy ?? DEFAULT_SKILL_POLICY;
+  const skillsEnabled = skills.length > 0;
   const soManagerFactory = opts.outputSchema ? new StructuredOutputManager(opts.outputSchema, resolveStrategy(opts.model)) : void 0;
   const modelCapabilities = opts.outputSchema ? getModelCapabilities(opts.model) : void 0;
   const responseFinalizeTool = soManagerFactory && modelCapabilities?.structuredOutput !== "native" ? soManagerFactory.getResponseTool() : void 0;
@@ -6224,12 +6422,31 @@ function createSmartAgent(opts) {
     const ref = { toolHistory: void 0, toolHistoryArchived: void 0, todoList: void 0, planVersion: 0, adherenceScore: 0 };
     const ctxTools = createContextTools(ref, { planningEnabled, includeGetToolResponse: false });
     const recoveryTool = createGetToolResponseTool(ref);
-    const base2 = [...userTools, ...ctxTools];
-    if (responseFinalizeTool) base2.push(responseFinalizeTool);
-    if (askUserConfig) base2.push(createAskUserQuestionTool(ref, askUserConfig));
-    const without = base2;
-    const withRec = [...without, recoveryTool];
-    return { stateRef: ref, toolsWithoutRecovery: without, toolsWithRecovery: withRec };
+    const coreBase = [...userTools, ...ctxTools];
+    if (responseFinalizeTool) coreBase.push(responseFinalizeTool);
+    if (askUserConfig) coreBase.push(createAskUserQuestionTool(ref, askUserConfig));
+    if (!skillsEnabled) {
+      const without = coreBase;
+      const withRec = [...without, recoveryTool];
+      return { stateRef: ref, toolsWithoutRecovery: without, toolsWithRecovery: withRec };
+    }
+    const toolSet = { stateRef: ref, toolsWithoutRecovery: [], toolsWithRecovery: [] };
+    const skillRegistryRef = createSkillRegistryRef();
+    const skillMetaTools = createSkillTools({ registryRef: skillRegistryRef, skills, policy: skillPolicy });
+    const baseWithMeta = [...coreBase, ...skillMetaTools];
+    const rebuild = () => {
+      const composed = composeToolSets({
+        base: baseWithMeta,
+        boundSkillTools: skillRegistryRef.boundSkillTools,
+        recoveryTool
+      });
+      toolSet.toolsWithoutRecovery = composed.toolsWithoutRecovery;
+      toolSet.toolsWithRecovery = composed.toolsWithRecovery;
+    };
+    skillRegistryRef.__onToolsChanged = rebuild;
+    toolSet.skillRegistryRef = skillRegistryRef;
+    rebuild();
+    return toolSet;
   };
   const base = createAgent({ ...runtimeOpts, tools: factoryToolsWithoutRecovery });
   base.__runtime.runtimeProfile = resolved.runtimeProfile;
@@ -6280,9 +6497,9 @@ function createSmartAgent(opts) {
       planVersion: ref.planVersion || state.planVersion || 1
     };
   }
-  function systemMessage2() {
+  function systemMessage2(extraBlock) {
     const sys = buildSystemPrompt(
-      [opts.systemPrompt, runtimeHint, structuredOutputHint].filter(Boolean).join("\n"),
+      [opts.systemPrompt, runtimeHint, structuredOutputHint, extraBlock].filter(Boolean).join("\n"),
       planningEnabled,
       opts.name || "Agent",
       opts.todoListPrompt
@@ -6332,8 +6549,10 @@ function createSmartAgent(opts) {
       stateRef.planVersion = input.planVersion || input.plan?.version || 0;
       stateRef.adherenceScore = input.plan?.adherenceScore || 0;
       const syncPlanFromRef = (state2) => syncPlanStateWith(stateRef, state2);
+      const availableSkills = skillsEnabled ? await resolveAvailableSkills(skills, { modelTier: skillPolicy.modelTier }) : [];
+      const skillBlock = availableSkills.length > 0 ? buildSkillHeaderBlock(availableSkills) : void 0;
       const alreadyHasSystem = Array.isArray(input.messages) && input.messages[0]?.role === "system";
-      const seedMessages = alreadyHasSystem ? [...input.messages || []] : [systemMessage2(), ...input.messages || []];
+      const seedMessages = alreadyHasSystem ? [...input.messages || []] : [systemMessage2(skillBlock), ...input.messages || []];
       let state = syncRuntimeTools(await syncMemory({ ...input, messages: seedMessages }), seedMessages, toolSet);
       let lastResult = null;
       let rawMessages = [...seedMessages];
@@ -9114,6 +9333,6 @@ function createProvider(config) {
   }
 }
 
-export { AnthropicProvider, AzureProvider, BaseProvider, BedrockProvider, DEFAULT_PROFILE_CONFIGS, GuardrailPhase, InMemoryMemoryStore, NativeJsonSchemaStrategy, OpenAICompatibleProvider, OpenAIProvider, ProviderError, StructuredOutputManager, ToolBasedStrategy, VertexProvider, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, validateReasoningConfig, withTools, writeSummaryFactsToMemory };
+export { AnthropicProvider, AzureProvider, BaseProvider, BedrockProvider, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, GuardrailPhase, InMemoryMemoryStore, NativeJsonSchemaStrategy, OpenAICompatibleProvider, OpenAIProvider, ProviderError, SMALL_TIER_SKILL_POLICY, StructuredOutputManager, ToolBasedStrategy, VertexProvider, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSystemPrompt, canOpenSkill, captureSnapshot, codePresenceRule, cognipeerSink, composeToolSets, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createProvider, createRegexGuardrail, createResolverNode, createSkillRegistryRef, createSkillTools, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveAvailableSkills, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, validateReasoningConfig, withTools, writeSummaryFactsToMemory };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map