art-framework 0.4.7 → 0.4.11

package/dist/index.d.ts

@@ -437,52 +437,402 @@ declare class LLMStreamSocket extends TypedSocket<StreamEvent, StreamEventTypeFi
     notifyStreamEvent(event: StreamEvent): void;
 }
 
+/**
+ * Represents the current status of a TodoItem within the PES Agent's execution plan.
+ * These states track the lifecycle of individual steps throughout the agent's processing.
+ *
+ * @enum {string}
+ */
 declare enum TodoItemStatus {
+    /**
+     * The item has been created but has not yet started execution.
+     * This is the initial state for all newly planned items.
+     */
     PENDING = "pending",
+    /**
+     * The item is currently being executed by the agent.
+     * Only one item should be in this state at a time per thread.
+     */
     IN_PROGRESS = "in_progress",
+    /**
+     * The item has been successfully completed.
+     * The agent will not re-execute items in this state.
+     */
     COMPLETED = "completed",
+    /**
+     * The item execution failed and could not be completed.
+     * The agent may retry the item or skip it based on configuration.
+     */
     FAILED = "failed",
+    /**
+     * The item was cancelled before execution could complete.
+     * This may occur due to user intervention, timeout, or agent decision.
+     */
     CANCELLED = "cancelled",
+    /**
+     * The item is waiting for external conditions to be met.
+     * This is typically used for A2A (Agent-to-Agent) tasks waiting for remote completion.
+     */
     WAITING = "waiting"
 }
+/**
+ * Represents a single step or task in the PES Agent's execution plan.
+ * Each TodoItem corresponds to one action the agent needs to take, which could be
+ * a tool call, a reasoning step, or a subtask.
+ *
+ * @interface TodoItem
+ */
 interface TodoItem {
+    /**
+     * A unique identifier for this specific todo item.
+     * This ID is used for tracking, logging, and referencing the item across systems.
+     * @property {string} id
+     */
     id: string;
+    /**
+     * A human-readable description of what this item accomplishes.
+     * This description is typically generated by the planning LLM and should be clear and actionable.
+     * @property {string} description
+     */
     description: string;
+    /**
+     * The current execution status of this item.
+     * Values come from the {@link TodoItemStatus} enum.
+     * @property {TodoItemStatus} status
+     */
     status: TodoItemStatus;
+    /**
+     * An array of todo item IDs that must be completed before this item can start.
+     * This enables the agent to define task dependencies and execution order.
+     * If empty or undefined, the item has no dependencies and can execute immediately.
+     * @property {string[]} [dependencies]
+     */
     dependencies?: string[];
+    /**
+     * The type of execution step this item represents.
+     * - 'tool': The item requires executing one or more tools.
+     * - 'reasoning': The item requires LLM reasoning without external tool calls.
+     *
+     * This classification is part of the TAEF (Tool-Aware Execution Framework) system.
+     * @property {'tool' | 'reasoning'} [stepType]
+     */
     stepType?: 'tool' | 'reasoning';
+    /**
+     * For tool-type steps, an array of tool names that must be called during execution.
+     * This is used by TAEF for validation - if required tools are not called,
+     * the agent may be prompted to retry or the step may fail validation.
+     * @property {string[]} [requiredTools]
+     */
     requiredTools?: string[];
+    /**
+     * A description of the expected outcome for this item.
+     * This helps the LLM understand what success looks like and guides execution.
+     * @property {string} [expectedOutcome]
+     */
     expectedOutcome?: string;
+    /**
+     * The validation mode for tool execution in this item.
+     * - 'strict': Required tools must be called for the step to pass validation.
+     * - 'advisory': Required tools are recommended but not enforced.
+     *
+     * @property {'strict' | 'advisory'} [toolValidationMode]
+     */
     toolValidationMode?: 'strict' | 'advisory';
+    /**
+     * The actual result produced by executing this item.
+     * The structure depends on the step type and what was executed.
+     * @property {any} [result]
+     */
     result?: any;
+    /**
+     * An array of thought strings captured during execution.
+     * These represent the agent's internal reasoning for this specific item.
+     * @property {string[]} [thoughts]
+     */
     thoughts?: string[];
+    /**
+     * The tool calls that were planned for this item.
+     * This comes from the planning phase and represents the intended execution.
+     * @property {ParsedToolCall[]} [toolCalls]
+     */
     toolCalls?: ParsedToolCall[];
+    /**
+     * The tool calls that were actually executed during processing.
+     * This may differ from the planned calls if the agent modified its approach.
+     * @property {ParsedToolCall[]} [actualToolCalls]
+     */
     actualToolCalls?: ParsedToolCall[];
+    /**
+     * The results from all tool executions for this item.
+     * Includes both successful and failed tool attempts.
+     * @property {ToolResult[]} [toolResults]
+     */
     toolResults?: ToolResult[];
+    /**
+     * The validation status for this item's execution.
+     * - 'passed': The item passed all validation checks (e.g., required tools called).
+     * - 'failed': The item failed validation.
+     * - 'skipped': Validation was skipped for this item.
+     *
+     * @property {'passed' | 'failed' | 'skipped'} [validationStatus]
+     */
     validationStatus?: 'passed' | 'failed' | 'skipped';
+    /**
+     * The Unix timestamp (in milliseconds) when this item was created.
+     * This is used for tracking execution order and debugging.
+     * @property {number} createdTimestamp
+     */
     createdTimestamp: number;
+    /**
+     * The Unix timestamp (in milliseconds) when this item was last updated.
+     * This tracks the most recent modification to the item's state.
+     * @property {number} updatedTimestamp
+     */
     updatedTimestamp: number;
 }
