art-framework 0.4.13 → 0.4.14

package/dist/index.d.ts

@@ -51,6 +51,484 @@ declare class TypedSocket<DataType, FilterType = any> {
     clearAllSubscriptions(): void;
 }
 
+/**
+ * @module types/hitl-types
+ *
+ * This module defines the types and contracts for Human-in-the-Loop (HITL) functionality
+ * in the ART framework. It establishes a clear contract for blocking tools to declare
+ * expected feedback types and for the framework to programmatically handle user responses.
+ *
+ * Key Design Principle:
+ * User feedback IS the tool result. When a user provides feedback (approval, text input,
+ * selection, etc.), the framework programmatically marks the tool call as SUCCESS with
+ * the feedback as the output. The LLM never needs to re-invoke the tool.
+ */
+/**
+ * Defines the three categories of tools in the ART framework.
+ *
+ * @remarks
+ * Each category has different execution semantics and framework handling:
+ *
+ * - `functional`: Regular tools that execute synchronously and return results immediately.
+ *   Examples: webSearch, calculator, fileRead, apiCall
+ *
+ * - `blocking`: Tools that require human input to complete. They return 'suspended' status
+ *   initially, and the framework waits for user feedback. The user's feedback becomes
+ *   the tool's result - no re-execution needed.
+ *   Examples: confirmAction, getUserInput, selectOption, requestApproval
+ *
+ * - `display`: Tools for generative UI that render content without producing a traditional
+ *   "result". They complete immediately but their output is visual/interactive.
+ *   Examples: renderChart, showModal, displayProgress, generateUI
+ */
+type ToolExecutionMode = 'functional' | 'blocking' | 'display';
+/**
+ * Defines the type of user input expected for HITL feedback.
+ *
+ * @remarks
+ * This enables blocking tools to declare what kind of UI the application
+ * should render to collect user feedback.
+ */
+type HITLInputType = 'boolean' | 'text' | 'select' | 'multiselect' | 'number' | 'date' | 'datetime' | 'file' | 'confirm' | 'custom';
+/**
+ * Schema for what kind of feedback a blocking tool expects.
+ *
+ * @remarks
+ * Tools declare this schema to inform the UI layer what input to collect.
+ * The framework uses this to validate feedback and construct the tool result.
+ *
+ * @example
+ * // Simple confirmation
+ * {
+ *   inputType: 'confirm',
+ *   prompt: 'Are you sure you want to delete this file?',
+ *   confirmLabel: 'Delete',
+ *   cancelLabel: 'Keep'
+ * }
+ *
+ * @example
+ * // Selection from options
+ * {
+ *   inputType: 'select',
+ *   prompt: 'Which deployment environment should we use?',
+ *   options: [
+ *     { value: 'staging', label: 'Staging', description: 'Test environment' },
+ *     { value: 'production', label: 'Production', description: 'Live environment' }
+ *   ],
+ *   required: true
+ * }
+ *
+ * @example
+ * // Text input with validation
+ * {
+ *   inputType: 'text',
+ *   prompt: 'Please provide the API key for the service:',
+ *   placeholder: 'sk-...',
+ *   validation: {
+ *     required: true,
+ *     pattern: '^sk-[a-zA-Z0-9]{32,}$',
+ *     patternMessage: 'Must be a valid API key starting with sk-'
+ *   }
+ * }
+ */
+interface HITLFeedbackSchema {
+    /**
+     * The type of input expected from the user.
+     */
+    inputType: HITLInputType;
+    /**
+     * Human-readable prompt shown to the user.
+     * This should clearly explain what input is needed and why.
+     */
+    prompt: string;
+    /**
+     * Optional title for the feedback dialog/section.
+     */
+    title?: string;
+    /**
+     * For select/multiselect: available options to choose from.
+     */
+    options?: HITLSelectOption[];
+    /**
+     * Validation constraints for the input.
+     */
+    validation?: HITLInputValidation;
+    /**
+     * Optional default value to pre-fill.
+     */
+    defaultValue?: unknown;
+    /**
+     * Placeholder text for text/number inputs.
+     */
+    placeholder?: string;
+    /**
+     * For confirm type: custom label for the approve button.
+     * @default 'Approve'
+     */
+    confirmLabel?: string;
+    /**
+     * For confirm type: custom label for the reject button.
+     * @default 'Reject'
+     */
+    cancelLabel?: string;
+    /**
+     * If true, user can modify the original tool arguments before submitting.
+     * The modified args are returned in the feedback.
+     * @default false
+     */
+    allowModifyArgs?: boolean;
+    /**
+     * For custom inputType: application-defined JSON schema for the input.
+     */
+    customSchema?: Record<string, unknown>;
+    /**
+     * Optional hint text shown below the input.
+     */
+    hint?: string;
+    /**
+     * Whether this is a sensitive input (e.g., password, API key).
+     * UI should mask the input if true.
+     * @default false
+     */
+    sensitive?: boolean;
+}
+/**
+ * An option for select/multiselect input types.
+ */
+interface HITLSelectOption {
+    /**
+     * The value returned when this option is selected.
+     */
+    value: string | number | boolean;
+    /**
+     * Human-readable label displayed to the user.
+     */
+    label: string;
+    /**
+     * Optional description providing more context about this option.
+     */
+    description?: string;
+    /**
+     * Whether this option is disabled (shown but not selectable).
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Optional icon identifier for UI rendering.
+     */
+    icon?: string;
+}
+/**
+ * Validation constraints for HITL input.
+ */
+interface HITLInputValidation {
+    /**
+     * Whether the input is required (non-empty).
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * For text: minimum character length.
+     */
+    minLength?: number;
+    /**
+     * For text: maximum character length.
+     */
+    maxLength?: number;
+    /**
+     * For number: minimum value.
+     */
+    min?: number;
+    /**
+     * For number: maximum value.
+     */
+    max?: number;
+    /**
+     * For text: regex pattern the input must match.
+     */
+    pattern?: string;
+    /**
+     * Custom error message when pattern validation fails.
+     */
+    patternMessage?: string;
+    /**
+     * For multiselect: minimum number of selections required.
+     */
+    minSelections?: number;
+    /**
+     * For multiselect: maximum number of selections allowed.
+     */
+    maxSelections?: number;
+}
+/**
+ * The standardized feedback structure returned by the user.
+ *
+ * @remarks
+ * This is the canonical format for user feedback. The framework converts this
+ * into a successful tool result when resuming execution. The LLM sees this
+ * as a normal tool completion.
+ */
+interface HITLFeedback {
+    /**
+     * Whether the action was approved/confirmed.
+     * For non-boolean input types, this is true if the user submitted
+     * (vs. cancelled/dismissed).
+     */
+    approved: boolean;
+    /**
+     * The user's input value, type depends on the inputType:
+     * - boolean: true/false
+     * - text: string
+     * - number: number
+     * - select: the selected option's value
+     * - multiselect: array of selected values
+     * - date/datetime: ISO string
+     * - file: file reference object
+     * - confirm: undefined (use approved field)
+     * - custom: matches customSchema
+     */
+    value?: unknown;
+    /**
+     * For text input type, the raw text entered.
+     * @deprecated Use `value` instead
+     */
+    textInput?: string;
+    /**
+     * For select/multiselect, the selected value(s).
+     * @deprecated Use `value` instead
+     */
+    selectedValues?: (string | number | boolean)[];
+    /**
+     * Modified tool arguments if allowModifyArgs was true and user modified them.
+     */
+    modifiedArgs?: Record<string, unknown>;
+    /**
+     * Optional reason/comment provided by the user.
+     * Particularly useful for rejections to explain why.
+     */
+    reason?: string;
+    /**
+     * Timestamp when feedback was provided.
+     */
+    timestamp: number;
+    /**
+     * Optional metadata about the feedback context.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for blocking tools in the ToolSchema.
+ *
+ * @remarks
+ * This is added to ToolSchema when executionMode is 'blocking'.
+ * It defines how the tool interacts with the HITL system.
+ */
+interface BlockingToolConfig {
+    /**
+     * The schema for feedback this tool expects.
+     * If not provided, defaults to a simple confirm schema.
+     */
+    feedbackSchema?: HITLFeedbackSchema;
+    /**
+     * Message to show in the approval dialog.
+     * Can include {{variable}} placeholders that will be replaced
+     * with values from the tool's input arguments.
+     */
+    approvalPrompt?: string;
+    /**
+     * Whether the tool auto-completes successfully when approved.
+     * If true (default), approval = success with feedback as output.
+     * If false, the tool's execute() is called again with hitlContext.
+     * @default true
+     */
+    completesOnApproval?: boolean;
+    /**
+     * Whether rejection allows retry with modified arguments.
+     * If true, rejection doesn't fail the step but allows re-planning.
+     * @default true
+     */
+    allowRetryOnReject?: boolean;
+    /**
+     * Timeout in milliseconds for user response.
+     * If exceeded, the tool fails with a timeout error.
+     * @default undefined (no timeout)
+     */
+    timeoutMs?: number;
+    /**
+     * Category of the blocking action for UI grouping.
+     * Examples: 'destructive', 'financial', 'external', 'sensitive'
+     */
+    category?: string;
+    /**
+     * Risk level for UI styling/warnings.
+     */
+    riskLevel?: 'low' | 'medium' | 'high' | 'critical';
+}
+/**
+ * Configuration for display tools in the ToolSchema.
+ *
+ * @remarks
+ * This is added to ToolSchema when executionMode is 'display'.
+ * Display tools render UI without producing traditional results.
+ */
+interface DisplayToolConfig {
+    /**
+     * The type of UI component this tool renders.
+     */
+    componentType?: string;
+    /**
+     * Whether the display persists or is ephemeral.
+     * @default 'persistent'
+     */
+    displayMode?: 'persistent' | 'ephemeral' | 'modal';
+    /**
+     * Whether this display supports user interaction.
+     * If true, interactions may generate new messages.
+     * @default false
+     */
+    interactive?: boolean;
+    /**
+     * Schema for the data this display component expects.
+     */
+    dataSchema?: Record<string, unknown>;
+}
+/**
+ * HITL-specific context passed to tools via ExecutionContext.
+ *
+ * @remarks
+ * This enables blocking tools to know if they're being called
+ * for initial suspension vs. post-approval execution.
+ */
+interface HITLContext {
+    /**
+     * True if this execution is resuming from a previous suspension.
+     */
+    isResuming: boolean;
+    /**
+     * True if the user approved the action.
+     * Only meaningful when isResuming is true.
+     */
+    wasApproved?: boolean;
+    /**
+     * The user's feedback if resuming from approval.
+     */
+    feedback?: HITLFeedback;
+    /**
+     * The original suspension ID being resumed.
+     */
+    suspensionId?: string;
+    /**
+     * The original tool arguments that were suspended.
+     */
+    originalArgs?: Record<string, unknown>;
+}
+/**
+ * Extended ToolResult for blocking tools that return 'suspended' status.
+ *
+ * @remarks
+ * When a blocking tool returns 'suspended', it should include the
+ * feedbackSchema so the UI knows what to render.
+ */
+interface BlockingToolSuspendedResult {
+    status: 'suspended';
+    callId: string;
+    toolName: string;
+    /**
+     * The feedback schema for the UI to render.
+     * If not provided, the framework uses the tool's schema config.
+     */
+    feedbackSchema?: HITLFeedbackSchema;
+    /**
+     * Display content to show in the suspension UI.
+     */
+    output?: {
+        message: string;
+        details?: Record<string, unknown>;
+        previewData?: unknown;
+    };
+    /**
+     * Metadata including the suspensionId.
+     */
+    metadata?: {
+        suspensionId: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * The successful result created by the framework when user provides feedback.
+ *
+ * @remarks
+ * This is what the LLM sees after resumption - a normal successful tool result.
+ * The content field contains a description, and output contains the feedback.
+ */
+interface BlockingToolCompletedResult {
+    status: 'success';
+    callId: string;
+    toolName: string;
+    /**
+     * The user's feedback structured as the tool output.
+     */
+    output: {
+        /**
+         * Human-readable summary of what happened.
+         */
+        message: string;
+        /**
+         * The feedback provided by the user.
+         */
+        feedback: HITLFeedback;
+        /**
+         * Whether the user approved the action.
+         */
+        approved: boolean;
+        /**
+         * The actual value provided (varies by input type).
+         */
+        value?: unknown;
+    };
+    /**
+     * Metadata about the completion.
+     */
+    metadata?: {
+        /**
+         * The original suspension ID that was resumed.
+         */
+        suspensionId?: string;
+        /**
+         * Timestamp of when feedback was received.
+         */
+        completedAt: number;
+        /**
+         * Duration from suspension to completion in ms.
+         */
+        waitDurationMs?: number;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Type guard to check if a ToolResult is a suspended blocking tool result.
+ */
+declare function isBlockingSuspendedResult(result: {
+    status: string;
+}): result is BlockingToolSuspendedResult;
+/**
+ * Type guard to check if feedback indicates approval.
+ */
+declare function isFeedbackApproved(feedback: HITLFeedback): boolean;
+/**
+ * Creates a standardized successful result from HITL feedback.
+ *
+ * @param originalCall - The original tool call that was suspended
+ * @param feedback - The user's feedback
+ * @param suspensionId - The suspension ID being resolved
+ * @returns A properly formatted successful ToolResult
+ */
+declare function createHITLSuccessResult(originalCall: {
+    callId: string;
+    toolName: string;
+    arguments?: unknown;
+}, feedback: HITLFeedback, suspensionId?: string): BlockingToolCompletedResult;
+
 /**
  * Entry defining an available provider adapter.
  *
@@ -1675,6 +2153,7 @@ interface LLMMetadata {
      */
     traceId?: string;
 }
+
 /**
  * Defines the schema for a tool, including its input parameters.
  * Uses JSON Schema format for inputSchema.
@@ -1712,13 +2191,36 @@ interface ToolSchema {
         description?: string;
     }>;
     /**
-     * Defines the execution mode of the tool.
-     * - 'immediate': The tool executes and returns a result immediately (default).
-     * - 'blocking': The tool initiates a process that requires human intervention (HITL).
-     *               The agent will suspend execution until resumed.
-     * @property {'immediate' | 'blocking'} [executionMode]
+     * Defines the execution mode (category) of the tool.
+     *
+     * @remarks
+     * Tools are categorized into three modes with different framework handling:
+     *
+     * - `functional` (default, also 'immediate' for backward compat): Regular tools that
+     *   execute synchronously and return results immediately.
+     *
+     * - `blocking`: HITL tools that require human input to complete. They return 'suspended'
+     *   status initially. When user provides feedback, the framework programmatically
+     *   completes the tool with the feedback as output - no re-execution needed.
+     *
+     * - `display`: Generative UI tools that render visual content. They complete immediately
+     *   but their output is meant for rendering rather than LLM consumption.
+     *
+     * @property {'functional' | 'immediate' | 'blocking' | 'display'} [executionMode]
+     */
+    executionMode?: 'functional' | 'immediate' | 'blocking' | 'display';
+    /**
+     * Configuration for blocking tools (HITL).
+     * Only applicable when executionMode is 'blocking'.
+     * @property {import('./hitl-types').BlockingToolConfig} [blockingConfig]
+     */
+    blockingConfig?: BlockingToolConfig;
+    /**
+     * Configuration for display tools (Generative UI).
+     * Only applicable when executionMode is 'display'.
+     * @property {import('./hitl-types').DisplayToolConfig} [displayConfig]
      */
-    executionMode?: 'immediate' | 'blocking';
+    displayConfig?: DisplayToolConfig;
 }
 /**
  * Represents the structured result of a tool execution.
@@ -2144,6 +2646,22 @@ interface ExecutionContext {
      * @property {string} [userId]
      */
     userId?: string;
+    /**
+     * HITL context for blocking tools.
+     *
+     * @remarks
+     * This enables blocking tools to differentiate between:
+     * - Initial invocation (should return 'suspended' to request user input)
+     * - Post-approval invocation (if completesOnApproval is false, tool is re-executed)
+     *
+     * For most blocking tools with completesOnApproval=true (default), the tool is NOT
+     * re-executed after approval - the framework creates the success result programmatically.
+     * This field is only populated when completesOnApproval=false and the tool needs
+     * to perform actual work after user approval.
+     *
+     * @property {import('./hitl-types').HITLContext} [hitlContext]
+     */
+    hitlContext?: HITLContext;
 }
 /**
  * Options for configuring an LLM call, including streaming and context information.
@@ -6565,6 +7083,6 @@ declare const generateUUID: () => string;
 /**
  * The current version of the ART Framework package.
  */
-declare const VERSION = "0.4.13";
+declare const VERSION = "0.4.14";
 
-export { type A2AAgentInfo, type A2ATask, type A2ATaskEvent, type A2ATaskFilter, type A2ATaskMetadata, A2ATaskPriority, type A2ATaskResult, A2ATaskSocket, A2ATaskStatus, ARTError, AdapterInstantiationError, type AgentDiscoveryConfig, AgentDiscoveryService, AgentFactory, type AgentFinalResponse, type AgentOptions, type AgentPersona, type AgentProps, type AgentState, AnthropicAdapter, type AnthropicAdapterOptions, ApiKeyStrategy, ApiQueueTimeoutError, type ArtInstance, type ArtInstanceConfig, type ArtStandardMessage, type ArtStandardMessageRole, ArtStandardMessageSchema, type ArtStandardPrompt, ArtStandardPromptSchema, AuthManager, type AvailableProviderEntry, CalculatorTool, type CallOptions, type ConversationManager, type ConversationMessage, ConversationSocket, type CreateA2ATaskRequest, DeepSeekAdapter, type DeepSeekAdapterOptions, ErrorCode, type ExecutionConfig, type ExecutionContext, type ExecutionMetadata, type ExecutionOutput, type FilterOptions, type FormattedPrompt, GeminiAdapter, type GeminiAdapterOptions, GenericOAuthStrategy, GroqAdapter, type GroqAdapterOptions, type IA2ATaskRepository, type IAgentCore, type IAuthStrategy, type IConversationRepository, type IObservationRepository, type IProviderManager, type IStateRepository, type IToolExecutor, type ITypedSocket, InMemoryStorageAdapter, IndexedDBStorageAdapter, type JsonObjectSchema, type JsonSchema, type LLMMetadata, LLMStreamSocket, LocalInstanceBusyError, LocalProviderConflictError, LogLevel, Logger, type LoggerConfig, type ManagedAdapterAccessor, McpClientController, McpManager, type McpManagerConfig, McpProxyTool, type McpResource, type McpResourceTemplate, type McpServerConfig, type McpServerStatus, type McpToolDefinition, type MessageOptions, MessageRole, ModelCapability, type OAuthConfig, type Observation, type ObservationFilter, type ObservationManager, ObservationSocket, ObservationType, OllamaAdapter, type OllamaAdapterOptions, OpenAIAdapter, type OpenAIAdapterOptions, OpenRouterAdapter, type OpenRouterAdapterOptions, OutputParser, PESAgent, type PESAgentStateData, type PKCEOAuthConfig, PKCEOAuthStrategy, type ParsedToolCall, type PromptBlueprint, type PromptContext, type ProviderAdapter, type ProviderManagerConfig, ProviderManagerImpl, ReasoningEngine, type RuntimeProviderConfig, type StageSpecificPrompts, StateManager, type StateSavingStrategy, type StepOutputEntry, type StorageAdapter, type StreamEvent, type StreamEventTypeFilter, SupabaseStorageAdapter, type SystemPromptMergeStrategy, type SystemPromptOverride, SystemPromptResolver, type SystemPromptSpec, type SystemPromptsRegistry, type TaskDelegationConfig, TaskDelegationService, type TaskStatusResponse, type ThreadConfig, type ThreadContext, type TodoItem, TodoItemStatus, ToolRegistry, type ToolResult, type ToolSchema, type ToolSystem, TypedSocket, UISystem, UnknownProviderError, type UnsubscribeFunction, type UpdateA2ATaskRequest, VERSION, type ZyntopiaOAuthConfig, ZyntopiaOAuthStrategy, createArtInstance, generateUUID };
+export { type A2AAgentInfo, type A2ATask, type A2ATaskEvent, type A2ATaskFilter, type A2ATaskMetadata, A2ATaskPriority, type A2ATaskResult, A2ATaskSocket, A2ATaskStatus, ARTError, AdapterInstantiationError, type AgentDiscoveryConfig, AgentDiscoveryService, AgentFactory, type AgentFinalResponse, type AgentOptions, type AgentPersona, type AgentProps, type AgentState, AnthropicAdapter, type AnthropicAdapterOptions, ApiKeyStrategy, ApiQueueTimeoutError, type ArtInstance, type ArtInstanceConfig, type ArtStandardMessage, type ArtStandardMessageRole, ArtStandardMessageSchema, type ArtStandardPrompt, ArtStandardPromptSchema, AuthManager, type AvailableProviderEntry, type BlockingToolCompletedResult, type BlockingToolConfig, type BlockingToolSuspendedResult, CalculatorTool, type CallOptions, type ConversationManager, type ConversationMessage, ConversationSocket, type CreateA2ATaskRequest, DeepSeekAdapter, type DeepSeekAdapterOptions, type DisplayToolConfig, ErrorCode, type ExecutionConfig, type ExecutionContext, type ExecutionMetadata, type ExecutionOutput, type FilterOptions, type FormattedPrompt, GeminiAdapter, type GeminiAdapterOptions, GenericOAuthStrategy, GroqAdapter, type GroqAdapterOptions, type HITLContext, type HITLFeedback, type HITLFeedbackSchema, type HITLInputType, type HITLInputValidation, type HITLSelectOption, type IA2ATaskRepository, type IAgentCore, type IAuthStrategy, type IConversationRepository, type IObservationRepository, type IProviderManager, type IStateRepository, type IToolExecutor, type ITypedSocket, InMemoryStorageAdapter, IndexedDBStorageAdapter, type JsonObjectSchema, type JsonSchema, type LLMMetadata, LLMStreamSocket, LocalInstanceBusyError, LocalProviderConflictError, LogLevel, Logger, type LoggerConfig, type ManagedAdapterAccessor, McpClientController, McpManager, type McpManagerConfig, McpProxyTool, type McpResource, type McpResourceTemplate, type McpServerConfig, type McpServerStatus, type McpToolDefinition, type MessageOptions, MessageRole, ModelCapability, type OAuthConfig, type Observation, type ObservationFilter, type ObservationManager, ObservationSocket, ObservationType, OllamaAdapter, type OllamaAdapterOptions, OpenAIAdapter, type OpenAIAdapterOptions, OpenRouterAdapter, type OpenRouterAdapterOptions, OutputParser, PESAgent, type PESAgentStateData, type PKCEOAuthConfig, PKCEOAuthStrategy, type ParsedToolCall, type PromptBlueprint, type PromptContext, type ProviderAdapter, type ProviderManagerConfig, ProviderManagerImpl, ReasoningEngine, type RuntimeProviderConfig, type StageSpecificPrompts, StateManager, type StateSavingStrategy, type StepOutputEntry, type StorageAdapter, type StreamEvent, type StreamEventTypeFilter, SupabaseStorageAdapter, type SystemPromptMergeStrategy, type SystemPromptOverride, SystemPromptResolver, type SystemPromptSpec, type SystemPromptsRegistry, type TaskDelegationConfig, TaskDelegationService, type TaskStatusResponse, type ThreadConfig, type ThreadContext, type TodoItem, TodoItemStatus, type ToolExecutionMode, ToolRegistry, type ToolResult, type ToolSchema, type ToolSystem, TypedSocket, UISystem, UnknownProviderError, type UnsubscribeFunction, type UpdateA2ATaskRequest, VERSION, type ZyntopiaOAuthConfig, ZyntopiaOAuthStrategy, createArtInstance, createHITLSuccessResult, generateUUID, isBlockingSuspendedResult, isFeedbackApproved };