@cognipeer/agent-sdk 0.8.12 → 0.9.1

package/dist/index.d.cts

@@ -444,14 +444,38 @@ type ContentPart$1 = {
     type: string;
     [key: string]: any;
 };
+/**
+ * Decides, per call, whether this invocation needs human approval.
+ *
+ * Return `true` to pause. Returning a non-boolean is treated as `false` except
+ * for a thrown error, which is treated as `true` — see `needsApproval`.
+ */
+type ToolApprovalPredicate = (args: any) => boolean;
 interface ToolInterface<TInput = any, TOutput = any, TCallOptions = any> {
     name: string;
     description?: string;
     invoke?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     call?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     schema?: any;
-    needsApproval?: boolean;
-    approvalPrompt?: string;
+    /**
+     * Whether a call must pause for a human before it runs.
+     *
+     * A boolean decides for the tool as a whole. A PREDICATE decides per call, with
+     * the parsed arguments in hand — which is the only way to express "ask before
+     * `rm`, but not before `ls`", because the interesting half of a dangerous tool
+     * is usually its arguments, not its name.
+     *
+     * The predicate runs inside the tools node, immediately before the call would
+     * execute, and it must not throw: a predicate that throws is treated as
+     * `true`, because a policy that cannot decide has not granted permission.
+     */
+    needsApproval?: boolean | ToolApprovalPredicate;
+    /**
+     * The text shown to whoever is asked. A function receives the same arguments
+     * the predicate saw, so the prompt can quote what is actually about to happen
+     * ("Delete 3 files under /src?") instead of describing the tool in general.
+     */
+    approvalPrompt?: string | ((args: any) => string | undefined);
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
     /**
@@ -1094,7 +1118,13 @@ type TraceToolDetails = {
     description?: string;
     inputSchema?: any;
     approval?: {
+        /** Set only when the tool answers statically. Absent when `conditional`. */
         required?: boolean;
+        /**
+         * The tool decides per call from its arguments, so no single answer can be
+         * recorded here. The actual verdict for each call is on its approval entry.
+         */
+        conditional?: boolean;
         prompt?: string;
         defaults?: any;
     };