+/**
+ * Represents the persistent state data for a PES Agent instance associated with a thread.
+ * This state is saved to storage and persists across multiple execution cycles.
+ *
+ * @interface PESAgentStateData
+ */
 interface PESAgentStateData {
+    /**
+     * The thread ID this state belongs to.
+     * Links the state to a specific conversation thread.
+     * @property {string} threadId
+     */
     threadId: string;
+    /**
+     * The user's intent extracted from their query.
+     * This is a concise summary of what the user wants to accomplish.
+     * @property {string} intent
+     */
     intent: string;
+    /**
+     * A concise title for the thread, typically <= 10 words.
+     * Generated based on the user's query and context.
+     * @property {string} title
+     */
     title: string;
+    /**
+     * The high-level plan describing how the agent will address the user's intent.
+     * This is a human-readable description of the overall approach.
+     * @property {string} plan
+     */
     plan: string;
+    /**
+     * The complete list of todo items representing the execution plan.
+     * This array contains all steps the agent needs to take, in execution order.
+     * @property {TodoItem[]} todoList
+     */
     todoList: TodoItem[];
+    /**
+     * The ID of the todo item currently being executed.
+     * If null, no item is currently active (e.g., planning phase, completed state).
+     * @property {string | null} currentStepId
+     */
     currentStepId: string | null;
+    /**
+     * Indicates whether the agent is currently paused.
+     * This flag is set when HITL (Human-in-the-Loop) is triggered.
+     * @property {boolean} isPaused
+     */
     isPaused: boolean;
+    /**
+     * Suspension context for HITL (Human-in-the-Loop) functionality.
+     * When a blocking tool is called, the agent suspends execution and stores
+     * the context here to allow resumption after user input.
+     *
+     * @remarks
+     * This field is only present when the agent is in a suspended state.
+     *
+     * @property {object} [suspension]
+     * @property {string} [suspension.suspensionId] - Unique ID for this suspension event.
+     * @property {string} [suspension.itemId] - The TodoItem ID that triggered suspension.
+     * @property {ParsedToolCall} [suspension.toolCall] - The specific tool call that caused suspension.
+     * @property {ArtStandardPrompt} [suspension.iterationState] - Captured message history for resumption.
+     */
     suspension?: {
+        /**
+         * Unique identifier for this suspension event.
+         * Used to match resume requests to the correct suspension.
+         * @property {string} suspensionId
+         */
         suspensionId: string;
+        /**
+         * The ID of the TodoItem that triggered the suspension.
+         * This identifies which step is waiting for human input.
+         * @property {string} itemId
+         */
         itemId: string;
+        /**
+         * The specific tool call that triggered the suspension.
+         * This is the call that requires human approval or input.
+         * @property {import('./index').ParsedToolCall} toolCall
+         */
         toolCall: ParsedToolCall;
+        /**
+         * The captured message history (ArtStandardPrompt) at the time of suspension.
+         * This allows the agent to resume execution with the correct context.
+         * @property {import('./index').ArtStandardPrompt} iterationState
+         */
         iterationState: ArtStandardPrompt;
+        /**
+         * Tool results from successful tools in the same batch that completed
+         * before the suspending tool was executed.
+         * This prevents data loss when a batch contains both successful and suspending tools.
+         *
+         * @since 0.4.11
+         * @property {import('./index').ToolResult[]} [partialToolResults]
+         */
+        partialToolResults?: ToolResult[];
+    };
+    /**
+     * A table of outputs from completed steps.
+     * This persists step outputs for use during resume operations and synthesis.
+     * Keys are step IDs, values are {@link StepOutputEntry} objects.
+     *
+     * @remarks
+     * This enables cross-step data access and ensures that the synthesis phase
+     * has access to all relevant information from completed steps.
+     *
+     * @property {Record<string, StepOutputEntry>} [stepOutputs]
+     */
+    stepOutputs?: Record<string, StepOutputEntry>;
+    /**
+     * Pending A2A tasks that the agent is waiting for.
+     * This enables recovery after process restart by tracking submitted but incomplete A2A tasks.
+     *
+     * @since 0.4.11
+     * @property {object} [pendingA2ATasks]
+     */
+    pendingA2ATasks?: {
+        /**
+         * The IDs of the A2A tasks being waited on.
+         * @property {string[]} taskIds
+         */
+        taskIds: string[];
+        /**
+         * When the tasks were submitted.
+         * @property {number} submittedAt
+         */
+        submittedAt: number;
+        /**
+         * The TodoItem ID that triggered the A2A delegation.
+         * @property {string} itemId
+         */
+        itemId: string;
     };
 }
