art-framework 0.3.9 → 0.4.1

package/dist/index.d.ts

@@ -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,
@@ -972,37 +1013,88 @@ interface ConversationMessage {
 }
 /**
  * Represents the type of an observation record, capturing significant events during agent execution.
+ * Observations are the primary mechanism for the agent to report its internal state and actions to the outside world (UI, logs, etc.).
  *
  * @enum {string}
  */
 declare enum ObservationType {
-    /** The user's inferred intent. */
+    /**
+     * The user's inferred intent.
+     * Generated during the planning phase to signal understanding of the user's goal.
+     */
     INTENT = "INTENT",
-    /** The generated concise thread title. */
+    /**
+     * The generated concise thread title.
+     * Usually generated once at the start of a new conversation.
+     */
     TITLE = "TITLE",
-    /** The agent's step-by-step plan to address the intent. */
+    /**
+     * The agent's step-by-step plan to address the intent.
+     * Contains the initial or updated TodoList.
+     */
     PLAN = "PLAN",
-    /** The agent's internal monologue or reasoning process. */
+    /**
+     * The agent's internal monologue or reasoning process.
+     * Often captures the 'thinking' blocks from reasoning models.
+     */
     THOUGHTS = "THOUGHTS",
-    /** Records the LLM's decision to call one or more tools (part of the plan). */
+    /**
+     * Records the LLM's decision to call one or more tools (part of the plan).
+     * Contains the tool name and arguments.
+     */
     TOOL_CALL = "TOOL_CALL",
-    /** Records the actual execution attempt and result of a specific tool call. */
+    /**
+     * Records the actual execution attempt and result of a specific tool call.
+     * Contains the result payload or error message.
+     */
     TOOL_EXECUTION = "TOOL_EXECUTION",
-    /** Records events specifically related to the synthesis phase (e.g., the LLM call). */
+    /**
+     * Records events specifically related to the synthesis phase (e.g., the LLM call).
+     */
     SYNTHESIS = "SYNTHESIS",
-    /** Records an error encountered during any phase of execution. */
+    /**
+     * Records an error encountered during any phase of execution.
+     * Contains error details and stack traces.
+     */
     ERROR = "ERROR",
-    /** Records the final AI response message generated by the agent. */
+    /**
+     * Records the final AI response message generated by the agent.
+     * This signals the completion of a turn.
+     */
     FINAL_RESPONSE = "FINAL_RESPONSE",
-    /** Records changes made to the agent's persistent state. */
+    /**
+     * Records changes made to the agent's persistent state.
+     * Useful for debugging state transitions.
+     */
     STATE_UPDATE = "STATE_UPDATE",
-    /** Logged by Agent Core when LLM stream consumption begins. */
+    /**
+     * Records updates to the plan structure (intent, title, or list changes).
+     * Triggered when the agent refines its plan during execution.
+     */
+    PLAN_UPDATE = "PLAN_UPDATE",
+    /**
+     * Records status changes of a specific todo item (e.g., PENDING -> IN_PROGRESS -> COMPLETED).
+     */
+    ITEM_STATUS_CHANGE = "ITEM_STATUS_CHANGE",
+    /**
+     * Logged by Agent Core when LLM stream consumption begins.
+     * Signals the UI to prepare for incoming tokens.
+     */
     LLM_STREAM_START = "LLM_STREAM_START",
-    /** Logged by Agent Core upon receiving a METADATA stream event. Content should be LLMMetadata. */
+    /**
+     * Logged by Agent Core upon receiving a METADATA stream event.
+     * Content contains LLMMetadata (token counts, latency).
+     */
     LLM_STREAM_METADATA = "LLM_STREAM_METADATA",
-    /** Logged by Agent Core upon receiving an END stream event. */
+    /**
+     * Logged by Agent Core upon receiving an END stream event.
+     * Signals the end of a streaming response.
+     */
     LLM_STREAM_END = "LLM_STREAM_END",
-    /** Logged by Agent Core upon receiving an ERROR stream event. Content should be Error object or message. */
+    /**
+     * Logged by Agent Core upon receiving an ERROR stream event.
+     * Content contains the Error object or message.
+     */
     LLM_STREAM_ERROR = "LLM_STREAM_ERROR"
 }
 /**
@@ -1029,6 +1121,7 @@ declare enum ModelCapability {
 }
 /**
  * Represents a recorded event during the agent's execution.
+ * Observations provide a granular log of the agent's internal state, decisions, and interactions.
  *
  * @interface Observation
  */
