art-framework 0.4.5 → 0.4.6

package/dist/index.d.cts

@@ -450,10 +450,16 @@ interface TodoItem {
     description: string;
     status: TodoItemStatus;
     dependencies?: string[];
+    stepType?: 'tool' | 'reasoning';
+    requiredTools?: string[];
+    expectedOutcome?: string;
+    toolValidationMode?: 'strict' | 'advisory';
     result?: any;
     thoughts?: string[];
     toolCalls?: ParsedToolCall[];
+    actualToolCalls?: ParsedToolCall[];
     toolResults?: ToolResult[];
+    validationStatus?: 'passed' | 'failed' | 'skipped';
     createdTimestamp: number;
     updatedTimestamp: number;
 }
@@ -465,6 +471,12 @@ interface PESAgentStateData {
     todoList: TodoItem[];
     currentStepId: string | null;
     isPaused: boolean;
+    suspension?: {
+        suspensionId: string;
+        itemId: string;
+        toolCall: ParsedToolCall;
+        iterationState: ArtStandardPrompt;
+    };
 }
 interface ExecutionOutput {
     thoughts?: string;
@@ -1041,6 +1053,12 @@ declare enum ObservationType {
     PLAN_UPDATE = "PLAN_UPDATE",
     /** Records status changes of a specific todo item. */
     ITEM_STATUS_CHANGE = "ITEM_STATUS_CHANGE",
+    /** Emitted when an agent pauses execution to wait for human input (Blocking Tool). */
+    AGENT_SUSPENDED = "AGENT_SUSPENDED",
+    /** Emitted when an agent resumes execution after receiving human input. */
+    AGENT_RESUMED = "AGENT_RESUMED",
+    /** Emitted if a suspension times out (reserved for future use). */
+    SUSPENSION_TIMEOUT = "SUSPENSION_TIMEOUT",
     /** Logged by Agent Core when LLM stream consumption begins. */
     LLM_STREAM_START = "LLM_STREAM_START",
     /** Logged by Agent Core upon receiving a METADATA stream event. Content should be LLMMetadata. */
@@ -1319,6 +1337,14 @@ interface ToolSchema {
         output?: any;
         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]
+     */
+    executionMode?: 'immediate' | 'blocking';
 }
 /**
  * Represents the structured result of a tool execution.
@@ -1337,10 +1363,10 @@ interface ToolResult {
      */
     toolName: string;
     /**
-     * Indicates whether the tool execution succeeded or failed.
-     * @property {'success' | 'error'} status
+     * Indicates whether the tool execution succeeded, failed, or was suspended.
+     * @property {'success' | 'error' | 'suspended'} status
      */
-    status: 'success' | 'error';
+    status: 'success' | 'error' | 'suspended';
     /**
      * The data returned by the tool upon successful execution. Structure may be validated against `outputSchema`.
      * @property {any} [output]
@@ -1361,6 +1387,7 @@ interface ToolResult {
             url?: string;
             [key: string]: any;
         }>;
+        suspensionId?: string;
         [key: string]: any;
     };
 }
@@ -1573,6 +1600,13 @@ interface AgentProps {
      * @property {AgentOptions} [options]
      */
     options?: AgentOptions;
+    /**
+     * Internal flag indicating this is a resume from a suspended state.
+     * Set automatically by `resumeExecution()` - do not set manually for regular queries.
+     * When true, the agent continues from the suspended step without triggering plan refinement.
+     * @property {boolean} [isResume]
+     */
+    isResume?: boolean;
 }
 /**
  * Options to override agent behavior at runtime.
@@ -3288,6 +3322,29 @@ interface IAuthStrategy {
 interface ArtInstance {
     /** The main method to process a user query using the configured Agent Core. */
     readonly process: IAgentCore['process'];
+    /**
+     * Resumes a suspended agent execution (HITL).
+     * @param threadId The ID of the suspended thread.
+     * @param suspensionId The ID provided in the suspension observation/state.
+     * @param decision The user's decision payload.
+     */
+    readonly resumeExecution: (threadId: string, suspensionId: string, decision: {
+        approved: boolean;
+        reason?: string;
+        modifiedArgs?: Record<string, unknown>;
+    }) => Promise<AgentFinalResponse>;
+    /**
+     * Checks if a thread is currently in a suspended state (waiting for HITL approval).
+     * Use this on app initialization to detect and restore suspension UI after page refresh.
+     * @param threadId The ID of the thread to check.
+     * @returns Suspension info if suspended, null otherwise.
+     */
+    readonly checkForSuspendedState: (threadId: string) => Promise<{
+        suspensionId: string;
+        itemId: string;
+        toolName: string;
+        toolInput: any;
+    } | null>;
     /** Accessor for the UI System, used to get sockets for subscriptions. */
     readonly uiSystem: UISystem$1;
     /** Accessor for the State Manager, used for managing thread configuration and state. */