@@ -1775,6 +1805,15 @@ type InvokeConfig = RunnableConfig & {
     limits?: Partial<AgentLimits>;
     onStateChange?: (state: SmartState) => boolean;
     checkpointReason?: string;
+    /**
+     * Keys of `skills` to open deterministically at the start of this invoke,
+     * before the first model call. Each one is opened through the real
+     * `open_skill` tool and written into the transcript as an assistant tool call
+     * plus its tool result, so the model starts the run with the skill's guidance
+     * and tools already bound instead of having to discover them. Unknown or
+     * unavailable keys are skipped. Ignored when the agent has no `skills`.
+     */
+    preopenedSkills?: string[];
 };
 type SnapshotRuntimeHint = {
     name?: string;
@@ -1865,8 +1904,13 @@ declare function createTool({ name, description, schema, func, needsApproval, ap
     description?: string;
     schema: ZodSchema;
     func: SmartToolFn;
-    needsApproval?: boolean;
-    approvalPrompt?: string;
+    /**
+     * `true` gates every call; a predicate gates the calls whose ARGUMENTS
+     * warrant it. See ToolApprovalPredicate.
+     */
+    needsApproval?: boolean | ToolApprovalPredicate;
+    /** A function form receives the call's arguments, so the prompt can quote them. */
+    approvalPrompt?: string | ((args: any) => string | undefined);
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
     /** When set, identical args within the same invoke short-circuit to the cached result. */
@@ -2108,6 +2152,56 @@ declare function parseSkillFrontmatter(md: string): SkillFrontmatter;
  */
 declare function loadSkillsFromDisk(opts: LoadSkillsOptions): Promise<Skill[]>;
 
+/**
+ * Deterministic pre-opening of skills at the start of an invoke.
+ *
+ * Some skills must not depend on the model choosing to discover them — an
+ * organization policy, or the integration a scheduled run is about. Those keys
+ * are passed per-invoke (`InvokeConfig.preopenedSkills`) and opened here BEFORE
+ * the first model call, by invoking the very same `open_skill` tool the model
+ * would have called. The run then continues normally: the skill's tools are
+ * bound in the registry and `bind_skill_tools` can still widen the surface.
+ *
+ * The opening is written into the transcript as a real tool exchange (one
+ * assistant message carrying the tool calls, then one tool message per call),
+ * because that is the shape the model is trained on and the shape the rest of
+ * the runtime — summarization, retention, `get_tool_response` — already
+ * understands. Tool call ids are derived from the skill key rather than random,
+ * so the same preopen set produces a byte-identical prefix on every run and the
+ * provider-side prompt cache keeps hitting.
+ */
+declare const PREOPEN_TOOL_CALL_PREFIX = "preopen_skill_";
+type PreopenSkillsResult = {
+    /** Synthetic transcript entries to append after the user message. */
+    messages: BaseMessage[];
+    /** Tool-history rows mirroring the synthetic calls. */
+    toolHistory: NonNullable<AgentState["toolHistory"]>;
+    /** Skill keys actually opened (available, resolved, not already open). */
+    openedKeys: string[];
+    /** Keys that were requested but could not be opened, with the reason. */
+    skipped: Array<{
+        skillKey: string;
+        reason: string;
+    }>;
+};
+/** Tool call ids must survive provider id charset rules; skill keys contain ':'. */
+declare function preopenToolCallId(skillKey: string): string;
+/**
+ * Open the requested skills through the real `open_skill` tool and return the
+ * transcript + tool-history entries that describe the exchange. Binding side
+ * effects (registry mutation + `__onToolsChanged`) happen inside the tool, so
+ * the caller only has to merge the returned messages/history into its state.
+ */
+declare function preopenSkills(input: {
+    skillKeys: string[];
+    tools: ToolInterface[];
+    /** Keys already open on the registry — a resumed run must not re-open them. */
+    alreadyOpenedKeys?: string[];
+    /** Existing transcript, used to keep the injection idempotent across resumes. */
+    existingMessages?: BaseMessage[];
+    onEvent?: (event: SmartAgentEvent) => void;
+}): Promise<PreopenSkillsResult>;
+
 /**
  * Pure registry helpers for the sub-agent primitive. No I/O, no agent loop —
  * the deterministic core, fully unit-testable on its own.
@@ -3335,4 +3429,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };
+export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, PREOPEN_TOOL_CALL_PREFIX, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type PreopenSkillsResult, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, preopenSkills, preopenToolCallId, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };

package/dist/index.d.ts

@@ -444,14 +444,38 @@ type ContentPart$1 = {
     type: string;
     [key: string]: any;
 };
+/**
+ * Decides, per call, whether this invocation needs human approval.
+ *
+ * Return `true` to pause. Returning a non-boolean is treated as `false` except
+ * for a thrown error, which is treated as `true` — see `needsApproval`.
+ */
+type ToolApprovalPredicate = (args: any) => boolean;
 interface ToolInterface<TInput = any, TOutput = any, TCallOptions = any> {
     name: string;
     description?: string;
     invoke?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     call?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     schema?: any;
-    needsApproval?: boolean;
-    approvalPrompt?: string;
+    /**
+     * Whether a call must pause for a human before it runs.
+     *
+     * A boolean decides for the tool as a whole. A PREDICATE decides per call, with
+     * the parsed arguments in hand — which is the only way to express "ask before
+     * `rm`, but not before `ls`", because the interesting half of a dangerous tool
+     * is usually its arguments, not its name.
+     *
+     * The predicate runs inside the tools node, immediately before the call would
+     * execute, and it must not throw: a predicate that throws is treated as
+     * `true`, because a policy that cannot decide has not granted permission.
+     */
+    needsApproval?: boolean | ToolApprovalPredicate;
+    /**
+     * The text shown to whoever is asked. A function receives the same arguments
+     * the predicate saw, so the prompt can quote what is actually about to happen
+     * ("Delete 3 files under /src?") instead of describing the tool in general.
+     */
+    approvalPrompt?: string | ((args: any) => string | undefined);
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
     /**
@@ -1094,7 +1118,13 @@ type TraceToolDetails = {
     description?: string;
     inputSchema?: any;
     approval?: {
+        /** Set only when the tool answers statically. Absent when `conditional`. */
         required?: boolean;
+        /**
+         * The tool decides per call from its arguments, so no single answer can be
+         * recorded here. The actual verdict for each call is on its approval entry.
+         */
+        conditional?: boolean;
         prompt?: string;
         defaults?: any;
     };
@@ -1775,6 +1805,15 @@ type InvokeConfig = RunnableConfig & {
     limits?: Partial<AgentLimits>;
     onStateChange?: (state: SmartState) => boolean;
     checkpointReason?: string;
+    /**
+     * Keys of `skills` to open deterministically at the start of this invoke,
+     * before the first model call. Each one is opened through the real
+     * `open_skill` tool and written into the transcript as an assistant tool call
+     * plus its tool result, so the model starts the run with the skill's guidance
+     * and tools already bound instead of having to discover them. Unknown or
+     * unavailable keys are skipped. Ignored when the agent has no `skills`.
+     */
+    preopenedSkills?: string[];
 };
 type SnapshotRuntimeHint = {
     name?: string;
@@ -1865,8 +1904,13 @@ declare function createTool({ name, description, schema, func, needsApproval, ap
     description?: string;
     schema: ZodSchema;
     func: SmartToolFn;
-    needsApproval?: boolean;
-    approvalPrompt?: string;
+    /**
+     * `true` gates every call; a predicate gates the calls whose ARGUMENTS
+     * warrant it. See ToolApprovalPredicate.
+     */
+    needsApproval?: boolean | ToolApprovalPredicate;
+    /** A function form receives the call's arguments, so the prompt can quote them. */
+    approvalPrompt?: string | ((args: any) => string | undefined);
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
     /** When set, identical args within the same invoke short-circuit to the cached result. */
@@ -2108,6 +2152,56 @@ declare function parseSkillFrontmatter(md: string): SkillFrontmatter;
  */
 declare function loadSkillsFromDisk(opts: LoadSkillsOptions): Promise<Skill[]>;
 
+/**
+ * Deterministic pre-opening of skills at the start of an invoke.
+ *
+ * Some skills must not depend on the model choosing to discover them — an
+ * organization policy, or the integration a scheduled run is about. Those keys
+ * are passed per-invoke (`InvokeConfig.preopenedSkills`) and opened here BEFORE
+ * the first model call, by invoking the very same `open_skill` tool the model
+ * would have called. The run then continues normally: the skill's tools are
+ * bound in the registry and `bind_skill_tools` can still widen the surface.
+ *
+ * The opening is written into the transcript as a real tool exchange (one
+ * assistant message carrying the tool calls, then one tool message per call),
+ * because that is the shape the model is trained on and the shape the rest of
+ * the runtime — summarization, retention, `get_tool_response` — already
+ * understands. Tool call ids are derived from the skill key rather than random,
+ * so the same preopen set produces a byte-identical prefix on every run and the
+ * provider-side prompt cache keeps hitting.
+ */
+declare const PREOPEN_TOOL_CALL_PREFIX = "preopen_skill_";
+type PreopenSkillsResult = {
+    /** Synthetic transcript entries to append after the user message. */
+    messages: BaseMessage[];
+    /** Tool-history rows mirroring the synthetic calls. */
+    toolHistory: NonNullable<AgentState["toolHistory"]>;
+    /** Skill keys actually opened (available, resolved, not already open). */
+    openedKeys: string[];
+    /** Keys that were requested but could not be opened, with the reason. */
+    skipped: Array<{
+        skillKey: string;
+        reason: string;
+    }>;
+};
+/** Tool call ids must survive provider id charset rules; skill keys contain ':'. */
+declare function preopenToolCallId(skillKey: string): string;
+/**
+ * Open the requested skills through the real `open_skill` tool and return the
+ * transcript + tool-history entries that describe the exchange. Binding side
+ * effects (registry mutation + `__onToolsChanged`) happen inside the tool, so
+ * the caller only has to merge the returned messages/history into its state.
+ */
+declare function preopenSkills(input: {
+    skillKeys: string[];
+    tools: ToolInterface[];
+    /** Keys already open on the registry — a resumed run must not re-open them. */
+    alreadyOpenedKeys?: string[];
+    /** Existing transcript, used to keep the injection idempotent across resumes. */
+    existingMessages?: BaseMessage[];
+    onEvent?: (event: SmartAgentEvent) => void;
+}): Promise<PreopenSkillsResult>;
+
 /**
  * Pure registry helpers for the sub-agent primitive. No I/O, no agent loop —
  * the deterministic core, fully unit-testable on its own.
@@ -3335,4 +3429,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };
+export { type AIMessage, ASK_USER_TOOL_NAME, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, type AudioContent, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuildChildConfig, type BuiltInRuntimeProfile, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type CompressToolOutputParams, type ContextPilotCCRConfig, type ContextPilotCacheAlignmentConfig, type ContextPilotCompressionConfig, type ContextPilotCompressionStats, type ContextPilotCompressorKind, type ContextPilotConfig, type ContextPilotDedupConfig, type ContextPilotDiffCompressionConfig, type ContextPilotJsonCompressionConfig, type ContextPilotLogCompressionConfig, type ContextPilotResult, type ContextPilotRuntime, type ContextPilotSearchCompressionConfig, type ContextPilotTextCompressionConfig, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, type DelegationEventStamp, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FileContent, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, type HumanInTheLoopAskUserConfig, type HumanInTheLoopOptions, type HumanInTheLoopRuntimeConfig, type ImageContent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type LoadSkillsOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, PREOPEN_TOOL_CALL_PREFIX, type PendingToolApproval, type PendingUserQuestion, type PlanEvent, type PlanStepRecord, type PlanningMode, type PreopenSkillsResult, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type PromptHooks, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionHookContext, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedContextPilotConfig, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, SMALL_TIER_SKILL_POLICY, type SerializableSmartState, type Skill, type SkillDisclosure, type SkillExecutionContext, type SkillFrontmatter, type SkillFs, type SkillModelTier, type SkillPolicy, type SkillRegistryRef, type SkillToolDeps, type SkillToolHeader, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SubagentDef, type SubagentEvent, type SubagentMode, type SubagentPendingRecord, type SubagentPolicy, type SubagentRegistryRef, type SubagentResult, type SubagentToolDeps, type SubagentToolNames, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, TOOL_INPUT_DIGEST_KEY, type TextContent, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInputDigestOptions, type ToolInputDigestResult, type ToolInputRetentionPolicy, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetentionDeclarations, type ToolRetentionSpec, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolDetails, type TraceToolResponseSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, type UserQuestionAnswer, type UserQuestionAnswerSet, type UserQuestionEvent, type UserQuestionItem, type UserQuestionOption, type UserQuestionResolution, type UserQuestionStatus, VertexProvider, type VertexProviderConfig, type VolatileContentFinding, type VolatileContentPattern, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, preopenSkills, preopenToolCallId, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };

package/dist/index.mjs

@@ -424,7 +424,7 @@ function createTool({
     run: execute,
     func: execute
   };
-  if (typeof needsApproval === "boolean") {
+  if (typeof needsApproval === "function" || typeof needsApproval === "boolean") {
     toolRecord.needsApproval = needsApproval;
   }
   if (approvalPrompt !== void 0) {
@@ -3473,6 +3473,29 @@ function selectPendingToolCalls(messages) {
 }
 
 // src/nodes/tools.ts
+function resolveNeedsApproval(tool, args) {
+  const spec = tool?.needsApproval;
+  if (typeof spec === "function") {
+    try {
+      return Boolean(spec(args));
+    } catch {
+      return true;
+    }
+  }
+  return Boolean(spec);
+}
+function resolveApprovalPrompt(tool, args) {
+  const prompt = tool?.approvalPrompt;
+  if (typeof prompt === "function") {
+    try {
+      const resolved = prompt(args);
+      return typeof resolved === "string" && resolved.length > 0 ? resolved : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  return typeof prompt === "string" ? prompt : void 0;
+}
 function normalizeMaxExecutionsPerRun(value) {
   if (value === null || value === void 0 || value === "") return null;
   const parsed = Number(value);
@@ -3519,10 +3542,13 @@ function buildToolDetails(tool, toolName) {
   }
   const inputSchema = normalizeToolSchema(tool, toolName);
   if (inputSchema !== void 0) details.inputSchema = inputSchema;
-  const needsApproval = typeof tool.needsApproval === "boolean" ? tool.needsApproval : void 0;
-  if (needsApproval !== void 0 || tool.approvalPrompt !== void 0 || tool.approvalDefaults !== void 0) {
+  const approvalSpec = tool.needsApproval;
+  const needsApproval = typeof approvalSpec === "boolean" ? approvalSpec : void 0;
+  const conditionalApproval = typeof approvalSpec === "function" ? true : void 0;
+  if (needsApproval !== void 0 || conditionalApproval !== void 0 || tool.approvalPrompt !== void 0 || tool.approvalDefaults !== void 0) {
     details.approval = {
       required: needsApproval,
+      conditional: conditionalApproval,
       prompt: typeof tool.approvalPrompt === "string" ? tool.approvalPrompt : void 0,
       defaults: tool.approvalDefaults !== void 0 ? sanitizeTracePayload(tool.approvalDefaults) : void 0
     };
@@ -3747,7 +3773,7 @@ function createToolsNode(initialTools, opts) {
         }
       }
       let approvalEntry = pendingByCallId.get(toolCallId);
-      const needsApproval = Boolean(tool.needsApproval);
+      const needsApproval = resolveNeedsApproval(tool, args);
       if (needsApproval) {
         if (!approvalEntry) {
           approvalEntry = {
@@ -3757,7 +3783,7 @@ function createToolsNode(initialTools, opts) {
             args,
             status: "pending",
             requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
-            metadata: tool.approvalPrompt || tool.approvalDefaults ? { prompt: tool.approvalPrompt, defaults: tool.approvalDefaults } : void 0
+            metadata: resolveApprovalPrompt(tool, args) !== void 0 || tool.approvalDefaults !== void 0 ? { prompt: resolveApprovalPrompt(tool, args), defaults: tool.approvalDefaults } : void 0
           };
           pendingApprovals.push(approvalEntry);
           pendingByCallId.set(toolCallId, approvalEntry);
@@ -7546,6 +7572,127 @@ function createSkillTools(deps) {
   if (isSearchDisclosure(deps.policy)) tools.unshift(createSearchSkillsTool(deps));
   return tools;
 }
+var PREOPEN_TOOL_CALL_PREFIX = "preopen_skill_";
+var OPEN_SKILL_TOOL_NAME = "open_skill";
+function preopenToolCallId(skillKey) {
+  return `${PREOPEN_TOOL_CALL_PREFIX}${skillKey.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+}
+function messagesContainCallId(messages, callId) {
+  if (!Array.isArray(messages)) return false;
+  return messages.some((message) => {
+    const calls = message?.tool_calls;
+    return Array.isArray(calls) && calls.some((call) => call?.id === callId);
+  });
+}
+function serializeToolContent(result) {
+  if (typeof result === "string") return result;
+  try {
+    return JSON.stringify(result);
+  } catch {
+    return String(result);
+  }
+}
+async function preopenSkills(input) {
+  const empty = { messages: [], toolHistory: [], openedKeys: [], skipped: [] };
+  const requested = [...new Set(
+    (input.skillKeys ?? []).map((key) => String(key ?? "").trim()).filter(Boolean)
+  )];
+  if (requested.length === 0) return empty;
+  const openSkillTool = input.tools.find((tool) => tool?.name === OPEN_SKILL_TOOL_NAME);
+  if (!openSkillTool) {
+    return { ...empty, skipped: requested.map((skillKey) => ({ skillKey, reason: "open_skill tool is not wired" })) };
+  }
+  const alreadyOpen = new Set(input.alreadyOpenedKeys ?? []);
+  const toolCalls = [];
+  const toolMessages = [];
+  const toolHistory = [];
+  const openedKeys = [];
+  const skipped = [];
+  for (const skillKey of requested) {
+    const toolCallId = preopenToolCallId(skillKey);
+    if (alreadyOpen.has(skillKey) || messagesContainCallId(input.existingMessages, toolCallId)) {
+      skipped.push({ skillKey, reason: "already open" });
+      continue;
+    }
+    const args = { skillKey };
+    input.onEvent?.({ type: "tool_call", phase: "start", name: OPEN_SKILL_TOOL_NAME, id: toolCallId, args });
+    const start = Date.now();
+    let result;
+    try {
+      result = await openSkillTool.invoke(args);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "open_skill failed";
+      input.onEvent?.({
+        type: "tool_call",
+        phase: "error",
+        name: OPEN_SKILL_TOOL_NAME,
+        id: toolCallId,
+        args,
+        error: { message },
+        durationMs: Date.now() - start
+      });
+      skipped.push({ skillKey, reason: message });
+      continue;
+    }
+    const durationMs = Date.now() - start;
+    if (result && typeof result === "object" && typeof result.error === "string") {
+      input.onEvent?.({
+        type: "tool_call",
+        phase: "skipped",
+        name: OPEN_SKILL_TOOL_NAME,
+        id: toolCallId,
+        args,
+        error: { message: result.error },
+        durationMs
+      });
+      skipped.push({ skillKey, reason: result.error });
+      continue;
+    }
+    if (result && typeof result === "object") delete result.__runtimeToolsDelta;
+    toolCalls.push({
+      id: toolCallId,
+      type: "function",
+      function: { name: OPEN_SKILL_TOOL_NAME, arguments: JSON.stringify(args) }
+    });
+    toolMessages.push({
+      role: "tool",
+      name: OPEN_SKILL_TOOL_NAME,
+      tool_call_id: toolCallId,
+      content: serializeToolContent(result)
+    });
+    toolHistory.push({
+      executionId: nanoid(),
+      toolName: OPEN_SKILL_TOOL_NAME,
+      args,
+      output: result,
+      rawOutput: result,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      tool_call_id: toolCallId,
+      summarized: false,
+      retentionPolicy: "keep_full",
+      status: "success"
+    });
+    openedKeys.push(skillKey);
+    input.onEvent?.({
+      type: "tool_call",
+      phase: "success",
+      name: OPEN_SKILL_TOOL_NAME,
+      id: toolCallId,
+      args,
+      result,
+      durationMs
+    });
+  }
+  if (toolCalls.length === 0) {
+    return { ...empty, skipped };
+  }
+  const assistantMessage = {
+    role: "assistant",
+    content: `Opening the ${openedKeys.join(", ")} skill${openedKeys.length > 1 ? "s" : ""} required for this task.`,
+    tool_calls: toolCalls
+  };
+  return { messages: [assistantMessage, ...toolMessages], toolHistory, openedKeys, skipped };
+}
 
 // src/smart/subagents/types.ts
 var DEFAULT_SUBAGENT_POLICY = {
@@ -8252,7 +8399,25 @@ function createSmartAgent(opts) {
       const disclosureBlock = [skillBlock, subagentBlock].filter(Boolean).join("\n\n") || void 0;
       const alreadyHasSystem = Array.isArray(input.messages) && input.messages[0]?.role === "system";
       const seedMessages = alreadyHasSystem ? [...input.messages || []] : [systemMessage2(disclosureBlock), ...input.messages || []];
-      let state = syncRuntimeTools(await syncMemory({ ...input, messages: seedMessages }), seedMessages, toolSet);
+      let seedToolHistory = input.toolHistory;
+      if (skillsEnabled && toolSet.skillRegistryRef) {
+        const preopenKeys = config?.preopenedSkills ?? [];
+        if (preopenKeys.length > 0) {
+          const preopened = await preopenSkills({
+            skillKeys: preopenKeys,
+            tools: toolSet.toolsWithoutRecovery,
+            alreadyOpenedKeys: toolSet.skillRegistryRef.openedSkillKeys,
+            existingMessages: seedMessages,
+            onEvent: config?.onEvent ?? opts.onEvent
+          });
+          if (preopened.messages.length > 0) {
+            seedMessages.push(...preopened.messages);
+            seedToolHistory = [...seedToolHistory ?? [], ...preopened.toolHistory];
+            stateRef.toolHistory = seedToolHistory;
+          }
+        }
+      }
+      let state = syncRuntimeTools(await syncMemory({ ...input, messages: seedMessages, toolHistory: seedToolHistory }), seedMessages, toolSet);
       let lastResult = null;
       let rawMessages = [...seedMessages];
       const effectiveMaxToolCalls = config?.limits?.maxToolCalls ?? resolved.limits.maxToolCalls ?? 10;
@@ -11513,6 +11678,6 @@ function createProvider(config) {
   }
 }
 
-export { ASK_USER_TOOL_NAME, AnthropicProvider, AzureProvider, BaseProvider, BedrockProvider, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, GuardrailPhase, InMemoryMemoryStore, NativeJsonSchemaStrategy, OpenAICompatibleProvider, OpenAIProvider, ProviderError, SMALL_TIER_SKILL_POLICY, StructuredOutputManager, TOOL_INPUT_DIGEST_KEY, ToolBasedStrategy, VertexProvider, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };
+export { ASK_USER_TOOL_NAME, AnthropicProvider, AzureProvider, BaseProvider, BedrockProvider, CCRStore, CONTEXT_PILOT_JSON_MARKER_KEY, CONTROL_PLANE_TOOL_NAMES, DEFAULT_MAX_TOOL_INPUT_FIELD_CHARS, DEFAULT_PROFILE_CONFIGS, DEFAULT_SKILL_POLICY, DEFAULT_SUBAGENT_POLICY, DEFAULT_SUBAGENT_TOOL_NAMES, DEFAULT_TOOL_INPUT_DIGEST_HEAD_CHARS, DELEGATION_TOOL_NAMES, DedupTracker, GuardrailPhase, InMemoryMemoryStore, NativeJsonSchemaStrategy, OpenAICompatibleProvider, OpenAIProvider, PREOPEN_TOOL_CALL_PREFIX, ProviderError, SMALL_TIER_SKILL_POLICY, StructuredOutputManager, TOOL_INPUT_DIGEST_KEY, ToolBasedStrategy, VertexProvider, agentVerdictRule, appendBoundTools, buildSkillHeaderBlock, buildSubagentCatalogBlock, buildSystemPrompt, canOpenSkill, canSpawn, captureSnapshot, codePresenceRule, coerceToolArgs, cognipeerSink, collectToolRetentionDeclarations, composeToolSets, compressDiffOutput, compressJsonOutput, compressLogOutput, compressSearchOutput, compressTextOutput, compressToolOutput, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createAskUserQuestionTool, createBindSkillToolsTool, createCodeGuardrail, createContextPilotRuntime, createContextSummarizeNode, createContextTools, createDelegateTool, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createOpenSkillTool, createParallelTool, createProvider, createRegexGuardrail, createResolverNode, createSearchSkillsTool, createSkillRegistryRef, createSkillTools, createSmartAgent, createSpawnTool, createSubagentRegistryRef, createSubagentTools, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, dedupeToolsByName, defaultTokenCounter, detectTextFormat, detectVolatileContent, digestToolInputArguments, digestToolInputValue, emptyUsage, evaluateGuardrails, extractLatestUserQuery, fileSink, findSubagent, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, loadSkillsFromDisk, normalizeSmartAgentOptions, otlpSink, parseSkillFrontmatter, preopenSkills, preopenToolCallId, readMemoryFacts, regexRule, resolveAvailableSkills, resolveAvailableSubagents, resolveInputRetention, resolveMemoryStore, resolveReasoning, resolveStrategy, resolveSubagentTools, resolveSummarizationRetention, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, scoreItemsByRelevance, searchSkills, seedChildMessages, selectTopIndicesInOrder, setTokenCounter, startStreamingSession, summarizeObject, tokenize, traceSessionToOtlp, validateReasoningConfig, validateToolArgs, withTools, withinDepth, writeSummaryFactsToMemory };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map