@@ -1043,6 +1136,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]
@@ -1142,7 +1241,7 @@ interface StreamEvent {
      */
     traceId: string;
     /**
-     * Optional identifier linking the event to a specific UI tab/window.
+     * Optional identifier linking the event to a specific UI session/window.
      * @property {string} [sessionId]
      */
     sessionId?: string;
@@ -1415,27 +1514,32 @@ interface ParsedToolCall {
 }
 /**
  * Configuration specific to a conversation thread.
+ * Controls behavior, tools, and provider settings for a particular interaction context.
  *
  * @interface ThreadConfig
  */
 interface ThreadConfig {
     /**
      * Default provider configuration for this thread.
+     * Determines which LLM and model will be used for reasoning.
      * @property {RuntimeProviderConfig} providerConfig
      */
     providerConfig: RuntimeProviderConfig;
     /**
      * An array of tool names (matching `ToolSchema.name`) that are permitted for use within this thread.
+     * Allows for scoping capabilities per conversation.
      * @property {string[]} enabledTools
      */
     enabledTools: string[];
     /**
      * The maximum number of past messages (`ConversationMessage` objects) to retrieve for context.
+     * Helps manage context window limits.
      * @property {number} historyLimit
      */
     historyLimit: number;
     /**
      * Optional system prompt override to be used for this thread, overriding instance or agent defaults.
+     * Allows for thread-specific role instructions.
      * @property {string | SystemPromptOverride} [systemPrompt]
      */
     systemPrompt?: string | SystemPromptOverride;
@@ -1448,13 +1552,15 @@ interface ThreadConfig {
 }
 /**
  * Represents non-configuration state associated with an agent or thread.
- * Could include user preferences, accumulated knowledge, etc. (Less defined for v1.0)
+ * This is the persistent memory of the agent, used to store planning progress,
+ * variables, and other dynamic data across execution cycles.
  *
  * @interface AgentState
  */
 interface AgentState {
     /**
-     * The primary data payload of the agent's state. Structure is application-defined.
+     * The primary data payload of the agent's state.
+     * Structure is application-defined but typically includes the current plan, todo list, etc.
      * @property {any} data
      */
     data: any;
@@ -1470,7 +1576,8 @@ interface AgentState {
     [key: string]: any;
 }
 /**
- * Encapsulates the configuration and state for a specific thread.
+ * Encapsulates the complete context for a specific thread, combining configuration and state.
+ * This object represents the full snapshot of a thread's environment.
  *
  * @interface ThreadContext
  */
@@ -1487,7 +1594,7 @@ interface ThreadContext {
     state: AgentState | null;
 }
 /**
- * Properties required to initiate an agent processing cycle.
+ * Properties required to initiate an agent processing cycle via `agent.process()`.
  *
  * @interface AgentProps
  */
@@ -1503,7 +1610,7 @@ interface AgentProps {
      */
     threadId: string;
     /**
-     * An optional identifier for the specific UI session, useful for targeting UI updates.
+     * An optional identifier for the specific UI session, useful for targeting UI updates via sockets.
      * @property {string} [sessionId]
      */
     sessionId?: string;
@@ -1524,7 +1631,7 @@ interface AgentProps {
     options?: AgentOptions;
 }
 /**
- * Options to override agent behavior at runtime.
+ * Options to override agent behavior at runtime during a `process` call.
  *
  * @interface AgentOptions
  */
@@ -2632,24 +2739,46 @@ declare class A2ATaskSocket extends TypedSocket<A2ATaskEvent, A2ATaskFilter> {
 }
 
 /**
- * A specialized TypedSocket for handling Observation data.
- * Allows filtering by ObservationType.
- * Can optionally fetch historical observations from a repository.
+ * A specialized `TypedSocket` designed for handling `Observation` data streams.
+ *
+ * @remarks
+ * This socket acts as the bridge between the agent's internal `ObservationManager` and the external UI or monitoring systems.
+ * It extends the generic `TypedSocket` to provide:
+ * 1. **Type-Safe Notification**: Specifically handles `Observation` objects.
+ * 2. **Specialized Filtering**: Allows subscribers to filter events by `ObservationType` (e.g., only subscribe to 'TOOL_EXECUTION' or 'THOUGHTS').
+ * 3. **Historical Access**: Provides a `getHistory` method that leverages the `IObservationRepository` to fetch past observations, enabling UIs to populate initial state.
+ *
+ * This class is a key component of the `UISystem`.
  */
 declare class ObservationSocket extends TypedSocket<Observation, ObservationType | ObservationType[]> {
     private observationRepository?;
+    /**
+     * Creates an instance of ObservationSocket.
+     * @param observationRepository - Optional repository for fetching observation history. If not provided, `getHistory` will return empty arrays.
+     */
     constructor(observationRepository?: IObservationRepository);
     /**
-     * Notifies subscribers about a new observation.
-     * @param observation - The observation data.
+     * Notifies all eligible subscribers about a new observation.
+     *
+     * @remarks
+     * This method is called by the `ObservationManager` whenever a new observation is recorded.
+     * It iterates through all active subscriptions and invokes their callbacks if:
+     * 1. The subscriber's `targetThreadId` (if any) matches the observation's `threadId`.
+     * 2. The subscriber's `filter` (if any) matches the observation's `type`.
+     *
+     * @param observation - The new `Observation` object to broadcast.
      */
     notifyObservation(observation: Observation): void;
     /**
-     * Retrieves historical observations, optionally filtered by type and thread.
-     * Requires an ObservationRepository to be configured.
-     * @param filter - Optional ObservationType or array of types to filter by.
-     * @param options - Optional threadId and limit.
-     * @returns A promise resolving to an array of observations.
+     * Retrieves historical observations from the underlying repository.
+     *
+     * @remarks
+     * This is typically used by UIs when they first connect to a thread to backfill the event log.
+     * It translates the socket's filter criteria into an `ObservationFilter` compatible with the repository.
+     *
+     * @param filter - Optional `ObservationType` or array of types to filter the history by.
+     * @param options - Required object containing `threadId` and optional `limit`.
+     * @returns A promise resolving to an array of `Observation` objects matching the criteria.
      */
     getHistory(filter?: ObservationType | ObservationType[], options?: {
         threadId?: string;
@@ -2829,7 +2958,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.
@@ -3442,6 +3578,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
@@ -3683,91 +3889,167 @@ 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.
+ * 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.
+     * Processes a user query through the PES (Plan-Execute-Synthesize) reasoning loop.
+     * This is the main entry point for the agent's execution logic.
      *
-     * **Workflow:**
-     * 1.  **Initiation & Config:** Loads thread configuration and resolves system prompt
-     * 2.  **Data Gathering:** Gathers history, available tools
-     * 3.  **Loop (ReAct-like):**
-     *     - **Planning:** LLM call for planning and parsing (with access to history of previous steps).
-     *     - **A2A Discovery & Delegation:** Identifies and delegates A2A tasks.
-     *     - **Tool Execution:** Executes identified local tool calls.
-     *     - **Observation:** Results are fed back into the next iteration.
-     * 4.  **Synthesis:** LLM call for final response generation including all results
-     * 5.  **Finalization:** Saves messages and cleanup
+     * The process involves:
+     * 1. **Configuration**: Loading thread context, resolving system prompts, and determining the active persona.
+     * 2. **Context Gathering**: Retrieving conversation history and available tools.
+     * 3. **Planning**: Generating a new plan (Todo List) or refining an existing one based on the new query.
+     * 4. **Execution**: Iterating through the Todo List, executing tasks, calling tools, and managing dependencies.
+     * 5. **Synthesis**: Aggregating results to generate a final, coherent response for the user.
+     * 6. **Finalization**: Saving the response and updating the conversation history.
      *
-     * @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.
+     * @param props - The input properties for the agent execution, including the user query, thread ID, and optional configuration overrides.
+     * @returns A promise that resolves with the final agent response and detailed execution metadata.
      */
     process(props: AgentProps): Promise<AgentFinalResponse>;
     /**
-     * Loads thread configuration and resolves the system prompt hierarchy.
-     * @private
+     * Persists the current agent state to the StateManager.
+     * @param threadId - The unique identifier of the thread.
+     * @param pesState - The current state of the PES agent.
      */
-    private _loadConfiguration;
+    private _saveState;
     /**
-     * Gathers conversation history for the current thread.
-     * @private
+     * Records observations related to the planning phase.
+     * Emits events for INTENT, TITLE (if new), and PLAN.
+     * @param threadId - The thread ID.
+     * @param traceId - The trace ID for correlation.
+     * @param planningOutput - The structured output from the planning LLM.
+     * @param rawText - The raw text output from the LLM (for debugging/audit).
      */
-    private _gatherHistory;
+    private _recordPlanObservations;
     /**
-     * Gathers available tools for the current thread.
-     * @private
+     * Executes the initial planning phase using the LLM.
+     * Generates the initial Todo List based on the user's query and available tools.
+     * @param props - Agent execution properties.
+     * @param systemPrompt - The resolved system prompt for planning.
+     * @param formattedHistory - The conversation history formatted for the LLM.
+     * @param availableTools - List of tools available for the plan.
+     * @param runtimeProviderConfig - Configuration for the LLM provider.
+     * @param traceId - Trace ID for logging and observations.
+     * @returns The structured planning output and metadata.
      */
-    private _gatherTools;
+    private _performPlanning;
     /**
-     * Performs the planning phase including LLM call and output parsing.
-     * @private
+     * Refines an existing plan based on new user input (follow-up).
+     * Updates the Todo List to accommodate the new request while preserving context.
+     * @param props - Agent execution properties.
+     * @param systemPrompt - The resolved system prompt.
+     * @param formattedHistory - Conversation history.
+     * @param currentState - The current agent state (including the existing plan).
+     * @param availableTools - Available tools.
+     * @param runtimeProviderConfig - LLM provider config.
+     * @param traceId - Trace ID.
+     * @returns The updated planning output.
+     */
+    private _performPlanRefinement;
+    /**
+     * Common internal method to call the LLM for planning or refinement.
+     * Handles streaming, observation recording, and output parsing.
+     * @param prompt - The constructed prompt.
+     * @param props - Agent properties.
+     * @param runtimeProviderConfig - Provider config.
+     * @param traceId - Trace ID.
+     * @returns Parsed output and metadata.
+     */
+    private _callPlanningLLM;
+    /**
+     * Orchestrates the execution of the Todo List.
+     * Loops through pending items, checks dependencies, and executes them.
+     * @param props - Agent properties.
+     * @param pesState - The current state containing the Todo List.
+     * @param availableTools - Tools available for execution.
+     * @param runtimeProviderConfig - Provider config.
+     * @param traceId - Trace ID.
+     * @returns Execution statistics (LLM calls, tool calls) and metadata.
+     */
+    private _executeTodoList;
+    /**
+     * Processes a single Todo Item.
+     * This involves calling the LLM to execute the step, potentially using tools, and updating the plan if necessary.
+     * @param props - Agent properties.
+     * @param item - The Todo Item to execute.
+     * @param state - Current agent state.
+     * @param availableTools - Available tools.
+     * @param runtimeProviderConfig - Provider config.
+     * @param traceId - Trace ID.
+     * @returns Result of the item execution (status, output, usage metrics).
+     */
+    private _processTodoItem;
+    /**
+     * Synthesizes the final response based on the completed tasks and the user's original query.
+     * @param props - Agent properties.
+     * @param systemPrompt - Synthesis system prompt.
+     * @param formattedHistory - Conversation history.
+     * @param state - Final agent state.
+     * @param runtimeProviderConfig - Provider config.
+     * @param traceId - Trace ID.
+     * @param finalPersona - The persona to use for synthesis.
+     * @returns The final response content and metadata.
      */
-    private _performPlanning;
+    private _performSynthesis;
     /**
-     * Delegates A2A tasks identified in the planning phase.
-     * @private
+     * Loads the initial configuration, thread context, and resolves prompts.
+     * @param props - Agent properties.
+     * @param traceId - Trace ID.
+     * @returns Loaded configuration and context.
+     * @throws {ARTError} If context or config is missing.
      */
-    private _delegateA2ATasks;
+    private _loadConfiguration;
     /**
-     * Waits for A2A tasks to complete with configurable timeout.
-     * @private
+     * Retrieves the conversation history for the thread.
+     * @param threadId - The thread ID.
+     * @param threadContext - The loaded thread context.
+     * @returns Formatted conversation history.
      */
-    private _waitForA2ACompletion;
+    private _gatherHistory;
     /**
-     * Executes local tools identified during planning.
-     * @private
+     * Retrieves available tools for the thread.
+     * @param threadId - The thread ID.
+     * @returns Array of available tool schemas.
      */
-    private _executeLocalTools;
+    private _gatherTools;
     /**
-     * Performs the synthesis phase including LLM call for final response generation.
-     * @private
+     * Delegates tasks to other agents (Agent-to-Agent).
+     * Discovers agents and sends task requests.
+     * @param planningOutput - Output from the planning phase containing potential delegation calls.
+     * @param threadId - Current thread ID.
+     * @param traceId - Trace ID.
+     * @returns Array of created A2A tasks.
      */
-    private _performSynthesis;
+    private _delegateA2ATasks;
     /**
-     * Finalizes the agent execution by saving the final message and performing cleanup.
-     * @private
+     * Waits for delegated A2A tasks to complete.
+     * Polls the repository until all tasks are in a terminal state or timeout is reached.
+     * @param a2aTasks - The tasks to wait for.
+     * @param threadId - Thread ID.
+     * @param traceId - Trace ID.
+     * @param maxWaitTimeMs - Maximum time to wait in milliseconds.
+     * @param pollIntervalMs - Polling interval.
+     * @returns The updated list of tasks.
+     */
+    private _waitForA2ACompletion;
+    /**
+     * Finalizes the agent execution by saving the AI response and recording the final observation.
+     * @param props - Agent properties.
+     * @param finalResponseContent - The content of the final AI message.
+     * @param traceId - Trace ID.
+     * @param uiMetadata - Optional UI metadata extracted from the response.
+     * @returns The created ConversationMessage object.
      */
     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.
+     * Helper to format internal conversation messages into the standard prompt format required by the LLM.
+     * @param history - Array of ConversationMessages.
+     * @returns Array of formatted prompt messages.
      */
     private formatHistoryForPrompt;
 }
@@ -4081,7 +4363,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-3-flash', 'gemini-pro'). Defaults to 'gemini-3-flash' if not provided. */
     model?: string;
     /** Optional: Override the base URL for the Google Generative AI API. */
     apiBaseUrl?: string;
@@ -4109,10 +4391,11 @@ declare class GeminiAdapter implements ProviderAdapter {
      * Handles both streaming and non-streaming requests based on `options.stream`.
      *
      * Thinking tokens (Gemini):
-     * - On supported Gemini models (e.g., `gemini-2.5-*`), you can enable thought output via `config.thinkingConfig`.
+     * - On supported Gemini models (e.g., `gemini-3-*`), you can enable thought output via `config.thinkingConfig`.
      * - This adapter reads provider-specific flags from the call options:
      *   - `options.gemini.thinking.includeThoughts: boolean` — when `true`, requests thought (reasoning) output.
      *   - `options.gemini.thinking.thinkingBudget?: number` — optional token budget for thinking.
+     *   - `options.gemini.thinking.thinkingLevel?: 'low' | 'minimal' | 'medium' | 'high'` — optional thinking level (Gemini 3+).
      * - When enabled and supported, the adapter will attempt to differentiate thought vs response parts and set
      *   `StreamEvent.tokenType` accordingly:
      *   - For planning calls (`callContext === 'AGENT_THOUGHT'`): `AGENT_THOUGHT_LLM_THINKING` or `AGENT_THOUGHT_LLM_RESPONSE`.
@@ -4154,22 +4437,20 @@ declare class GeminiAdapter implements ProviderAdapter {
      */
     call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
     /**
-     * Translates the provider-agnostic `ArtStandardPrompt` into the Gemini API's `Content[]` format.
+     * Translates the provider-agnostic `ArtStandardPrompt` into the Gemini API's `Content[]` format
+     * and extracts any system instructions.
      *
      * Key translations:
-     * - `system` role: Merged into the first `user` message.
+     * - `system` role: Extracted to `systemInstruction`.
      * - `user` role: Maps to Gemini's `user` role.
      * - `assistant` role: Maps to Gemini's `model` role. Handles text content and `tool_calls` (mapped to `functionCall`).
      * - `tool_result` role: Maps to Gemini's `user` role with a `functionResponse` part.
      * - `tool_request` role: Skipped (implicitly handled by `assistant`'s `tool_calls`).
      *
-     * Adds validation to ensure the conversation doesn't start with a 'model' role.
-     *
      * @private
      * @param {ArtStandardPrompt} artPrompt - The input `ArtStandardPrompt` array.
-     * @returns {Content[]} The `Content[]` array formatted for the Gemini API.
-     * @throws {ARTError} If translation encounters an issue, such as a `tool_result` missing required fields (ErrorCode.PROMPT_TRANSLATION_FAILED).
-     * @see https://ai.google.dev/api/rest/v1beta/Content
+     * @returns {{ contents: Content[], systemInstruction?: string }} The Gemini formatted payload.
+     * @throws {ARTError} If translation encounters an issue.
      */
     private translateToGemini;
 }
@@ -4180,7 +4461,7 @@ declare class GeminiAdapter implements ProviderAdapter {
 interface OpenAIAdapterOptions {
     /** Your OpenAI API key. Handle securely. */
     apiKey: string;
-    /** The default OpenAI model ID to use (e.g., 'gpt-4o', 'gpt-5', 'gpt-5-mini'). */
+    /** The default OpenAI model ID to use (e.g., 'gpt-5.2-instant', 'gpt-5.2-thinking', 'gpt-5.2-pro'). */
     model?: string;
     /** Optional: Override the base URL for the OpenAI API (e.g., for Azure OpenAI or custom proxies). */
     apiBaseUrl?: string;
@@ -4259,7 +4540,7 @@ declare class OpenAIAdapter implements ProviderAdapter {
 interface AnthropicAdapterOptions {
     /** Your Anthropic API key. Handle securely. */
     apiKey: string;
-    /** The default Anthropic model ID to use (e.g., 'claude-3-opus-20240229', 'claude-3-5-sonnet-20240620'). */
+    /** The default Anthropic model ID to use (e.g., 'claude_4.5_sonnet', 'claude_4.5_opus'). */
     model?: string;
     /** Optional: Override the base URL for the Anthropic API. */
     apiBaseUrl?: string;
@@ -4948,7 +5229,17 @@ declare class McpProxyTool implements IToolExecutor {
 
 /**
  * Manages thread-specific configuration (ThreadConfig) and state (AgentState)
- * using an underlying StateRepository. Supports explicit and implicit state saving strategies.
+ * using an underlying StateRepository.
+ *
+ * This class serves as the central point for accessing and modifying the persistent context
+ * of a conversation thread. It supports two state saving strategies:
+ *
+ * 1. **Explicit**: The agent is responsible for calling `setAgentState()` whenever it wants to persist changes.
+ *    `saveStateIfModified()` is a no-op. This gives fine-grained control but requires discipline.
+ *
+ * 2. **Implicit**: State is loaded via `loadThreadContext()` and cached. The agent modifies the state object in-memory.
+ *    Calls to `saveStateIfModified()` (typically at the end of an execution cycle) compare the current state
+ *    against the initial snapshot and persist only if changes are detected. This simplifies agent logic.
  */
 declare class StateManager implements StateManager$1 {
     private repository;
@@ -4962,8 +5253,12 @@ declare class StateManager implements StateManager$1 {
     constructor(stateRepository: IStateRepository, strategy?: StateSavingStrategy);
     /**
      * Loads the complete context (`ThreadConfig` and `AgentState`) for a specific thread.
-     * If in 'implicit' state saving strategy, it caches the loaded context and a snapshot
-     * of its AgentState for later comparison in `saveStateIfModified`.
+     *
+     * - In **Implicit** mode: Caches the loaded context and creates a snapshot of the `AgentState`.
+     *   This snapshot is used later by `saveStateIfModified` to detect changes. Subsequent loads
+     *   within the same lifecycle might return the cached object to maintain reference consistency.
+     * - In **Explicit** mode: Simply fetches data from the repository.
+     *
      * @param {string} threadId - The unique identifier for the thread.
      * @param {string} [_userId] - Optional user identifier (currently unused).
      * @returns {Promise<ThreadContext>} A promise resolving to the `ThreadContext` object.
@@ -4989,11 +5284,13 @@ declare class StateManager implements StateManager$1 {
     getThreadConfigValue<T>(threadId: string, key: string): Promise<T | undefined>;
     /**
      * Persists the thread's `AgentState` if it has been modified.
+     *
      * Behavior depends on the `stateSavingStrategy`:
-     * - 'explicit': This method is a no-op for `AgentState` persistence and logs a warning.
-     * - 'implicit': Compares the current `AgentState` (from the cached `ThreadContext` modified by the agent)
-     *               with the snapshot taken during `loadThreadContext`. If different, saves the state
-     *               to the repository and updates the snapshot.
+     * - **'explicit'**: This method is a no-op for `AgentState` persistence and logs a warning. State must be saved manually via `setAgentState`.
+     * - **'implicit'**: Compares the current `AgentState` (from the cached `ThreadContext` modified by the agent)
+     *   with the snapshot taken during `loadThreadContext`. If different, saves the state
+     *   to the repository and updates the snapshot.
+     *
      * @param {string} threadId - The ID of the thread whose state might need saving.
      * @returns {Promise<void>} A promise that resolves when the state is saved or the operation is skipped.
      */
@@ -5008,8 +5305,10 @@ declare class StateManager implements StateManager$1 {
     setThreadConfig(threadId: string, config: ThreadConfig): Promise<void>;
     /**
      * Explicitly sets or updates the AgentState for a specific thread by calling the underlying state repository.
-     * If in 'implicit' mode, this also updates the cached snapshot to prevent `saveStateIfModified`
-     * from re-saving the same state immediately.
+     *
+     * - If in **Implicit** mode: This also updates the cached snapshot to prevent `saveStateIfModified`
+     *   from re-saving the same state immediately (optimizing writes).
+     *
      * @param {string} threadId - The unique identifier of the thread.
      * @param {AgentState} state - The AgentState object to save. Must not be undefined or null.
      * @returns {Promise<void>} A promise that resolves when the state is saved.
@@ -5202,6 +5501,6 @@ declare const generateUUID: () => string;
 /**
  * The current version of the ART Framework package.
  */
-declare const VERSION = "0.3.8";
+declare const VERSION = "0.4.1";
 
-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 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 };