+/**
+ * Represents a cached output entry from a completed execution step.
+ * These entries are persisted in the PESAgentStateData to enable resume
+ * capability and cross-step data access.
+ *
+ * @interface StepOutputEntry
+ */
+interface StepOutputEntry {
+    /**
+     * The ID of the step this output belongs to.
+     * Matches the TodoItem.id.
+     * @property {string} stepId
+     */
+    stepId: string;
+    /**
+     * A description of the step.
+     * Matches the TodoItem.description.
+     * @property {string} description
+     */
+    description: string;
+    /**
+     * The type of step that produced this output.
+     * Matches the TodoItem.stepType.
+     * @property {'tool' | 'reasoning'} stepType
+     */
+    stepType: 'tool' | 'reasoning';
+    /**
+     * The final status of the step.
+     * Matches the TodoItem.status at completion time.
+     * @property {TodoItemStatus} status
+     */
+    status: TodoItemStatus;
+    /**
+     * The Unix timestamp (in milliseconds) when the step was completed.
+     * @property {number} [completedAt]
+     */
+    completedAt?: number;
+    /**
+     * The raw result from the step execution.
+     * This contains full, untruncated data for use by downstream steps.
+     * For tool steps, this includes tool outputs. For reasoning steps,
+     * this includes the LLM response.
+     *
+     * @remarks
+     * Unlike the step context which may truncate large outputs,
+     * this rawResult preserves the complete data.
+     *
+     * @property {any} [rawResult]
+     */
+    rawResult?: any;
+    /**
+     * Array of tool results if this was a tool-type step.
+     * Contains all tool execution attempts including errors.
+     * @property {ToolResult[]} [toolResults]
+     */
+    toolResults?: ToolResult[];
+    /**
+     * An optional summary of the step output.
+     * This provides a quick reference without loading the full rawResult.
+     * Useful for synthesis and debugging.
+     * @property {string} [summary]
+     */
+    summary?: string;
+}
+/**
+ * Represents the structured output from an LLM execution call during the PES Agent's
+ * execution phase. This is parsed from the raw LLM response.
+ *
+ * @interface ExecutionOutput
+ */
 interface ExecutionOutput {
+    /**
+     * The agent's thoughts or reasoning for this execution step.
+     * This may include decision-making logic or reflections.
+     * @property {string} [thoughts]
+     */
     thoughts?: string;
+    /**
+     * The main response content from the LLM.
+     * This is the primary textual output from the execution step.
+     * @property {string} [content]
+     */
     content?: string;
+    /**
+     * Any tool calls the LLM decided to make during execution.
+     * These are parsed and will be executed by the ToolSystem.
+     * @property {ParsedToolCall[]} [toolCalls]
+     */
     toolCalls?: ParsedToolCall[];
+    /**
+     * The agent's decision on how to proceed after this execution.
+     * - 'continue': Proceed to the next iteration or step.
+     * - 'wait': Pause and wait for external input (rare in execution phase).
+     * - 'complete_item': Mark the current item as complete and move to the next.
+     * - 'update_plan': Modify the execution plan (intent, todo list, etc.).
+     *
+     * @property {'continue' | 'wait' | 'complete_item' | 'update_plan'} [nextStepDecision]
+     */
     nextStepDecision?: 'continue' | 'wait' | 'complete_item' | 'update_plan';
+    /**
+     * Updates to the plan if the agent decided to modify it.
+     * This can include changes to intent, plan description, or the todo list.
+     *
+     * @property {object} [updatedPlan]
+     * @property {string} [updatedPlan.intent] - Modified intent statement.
+     * @property {string} [updatedPlan.plan] - Modified plan description.
+     * @property {TodoItem[]} [updatedPlan.todoList] - Modified list of todo items.
+     */
     updatedPlan?: {
         intent?: string;
         plan?: string;
@@ -1181,25 +1531,49 @@ interface StreamEvent {
      */
     data: any;
     /**
-     * Optional: Provides a more specific classification for `TOKEN` events,
-     * combining LLM-level detection (thinking/response, if available from adapter)
-     * and agent-level context (`callContext` from `CallOptions`).
-     * Used by consumers (like UI) to differentiate between intermediate thoughts and the final response.
+     * Classification for TOKEN events, combining phase context and thinking detection.
      *
-     * - `LLM_THINKING`: Token identified by the adapter as part of the LLM's internal reasoning/thought process.
-     * - `LLM_RESPONSE`: Token identified by the adapter as part of the LLM's final response content.
-     * - `AGENT_THOUGHT_LLM_THINKING`: Token from an LLM call made in the 'AGENT_THOUGHT' context, identified as thinking.
-     * - `AGENT_THOUGHT_LLM_RESPONSE`: Token from an LLM call made in the 'AGENT_THOUGHT' context, identified as response (e.g., the raw planning output).
-     * - `FINAL_SYNTHESIS_LLM_THINKING`: Token from an LLM call made in the 'FINAL_SYNTHESIS' context, identified as thinking.
-     * - `FINAL_SYNTHESIS_LLM_RESPONSE`: Token from an LLM call made in the 'FINAL_SYNTHESIS' context, identified as response (part of the final answer to the user).
+     * @since 0.4.11 - Breaking change: New phase-based naming scheme.
+     *
+     * Phase-specific token types:
+     * - `PLANNING_LLM_THINKING`: Thinking token during planning phase.
+     * - `PLANNING_LLM_RESPONSE`: Response token during planning phase.
+     * - `EXECUTION_LLM_THINKING`: Thinking token during execution phase (per-step).
+     * - `EXECUTION_LLM_RESPONSE`: Response token during execution phase.
+     * - `SYNTHESIS_LLM_THINKING`: Thinking token during synthesis phase.
+     * - `SYNTHESIS_LLM_RESPONSE`: Response token during synthesis phase.
+     * - `LLM_THINKING`: Generic fallback when callContext not provided.
+     * - `LLM_RESPONSE`: Generic fallback when callContext not provided.
      *
      * @remarks
      * Not all adapters can reliably distinguish 'LLM_THINKING' vs 'LLM_RESPONSE'.
-     * Adapters should prioritize setting the agent context part (`AGENT_THOUGHT_...` or `FINAL_SYNTHESIS_...`) based on `CallOptions.callContext`.
-     * If thinking detection is unavailable, adapters should default to `AGENT_THOUGHT_LLM_RESPONSE` or `FINAL_SYNTHESIS_LLM_RESPONSE`.
-     * @property {'LLM_THINKING' | 'LLM_RESPONSE' | 'AGENT_THOUGHT_LLM_THINKING' | 'AGENT_THOUGHT_LLM_RESPONSE' | 'FINAL_SYNTHESIS_LLM_THINKING' | 'FINAL_SYNTHESIS_LLM_RESPONSE'} [tokenType]
+     * Adapters should prioritize setting the phase-based token type based on `CallOptions.callContext`.
+     */
+    tokenType?: 'PLANNING_LLM_THINKING' | 'PLANNING_LLM_RESPONSE' | 'EXECUTION_LLM_THINKING' | 'EXECUTION_LLM_RESPONSE' | 'SYNTHESIS_LLM_THINKING' | 'SYNTHESIS_LLM_RESPONSE' | 'LLM_THINKING' | 'LLM_RESPONSE';
+    /**
+     * Phase identification for the agent execution lifecycle.
+     * @since 0.4.11
+     * @property {'planning' | 'execution' | 'synthesis'} [phase]
+     */
+    phase?: 'planning' | 'execution' | 'synthesis';
+    /**
+     * Step ID during execution phase. Links tokens to specific TodoItem being executed.
+     * @since 0.4.11 - Only populated during execution phase.
+     * @property {string} [stepId]
+     */
+    stepId?: string;
+    /**
+     * Step description during execution phase.
+     * @since 0.4.11 - Only populated during execution phase.
+     * @property {string} [stepDescription]
+     */
+    stepDescription?: string;
+    /**
+     * Token emission timestamp (Unix ms).
+     * @since 0.4.11
+     * @property {number} [timestamp]
      */
-    tokenType?: 'LLM_THINKING' | 'LLM_RESPONSE' | 'AGENT_THOUGHT_LLM_THINKING' | 'AGENT_THOUGHT_LLM_RESPONSE' | 'FINAL_SYNTHESIS_LLM_THINKING' | 'FINAL_SYNTHESIS_LLM_RESPONSE';
+    timestamp?: number;
     /**
      * The identifier of the conversation thread this event belongs to.
      * @property {string} threadId
@@ -1658,6 +2032,12 @@ interface AgentOptions {
      * @property {Partial<AgentPersona>} [persona]
      */
     persona?: Partial<AgentPersona>;
+    /**
+     * Optional: Configuration for execution phase behavior (TAEF parameters) for this specific call.
+     * Overrides thread and instance-level execution config.
+     * @property {ExecutionConfig} [executionConfig]
+     */
+    executionConfig?: ExecutionConfig;
 }
 /**
  * The final structured response returned by the agent core after processing.
@@ -1788,12 +2168,23 @@ interface CallOptions {
      */
     stream?: boolean;
     /**
-     * Provides context for the LLM call, allowing adapters to differentiate
-     * between agent-level thoughts and final synthesis calls for token typing.
-     * Agent Core MUST provide this.
-     * @property {'AGENT_THOUGHT' | 'FINAL_SYNTHESIS' | string} [callContext]
+     * Provides context for the LLM call, identifying which phase of agent execution
+     * is making the request. This determines the tokenType prefix in StreamEvents.
+     *
+     * @since 0.4.11 - Breaking change: Replaced 'AGENT_THOUGHT' and 'FINAL_SYNTHESIS'
+     *                 with phase-specific values.
+     * @property {'PLANNING_THOUGHTS' | 'EXECUTION_THOUGHTS' | 'SYNTHESIS_THOUGHTS' | string} [callContext]
      */
-    callContext?: 'AGENT_THOUGHT' | 'FINAL_SYNTHESIS' | string;
+    callContext?: 'PLANNING_THOUGHTS' | 'EXECUTION_THOUGHTS' | 'SYNTHESIS_THOUGHTS' | string;
+    /**
+     * Step context for execution phase, passed to StreamEvent for step identification.
+     * @since 0.4.11 - Only used during execution phase.
+     * @property {{ stepId: string; stepDescription: string }} [stepContext]
+     */
+    stepContext?: {
+        stepId: string;
+        stepDescription: string;
+    };
     /**
      * An optional callback function invoked when the LLM streams intermediate 'thoughts' or reasoning steps.
      * @deprecated Prefer using StreamEvent with appropriate tokenType for thoughts. Kept for potential transitional compatibility.
@@ -2134,6 +2525,11 @@ interface ArtInstanceConfig {
      * @property {AgentPersona} [persona]
      */
     persona?: AgentPersona;
+    /**
+     * Optional: Configuration for execution phase behavior (TAEF parameters).
+     * @property {ExecutionConfig} [execution]
+     */
+    execution?: ExecutionConfig;
     /**
      * Optional configuration for MCP (Model Context Protocol) manager.
      * Enables connection to external MCP servers for dynamic tool loading.
@@ -2585,6 +2981,40 @@ interface AgentPersona {
      */
     prompts: StageSpecificPrompts;
 }
+/**
+ * Configuration options for the execution phase of the PES Agent.
+ * Controls TAEF (Tool-Aware Execution Framework) behavior.
+ *
+ * @interface ExecutionConfig
+ */
+interface ExecutionConfig {
+    /**
+     * Maximum number of LLM iterations per todo item during execution.
+     * Default: 5
+     * @property {number} [maxIterations]
+     */
+    maxIterations?: number;
+    /**
+     * Maximum number of TAEF tool validation retries when required tools are not invoked.
+     * Default: 2
+     * @property {number} [taefMaxRetries]
+     */
+    taefMaxRetries?: number;
+    /**
+     * Maximum character length for tool result serialization in step context.
+     * Higher values preserve more data for the LLM but increase token usage.
+     * Default: 60000 (effectively no practical limit)
+     * @property {number} [toolResultMaxLength]
+     */
+    toolResultMaxLength?: number;
+    /**
+     * Whether to enable A2A (Agent-to-Agent) delegation during execution.
+     * When true, injects the delegate_to_agent tool into execution context.
+     * Default: false
+     * @property {boolean} [enableA2ADelegation]
+     */
+    enableA2ADelegation?: boolean;
+}
 /**
  * Defines stage-specific system prompts for planning and synthesis.
  *
@@ -2603,6 +3033,13 @@ interface StageSpecificPrompts {
      * @property {string} [synthesis]
      */
     synthesis?: string;
+    /**
+     * Custom system prompt template for tool execution steps.
+     * If provided, overrides the default execution prompt.
+     * Supports variable interpolation: ${item.description}, ${completedItemsContext}, etc.
+     * @property {string} [execution]
+     */
+    execution?: string;
 }
 
 /**
@@ -2856,7 +3293,7 @@ interface IAgentCore {
 /**
  * Interface for the component responsible for interacting with LLMs.
  */
-interface ReasoningEngine {
+interface ReasoningEngine$1 {
     /**
      * Executes a call to the configured Large Language Model (LLM).
      * This method is typically implemented by a specific `ProviderAdapter`.
@@ -2876,7 +3313,7 @@ interface ReasoningEngine {
  * Resolves the final system prompt from base + instance/thread/call overrides
  * using tag+variables and merge strategies.
  */
-interface SystemPromptResolver {
+interface SystemPromptResolver$1 {
     resolve(input: {
         base: string;
         instance?: string | SystemPromptOverride;
@@ -2887,7 +3324,7 @@ interface SystemPromptResolver {
 /**
  * Interface for parsing structured output from LLM responses.
  */
-interface OutputParser {
+interface OutputParser$1 {
     /**
      * Parses the raw string output from the planning LLM call to extract structured information.
      * Implementations should be robust to variations in LLM output formatting.
@@ -2935,7 +3372,7 @@ interface OutputParser {
  * Base interface for LLM Provider Adapters, extending the core ReasoningEngine.
  * Implementations will handle provider-specific API calls, authentication, etc.
  */
-interface ProviderAdapter extends ReasoningEngine {
+interface ProviderAdapter extends ReasoningEngine$1 {
     /** The unique identifier name for this provider (e.g., 'openai', 'anthropic'). */
     readonly providerName: string;
     /** Optional: Method for graceful shutdown */
@@ -3846,9 +4283,9 @@ interface PESAgentDependencies {
     /** Registry for available tools. */
     toolRegistry: ToolRegistry$1;
     /** Handles interaction with the LLM provider. */
-    reasoningEngine: ReasoningEngine;
+    reasoningEngine: ReasoningEngine$1;
     /** Parses LLM responses. */
-    outputParser: OutputParser;
+    outputParser: OutputParser$1;
     /** Records agent execution observations. */
     observationManager: ObservationManager;
     /** Orchestrates tool execution. */
@@ -3862,7 +4299,7 @@ interface PESAgentDependencies {
     /** Service for delegating A2A tasks. */
     taskDelegationService?: TaskDelegationService | null;
     /** Resolver for standardized system prompt composition. */
-    systemPromptResolver: SystemPromptResolver;
+    systemPromptResolver: SystemPromptResolver$1;
     /** Optional: Defines the default identity and high-level guidance for the agent. */
     persona?: AgentPersona;
 }
@@ -3876,6 +4313,13 @@ declare class PESAgent implements IAgentCore {
     constructor(dependencies: PESAgentDependencies);
     process(props: AgentProps): Promise<AgentFinalResponse>;
     private _saveState;
+    /**
+     * Issue #2 fix: Persists execution step results to ConversationManager for follow-up query context.
+     * This ensures that completed step information is available in conversation history.
+     *
+     * @since 0.4.11
+     */
+    private _persistExecutionSummary;
     private _recordPlanObservations;
     private _performPlanning;
     private _performPlanRefinement;
@@ -3884,6 +4328,7 @@ declare class PESAgent implements IAgentCore {
     /**
      * Builds execution prompt for TOOL-type steps.
      * Emphasizes tool invocation and explicitly names required tools.
+     * Includes Data Flow Directive to guide LLM in extracting data from previous results.
      */
     private _buildToolStepPrompt;
     /**
@@ -4499,9 +4944,6 @@ declare class OpenRouterAdapter implements ProviderAdapter {
     private translateToOpenAI;
 }
 
-/**
- * Configuration options required for the `DeepSeekAdapter`.
- */
 interface DeepSeekAdapterOptions {
     /** Your DeepSeek API key. Handle securely. */
     apiKey: string;
@@ -5322,35 +5764,730 @@ declare class ToolRegistry implements ToolRegistry$1 {
 }
 
 /**
- * Manages the lifecycle and access to multiple ProviderAdapter implementations.
+ * @module systems/reasoning/ProviderManagerImpl
+ *
+ * This module provides the default implementation of the IProviderManager interface.
+ * It manages the lifecycle of provider adapters, handles concurrency limits,
+ * supports both API-based and local providers, and implements intelligent pooling
+ * and queueing strategies.
+ *
+ * Key features:
+ * - Multi-provider support with dynamic adapter registration
+ * - Concurrency limiting per provider (configurable)
+ * - Instance pooling and reuse for API-based providers
+ * - Singleton pattern for local providers (e.g., Ollama)
+ * - Request queuing for API providers when limits are reached
+ * - Automatic idle timeout and eviction for API instances
+ * - Safe error handling with proper cleanup
+ *
+ * @see IProviderManager for the interface definition
+ * @see AvailableProviderEntry for provider registration
+ * @see RuntimeProviderConfig for runtime provider configuration
+ * @see ManagedAdapterAccessor for managed adapter access
+ */
+
+/**
+ * Default implementation of the IProviderManager interface.
+ *
+ * @remarks
+ * This class provides intelligent management of LLM provider adapters with the following capabilities:
+ *
+ * **Lifecycle Management:**
+ * - Creates new adapter instances on demand
+ * - Reuses idle instances when possible
+ * - Properly shuts down instances when they're no longer needed
+ *
+ * **Concurrency Control:**
+ * - Enforces maximum parallel API calls per provider (configurable)
+ * - Implements a queue-based system for requests exceeding limits
+ * - Prevents resource exhaustion by queuing when all instances are busy
+ *
+ * **Provider Types:**
+ * - API-based providers (OpenAI, Anthropic, etc.):
+ *   - Multiple instances can be created and pooled
+ *   - Instances have an idle timeout after which they're evicted
+ *   - Supports concurrent requests up to the configured limit
+ *
+ * - Local providers (Ollama, local LLMs):
+ *   - Enforced singleton pattern (only one instance can be active)
+ *   - Prevents multiple simultaneous requests to the same local instance
+ *   - Throws specific errors if conflicting requests are made
+ *
+ * **Request Queuing:**
+ * - When an API provider's limit is reached, new requests are queued
+ * - Requests are processed in FIFO (First-In-First-Out) order
+ * - When an instance becomes available (released), queued requests are served
+ * - Prevents request loss and ensures fair resource allocation
+ *
+ * **Error Handling:**
+ * - Throws specific errors for provider-related failures
+ *   - Includes UnknownProviderError for unregistered providers
+ *   - Includes LocalProviderConflictError for conflicting local requests
+ *   - Includes LocalInstanceBusyError for busy local instances
+ *   - Ensures proper cleanup even when errors occur
+ *
+ * **Security:**
+ * - Never includes secrets (API keys) in signature strings for logging
+ * - Sanitizes configuration signatures to prevent sensitive data leakage
+ *
+ * Usage Example:
+ * ```typescript
+ * const manager = new ProviderManagerImpl({
+ *   availableProviders: [
+ *     { name: 'openai', adapter: OpenAIAdapter, baseOptions: { apiKey: 'sk-...' } },
+ *     { name: 'ollama', adapter: OllamaAdapter, isLocal: true }
+ *   ],
+ *   maxParallelApiInstancesPerProvider: 3,
+ *   apiInstanceIdleTimeoutSeconds: 300
+ * });
+ *
+ * // Get an adapter
+ * const accessor = await manager.getAdapter({
+ *   providerName: 'openai',
+ *   modelId: 'gpt-4',
+ *   adapterOptions: { temperature: 0.7 }
+ * });
+ *
+ * // Use the adapter
+ * const stream = await accessor.adapter.call(prompt, options);
+ * for await (const event of stream) { ... }
+ *
+ * // Release the adapter (important!)
+ * accessor.release();
+ * ```
+ *
+ * @class ProviderManagerImpl
+ * @implements IProviderManager
  */
 declare class ProviderManagerImpl implements IProviderManager {
+    /**
+     * Map of registered provider configurations.
+     * Keys are provider names (e.g., 'openai', 'anthropic', 'ollama_local').
+     * @private
+     */
     private availableProviders;
+    /**
+     * Maximum number of concurrent active instances per API-based provider.
+     * Default: 5
+     * @private
+     */
     private maxParallelApiInstancesPerProvider;
+    /**
+     * Timeout in milliseconds for an API instance before it's evicted.
+     * Default: 300,000ms (5 minutes)
+     * @private
+     */
     private apiInstanceIdleTimeoutMs;
+    /**
+     * Map of currently managed adapter instances.
+     * Keys are configuration signatures, values are instance metadata.
+     * @private
+     */
     private managedInstances;
+    /**
+     * Queue of pending requests that couldn't be immediately fulfilled.
+     * @private
+     */
     private requestQueue;
+    /**
+     * Creates a new ProviderManagerImpl instance.
+     *
+     * @param config - Configuration for the provider manager.
+     *
+     * @remarks
+     * The configuration must include:
+     * - `availableProviders`: Array of provider entries with adapter classes
+     * - `maxParallelApiInstancesPerProvider`: Maximum concurrent API calls per provider (optional)
+     * - `apiInstanceIdleTimeoutSeconds`: Idle timeout for API instances in seconds (optional)
+     */
     constructor(config: ProviderManagerConfig);
     /**
-     * Generates a stable configuration signature for caching.
-     * @param config The runtime provider configuration.
-     * @returns A string signature.
+     * Generates a stable configuration signature for caching and lookup.
+     *
+     * @remarks
+     * The signature is used as the key in the managedInstances map.
+     * It includes provider name and model ID, allowing different instances
+     * of the same provider with different models to coexist.
+     *
+     * Security Note: Never includes sensitive data like API keys.
+     * Keys are replaced with '***' before being used in the signature.
+     *
+     * @param config - The runtime provider configuration.
+     * @returns A stable string signature uniquely identifying this configuration.
+     *
+     * @private
      */
     private _getConfigSignature;
+    /**
+     * Returns an array of all registered provider names.
+     *
+     * @returns Array of provider name strings.
+     */
     getAvailableProviders(): string[];
+    /**
+     * Gets a managed adapter instance based on runtime configuration.
+     *
+     * @remarks
+     * This method implements sophisticated adapter management:
+     *
+     * 1. **Cache Check**: First checks if an existing instance matches the requested configuration
+     *    - If found and idle, reuses it immediately
+     *    - Updates lastUsedTimestamp for idle timeout tracking
+     *    - Clears any existing idle timer
+     *
+     * 2. **Local Provider Constraints**: For local providers (isLocal: true):
+     *    - Only one instance of a local provider can be active at a time
+     *    - If requesting a different model of an active local instance, throws LocalProviderConflictError
+     *    - If the same local instance is already active and busy, throws LocalInstanceBusyError
+     *    - This prevents concurrent access issues with local LLMs
+     *
+     * 3. **API Provider Concurrency**:
+     *    - Counts currently active instances for this provider
+     *    - If under maxParallelApiInstancesPerProvider, creates new instance
+     *    - If at the limit, queues the request instead of failing
+     *    - Ensures fair resource allocation and prevents request loss
+     *
+     * 4. **Instance Creation**: Creates new instances using provider's adapter class
+     *    - Merges base options from provider entry with runtime adapter options
+     *    - Provider-specific options (API keys) are merged in
+     *    - Adapter instantiation errors are wrapped in AdapterInstantiationError
+     *
+     * 5. **Accessor Return**: Returns an object with:
+     *    - adapter: The ready-to-use ProviderAdapter instance
+     *    - release: Function to release the adapter back to the manager
+     *
+     * @param config - The runtime provider configuration specifying which provider and model to use.
+     *
+     * @returns A promise resolving to a ManagedAdapterAccessor containing the adapter and release function.
+     *
+     * @throws {UnknownProviderError} If the provider name is not registered.
+     * @throws {LocalProviderConflictError} If requesting a different model of an active local provider.
+     * @throws {LocalInstanceBusyError} If the requested local instance is currently busy.
+     *
+     * @example
+     * ```typescript
+     * // Request with a pooled instance
+     * const accessor = await manager.getAdapter({
+     *   providerName: 'openai',
+     *   modelId: 'gpt-4',
+     *   adapterOptions: { temperature: 0.7 }
+     * });
+     * const stream = await accessor.adapter.call(prompt, options);
+     * for await (const event of stream) { ... }
+     * accessor.release();
+     *
+     * // Request that will be queued if limit reached
+     * const accessor2 = await manager.getAdapter({
+     *   providerName: 'openai',
+     *   modelId: 'gpt-4'
+     * });
+     * // ... request completes ...
+     * ```
+     */
     getAdapter(config: RuntimeProviderConfig): Promise<ManagedAdapterAccessor>;
     /**
      * Internal method to release an adapter instance back to the manager.
-     * @param configSignature The signature of the instance to release.
+     *
+     * @param configSignature - The signature of the instance to release.
+     *
+     * @remarks
+     * This method:
+     * 1. Marks the instance as 'idle'
+     * 2. Clears any idle timer
+     * 3. Clears lastUsedTimestamp
+     * 4. Does NOT delete the instance from managedInstances
+     * 5. Checks request queue for pending requests that can now be fulfilled
+     *
+     * The instance remains in the pool for future reuse.
+     *
+     * @private
      */
     private _releaseAdapter;
     /**
      * Internal method to evict an instance from the manager.
-     * @param configSignature The signature of the instance to evict.
+     *
+     * @param configSignature - The signature of the instance to evict.
+     *
+     * @remarks
+     * This method:
+     * 1. Calls the adapter's shutdown method if available
+     * 2. Removes the instance from managedInstances
+     * 3. Clears the idle timer if present
+     *
+     * Eviction can happen due to:
+     * - Idle timeout (for API instances)
+     * - Manager shutdown (not implemented yet but reserved)
+     *
+     * @private
      */
     private _evictInstance;
 }
 
+/**
+ * @module systems/reasoning/ReasoningEngine
+ *
+ * This module provides the default implementation of the ReasoningEngine interface,
+ * which serves as the primary abstraction for interacting with Large Language Models (LLMs)
+ * in the ART framework.
+ *
+ * Key features:
+ * - Multi-provider support via IProviderManager
+ * - Automatic adapter lifecycle management (acquisition, pooling, release)
+ * - Streaming response support with proper resource cleanup
+ * - Runtime provider selection based on thread/call configuration
+ *
+ * @see IReasoningEngine for the interface definition
+ * @see ProviderAdapter for adapter interface to different LLM providers
+ * @see IProviderManager for provider management interface
+ */
+
+/**
+ * Default implementation of the ReasoningEngine interface.
+ *
+ * This class serves as the central point for all LLM interactions within the ART framework.
+ * It abstracts away the specifics of dealing with different LLM providers (OpenAI, Anthropic,
+ * Gemini, etc.) by delegating to provider-specific ProviderAdapter instances obtained from the
+ * IProviderManager.
+ *
+ * Key responsibilities:
+ * 1. Dynamic Provider Selection: Obtains the appropriate ProviderAdapter instance based on
+ *    runtime configuration (RuntimeProviderConfig) specified in CallOptions. This allows different
+ *    threads or calls to use different LLM providers or models.
+ *
+ * 2. Resource Management: Ensures that adapter instances are properly released back to the
+ *    IProviderManager after use, enabling connection pooling, reuse, and proper cleanup.
+ *    This is critical for maintaining performance and preventing resource leaks.
+ *
+ * 3. Streaming Support: Returns an AsyncIterable that yields tokens, metadata, and
+ *    lifecycle events as they arrive from the LLM provider. The implementation wraps the
+ *    adapter's stream to ensure proper resource cleanup even if iteration is aborted or errors occur.
+ *
+ * 4. Error Handling: Transforms provider-specific errors into a consistent interface and
+ *    ensures adapters are released even when errors occur during call setup or stream processing.
+ *
+ * @class ReasoningEngine
+ * @implements IReasoningEngine
+ */
+declare class ReasoningEngine implements ReasoningEngine$1 {
+    /**
+     * The provider manager instance used to obtain adapter instances at runtime.
+     * This manager handles adapter instantiation, pooling, concurrency limits, and lifecycle management.
+     * @private
+     */
+    private providerManager;
+    /**
+     * Creates a new ReasoningEngine instance.
+     *
+     * @param providerManager - The IProviderManager instance responsible for managing provider adapters.
+     *                            This manager must be pre-configured with available providers and their settings.
+     *
+     * @remarks
+     * The engine does not create adapters directly but relies on the provider manager to supply
+     * them on demand. This enables centralized management of provider credentials, connection pooling,
+     * and concurrency control.
+     */
+    constructor(providerManager: IProviderManager);
+    /**
+     * Executes an LLM call using a dynamically selected provider adapter.
+     *
+     * @remarks
+     * This method orchestrates the entire LLM call lifecycle:
+     *
+     * 1. Provider Configuration Validation: Ensures that providerConfig is present in CallOptions.
+     *    This is required for the multi-provider architecture.
+     *
+     * 2. Adapter Acquisition: Requests a ManagedAdapterAccessor from the IProviderManager.
+     *    The manager handles:
+     *    - Instantiating new adapters if needed
+     *    - Reusing existing adapters from the pool
+     *    - Enforcing concurrency limits (e.g., max parallel API calls per provider)
+     *    - Managing singleton behavior for local providers (e.g., Ollama)
+     *    - Queueing requests when limits are reached
+     *
+     * 3. Call Delegation: Delegates the actual LLM call to the obtained adapter's call method.
+     *    The adapter is responsible for:
+     *    - Formatting the prompt for the specific provider API
+     *    - Making the HTTP request
+     *    - Parsing provider responses into standard StreamEvent objects
+     *    - Handling provider-specific streaming logic
+     *
+     * 4. Resource Cleanup: Wraps the adapter's stream in a generator that automatically calls
+     *    accessor.release() when the stream is consumed, errors occur, or iteration is aborted.
+     *    This ensures adapters are always returned to the pool, preventing resource leaks.
+     *
+     * 5. Error Handling: Catches and logs any errors during adapter acquisition or call execution,
+     *    ensuring the adapter is released before re-throwing the error to the caller.
+     *
+     * @param prompt - The prompt to send to the LLM. This is the FormattedPrompt type,
+     *                  which represents an array of standardized messages (ArtStandardMessage[]).
+     *                  The provider adapter is responsible for translating this to the specific
+     *                  API format required by the underlying LLM provider.
+     *
+     * @param options - Configuration options for this specific LLM call. Must include:
+     *                  - threadId (string): Required for identifying the thread and loading its configuration
+     *                  - providerConfig (RuntimeProviderConfig): Specifies which provider and model to use
+     *                  - traceId (string, optional): For distributed tracing and debugging
+     *                  - userId (string, optional): For user-specific configuration or logging
+     *                  - sessionId (string, optional): For multi-tab/session UI scenarios
+     *                  - stream (boolean, optional): Whether to request streaming responses (default: false)
+     *                  - callContext (string, optional): Context for the call (e.g., 'AGENT_THOUGHT', 'FINAL_SYNTHESIS')
+     *                  - Additional provider-specific parameters (e.g., temperature, max_tokens)
+     *
+     * @returns A promise resolving to an AsyncIterable<StreamEvent>. The iterable yields events as they arrive:
+     *          - TOKEN: Individual text tokens from the LLM
+     *          - METADATA: Metadata about the call (token counts, timing, stop reason)
+     *          - END: Signal that the stream has completed successfully
+     *          - ERROR: Indicates an error occurred during streaming
+     *
+     *          The returned iterable is wrapped to ensure proper adapter cleanup when iteration completes
+     *          or is interrupted.
+     *
+     * @throws {Error} Throws various errors that may occur:
+     *          - Missing "providerConfig" in CallOptions: If provider configuration is not supplied
+     *          - Provider-specific errors from adapter acquisition or execution (e.g., authentication failures, rate limits)
+     *          - Network errors or timeouts
+     */
+    call(prompt: FormattedPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
+}
+
+/**
+ * @module systems/reasoning/OutputParser
+ *
+ * This module provides implementation for parsing structured output from LLM responses
+ * in the ART framework. It handles planning, execution, and synthesis outputs.
+ *
+ * Key features:
+ * - Multi-format parsing support (JSON with markers, markdown code blocks, brace matching)
+ * - XML tag extraction for thoughts (e.g., <think> tags)
+ * - Zod schema validation for structured data
+ * - Robust error handling and fallback parsing
+ *
+ * @see IOutputParser for interface definition
+ * @see ParsedToolCall for parsed tool call structure
+ * @see TodoItem for parsed todo item structure
+ * @see ExecutionOutput for execution output structure
+ */
+
+/**
+ * Default implementation of the IOutputParser interface.
+ *
+ * @remarks
+ * This class provides robust parsing capabilities for structured output from LLMs.
+ * It is designed to handle variations in LLM output formatting across different providers
+ * and models. The parser uses a multi-tier strategy for extracting structured data:
+ *
+ * 1. XML Tag Extraction: Extracts content from XML-like tags (e.g., <think>)
+ *    using the XmlMatcher utility. This separates "thoughts" or "reasoning" from
+ *    the main structured output.
+ *
+ * 2. JSON Extraction: Attempts multiple strategies to find and parse JSON:
+ *    - Priority 1: Explicit JSON markers (---JSON_OUTPUT_START--- ... ---JSON_OUTPUT_END---)
+ *    - Priority 2: Markdown code blocks (```json ... ``` or ``` ... ```)
+ *    - Priority 3: Strip markdown fences and attempt direct parsing
+ *    - Priority 4: Find JSON object by brace matching for mixed content
+ *
+ * 3. Schema Validation: Uses Zod schemas to validate parsed structures:
+ *    - ParsedToolCall validation ensures tool calls have required fields
+ *    - TodoItem validation ensures todo items conform to expected structure
+ *
+ * 4. Fallback Parsing: If JSON extraction fails, attempts to extract information
+ *    from labeled sections (e.g., "Title: ...", "Intent: ...", "Plan: ...")
+ *
+ * The parser is resilient to:
+ * - Malformed or incomplete XML tags
+ * - Missing or malformed JSON
+ * - Mixed content (text + JSON)
+ * - Provider-specific formatting differences
+ *
+ * @class OutputParser
+ * @implements IOutputParser
+ */
+declare class OutputParser implements OutputParser$1 {
+    /**
+     * Helper method for parsing JSON from a raw string with multiple fallback strategies.
+     *
+     * @remarks
+     * This method implements a tiered approach to finding and parsing JSON:
+     *
+     * 1. **Explicit Markers**: Looks for ---JSON_OUTPUT_START--- and ---JSON_OUTPUT_END---
+     *    markers. This is the most reliable method as markers are unambiguous.
+     *
+     * 2. **Markdown Code Blocks**: Looks for fenced code blocks with ```json, ```JSON,
+     *    or just ``` delimiters. Handles case-insensitive matching.
+     *
+     * 3. **Fence Stripping**: If regex didn't catch markdown blocks (e.g., malformed),
+     *    strips leading ``` and trailing ``` markers and attempts parsing.
+     *
+     * 4. **Brace Matching**: As a fallback for mixed content, finds the first
+     *    { and last } characters and extracts the content between them.
+     *
+     * The method is resilient to:
+     * - Non-JSON content outside of delimiters
+     * - Malformed JSON (returns null)
+     * - Circular references (though less likely in LLM output)
+     * - Non-serializable values (functions, symbols)
+     *
+     * @param raw - The raw string that may contain JSON.
+     * @returns The parsed JavaScript object if valid JSON is found, null otherwise.
+     *
+     * @private
+     */
+    private tryParseJson;
+    /**
+     * Parses the raw string output from the planning LLM call.
+     *
+     * @remarks
+     * The planning phase generates structured output including:
+     * - title: A concise thread title (<= 10 words)
+     * - intent: A summary of the user's goal
+     * - plan: A human-readable description of the approach
+     * - toolCalls: Structured tool call requests
+     * - todoList: A list of TodoItem objects representing the execution plan
+     * - thoughts: Content extracted from <think> XML tags
+     *
+     * This method:
+     * 1. Extracts thoughts from <think> tags using XmlMatcher
+     * 2. Attempts to parse the remaining content as JSON
+     * 3. Validates toolCalls against Zod schema
+     * 4. Validates todoList against Zod schema
+     * 5. Falls back to section-based parsing if JSON fails
+     *
+     * The fallback section-based parsing looks for labeled sections like:
+     * "Title: ...", "Intent: ...", "Plan: ..." using regex patterns.
+     *
+     * @param output - The raw string response from the planning LLM.
+     *
+     * @returns A promise resolving to an object containing:
+     *          - title (string, optional): Concise thread title
+     *          - intent (string, optional): User's goal summary
+     *          - plan (string, optional): Human-readable plan description
+     *          - toolCalls (ParsedToolCall[], optional): Parsed tool call requests
+     *          - todoList (TodoItem[], optional): List of execution steps
+     *          - thoughts (string, optional): Extracted from <think> tags
+     *
+     * @throws Never throws; errors are handled gracefully with empty results.
+     */
+    parsePlanningOutput(output: string): Promise<{
+        title?: string;
+        intent?: string;
+        plan?: string;
+        toolCalls?: ParsedToolCall[];
+        thoughts?: string;
+        todoList?: TodoItem[];
+    }>;
+    /**
+     * Parses the raw string output from an execution LLM call (per todo item).
+     *
+     * @remarks
+     * The execution phase generates output that may include:
+     * - thoughts: Reasoning extracted from <think> tags
+     * - toolCalls: Structured tool call requests for the current step
+     * - nextStepDecision: Decision on how to proceed (continue, wait, complete_item, update_plan)
+     * - updatedPlan: Modifications to the execution plan
+     * - content: Freeform text response
+     *
+     * This method:
+     * 1. Extracts thoughts from <think> tags using XmlMatcher
+     * 2. Attempts to parse the remaining content as JSON
+     * 3. Validates toolCalls against Zod schema
+     * 4. Extracts structured fields if JSON parsing succeeds
+     * 5. Falls back to treating everything as freeform content if JSON fails
+     *
+     * The nextStepDecision values guide the TAEF execution:
+     * - 'continue': Proceed with next iteration
+     * - 'wait': Pause execution (rare in execution phase)
+     * - 'complete_item': Mark current todo item as complete
+     * - 'update_plan': Modify the execution plan
+     *
+     * @param output - The raw string response from the execution LLM.
+     *
+     * @returns A promise resolving to an ExecutionOutput object containing:
+     *          - thoughts (string, optional): Extracted from <think> tags
+     *          - toolCalls (ParsedToolCall[], optional): Parsed tool call requests
+     *          - nextStepDecision (string, optional): How to proceed
+     *          - updatedPlan (object, optional): Plan modifications
+     *          - content (string, optional): Freeform text response
+     *
+     * @throws Never throws; errors are handled gracefully with empty results.
+     */
+    parseExecutionOutput(output: string): Promise<ExecutionOutput>;
+    /**
+     * Parses the raw string output from the synthesis LLM call.
+     *
+     * @remarks
+     * The synthesis phase generates the final, user-facing response.
+     * This method typically just trims the output, as synthesis output
+     * is usually freeform text without structured components.
+     *
+     * Future enhancements might include:
+     * - Removing extraneous tags or markers
+     * - Formatting cleanup
+     * - Extracting specific sections if needed
+     *
+     * @param output - The raw string response from the synthesis LLM.
+     *
+     * @returns A promise resolving to the cleaned, final response string.
+     *
+     * @throws Never throws; always returns at least an empty string.
+     */
+    parseSynthesisOutput(output: string): Promise<string>;
+}
+
+/**
+ * Default implementation of ISystemPromptResolver interface.
+ *
+ * @remarks
+ * This class manages the resolution and merging of system prompts across multiple levels:
+ * 1. Base prompt - The fundamental system instruction from agent persona or framework defaults
+ * 2. Instance-level override - Global configuration applied to all threads in an ART instance
+ * 3. Thread-level override - Configuration specific to a single conversation thread
+ * 4. Call-level override - Configuration for a specific LLM call
+ *
+ * Each level can provide either:
+ * - A preset tag that references a template from SystemPromptsRegistry
+ * - Freeform content that is directly used
+ *
+ * The resolution process:
+ * 1. Starts with the base prompt
+ * 2. Applies instance-level override (if provided)
+ * 3. Applies thread-level override (if provided)
+ * 4. Applies call-level override (if provided)
+ *
+ * At each level, the override is:
+ * - Rendered from a template if a tag is specified (with variable substitution)
+ * - Used directly if freeform content is provided
+ * - Applied using the specified merge strategy (append or prepend)
+ *
+ * Template rendering supports:
+ * - Simple variable interpolation: {{variableName}}
+ * - Prompt fragment references: {{fragment:name}}
+ *
+ * @example
+ * ```typescript
+ * const resolver = new SystemPromptResolver({
+ *   specs: {
+ *     'default': {
+ *       template: 'You are {{name}}. Be {{tone}}.',
+ *       defaultVariables: { name: 'AI Assistant', tone: 'helpful' }
+ *     },
+ *     'expert': {
+ *       template: 'You are an expert in {{topic}}.',
+ *       mergeStrategy: 'prepend'
+ *     }
+ *   },
+ *   defaultTag: 'default'
+ * });
+ *
+ * const result = await resolver.resolve({
+ *   base: 'System: You are helpful.',
+ *   instance: { tag: 'expert', variables: { topic: 'physics' } },
+ *   thread: { tag: 'default', strategy: 'append' }
+ * }, 'trace-123');
+ * // Result combines: base + expert (prepended) + default (appended)
+ * ```
+ *
+ * @class SystemPromptResolver
+ * @implements ISystemPromptResolver
+ */
+declare class SystemPromptResolver implements SystemPromptResolver$1 {
+    /**
+     * Optional registry of system prompt presets (templates) that can be referenced by tag.
+     * @private
+     * @type {SystemPromptsRegistry | undefined}
+     */
+    private readonly registry?;
+    /**
+     * Creates a new SystemPromptResolver instance.
+     *
+     * @param registry - Optional registry of prompt preset templates indexed by tag name.
+     *                    If provided, overrides can reference templates by tag name.
+     */
+    constructor(registry?: SystemPromptsRegistry);
+    /**
+     * Resolves the final system prompt by applying overrides in precedence order.
+     *
+     * @remarks
+     * The resolution process follows this precedence hierarchy (highest to lowest):
+     * 1. Call-level override (immediate, most specific)
+     * 2. Thread-level override (conversation-specific)
+     * 3. Instance-level override (instance-wide)
+     * 4. Base prompt (default)
+     *
+     * For each override level:
+     * - If a tag is provided and exists in registry: Render the template
+     * - If freeform content is provided: Use it directly
+     * - Apply using the specified merge strategy (defaults to 'append')
+     * - Variables for template rendering come from defaultVariables merged with provided variables
+     *
+     * Template variable substitution:
+     * - Variables are wrapped in double braces: {{variableName}}
+     * - Supports fragment references: {{fragment:name}} (for PromptManager integration)
+     * - Missing variables render as empty strings
+     *
+     * Merge strategies:
+     * - 'append': Adds content to the end of existing prompt (default)
+     * - 'prepend': Adds content to the beginning of existing prompt
+     *
+     * Note: 'replace' strategy is intentionally unsupported to prevent custom prompts
+     * from overriding framework-required structural contracts.
+     *
+     * @param input - Object containing the base prompt and optional overrides at each level.
+     *                - base (string): The fundamental system prompt (required)
+     *                - instance (string | SystemPromptOverride): Instance-level override
+     *                - thread (string | SystemPromptOverride): Thread-level override
+     *                - call (string | SystemPromptOverride): Call-level override
+     * @param traceId - Optional trace identifier for logging and debugging purposes.
+     *
+     * @returns A promise resolving to the final, resolved system prompt string.
+     *
+     * @example
+     * ```typescript
+     * const result = await resolver.resolve({
+     *   base: 'You are a helpful AI.',
+     *   instance: {
+     *     tag: 'technical',
+     *     variables: { specialization: 'web development' }
+     *   },
+     *   thread: { content: 'Be concise in your responses.' }
+     * }, 'trace-123');
+     * ```
+     */
+    resolve(input: {
+        base: string;
+        instance?: string | SystemPromptOverride;
+        thread?: string | SystemPromptOverride;
+        call?: string | SystemPromptOverride;
+    }, traceId?: string): Promise<string>;
+    /**
+     * Renders a template string by replacing variable placeholders with provided values.
+     *
+     * @remarks
+     * Supported placeholder format: {{variableName}}
+     * - Variable names are trimmed of whitespace
+     * - Missing variables render as empty strings
+     * - Values are converted to strings using String()
+     *
+     * This simple templating system supports basic variable interpolation.
+     * It does not support complex features like loops, conditionals, or nested objects.
+     *
+     * @param template - The template string containing variable placeholders.
+     * @param variables - Record of variable names to their string or string-convertible values.
+     *
+     * @returns The rendered string with all placeholders substituted.
+     *
+     * @private
+     * @example
+     * ```typescript
+     * const rendered = renderTemplate(
+     *   'Hello {{name}}, you are {{age}} years old.',
+     *   { name: 'Alice', age: 30 }
+     * );
+     * // Result: 'Hello Alice, you are 30 years old.'
+     * ```
+     */
+    private renderTemplate;
+}
+
 /**
  * Generates a unique Version 4 UUID (Universally Unique Identifier) string.
  *
@@ -5418,6 +6555,6 @@ declare const generateUUID: () => string;
 /**
  * The current version of the ART Framework package.
  */
-declare const VERSION = "0.4.7";
+declare const VERSION = "0.4.11";
 
-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 };
+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 };