@cognipeer/agent-sdk 0.7.1 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -107,6 +107,71 @@ declare function withTools(model: SmartModel, tools: any[], options?: {
107
107
  }): BaseChatModel;
108
108
  declare function fromLangchainModel(lcModel: any): BaseChatModel;
109
109
 
110
+ /**
111
+ * Skill primitive — progressive capability disclosure for the smart agent.
112
+ *
113
+ * A Skill is a lazy, self-contained capability bundle. The model always sees a
114
+ * cheap one-line `header`; it calls `open_skill(key)` to load the skill's prompt
115
+ * and (for small skills) bind its tools, or `bind_skill_tools(key, names)` to
116
+ * bind a chosen subset of a fat skill. This keeps the number of bound tools per
117
+ * step small — the property small models need — and replaces an up-front
118
+ * tool-selector pass with on-demand disclosure.
119
+ */
120
+ type SkillToolHeader = {
121
+ name: string;
122
+ description?: string;
123
+ };
124
+ type SkillModelTier = "small" | "large";
125
+ type Skill = {
126
+ /** Stable key, e.g. "mcp:atlassian" | "integration:google" | "builtin:drawio". */
127
+ key: string;
128
+ title: string;
129
+ /** One-line "what + when to use" the model always sees in the catalog. */
130
+ header: string;
131
+ /** Injected (as the open_skill result) only after the skill is opened. */
132
+ prompt: string | (() => Promise<string> | string);
133
+ /** When true, opening this skill should trigger sandbox bootstrap. */
134
+ needsSandbox?: boolean;
135
+ /** Gate: a "large"-only skill is hidden from a small-tier model. */
136
+ minModelTier?: SkillModelTier;
137
+ /** Whether the skill is usable in the current workspace (integration connected, etc.). */
138
+ isAvailable?: () => boolean | Promise<boolean>;
139
+ /** Cheap list of the skill's tool headers (names + one-liners). */
140
+ listToolIndex: () => Promise<SkillToolHeader[]> | SkillToolHeader[];
141
+ /** Bind concrete tools. With no names, bind the whole (small) skill. */
142
+ bindTools: (names?: string[]) => Promise<ToolInterface[]> | ToolInterface[];
143
+ /** Optional embedding/heuristic ranking of tool headers for a fat skill. */
144
+ rankToolHeaders?: (query: string, headers: SkillToolHeader[]) => Promise<SkillToolHeader[]> | SkillToolHeader[];
145
+ /** Deterministic floor: tools to bind when a weak model gives no usable query. */
146
+ defaultBindNames?: string[];
147
+ };
148
+ type SkillPolicy = {
149
+ /** Max distinct skills open at once (small tier should be 1). */
150
+ maxOpenSkills: number;
151
+ /** Max tools bound from a single skill in one bind call. */
152
+ maxBoundToolsPerSkill: number;
153
+ /** Overall cap on skill-bound tools across the whole run. */
154
+ maxBoundToolsTotal: number;
155
+ /** Current model tier; gates `minModelTier`. */
156
+ modelTier?: SkillModelTier;
157
+ };
158
+ declare const DEFAULT_SKILL_POLICY: SkillPolicy;
159
+ declare const SMALL_TIER_SKILL_POLICY: SkillPolicy;
160
+ /**
161
+ * Mutable per-invoke registry. The skill tools mutate this ref (append-only) and
162
+ * call `__onToolsChanged` so the runtime can rebuild its tool sets. Mirrors the
163
+ * stateRef pattern used by createAskUserQuestionTool.
164
+ */
165
+ type SkillRegistryRef = {
166
+ /** Append-only: skills the model has opened this run. */
167
+ openedSkillKeys: string[];
168
+ /** Append-only, deduped by tool name: tools bound from opened skills. */
169
+ boundSkillTools: ToolInterface[];
170
+ /** Rebuild hook wired by createSmartAgent; rebuilds both recovery variants. */
171
+ __onToolsChanged?: () => void;
172
+ };
173
+ declare function createSkillRegistryRef(): SkillRegistryRef;
174
+
110
175
  type ImageURL = {
111
176
  url: string;
112
177
  detail?: 'auto' | 'low' | 'high';
@@ -577,6 +642,15 @@ type SmartAgentOptions = {
577
642
  costEstimator?: AgentOptions["costEstimator"];
578
643
  /** See AgentOptions.humanInTheLoop. */
579
644
  humanInTheLoop?: HumanInTheLoopOptions;
645
+ /**
646
+ * Progressive capability disclosure. When provided, the agent exposes cheap
647
+ * skill headers in its system prompt and binds a skill's tools on demand via
648
+ * the built-in open_skill / bind_skill_tools tools. Keeps the bound-tool count
649
+ * per step small. An empty array is a no-op.
650
+ */
651
+ skills?: Skill[];
652
+ /** Caps/tiering for skill disclosure. Defaults to DEFAULT_SKILL_POLICY. */
653
+ skillPolicy?: SkillPolicy;
580
654
  };
581
655
  type AgentRuntimeConfig = {
582
656
  name?: string;
@@ -1449,6 +1523,58 @@ declare function createSmartAgent<TOutput = unknown>(opts: SmartAgentOptions & {
1449
1523
  outputSchema?: ZodSchema<TOutput>;
1450
1524
  }): SmartAgentInstance<TOutput>;
1451
1525
 
1526
+ /**
1527
+ * Pure registry helpers for the skill primitive. No I/O, no agent loop — these
1528
+ * are the deterministic core, fully unit-testable on their own.
1529
+ */
1530
+ /**
1531
+ * Rebuild BOTH runtime tool-set variants with fresh array references.
1532
+ *
1533
+ * This is the heart of mid-run skill binding. `syncRuntimeTools` swaps between
1534
+ * two PRE-COMPUTED arrays and short-circuits on `currentRuntime.tools ===
1535
+ * nextTools`. So to make newly-bound skill tools take effect we must hand back
1536
+ * NEW array references (breaking the `===` short-circuit) AND include the skill
1537
+ * tools in the recovery variant too (otherwise a recovery-swap iteration would
1538
+ * silently drop them).
1539
+ */
1540
+ declare function composeToolSets(input: {
1541
+ base: ToolInterface[];
1542
+ boundSkillTools: ToolInterface[];
1543
+ recoveryTool?: ToolInterface;
1544
+ }): {
1545
+ toolsWithoutRecovery: ToolInterface[];
1546
+ toolsWithRecovery: ToolInterface[];
1547
+ };
1548
+ /**
1549
+ * Append tools to the registry, append-only and deduped by name, honoring the
1550
+ * overall total cap. Returns the tools actually added (may be fewer than asked).
1551
+ */
1552
+ declare function appendBoundTools(ref: SkillRegistryRef, newTools: ToolInterface[], policy: Pick<SkillPolicy, "maxBoundToolsTotal">): ToolInterface[];
1553
+ /** Precedence guard: may the model open another (not-yet-open) skill? */
1554
+ declare function canOpenSkill(ref: SkillRegistryRef, policy: SkillPolicy): {
1555
+ ok: true;
1556
+ } | {
1557
+ ok: false;
1558
+ reason: string;
1559
+ };
1560
+ /** Filter the catalog to skills usable now: available + tier-gated. */
1561
+ declare function resolveAvailableSkills(skills: Skill[], opts?: {
1562
+ modelTier?: SkillPolicy["modelTier"];
1563
+ }): Promise<Skill[]>;
1564
+ /** The cheap header block the model always sees in its system prompt. */
1565
+ declare function buildSkillHeaderBlock(skills: Skill[]): string;
1566
+ declare function dedupeToolsByName(tools: ToolInterface[]): ToolInterface[];
1567
+
1568
+ type SkillToolDeps = {
1569
+ registryRef: SkillRegistryRef;
1570
+ skills: Skill[];
1571
+ policy: SkillPolicy;
1572
+ };
1573
+ declare function createOpenSkillTool(deps: SkillToolDeps): ToolInterface;
1574
+ declare function createBindSkillToolsTool(deps: SkillToolDeps): ToolInterface;
1575
+ /** Both skill tools for an invoke, sharing one registry ref. */
1576
+ declare function createSkillTools(deps: SkillToolDeps): ToolInterface[];
1577
+
1452
1578
  type EvalHarnessParams = {
1453
1579
  profiles: EvalProfileTarget[];
1454
1580
  cases: EvalCase[];
@@ -2113,6 +2239,18 @@ declare class AnthropicProvider extends BaseProvider {
2113
2239
  completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
2114
2240
  private buildRequestBody;
2115
2241
  private splitSystemMessages;
2242
+ /**
2243
+ * Converts unified messages to Anthropic format, coalescing consecutive
2244
+ * tool-result messages into a single `user` turn.
2245
+ *
2246
+ * The unified message list carries one `role: "tool"` entry per tool call
2247
+ * (mirroring OpenAI's shape). Anthropic's Messages API expects every
2248
+ * `tool_result` block answering a single assistant turn's `tool_use`
2249
+ * block(s) to be batched into ONE `user` message rather than sent as
2250
+ * separate consecutive `user` messages.
2251
+ */
2252
+ private toAnthropicMessages;
2253
+ private toAnthropicToolResult;
2116
2254
  private toAnthropicMessage;
2117
2255
  private toAnthropicTool;
2118
2256
  private doFetch;
@@ -2150,6 +2288,19 @@ declare class BedrockProvider extends BaseProvider {
2150
2288
  completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
2151
2289
  private buildConverseBody;
2152
2290
  private splitSystemMessages;
2291
+ /**
2292
+ * Converts unified messages to Bedrock Converse format, coalescing
2293
+ * consecutive tool-result messages into a single `user` turn.
2294
+ *
2295
+ * The unified message list carries one `role: "tool"` entry per tool call
2296
+ * (mirroring OpenAI's shape). Bedrock's Converse API requires every
2297
+ * `toolResult` block answering a single assistant turn's `toolUse`
2298
+ * block(s) to be batched into ONE `user` message — sending them as
2299
+ * separate consecutive `user` messages triggers: "Expected toolResult
2300
+ * blocks at messages.N.content for the following Ids: ...".
2301
+ */
2302
+ private toBedrockMessages;
2303
+ private toBedrockToolResult;
2153
2304
  private toBedrockMessage;
2154
2305
  private toBedrockTool;
2155
2306
  private doFetch;
@@ -2171,6 +2322,7 @@ declare class VertexProvider extends BaseProvider {
2171
2322
  private buildUrl;
2172
2323
  private buildGeminiBody;
2173
2324
  private buildContents;
2325
+ private toGeminiFunctionResponsePart;
2174
2326
  private toGeminiContent;
2175
2327
  private toGeminiTool;
2176
2328
  private getAccessToken;
@@ -2228,4 +2380,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
2228
2380
  */
2229
2381
  declare function createProvider(config: ProviderConfig): BaseProvider;
2230
2382
 
2231
- 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 };
2383
+ 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 CHANGED
@@ -107,6 +107,71 @@ declare function withTools(model: SmartModel, tools: any[], options?: {
107
107
  }): BaseChatModel;
108
108
  declare function fromLangchainModel(lcModel: any): BaseChatModel;
109
109
 
110
+ /**
111
+ * Skill primitive — progressive capability disclosure for the smart agent.
112
+ *
113
+ * A Skill is a lazy, self-contained capability bundle. The model always sees a
114
+ * cheap one-line `header`; it calls `open_skill(key)` to load the skill's prompt
115
+ * and (for small skills) bind its tools, or `bind_skill_tools(key, names)` to
116
+ * bind a chosen subset of a fat skill. This keeps the number of bound tools per
117
+ * step small — the property small models need — and replaces an up-front
118
+ * tool-selector pass with on-demand disclosure.
119
+ */
120
+ type SkillToolHeader = {
121
+ name: string;
122
+ description?: string;
123
+ };
124
+ type SkillModelTier = "small" | "large";
125
+ type Skill = {
126
+ /** Stable key, e.g. "mcp:atlassian" | "integration:google" | "builtin:drawio". */
127
+ key: string;
128
+ title: string;
129
+ /** One-line "what + when to use" the model always sees in the catalog. */
130
+ header: string;
131
+ /** Injected (as the open_skill result) only after the skill is opened. */
132
+ prompt: string | (() => Promise<string> | string);
133
+ /** When true, opening this skill should trigger sandbox bootstrap. */
134
+ needsSandbox?: boolean;
135
+ /** Gate: a "large"-only skill is hidden from a small-tier model. */
136
+ minModelTier?: SkillModelTier;
137
+ /** Whether the skill is usable in the current workspace (integration connected, etc.). */
138
+ isAvailable?: () => boolean | Promise<boolean>;
139
+ /** Cheap list of the skill's tool headers (names + one-liners). */
140
+ listToolIndex: () => Promise<SkillToolHeader[]> | SkillToolHeader[];
141
+ /** Bind concrete tools. With no names, bind the whole (small) skill. */
142
+ bindTools: (names?: string[]) => Promise<ToolInterface[]> | ToolInterface[];
143
+ /** Optional embedding/heuristic ranking of tool headers for a fat skill. */
144
+ rankToolHeaders?: (query: string, headers: SkillToolHeader[]) => Promise<SkillToolHeader[]> | SkillToolHeader[];
145
+ /** Deterministic floor: tools to bind when a weak model gives no usable query. */
146
+ defaultBindNames?: string[];
147
+ };
148
+ type SkillPolicy = {
149
+ /** Max distinct skills open at once (small tier should be 1). */
150
+ maxOpenSkills: number;
151
+ /** Max tools bound from a single skill in one bind call. */
152
+ maxBoundToolsPerSkill: number;
153
+ /** Overall cap on skill-bound tools across the whole run. */
154
+ maxBoundToolsTotal: number;
155
+ /** Current model tier; gates `minModelTier`. */
156
+ modelTier?: SkillModelTier;
157
+ };
158
+ declare const DEFAULT_SKILL_POLICY: SkillPolicy;
159
+ declare const SMALL_TIER_SKILL_POLICY: SkillPolicy;
160
+ /**
161
+ * Mutable per-invoke registry. The skill tools mutate this ref (append-only) and
162
+ * call `__onToolsChanged` so the runtime can rebuild its tool sets. Mirrors the
163
+ * stateRef pattern used by createAskUserQuestionTool.
164
+ */
165
+ type SkillRegistryRef = {
166
+ /** Append-only: skills the model has opened this run. */
167
+ openedSkillKeys: string[];
168
+ /** Append-only, deduped by tool name: tools bound from opened skills. */
169
+ boundSkillTools: ToolInterface[];
170
+ /** Rebuild hook wired by createSmartAgent; rebuilds both recovery variants. */
171
+ __onToolsChanged?: () => void;
172
+ };
173
+ declare function createSkillRegistryRef(): SkillRegistryRef;
174
+
110
175
  type ImageURL = {
111
176
  url: string;
112
177
  detail?: 'auto' | 'low' | 'high';
@@ -577,6 +642,15 @@ type SmartAgentOptions = {
577
642
  costEstimator?: AgentOptions["costEstimator"];
578
643
  /** See AgentOptions.humanInTheLoop. */
579
644
  humanInTheLoop?: HumanInTheLoopOptions;
645
+ /**
646
+ * Progressive capability disclosure. When provided, the agent exposes cheap
647
+ * skill headers in its system prompt and binds a skill's tools on demand via
648
+ * the built-in open_skill / bind_skill_tools tools. Keeps the bound-tool count
649
+ * per step small. An empty array is a no-op.
650
+ */
651
+ skills?: Skill[];
652
+ /** Caps/tiering for skill disclosure. Defaults to DEFAULT_SKILL_POLICY. */
653
+ skillPolicy?: SkillPolicy;
580
654
  };
581
655
  type AgentRuntimeConfig = {
582
656
  name?: string;
@@ -1449,6 +1523,58 @@ declare function createSmartAgent<TOutput = unknown>(opts: SmartAgentOptions & {
1449
1523
  outputSchema?: ZodSchema<TOutput>;
1450
1524
  }): SmartAgentInstance<TOutput>;
1451
1525
 
1526
+ /**
1527
+ * Pure registry helpers for the skill primitive. No I/O, no agent loop — these
1528
+ * are the deterministic core, fully unit-testable on their own.
1529
+ */
1530
+ /**
1531
+ * Rebuild BOTH runtime tool-set variants with fresh array references.
1532
+ *
1533
+ * This is the heart of mid-run skill binding. `syncRuntimeTools` swaps between
1534
+ * two PRE-COMPUTED arrays and short-circuits on `currentRuntime.tools ===
1535
+ * nextTools`. So to make newly-bound skill tools take effect we must hand back
1536
+ * NEW array references (breaking the `===` short-circuit) AND include the skill
1537
+ * tools in the recovery variant too (otherwise a recovery-swap iteration would
1538
+ * silently drop them).
1539
+ */
1540
+ declare function composeToolSets(input: {
1541
+ base: ToolInterface[];
1542
+ boundSkillTools: ToolInterface[];
1543
+ recoveryTool?: ToolInterface;
1544
+ }): {
1545
+ toolsWithoutRecovery: ToolInterface[];
1546
+ toolsWithRecovery: ToolInterface[];
1547
+ };
1548
+ /**
1549
+ * Append tools to the registry, append-only and deduped by name, honoring the
1550
+ * overall total cap. Returns the tools actually added (may be fewer than asked).
1551
+ */
1552
+ declare function appendBoundTools(ref: SkillRegistryRef, newTools: ToolInterface[], policy: Pick<SkillPolicy, "maxBoundToolsTotal">): ToolInterface[];
1553
+ /** Precedence guard: may the model open another (not-yet-open) skill? */
1554
+ declare function canOpenSkill(ref: SkillRegistryRef, policy: SkillPolicy): {
1555
+ ok: true;
1556
+ } | {
1557
+ ok: false;
1558
+ reason: string;
1559
+ };
1560
+ /** Filter the catalog to skills usable now: available + tier-gated. */
1561
+ declare function resolveAvailableSkills(skills: Skill[], opts?: {
1562
+ modelTier?: SkillPolicy["modelTier"];
1563
+ }): Promise<Skill[]>;
1564
+ /** The cheap header block the model always sees in its system prompt. */
1565
+ declare function buildSkillHeaderBlock(skills: Skill[]): string;
1566
+ declare function dedupeToolsByName(tools: ToolInterface[]): ToolInterface[];
1567
+
1568
+ type SkillToolDeps = {
1569
+ registryRef: SkillRegistryRef;
1570
+ skills: Skill[];
1571
+ policy: SkillPolicy;
1572
+ };
1573
+ declare function createOpenSkillTool(deps: SkillToolDeps): ToolInterface;
1574
+ declare function createBindSkillToolsTool(deps: SkillToolDeps): ToolInterface;
1575
+ /** Both skill tools for an invoke, sharing one registry ref. */
1576
+ declare function createSkillTools(deps: SkillToolDeps): ToolInterface[];
1577
+
1452
1578
  type EvalHarnessParams = {
1453
1579
  profiles: EvalProfileTarget[];
1454
1580
  cases: EvalCase[];
@@ -2113,6 +2239,18 @@ declare class AnthropicProvider extends BaseProvider {
2113
2239
  completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
2114
2240
  private buildRequestBody;
2115
2241
  private splitSystemMessages;
2242
+ /**
2243
+ * Converts unified messages to Anthropic format, coalescing consecutive
2244
+ * tool-result messages into a single `user` turn.
2245
+ *
2246
+ * The unified message list carries one `role: "tool"` entry per tool call
2247
+ * (mirroring OpenAI's shape). Anthropic's Messages API expects every
2248
+ * `tool_result` block answering a single assistant turn's `tool_use`
2249
+ * block(s) to be batched into ONE `user` message rather than sent as
2250
+ * separate consecutive `user` messages.
2251
+ */
2252
+ private toAnthropicMessages;
2253
+ private toAnthropicToolResult;
2116
2254
  private toAnthropicMessage;
2117
2255
  private toAnthropicTool;
2118
2256
  private doFetch;
@@ -2150,6 +2288,19 @@ declare class BedrockProvider extends BaseProvider {
2150
2288
  completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
2151
2289
  private buildConverseBody;
2152
2290
  private splitSystemMessages;
2291
+ /**
2292
+ * Converts unified messages to Bedrock Converse format, coalescing
2293
+ * consecutive tool-result messages into a single `user` turn.
2294
+ *
2295
+ * The unified message list carries one `role: "tool"` entry per tool call
2296
+ * (mirroring OpenAI's shape). Bedrock's Converse API requires every
2297
+ * `toolResult` block answering a single assistant turn's `toolUse`
2298
+ * block(s) to be batched into ONE `user` message — sending them as
2299
+ * separate consecutive `user` messages triggers: "Expected toolResult
2300
+ * blocks at messages.N.content for the following Ids: ...".
2301
+ */
2302
+ private toBedrockMessages;
2303
+ private toBedrockToolResult;
2153
2304
  private toBedrockMessage;
2154
2305
  private toBedrockTool;
2155
2306
  private doFetch;
@@ -2171,6 +2322,7 @@ declare class VertexProvider extends BaseProvider {
2171
2322
  private buildUrl;
2172
2323
  private buildGeminiBody;
2173
2324
  private buildContents;
2325
+ private toGeminiFunctionResponsePart;
2174
2326
  private toGeminiContent;
2175
2327
  private toGeminiTool;
2176
2328
  private getAccessToken;
@@ -2228,4 +2380,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
2228
2380
  */
2229
2381
  declare function createProvider(config: ProviderConfig): BaseProvider;
2230
2382
 
2231
- 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 };
2383
+ 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 };