@@ -3824,6 +3881,21 @@ declare class PESAgent implements IAgentCore {
     private _performPlanRefinement;
     private _callPlanningLLM;
     private _executeTodoList;
+    /**
+     * Builds execution prompt for TOOL-type steps.
+     * Emphasizes tool invocation and explicitly names required tools.
+     */
+    private _buildToolStepPrompt;
+    /**
+     * Builds execution prompt for REASONING-type steps.
+     * Emphasizes analysis and synthesis without requiring tool invocation.
+     */
+    private _buildReasoningStepPrompt;
+    /**
+     * TAEF: Retry mechanism when required tools were not invoked.
+     * Appends enforcement prompt and returns the messages for retry.
+     */
+    private _buildToolEnforcementPrompt;
     private _processTodoItem;
     private _performSynthesis;
     private _loadConfiguration;
@@ -5346,6 +5418,6 @@ declare const generateUUID: () => string;
 /**
  * The current version of the ART Framework package.
  */
-declare const VERSION = "0.4.5";
+declare const VERSION = "0.4.6";
 
 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 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, type OutputParser, PESAgent, type PESAgentStateData, type PKCEOAuthConfig, PKCEOAuthStrategy, type ParsedToolCall, type PromptBlueprint, type PromptContext, type ProviderAdapter, type ProviderManagerConfig, ProviderManagerImpl, type ReasoningEngine, type RuntimeProviderConfig, type StageSpecificPrompts, StateManager, type StateSavingStrategy, type StorageAdapter, type StreamEvent, type StreamEventTypeFilter, SupabaseStorageAdapter, type SystemPromptMergeStrategy, type SystemPromptOverride, type 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 };

package/dist/index.d.ts

@@ -450,10 +450,16 @@ interface TodoItem {
     description: string;
     status: TodoItemStatus;
     dependencies?: string[];
+    stepType?: 'tool' | 'reasoning';
+    requiredTools?: string[];
+    expectedOutcome?: string;
+    toolValidationMode?: 'strict' | 'advisory';
     result?: any;
     thoughts?: string[];
     toolCalls?: ParsedToolCall[];
+    actualToolCalls?: ParsedToolCall[];
     toolResults?: ToolResult[];
+    validationStatus?: 'passed' | 'failed' | 'skipped';
     createdTimestamp: number;
     updatedTimestamp: number;
 }
@@ -465,6 +471,12 @@ interface PESAgentStateData {
     todoList: TodoItem[];
     currentStepId: string | null;
     isPaused: boolean;
+    suspension?: {
+        suspensionId: string;
+        itemId: string;
+        toolCall: ParsedToolCall;
+        iterationState: ArtStandardPrompt;
+    };
 }
 interface ExecutionOutput {
     thoughts?: string;
@@ -1041,6 +1053,12 @@ declare enum ObservationType {
     PLAN_UPDATE = "PLAN_UPDATE",
     /** Records status changes of a specific todo item. */
     ITEM_STATUS_CHANGE = "ITEM_STATUS_CHANGE",
+    /** Emitted when an agent pauses execution to wait for human input (Blocking Tool). */
+    AGENT_SUSPENDED = "AGENT_SUSPENDED",
+    /** Emitted when an agent resumes execution after receiving human input. */
+    AGENT_RESUMED = "AGENT_RESUMED",
+    /** Emitted if a suspension times out (reserved for future use). */
+    SUSPENSION_TIMEOUT = "SUSPENSION_TIMEOUT",
     /** Logged by Agent Core when LLM stream consumption begins. */
     LLM_STREAM_START = "LLM_STREAM_START",
     /** Logged by Agent Core upon receiving a METADATA stream event. Content should be LLMMetadata. */
@@ -1319,6 +1337,14 @@ interface ToolSchema {
         output?: any;
         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]
+     */
+    executionMode?: 'immediate' | 'blocking';
 }
 /**
  * Represents the structured result of a tool execution.
@@ -1337,10 +1363,10 @@ interface ToolResult {
      */
     toolName: string;
     /**
-     * Indicates whether the tool execution succeeded or failed.
-     * @property {'success' | 'error'} status
+     * Indicates whether the tool execution succeeded, failed, or was suspended.
+     * @property {'success' | 'error' | 'suspended'} status
      */
-    status: 'success' | 'error';
+    status: 'success' | 'error' | 'suspended';
     /**
      * The data returned by the tool upon successful execution. Structure may be validated against `outputSchema`.
      * @property {any} [output]
@@ -1361,6 +1387,7 @@ interface ToolResult {
             url?: string;
             [key: string]: any;
         }>;
+        suspensionId?: string;
         [key: string]: any;
     };
 }
@@ -1573,6 +1600,13 @@ interface AgentProps {
      * @property {AgentOptions} [options]
      */
     options?: AgentOptions;
+    /**
+     * Internal flag indicating this is a resume from a suspended state.
+     * Set automatically by `resumeExecution()` - do not set manually for regular queries.
+     * When true, the agent continues from the suspended step without triggering plan refinement.
+     * @property {boolean} [isResume]
+     */
+    isResume?: boolean;
 }
 /**
  * Options to override agent behavior at runtime.
@@ -3288,6 +3322,29 @@ interface IAuthStrategy {
 interface ArtInstance {
     /** The main method to process a user query using the configured Agent Core. */
     readonly process: IAgentCore['process'];
+    /**
+     * Resumes a suspended agent execution (HITL).
+     * @param threadId The ID of the suspended thread.
+     * @param suspensionId The ID provided in the suspension observation/state.
+     * @param decision The user's decision payload.
+     */
+    readonly resumeExecution: (threadId: string, suspensionId: string, decision: {
+        approved: boolean;
+        reason?: string;
+        modifiedArgs?: Record<string, unknown>;
+    }) => Promise<AgentFinalResponse>;
+    /**
+     * Checks if a thread is currently in a suspended state (waiting for HITL approval).
+     * Use this on app initialization to detect and restore suspension UI after page refresh.
+     * @param threadId The ID of the thread to check.
+     * @returns Suspension info if suspended, null otherwise.
+     */
+    readonly checkForSuspendedState: (threadId: string) => Promise<{
+        suspensionId: string;
+        itemId: string;
+        toolName: string;
+        toolInput: any;
+    } | null>;
     /** Accessor for the UI System, used to get sockets for subscriptions. */
     readonly uiSystem: UISystem$1;
     /** Accessor for the State Manager, used for managing thread configuration and state. */
@@ -3824,6 +3881,21 @@ declare class PESAgent implements IAgentCore {
     private _performPlanRefinement;
     private _callPlanningLLM;
     private _executeTodoList;
+    /**
+     * Builds execution prompt for TOOL-type steps.
+     * Emphasizes tool invocation and explicitly names required tools.
+     */
+    private _buildToolStepPrompt;
+    /**
+     * Builds execution prompt for REASONING-type steps.
+     * Emphasizes analysis and synthesis without requiring tool invocation.
+     */
+    private _buildReasoningStepPrompt;
+    /**
+     * TAEF: Retry mechanism when required tools were not invoked.
+     * Appends enforcement prompt and returns the messages for retry.
+     */
+    private _buildToolEnforcementPrompt;
     private _processTodoItem;
     private _performSynthesis;
     private _loadConfiguration;
@@ -5346,6 +5418,6 @@ declare const generateUUID: () => string;
 /**
  * The current version of the ART Framework package.
  */
-declare const VERSION = "0.4.5";
+declare const VERSION = "0.4.6";
 
 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 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, type OutputParser, PESAgent, type PESAgentStateData, type PKCEOAuthConfig, PKCEOAuthStrategy, type ParsedToolCall, type PromptBlueprint, type PromptContext, type ProviderAdapter, type ProviderManagerConfig, ProviderManagerImpl, type ReasoningEngine, type RuntimeProviderConfig, type StageSpecificPrompts, StateManager, type StateSavingStrategy, type StorageAdapter, type StreamEvent, type StreamEventTypeFilter, SupabaseStorageAdapter, type SystemPromptMergeStrategy, type SystemPromptOverride, type 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 };