@cognipeer/agent-sdk 0.6.5 → 0.6.6

package/dist/index.d.cts

@@ -299,6 +299,12 @@ type AgentOptions = {
         cachedInputTokens?: number;
         reasoningTokens?: number;
     }) => number;
+    /**
+     * Human-in-the-loop hooks. When `askUser` is enabled, the agent gains a
+     * built-in `ask_user_question` tool that pauses the run with structured
+     * questions for the host application to answer.
+     */
+    humanInTheLoop?: HumanInTheLoopOptions;
 };
 type ReasoningLevel = "low" | "medium" | "high";
 type ReflectionCadence = "off" | "every_turn" | "after_tool" | "on_branch";
@@ -538,6 +544,8 @@ type SmartAgentOptions = {
     tokenCounter?: (text: string) => number;
     /** See AgentOptions.costEstimator. */
     costEstimator?: AgentOptions["costEstimator"];
+    /** See AgentOptions.humanInTheLoop. */
+    humanInTheLoop?: HumanInTheLoopOptions;
 };
 type AgentRuntimeConfig = {
     name?: string;
@@ -554,6 +562,7 @@ type AgentRuntimeConfig = {
     tracing?: TracingConfig;
     runtimeProfile?: RuntimeProfile;
     smart?: ResolvedSmartAgentConfig;
+    humanInTheLoop?: HumanInTheLoopRuntimeConfig;
 };
 type TraceMessageSection = {
     id?: string;
@@ -786,6 +795,7 @@ type AgentState = {
     metadata?: Record<string, any>;
     ctx?: Record<string, any>;
     pendingApprovals?: PendingToolApproval[];
+    pendingUserQuestions?: PendingUserQuestion[];
     usage?: {
         perRequest: Array<{
             id: string;
@@ -1032,6 +1042,93 @@ type ToolApprovalEvent = {
     decidedBy?: string;
     comment?: string;
 };
+type UserQuestionOption = {
+    /** Label shown to the user. */
+    label: string;
+    /** Value returned in the resolution. Defaults to `label` when omitted. */
+    value?: string;
+    /** Optional helper text rendered alongside the option. */
+    description?: string;
+    /** Optional code / ASCII preview rendered when the option is focused. */
+    preview?: string;
+};
+type UserQuestionItem = {
+    /** The full question text shown to the user. */
+    question: string;
+    /** Short label (chip / tag) displayed alongside the question. */
+    header?: string;
+    /** When true the user may pick multiple options. Default: false. */
+    multiSelect?: boolean;
+    /** Placeholder shown for the free-text input (when enabled globally). */
+    placeholder?: string;
+    /** Predefined options; omit for a pure free-text question. */
+    options?: UserQuestionOption[];
+    /** When true the user must answer this item. Default: true. */
+    required?: boolean;
+};
+type UserQuestionStatus = "pending" | "answered" | "cancelled" | "executed";
+type UserQuestionAnswer = {
+    /** Selected option values. Single-select questions report exactly one entry. */
+    values: string[];
+    /** Populated when the user typed a custom answer (only when free-text is enabled). */
+    freeText?: string;
+    /** Optional reviewer notes. */
+    notes?: string;
+};
+/** Keyed by the question text (or `header`, if both questions share text). */
+type UserQuestionAnswerSet = Record<string, UserQuestionAnswer>;
+type PendingUserQuestion = {
+    id: string;
+    toolCallId: string;
+    toolName: "ask_user_question";
+    questions: UserQuestionItem[];
+    status: UserQuestionStatus;
+    requestedAt: string;
+    answeredAt?: string;
+    answeredBy?: string;
+    answers?: UserQuestionAnswerSet;
+    cancelled?: boolean;
+    notes?: string;
+    /** Snapshot of the global free-text flag at request time, for UI rendering. */
+    allowFreeText?: boolean;
+    metadata?: Record<string, any>;
+};
+type UserQuestionResolution = {
+    id: string;
+    answers?: UserQuestionAnswerSet;
+    answeredBy?: string;
+    notes?: string;
+    /** When true the tool call is reported back as cancelled / unanswered. */
+    cancelled?: boolean;
+};
+type UserQuestionEvent = {
+    type: "user_question";
+    status: "pending" | "answered" | "cancelled";
+    id: string;
+    toolCallId: string;
+    questions?: UserQuestionItem[];
+    answers?: UserQuestionAnswerSet;
+    answeredBy?: string;
+    allowFreeText?: boolean;
+};
+type HumanInTheLoopAskUserConfig = {
+    enabled: boolean;
+    allowFreeText: boolean;
+    promptOverride?: string;
+};
+type HumanInTheLoopRuntimeConfig = {
+    askUser?: HumanInTheLoopAskUserConfig;
+};
+type HumanInTheLoopOptions = {
+    askUser?: boolean | {
+        /** Allow the user to type a custom "Other" answer. Default: true. */
+        allowFreeText?: boolean;
+        /** Override the built-in tool description. */
+        promptOverride?: string;
+        /** Convenience: subscribe to user_question events without setting up onEvent. */
+        onQuestion?: (event: UserQuestionEvent) => void;
+    };
+};
 type GuardrailEvent = {
     type: "guardrail";
     phase: GuardrailPhase;
@@ -1043,7 +1140,7 @@ type GuardrailEvent = {
     reason?: string;
     details?: Record<string, any>;
 };
-type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent | ReflectionEvent;
+type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | UserQuestionEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent | ReflectionEvent;
 type ReflectionEvent = {
     type: "reflection";
     id: string;
@@ -1136,6 +1233,7 @@ type AgentInstance<TOutput = unknown> = {
     snapshot: (state: SmartState, options?: SnapshotOptions) => AgentSnapshot;
     resume: (snapshot: AgentSnapshot, config?: InvokeConfig, restoreOptions?: RestoreSnapshotOptions) => Promise<AgentInvokeResult<TOutput>>;
     resolveToolApproval: (state: SmartState, resolution: ToolApprovalResolution) => SmartState;
+    resolveUserQuestion: (state: SmartState, resolution: UserQuestionResolution) => SmartState;
     asTool: (opts: {
         toolName: string;
         description?: string;
@@ -1580,6 +1678,16 @@ declare function restoreSnapshot(snapshot: AgentSnapshot, restoreOptions?: Resto
 
 declare function resolveToolApprovalState(state: SmartState, resolution: ToolApprovalResolution): SmartState;
 
+declare function resolveUserQuestionState(state: SmartState, resolution: UserQuestionResolution): SmartState;
+
+type AskUserStateRef = {
+    pendingUserQuestions?: PendingUserQuestion[];
+    ctx?: Record<string, any>;
+    __onEvent?: (event: any) => void;
+    __currentToolCallId?: string;
+};
+declare function createAskUserQuestionTool(stateRef: AskUserStateRef, config: HumanInTheLoopAskUserConfig): ToolInterface<any, any, any>;
+
 declare function fromLangchainTools<T extends ToolInterface = ToolInterface>(tools: any[]): T[];
 
 declare function fileSink(path?: string): TraceSinkConfig;
@@ -1975,4 +2083,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, 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 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 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 TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, 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, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };
+export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, 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 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 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, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };

package/dist/index.d.ts

@@ -299,6 +299,12 @@ type AgentOptions = {
         cachedInputTokens?: number;
         reasoningTokens?: number;
     }) => number;
+    /**
+     * Human-in-the-loop hooks. When `askUser` is enabled, the agent gains a
+     * built-in `ask_user_question` tool that pauses the run with structured
+     * questions for the host application to answer.
+     */
+    humanInTheLoop?: HumanInTheLoopOptions;
 };
 type ReasoningLevel = "low" | "medium" | "high";
 type ReflectionCadence = "off" | "every_turn" | "after_tool" | "on_branch";
@@ -538,6 +544,8 @@ type SmartAgentOptions = {
     tokenCounter?: (text: string) => number;
     /** See AgentOptions.costEstimator. */
     costEstimator?: AgentOptions["costEstimator"];
+    /** See AgentOptions.humanInTheLoop. */
+    humanInTheLoop?: HumanInTheLoopOptions;
 };
 type AgentRuntimeConfig = {
     name?: string;
@@ -554,6 +562,7 @@ type AgentRuntimeConfig = {
     tracing?: TracingConfig;
     runtimeProfile?: RuntimeProfile;
     smart?: ResolvedSmartAgentConfig;
+    humanInTheLoop?: HumanInTheLoopRuntimeConfig;
 };
 type TraceMessageSection = {
     id?: string;
@@ -786,6 +795,7 @@ type AgentState = {
     metadata?: Record<string, any>;
     ctx?: Record<string, any>;
     pendingApprovals?: PendingToolApproval[];
+    pendingUserQuestions?: PendingUserQuestion[];
     usage?: {
         perRequest: Array<{
             id: string;
@@ -1032,6 +1042,93 @@ type ToolApprovalEvent = {
     decidedBy?: string;
     comment?: string;
 };
+type UserQuestionOption = {
+    /** Label shown to the user. */
+    label: string;
+    /** Value returned in the resolution. Defaults to `label` when omitted. */
+    value?: string;
+    /** Optional helper text rendered alongside the option. */
+    description?: string;
+    /** Optional code / ASCII preview rendered when the option is focused. */
+    preview?: string;
+};
+type UserQuestionItem = {
+    /** The full question text shown to the user. */
+    question: string;
+    /** Short label (chip / tag) displayed alongside the question. */
+    header?: string;
+    /** When true the user may pick multiple options. Default: false. */
+    multiSelect?: boolean;
+    /** Placeholder shown for the free-text input (when enabled globally). */
+    placeholder?: string;
+    /** Predefined options; omit for a pure free-text question. */
+    options?: UserQuestionOption[];
+    /** When true the user must answer this item. Default: true. */
+    required?: boolean;
+};
+type UserQuestionStatus = "pending" | "answered" | "cancelled" | "executed";
+type UserQuestionAnswer = {
+    /** Selected option values. Single-select questions report exactly one entry. */
+    values: string[];
+    /** Populated when the user typed a custom answer (only when free-text is enabled). */
+    freeText?: string;
+    /** Optional reviewer notes. */
+    notes?: string;
+};
+/** Keyed by the question text (or `header`, if both questions share text). */
+type UserQuestionAnswerSet = Record<string, UserQuestionAnswer>;
+type PendingUserQuestion = {
+    id: string;
+    toolCallId: string;
+    toolName: "ask_user_question";
+    questions: UserQuestionItem[];
+    status: UserQuestionStatus;
+    requestedAt: string;
+    answeredAt?: string;
+    answeredBy?: string;
+    answers?: UserQuestionAnswerSet;
+    cancelled?: boolean;
+    notes?: string;
+    /** Snapshot of the global free-text flag at request time, for UI rendering. */
+    allowFreeText?: boolean;
+    metadata?: Record<string, any>;
+};
+type UserQuestionResolution = {
+    id: string;
+    answers?: UserQuestionAnswerSet;
+    answeredBy?: string;
+    notes?: string;
+    /** When true the tool call is reported back as cancelled / unanswered. */
+    cancelled?: boolean;
+};
+type UserQuestionEvent = {
+    type: "user_question";
+    status: "pending" | "answered" | "cancelled";
+    id: string;
+    toolCallId: string;
+    questions?: UserQuestionItem[];
+    answers?: UserQuestionAnswerSet;
+    answeredBy?: string;
+    allowFreeText?: boolean;
+};
+type HumanInTheLoopAskUserConfig = {
+    enabled: boolean;
+    allowFreeText: boolean;
+    promptOverride?: string;
+};
+type HumanInTheLoopRuntimeConfig = {
+    askUser?: HumanInTheLoopAskUserConfig;
+};
+type HumanInTheLoopOptions = {
+    askUser?: boolean | {
+        /** Allow the user to type a custom "Other" answer. Default: true. */
+        allowFreeText?: boolean;
+        /** Override the built-in tool description. */
+        promptOverride?: string;
+        /** Convenience: subscribe to user_question events without setting up onEvent. */
+        onQuestion?: (event: UserQuestionEvent) => void;
+    };
+};
 type GuardrailEvent = {
     type: "guardrail";
     phase: GuardrailPhase;
@@ -1043,7 +1140,7 @@ type GuardrailEvent = {
     reason?: string;
     details?: Record<string, any>;
 };
-type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent | ReflectionEvent;
+type SmartAgentEvent = ToolCallEvent | ToolApprovalEvent | UserQuestionEvent | PlanEvent | SummarizationEvent | FinalAnswerEvent | MetadataEvent | HandoffEvent | GuardrailEvent | ProgressEvent | StreamEvent | CancelledEvent | ReflectionEvent;
 type ReflectionEvent = {
     type: "reflection";
     id: string;
@@ -1136,6 +1233,7 @@ type AgentInstance<TOutput = unknown> = {
     snapshot: (state: SmartState, options?: SnapshotOptions) => AgentSnapshot;
     resume: (snapshot: AgentSnapshot, config?: InvokeConfig, restoreOptions?: RestoreSnapshotOptions) => Promise<AgentInvokeResult<TOutput>>;
     resolveToolApproval: (state: SmartState, resolution: ToolApprovalResolution) => SmartState;
+    resolveUserQuestion: (state: SmartState, resolution: UserQuestionResolution) => SmartState;
     asTool: (opts: {
         toolName: string;
         description?: string;
@@ -1580,6 +1678,16 @@ declare function restoreSnapshot(snapshot: AgentSnapshot, restoreOptions?: Resto
 
 declare function resolveToolApprovalState(state: SmartState, resolution: ToolApprovalResolution): SmartState;
 
+declare function resolveUserQuestionState(state: SmartState, resolution: UserQuestionResolution): SmartState;
+
+type AskUserStateRef = {
+    pendingUserQuestions?: PendingUserQuestion[];
+    ctx?: Record<string, any>;
+    __onEvent?: (event: any) => void;
+    __currentToolCallId?: string;
+};
+declare function createAskUserQuestionTool(stateRef: AskUserStateRef, config: HumanInTheLoopAskUserConfig): ToolInterface<any, any, any>;
+
 declare function fromLangchainTools<T extends ToolInterface = ToolInterface>(tools: any[]): T[];
 
 declare function fileSink(path?: string): TraceSinkConfig;
@@ -1975,4 +2083,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, 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 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 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 TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, 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, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };
+export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, 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 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 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, resolveStrategy, resolveToolApprovalState, resolveUserQuestionState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };