art-framework 0.3.8 → 0.4.0

package/dist/index.d.cts

@@ -437,6 +437,47 @@ declare class LLMStreamSocket extends TypedSocket<StreamEvent, StreamEventTypeFi
     notifyStreamEvent(event: StreamEvent): void;
 }
 
+declare enum TodoItemStatus {
+    PENDING = "pending",
+    IN_PROGRESS = "in_progress",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    CANCELLED = "cancelled",
+    WAITING = "waiting"
+}
+interface TodoItem {
+    id: string;
+    description: string;
+    status: TodoItemStatus;
+    dependencies?: string[];
+    result?: any;
+    thoughts?: string[];
+    toolCalls?: ParsedToolCall[];
+    toolResults?: ToolResult[];
+    createdTimestamp: number;
+    updatedTimestamp: number;
+}
+interface PESAgentStateData {
+    threadId: string;
+    intent: string;
+    title: string;
+    plan: string;
+    todoList: TodoItem[];
+    currentStepId: string | null;
+    isPaused: boolean;
+}
+interface ExecutionOutput {
+    thoughts?: string;
+    content?: string;
+    toolCalls?: ParsedToolCall[];
+    nextStepDecision?: 'continue' | 'wait' | 'complete_item' | 'update_plan';
+    updatedPlan?: {
+        intent?: string;
+        plan?: string;
+        todoList?: TodoItem[];
+    };
+}
+
 /**
  * @module types/schemas
  * This module defines Zod schemas for validating the core data structures of the ART framework,
@@ -996,6 +1037,10 @@ declare enum ObservationType {
     FINAL_RESPONSE = "FINAL_RESPONSE",
     /** Records changes made to the agent's persistent state. */
     STATE_UPDATE = "STATE_UPDATE",
+    /** Records updates to the plan structure (intent, title, or list changes). */
+    PLAN_UPDATE = "PLAN_UPDATE",
+    /** Records status changes of a specific todo item. */
+    ITEM_STATUS_CHANGE = "ITEM_STATUS_CHANGE",
     /** 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. */
@@ -1043,6 +1088,12 @@ interface Observation {
      * @property {string} threadId
      */
     threadId: string;
+    /**
+     * An optional identifier for the parent object (e.g., a TodoItem ID) to which this observation belongs.
+     * This allows differentiation between primary (user query) and secondary (sub-task) observations.
+     * @property {string} [parentId]
+     */
+    parentId?: string;
     /**
      * An optional identifier for tracing a request across multiple systems or components.
      * @property {string} [traceId]
@@ -2787,41 +2838,6 @@ interface ReasoningEngine {
      */
     call(prompt: FormattedPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
 }
-/**
- * Interface for the stateless prompt assembler.
- * Uses a blueprint (template) and context provided by Agent Logic
- * to create a standardized prompt format (`ArtStandardPrompt`).
- */
-interface PromptManager {
-    /**
-     * Retrieves a named prompt fragment (e.g., a piece of instruction text).
-     * Optionally allows for simple variable substitution if the fragment is a basic template.
-     *
-     * @param name - The unique identifier for the fragment.
-     * @param context - Optional data for simple variable substitution within the fragment.
-     * @returns The processed prompt fragment string.
-     * @throws {ARTError} If the fragment is not found.
-     */
-    getFragment(name: string, context?: Record<string, any>): string;
-    /**
-     * Validates a constructed prompt object against the standard schema.
-     *
-     * @param prompt - The ArtStandardPrompt object constructed by the agent.
-     * @returns The validated prompt object (potentially after normalization if the schema does that).
-     * @throws {ZodError} If validation fails (can be caught and wrapped in ARTError).
-     */
-    validatePrompt(prompt: ArtStandardPrompt): ArtStandardPrompt;
-    /**
-     * Assembles a prompt using a Mustache template (blueprint) and context data.
-     * Renders the template with the provided context and parses the result as an ArtStandardPrompt.
-     *
-     * @param blueprint - The Mustache template containing the prompt structure.
-     * @param context - The context data to inject into the template.
-     * @returns A promise resolving to the assembled ArtStandardPrompt.
-     * @throws {ARTError} If template rendering or JSON parsing fails.
-     */
-    assemblePrompt(blueprint: PromptBlueprint, context: PromptContext): Promise<ArtStandardPrompt>;
-}
 /**
  * Resolves the final system prompt from base + instance/thread/call overrides
  * using tag+variables and merge strategies.
@@ -2864,7 +2880,14 @@ interface OutputParser {
         plan?: string;
         toolCalls?: ParsedToolCall[];
         thoughts?: string;
+        todoList?: TodoItem[];
     }>;
+    /**
+     * Parses the raw string output from the execution LLM call (per todo item).
+     * @param output - The raw string response from the execution LLM call.
+     * @returns A promise resolving to the structured execution output.
+     */
+    parseExecutionOutput(output: string): Promise<ExecutionOutput>;
     /**
      * Parses the raw string output from the synthesis LLM call to extract the final, user-facing response content.
      * This might involve removing extraneous tags or formatting.
@@ -3477,6 +3500,76 @@ declare class McpManager {
     uninstallServer(serverId: string): Promise<void>;
 }
 
+/**
+ * Configuration object required by the AgentFactory and createArtInstance function.
+ * This will now use ArtInstanceConfig from types.ts which includes stateSavingStrategy.
+ */
+/**
+ * Handles the instantiation and wiring of all core ART framework components based on provided configuration.
+ * This class performs the dependency injection needed to create a functional `ArtInstance`.
+ * It's typically used internally by the `createArtInstance` function.
+ */
+declare class AgentFactory {
+    private config;
+    private storageAdapter;
+    private uiSystem;
+    private conversationRepository;
+    private observationRepository;
+    private stateRepository;
+    private a2aTaskRepository;
+    private conversationManager;
+    private stateManager;
+    private observationManager;
+    private toolRegistry;
+    private providerManager;
+    private reasoningEngine;
+    private outputParser;
+    private systemPromptResolver;
+    private toolSystem;
+    private authManager;
+    private mcpManager;
+    private agentDiscoveryService;
+    private taskDelegationService;
+    /**
+     * Creates a new AgentFactory instance.
+     * @param config - The configuration specifying which adapters and components to use.
+     */
+    constructor(config: ArtInstanceConfig);
+    /**
+     * Asynchronously initializes all core components based on the configuration.
+     * This includes setting up the storage adapter, repositories, managers, tool registry,
+     * reasoning engine, and UI system.
+     * This method MUST be called before `createAgent()`.
+     * @returns A promise that resolves when initialization is complete.
+     * @throws {Error} If configuration is invalid or initialization fails for a component.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Creates an instance of the configured Agent Core (e.g., `PESAgent`) and injects
+     * all necessary initialized dependencies (managers, systems, etc.).
+     * Requires `initialize()` to have been successfully called beforehand.
+     * @returns An instance implementing the `IAgentCore` interface.
+     * @throws {Error} If `initialize()` was not called or if essential components failed to initialize.
+     */
+    createAgent(): IAgentCore;
+    /** Gets the initialized Storage Adapter instance. */
+    getStorageAdapter(): StorageAdapter | null;
+    /** Gets the initialized UI System instance. */
+    getUISystem(): UISystem$1 | null;
+    /** Gets the initialized Tool Registry instance. */
+    getToolRegistry(): ToolRegistry$1 | null;
+    /** Gets the initialized State Manager instance. */
+    getStateManager(): StateManager$1 | null;
+    /** Gets the initialized Conversation Manager instance. */
+    getConversationManager(): ConversationManager | null;
+    /** Gets the initialized Observation Manager instance. */
+    getObservationManager(): ObservationManager | null;
+    /** Gets the initialized Auth Manager instance. */
+    getAuthManager(): AuthManager | null;
+    /** Gets the initialized MCP Manager instance. */
+    getMcpManager(): McpManager | null;
+}
+
 /**
  * High-level factory function to create and initialize a complete ART framework instance.
  * This simplifies the setup process by handling the instantiation and wiring of all
@@ -3691,11 +3784,6 @@ declare class TaskDelegationService {
 interface PESAgentDependencies {
     /** Manages thread configuration and state. */
     stateManager: StateManager$1;
-    /**
-     * Optional default system prompt string provided at the ART instance level.
-     * This serves as a custom prompt part if no thread-specific or call-specific
-     * system prompt is provided. It's appended to the agent's base system prompt.
-     */
     /** Manages conversation history. */
     conversationManager: ConversationManager;
     /** Registry for available tools. */
@@ -3723,101 +3811,27 @@ interface PESAgentDependencies {
 }
 /**
  * Implements the Plan-Execute-Synthesize (PES) agent orchestration logic.
- * This agent follows a structured approach:
- * 1.  **Plan:** Understand the user query, determine intent, and create a plan (potentially involving tool calls).
- * 2.  **Execute:** Run any necessary tools identified in the planning phase.
- * 3.  **Synthesize:** Generate a final response based on the query, plan, and tool results.
- *
- * It constructs standardized prompts (`ArtStandardPrompt`) directly as JavaScript objects
- * for the `ReasoningEngine`. It processes the `StreamEvent` output from the reasoning engine for both planning and synthesis.
- *
- * // @see {PromptManager} // Removed
- * @see {ReasoningEngine}
- * @see {ArtStandardPrompt}
- * @see {StreamEvent}
+ * Refactored to support persistent TodoList execution and iterative refinement.
  */
 declare class PESAgent implements IAgentCore {
     private readonly deps;
     private readonly persona;
-    /**
-     * Creates an instance of the PESAgent.
-     * @param {module:core/agents/pes-agent.PESAgentDependencies} dependencies - An object containing instances of all required subsystems (managers, registries, etc.).
-     */
     constructor(dependencies: PESAgentDependencies);
-    /**
-     * Executes the full Plan-Execute-Synthesize cycle for a given user query.
-     *
-     * **Workflow:**
-     * 1.  **Initiation & Config:** Loads thread configuration and resolves system prompt
-     * 2.  **Data Gathering:** Gathers history, available tools
-     * 3.  **Planning:** LLM call for planning and parsing
-     * 4.  **A2A Discovery & Delegation:** Identifies and delegates A2A tasks to remote agents
-     * 5.  **Tool Execution:** Executes identified local tool calls
-     * 6.  **Synthesis:** LLM call for final response generation including A2A results
-     * 7.  **Finalization:** Saves messages and cleanup
-     *
-     * @param {AgentProps} props - The input properties containing the user query, threadId, userId, traceId, etc.
-     * @returns {Promise<AgentFinalResponse>} A promise resolving to the final response, including the AI message and execution metadata.
-     * @throws {ARTError} If a critical error occurs that prevents the agent from completing the process.
-     */
     process(props: AgentProps): Promise<AgentFinalResponse>;
-    /**
-     * Loads thread configuration and resolves the system prompt hierarchy.
-     * @private
-     */
+    private _saveState;
+    private _recordPlanObservations;
+    private _performPlanning;
+    private _performPlanRefinement;
+    private _callPlanningLLM;
+    private _executeTodoList;
+    private _processTodoItem;
+    private _performSynthesis;
     private _loadConfiguration;
-    /**
-     * Gathers conversation history for the current thread.
-     * @private
-     */
     private _gatherHistory;
-    /**
-     * Gathers available tools for the current thread.
-     * @private
-     */
     private _gatherTools;
-    /**
-     * Performs the planning phase including LLM call and output parsing.
-     * @private
-     *
-     * @remarks
-     * The planning prompt instructs the LLM to produce a concise `title` (<= 10 words)
-     * alongside `intent`, `plan`, and `toolCalls`. After parsing, a `TITLE` observation
-     * is emitted (if present) for UI components to subscribe via `ObservationSocket`.
-     */
-    private _performPlanning;
-    /**
-     * Delegates A2A tasks identified in the planning phase.
-     * @private
-     */
     private _delegateA2ATasks;
-    /**
-     * Waits for A2A tasks to complete with configurable timeout.
-     * Polls task status periodically and updates local repository with results.
-     * @private
-     */
     private _waitForA2ACompletion;
-    /**
-     * Executes local tools identified during planning.
-     * @private
-     */
-    private _executeLocalTools;
-    /**
-     * Performs the synthesis phase including LLM call for final response generation.
-     * @private
-     */
-    private _performSynthesis;
-    /**
-     * Finalizes the agent execution by saving the final message and performing cleanup.
-     * @private
-     */
     private _finalize;
-    /**
-     * Formats conversation history messages for direct inclusion in ArtStandardPrompt.
-     * Converts internal MessageRole to ArtStandardMessageRole.
-     * @param history - Array of ConversationMessage objects.
-     * @returns Array of messages suitable for ArtStandardPrompt.
-     */
     private formatHistoryForPrompt;
 }
 
@@ -4130,7 +4144,7 @@ declare class SupabaseStorageAdapter implements StorageAdapter {
 interface GeminiAdapterOptions {
     /** Your Google AI API key (e.g., from Google AI Studio). Handle securely. */
     apiKey: string;
-    /** The default Gemini model ID to use (e.g., 'gemini-1.5-flash-latest', 'gemini-pro'). Defaults to 'gemini-1.5-flash-latest' if not provided. */
+    /** The default Gemini model ID to use (e.g., 'gemini-2.5-flash', 'gemini-pro'). Defaults to 'gemini-2.5-flash' if not provided. */
     model?: string;
     /** Optional: Override the base URL for the Google Generative AI API. */
     apiBaseUrl?: string;
@@ -5253,4 +5267,4 @@ declare const generateUUID: () => string;
  */
 declare const VERSION = "0.3.8";
 
-export { type A2AAgentInfo, type A2ATask, type A2ATaskEvent, type A2ATaskFilter, type A2ATaskMetadata, A2ATaskPriority, type A2ATaskResult, A2ATaskSocket, A2ATaskStatus, ARTError, AdapterInstantiationError, type AgentDiscoveryConfig, AgentDiscoveryService, 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 FilterOptions, type FormattedPrompt, GeminiAdapter, type GeminiAdapterOptions, GenericOAuthStrategy, 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 PKCEOAuthConfig, PKCEOAuthStrategy, type ParsedToolCall, type PromptBlueprint, type PromptContext, type PromptManager, 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, 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, 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, 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 };