art-framework 0.2.8 → 0.3.0

package/dist/index.d.ts

@@ -51,47 +51,126 @@ declare class TypedSocket<DataType, FilterType = any> {
     clearAllSubscriptions(): void;
 }
 
-/** Entry defining an available provider adapter */
+/**
+ * Entry defining an available provider adapter.
+ *
+ * @interface AvailableProviderEntry
+ */
 interface AvailableProviderEntry {
+    /**
+     * Unique key, e.g., 'openai', 'anthropic', 'ollama_local'.
+     * @property {string} name
+     */
     name: string;
+    /**
+     * The adapter class.
+     * @property {new (options: any) => ProviderAdapter} adapter
+     */
     adapter: new (options: any) => ProviderAdapter;
+    /**
+     * Optional base config (rarely needed if options are per-call).
+     * @property {any} [baseOptions]
+     */
     baseOptions?: any;
+    /**
+     * Default: false. Determines singleton vs. pooling behavior.
+     * @property {boolean} [isLocal]
+     */
     isLocal?: boolean;
 }
-/** Configuration for the ProviderManager passed during ART initialization */
+/**
+ * Configuration for the ProviderManager passed during ART initialization.
+ *
+ * @interface ProviderManagerConfig
+ */
 interface ProviderManagerConfig {
+    /**
+     * @property {AvailableProviderEntry[]} availableProviders
+     */
     availableProviders: AvailableProviderEntry[];
-    /** Max concurrent ACTIVE instances per API-based provider NAME. Default: 5 */
+    /**
+     * Max concurrent ACTIVE instances per API-based provider NAME. Default: 5.
+     * @property {number} [maxParallelApiInstancesPerProvider]
+     */
     maxParallelApiInstancesPerProvider?: number;
-    /** Time in seconds an API adapter instance can be idle before being eligible for removal. Default: 300 */
+    /**
+     * Time in seconds an API adapter instance can be idle before being eligible for removal. Default: 300.
+     * @property {number} [apiInstanceIdleTimeoutSeconds]
+     */
     apiInstanceIdleTimeoutSeconds?: number;
 }
-/** Configuration passed AT RUNTIME for a specific LLM call */
+/**
+ * Configuration passed AT RUNTIME for a specific LLM call.
+ *
+ * @interface RuntimeProviderConfig
+ */
 interface RuntimeProviderConfig {
+    /**
+     * Must match a name in AvailableProviderEntry.
+     * @property {string} providerName
+     */
     providerName: string;
+    /**
+     * Specific model identifier (e.g., 'gpt-4o', 'llama3:latest').
+     * @property {string} modelId
+     */
     modelId: string;
+    /**
+     * Specific options for THIS instance (apiKey, temperature, contextSize, baseUrl, etc.).
+     * @property {any} adapterOptions
+     */
     adapterOptions: any;
 }
-/** Object returned by ProviderManager granting access to an adapter instance */
+/**
+ * Object returned by ProviderManager granting access to an adapter instance.
+ *
+ * @interface ManagedAdapterAccessor
+ */
 interface ManagedAdapterAccessor {
+    /**
+     * The ready-to-use adapter instance.
+     * @property {ProviderAdapter} adapter
+     */
     adapter: ProviderAdapter;
-    /** Signals that the current call using this adapter instance is finished. */
+    /**
+     * Signals that the current call using this adapter instance is finished.
+     * @property {() => void} release
+     */
     release: () => void;
 }
-/** Interface for the ProviderManager */
+/**
+ * Interface for the ProviderManager.
+ *
+ * @interface IProviderManager
+ */
 interface IProviderManager {
-    /** Returns identifiers for all registered potential providers */
+    /**
+     * Returns identifiers for all registered potential providers.
+     * @returns {string[]}
+     */
     getAvailableProviders(): string[];
     /**
      * Gets a managed adapter instance based on the runtime config.
+     *
+     * @remarks
      * Handles instance creation, caching, pooling limits, and singleton constraints.
      * May queue requests or throw errors based on concurrency limits.
+     *
+     * @param {RuntimeProviderConfig} config
+     * @returns {Promise<ManagedAdapterAccessor>}
      */
     getAdapter(config: RuntimeProviderConfig): Promise<ManagedAdapterAccessor>;
 }
 
+/**
+ * @module utils/logger
+ * Provides a simple, static, and configurable logger for the ART framework.
+ * It supports different log levels and can be enabled or disabled globally.
+ */
 /**
  * Defines the available logging levels, ordered from most verbose to least verbose.
+ *
+ * @enum {number}
  */
 declare enum LogLevel {
     /** Detailed debugging information, useful for development. */
@@ -105,114 +184,276 @@ declare enum LogLevel {
 }
 /**
  * Configuration options for the static Logger class.
+ *
+ * @interface LoggerConfig
  */
 interface LoggerConfig {
-    /** The minimum log level to output messages for. Messages below this level will be ignored. */
+    /**
+     * The minimum log level to output messages for. Messages below this level will be ignored.
+     * @property {LogLevel} level
+     */
     level: LogLevel;
-    /** An optional prefix string to prepend to all log messages (e.g., '[MyApp]'). Defaults to '[ART]'. */
+    /**
+     * An optional prefix string to prepend to all log messages (e.g., '[MyApp]'). Defaults to '[ART]'.
+     * @property {string} [prefix]
+     */
     prefix?: string;
 }
 /**
  * A simple static logger class for outputting messages to the console at different levels.
+ *
+ * @remarks
  * Configuration is global via the static `configure` method.
+ *
+ * @class Logger
  */
 declare class Logger {
     private static config;
     /**
      * Configures the static logger settings.
-     * @param config - A partial `LoggerConfig` object. Provided settings will override defaults.
+     *
+     * @param config A partial `LoggerConfig` object. Provided settings will override defaults.
      */
     static configure(config: Partial<LoggerConfig>): void;
     /**
      * Logs a message at the DEBUG level.
+     *
+     * @remarks
      * Only outputs if the configured log level is DEBUG.
-     * @param message - The main log message string.
-     * @param args - Additional arguments to include in the console output (e.g., objects, arrays).
+     *
+     * @param message The main log message string.
+     * @param args Additional arguments to include in the console output (e.g., objects, arrays).
      */
     static debug(message: string, ...args: any[]): void;
     /**
      * Logs a message at the INFO level.
+     *
+     * @remarks
      * Outputs if the configured log level is INFO or DEBUG.
-     * @param message - The main log message string.
-     * @param args - Additional arguments to include in the console output.
+     *
+     * @param message The main log message string.
+     * @param args Additional arguments to include in the console output.
      */
     static info(message: string, ...args: any[]): void;
     /**
      * Logs a message at the WARN level.
+     *
+     * @remarks
      * Outputs if the configured log level is WARN, INFO, or DEBUG.
-     * @param message - The main log message string.
-     * @param args - Additional arguments to include in the console output.
+     *
+     * @param message The main log message string.
+     * @param args Additional arguments to include in the console output.
      */
     static warn(message: string, ...args: any[]): void;
     /**
      * Logs a message at the ERROR level.
+     *
+     * @remarks
      * Outputs if the configured log level is ERROR, WARN, INFO, or DEBUG.
-     * @param message - The main log message string.
-     * @param args - Additional arguments to include in the console output (often an error object).
+     *
+     * @param message The main log message string.
+     * @param args Additional arguments to include in the console output (often an error object).
      */
     static error(message: string, ...args: any[]): void;
 }
 
 /**
  * Defines standard error codes for the ART framework.
+ * These codes categorize errors originating from different subsystems.
  */
 declare enum ErrorCode {
+    /** Invalid or malformed configuration provided. */
     INVALID_CONFIG = "INVALID_CONFIG",
-    MISSING_API_KEY = "MISSING_API_KEY",
+    /** A required API key was not provided. */
+    MISSING_API_key = "MISSING_API_KEY",
+    /** General configuration-related error. */
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR",
+    /** A generic error occurred in the storage layer. */
     STORAGE_ERROR = "STORAGE_ERROR",
+    /** The requested thread could not be found in storage. */
     THREAD_NOT_FOUND = "THREAD_NOT_FOUND",
+    /** Failed to save data to the storage layer. */
     SAVE_FAILED = "SAVE_FAILED",
+    /** An error occurred while communicating with the LLM provider. */
     LLM_PROVIDER_ERROR = "LLM_PROVIDER_ERROR",
+    /** Failed to generate a prompt. */
     PROMPT_GENERATION_FAILED = "PROMPT_GENERATION_FAILED",
+    /** Failed to parse the output from the LLM. */
     OUTPUT_PARSING_FAILED = "OUTPUT_PARSING_FAILED",
-    PROMPT_ASSEMBLY_FAILED = "PROMPT_ASSEMBLY_FAILED",// Error during prompt template rendering or initial structure creation (legacy, might be removed)
-    PROMPT_FRAGMENT_NOT_FOUND = "PROMPT_FRAGMENT_NOT_FOUND",// Requested prompt fragment does not exist
-    PROMPT_VALIDATION_FAILED = "PROMPT_VALIDATION_FAILED",// Constructed prompt object failed schema validation
-    PROMPT_TRANSLATION_FAILED = "PROMPT_TRANSLATION_FAILED",// Added for Adapter translation
+    /** Error during prompt template rendering or initial structure creation. */
+    PROMPT_ASSEMBLY_FAILED = "PROMPT_ASSEMBLY_FAILED",
+    /** The requested prompt fragment does not exist. */
+    PROMPT_FRAGMENT_NOT_FOUND = "PROMPT_FRAGMENT_NOT_FOUND",
+    /** The constructed prompt object failed schema validation. */
+    PROMPT_VALIDATION_FAILED = "PROMPT_VALIDATION_FAILED",
+    /** Failed to translate the ART standard prompt to a provider-specific format. */
+    PROMPT_TRANSLATION_FAILED = "PROMPT_TRANSLATION_FAILED",
+    /** The requested tool could not be found in the registry. */
     TOOL_NOT_FOUND = "TOOL_NOT_FOUND",
+    /** The provided tool schema failed validation. */
     TOOL_SCHEMA_VALIDATION_FAILED = "TOOL_SCHEMA_VALIDATION_FAILED",
-    TOOL_EXECUTION_ERROR = "TOOL_EXECUTION_ERROR",// Generic tool execution error
+    /** A generic error occurred during tool execution. */
+    TOOL_EXECUTION_ERROR = "TOOL_EXECUTION_ERROR",
+    /** The requested tool is disabled for the current thread. */
     TOOL_DISABLED = "TOOL_DISABLED",
+    /** The planning phase of the agent failed. */
     PLANNING_FAILED = "PLANNING_FAILED",
-    TOOL_EXECUTION_FAILED = "TOOL_EXECUTION_FAILED",// Error within the ToolSystem execution loop
+    /** An error occurred within the ToolSystem execution loop. */
+    TOOL_EXECUTION_FAILED = "TOOL_EXECUTION_FAILED",
+    /** The synthesis phase of the agent failed. */
     SYNTHESIS_FAILED = "SYNTHESIS_FAILED",
-    AGENT_PROCESSING_ERROR = "AGENT_PROCESSING_ERROR",// General error during agent.process
+    /** A general error occurred during the agent's process method. */
+    AGENT_PROCESSING_ERROR = "AGENT_PROCESSING_ERROR",
+    /** An A2A (Agent-to-Agent) task delegation failed. */
+    DELEGATION_FAILED = "DELEGATION_FAILED",
+    /** A network error occurred. */
     NETWORK_ERROR = "NETWORK_ERROR",
+    /** An operation timed out. */
     TIMEOUT_ERROR = "TIMEOUT_ERROR",
+    /** An operation timed out (duplicate of TIMEOUT_ERROR). */
+    TIMEOUT = "TIMEOUT",
+    /** An error occurred with an external service. */
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR",
+    /** The requested task was not found. */
+    TASK_NOT_FOUND = "TASK_NOT_FOUND",
+    /** Input data failed validation. */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** The request was invalid or malformed. */
+    INVALID_REQUEST = "INVALID_REQUEST",
+    /** A task with the same ID already exists. */
+    DUPLICATE_TASK_ID = "DUPLICATE_TASK_ID",
+    /** A generic error occurred in a repository. */
+    REPOSITORY_ERROR = "REPOSITORY_ERROR",
+    /** A connection is already established. */
+    ALREADY_CONNECTED = "ALREADY_CONNECTED",
+    /** A required configuration is missing. */
+    MISSING_CONFIG = "MISSING_CONFIG",
+    /** The requested feature is not implemented. */
+    NOT_IMPLEMENTED = "NOT_IMPLEMENTED",
+    /** No active connection is available. */
+    NOT_CONNECTED = "NOT_CONNECTED",
+    /** The request timed out. */
+    REQUEST_TIMEOUT = "REQUEST_TIMEOUT",
+    /** Standard input is not available. */
+    NO_STDIN = "NO_STDIN",
+    /** The provided URL is not an HTTP/HTTPS URL. */
+    NO_HTTP_URL = "NO_HTTP_URL",
+    /** An HTTP error occurred. */
+    HTTP_ERROR = "HTTP_ERROR",
+    /** The requested server was not found. */
+    SERVER_NOT_FOUND = "SERVER_NOT_FOUND",
+    /** A health check for a service failed. */
+    HEALTH_CHECK_FAILED = "HEALTH_CHECK_FAILED",
+    /** Failed to discover tools from a remote source. */
+    TOOL_DISCOVERY_FAILED = "TOOL_DISCOVERY_FAILED",
+    /** The requested transport protocol is not supported. */
+    UNSUPPORTED_TRANSPORT = "UNSUPPORTed_TRANSPORT",
+    /** A CORS browser extension is required to proceed. */
+    CORS_EXTENSION_REQUIRED = "CORS_EXTENSION_REQUIRED",
+    /** CORS permissions are required but have not been granted. */
+    CORS_PERMISSION_REQUIRED = "CORS_PERMISSION_REQUIRED",
+    /** An unknown or unexpected error occurred. */
     UNKNOWN_ERROR = "UNKNOWN_ERROR",
-    UNKNOWN_PROVIDER = "UNKNOWN_PROVIDER",// Checklist item 4.7
-    LOCAL_PROVIDER_CONFLICT = "LOCAL_PROVIDER_CONFLICT",// Checklist item 4.7
-    LOCAL_INSTANCE_BUSY = "LOCAL_INSTANCE_BUSY",// Checklist item 4.7
-    API_QUEUE_TIMEOUT = "API_QUEUE_TIMEOUT",// Checklist item 4.7 (optional)
+    /** The requested LLM provider is not known or configured. */
+    UNKNOWN_PROVIDER = "UNKNOWN_PROVIDER",
+    /** Attempted to activate a local provider when another is already active. */
+    LOCAL_PROVIDER_CONFLICT = "LOCAL_PROVIDER_CONFLICT",
+    /** The requested local LLM instance is currently busy. */
+    LOCAL_INSTANCE_BUSY = "LOCAL_INSTANCE_BUSY",
+    /** Timeout waiting for an available instance of an API provider. */
+    API_QUEUE_TIMEOUT = "API_QUEUE_TIMEOUT",
+    /** Failed to instantiate an adapter for a provider. */
     ADAPTER_INSTANTIATION_ERROR = "ADAPTER_INSTANTIATION_ERROR"
 }
 /**
  * Custom error class for ART framework specific errors.
+ * It includes an error code, an optional original error for chaining,
+ * and a details object for additional context.
  */
 declare class ARTError extends Error {
+    /** The specific error code from the ErrorCode enum. */
     readonly code: ErrorCode;
+    /** The original error that caused this error, if any. */
     readonly originalError?: Error;
-    constructor(message: string, code: ErrorCode, originalError?: Error);
+    /** A record of additional details about the error. */
+    details: Record<string, any>;
+    /**
+     * Creates an instance of ARTError.
+     * @param {string} message - The error message.
+     * @param {ErrorCode} code - The error code.
+     * @param {Error} [originalError] - The original error, if any.
+     * @param {Record<string, any>} [details={}] - Additional details about the error.
+     */
+    constructor(message: string, code: ErrorCode, originalError?: Error, details?: Record<string, any>);
+    /**
+     * Returns a string representation of the error, including the original error if present.
+     * @returns {string} The string representation of the error.
+     */
     toString(): string;
 }
+/**
+ * Error thrown when a requested LLM provider is not known or configured.
+ */
 declare class UnknownProviderError extends ARTError {
     constructor(providerName: string);
 }
+/**
+ * Error thrown when attempting to activate a local provider while another is already active.
+ */
 declare class LocalProviderConflictError extends ARTError {
     constructor(requestedProvider: string, activeProvider: string);
 }
+/**
+ * Error thrown when a requested local LLM instance is currently busy.
+ */
 declare class LocalInstanceBusyError extends ARTError {
     constructor(providerName: string, modelId: string);
 }
+/**
+ * Error thrown when a timeout occurs while waiting for an available instance of an API provider.
+ */
 declare class ApiQueueTimeoutError extends ARTError {
     constructor(providerName: string);
 }
+/**
+ * Error thrown when an adapter for a provider fails to instantiate.
+ */
 declare class AdapterInstantiationError extends ARTError {
     constructor(providerName: string, originalError: Error);
 }
 
+type StreamEventTypeFilter = StreamEvent['type'] | Array<StreamEvent['type']>;
+/**
+ * A dedicated socket for broadcasting LLM stream events (`StreamEvent`) to UI subscribers.
+ * Extends the generic TypedSocket and implements filtering based on `StreamEvent.type`.
+ */
+declare class LLMStreamSocket extends TypedSocket<StreamEvent, StreamEventTypeFilter> {
+    constructor();
+    /**
+     * Notifies subscribers about a new LLM stream event.
+     * Filters based on event type if a filter is provided during subscription.
+     * @param event - The StreamEvent data.
+     */
+    notifyStreamEvent(event: StreamEvent): void;
+}
+
+/**
+ * @module types/schemas
+ * This module defines Zod schemas for validating the core data structures of the ART framework,
+ * ensuring type safety and data integrity at runtime.
+ */
+
 /**
- * Zod schema for validating a single ArtStandardMessage object.
+ * Zod schema for validating a single {@link ArtStandardMessage} object.
+ *
+ * @remarks
+ * This schema enforces the structural and type requirements for each message, including:
+ * - A valid `role` from the {@link ArtStandardMessageRole} enum.
+ * - `content` that matches the expected type for a given role (e.g., string for 'user', string or null for 'assistant').
+ * - The presence of `tool_call_id` for 'tool' or 'tool_result' roles.
+ * - The structure of `tool_calls` when present in an 'assistant' message.
+ *
+ * It uses a `.refine()` method to implement context-aware validation based on the message's `role`.
  */
 declare const ArtStandardMessageSchema: z.ZodEffects<z.ZodObject<{
     role: z.ZodType<ArtStandardMessageRole, z.ZodTypeDef, ArtStandardMessageRole>;
@@ -301,7 +542,11 @@ declare const ArtStandardMessageSchema: z.ZodEffects<z.ZodObject<{
     tool_call_id?: string | undefined;
 }>;
 /**
- * Zod schema for validating an entire ArtStandardPrompt (an array of messages).
+ * Zod schema for validating an entire {@link ArtStandardPrompt} (an array of messages).
+ *
+ * @remarks
+ * This is a straightforward array schema that applies the {@link ArtStandardMessageSchema} to each element,
+ * ensuring that every message in the prompt conforms to the required structure.
  */
 declare const ArtStandardPromptSchema: z.ZodArray<z.ZodEffects<z.ZodObject<{
     role: z.ZodType<ArtStandardMessageRole, z.ZodTypeDef, ArtStandardMessageRole>;
@@ -390,38 +635,352 @@ declare const ArtStandardPromptSchema: z.ZodArray<z.ZodEffects<z.ZodObject<{
     tool_call_id?: string | undefined;
 }>, "many">;
 
+/**
+ * @module systems/mcp/types
+ * This module defines the public and internal types used for configuring
+ * and managing the state of the MCP (Multi-Capability Provider) system.
+ */
+/**
+ * Defines the connection details for a streamable HTTP-based MCP server.
+ * This is the primary transport mechanism for browser-based MCP communication.
+ *
+ * @interface StreamableHttpConnection
+ */
+interface StreamableHttpConnection {
+    /**
+     * The base URL of the MCP server.
+     * @property {string} url
+     */
+    url: string;
+    /**
+     * Optional headers to include in every request to the server.
+     * @property {Record<string, string>} [headers]
+     */
+    headers?: Record<string, string>;
+    /**
+     * The ID of an authentication strategy to use for this connection.
+     * @property {string} [authStrategyId]
+     */
+    authStrategyId?: string;
+    /**
+     * Optional OAuth configuration for automatic PKCE setup per server.
+     * This enables secure, per-server authentication without manual token handling.
+     * @property {object} [oauth]
+     */
+    oauth?: {
+        /**
+         * The type of OAuth flow, currently supporting 'pkce'.
+         * @property {'pkce'} type
+         */
+        type: 'pkce';
+        /**
+         * The OAuth 2.1 Authorization Endpoint URL.
+         * @property {string} authorizationEndpoint
+         */
+        authorizationEndpoint: string;
+        /**
+         * The OAuth 2.1 Token Endpoint URL.
+         * @property {string} tokenEndpoint
+         */
+        tokenEndpoint: string;
+        /**
+         * The public client ID for the OAuth application.
+         * @property {string} clientId
+         */
+        clientId: string;
+        /**
+         * A space-delimited string of OAuth scopes to request.
+         * @property {string} scopes
+         */
+        scopes: string;
+        /**
+         * The redirect URI that will handle the OAuth callback.
+         * @property {string} redirectUri
+         */
+        redirectUri: string;
+        /**
+         * Optional 'resource' parameter for OAuth 2.1, often used as an audience identifier.
+         * @property {string} [resource]
+         */
+        resource?: string;
+        /**
+         * Determines whether to open the login page in a new tab.
+         * Defaults to true if omitted.
+         * @property {boolean} [openInNewTab]
+         */
+        openInNewTab?: boolean;
+        /**
+         * An optional BroadcastChannel name for delivering tokens, useful in multi-window scenarios.
+         * @property {string} [channelName]
+         */
+        channelName?: string;
+    };
+}
+/**
+ * Defines the schema for a tool provided by an MCP server.
+ *
+ * @interface McpToolDefinition
+ */
+interface McpToolDefinition {
+    /**
+     * The name of the tool.
+     * @property {string} name
+     */
+    name: string;
+    /**
+     * A description of what the tool does.
+     * @property {string} [description]
+     */
+    description?: string;
+    /**
+     * The JSON schema for the tool's input.
+     * @property {any} inputSchema
+     */
+    inputSchema: any;
+    /**
+     * The JSON schema for the tool's output.
+     * @property {any} [outputSchema]
+     */
+    outputSchema?: any;
+}
+/**
+ * Defines a static resource provided by an MCP server.
+ *
+ * @interface McpResource
+ */
+interface McpResource {
+    /**
+     * The URI of the resource.
+     * @property {string} uri
+     */
+    uri: string;
+    /**
+     * The name of the resource.
+     * @property {string} name
+     */
+    name: string;
+    /**
+     * The MIME type of the resource.
+     * @property {string} [mimeType]
+     */
+    mimeType?: string;
+    /**
+     * A description of the resource.
+     * @property {string} [description]
+     */
+    description?: string;
+}
+/**
+ * Defines a template for a resource provided by an MCP server.
+ *
+ * @interface McpResourceTemplate
+ */
+interface McpResourceTemplate {
+    /**
+     * The URI template for the resource.
+     * @property {string} uriTemplate
+     */
+    uriTemplate: string;
+    /**
+     * The name of the resource template.
+     * @property {string} name
+     */
+    name: string;
+    /**
+     * A description of the resource template.
+     * @property {string} [description]
+     */
+    description?: string;
+    /**
+     * The MIME type of the resource.
+     * @property {string} [mimeType]
+     */
+    mimeType?: string;
+}
+/**
+ * Represents the configuration for a single MCP server.
+ *
+ * @remarks
+ * This is the format for each server entry in the `art_mcp_config.json` file.
+ * It contains all the necessary information for discovering, installing, and connecting to an MCP server.
+ *
+ * @typedef {object} McpServerConfig
+ */
+type McpServerConfig = {
+    /**
+     * A unique identifier for the server.
+     * @property {string} id
+     */
+    id: string;
+    /**
+     * The transport type for the server, currently only 'streamable-http' is supported.
+     * @property {'streamable-http'} type
+     */
+    type: 'streamable-http';
+    /**
+     * Whether the server is enabled and should be connected to.
+     * @property {boolean} enabled
+     */
+    enabled: boolean;
+    /**
+     * A user-friendly name for the server.
+     * @property {string} [displayName]
+     */
+    displayName?: string;
+    /**
+     * A description of the server and its capabilities.
+     * @property {string} [description]
+     */
+    description?: string;
+    /**
+     * The connection details for the server.
+     * @see module:systems/mcp/types.StreamableHttpConnection
+     */
+    connection: StreamableHttpConnection;
+    /**
+     * Information about how the server was installed (e.g., 'git', 'npm', 'manual').
+     * @property {object} [installation]
+     */
+    installation?: {
+        source: 'git' | 'npm' | 'manual';
+        [key: string]: any;
+    };
+    /**
+     * The timeout in milliseconds for requests to the server.
+     * @property {number} [timeout]
+     */
+    timeout?: number;
+    /**
+     * The tools provided by the server.
+     * @property {McpToolDefinition[]} tools
+     */
+    tools: McpToolDefinition[];
+    /**
+     * The static resources provided by the server.
+     * @property {McpResource[]} resources
+     */
+    resources: McpResource[];
+    /**
+     * The resource templates provided by the server.
+     * @property {McpResourceTemplate[]} resourceTemplates
+     */
+    resourceTemplates: McpResourceTemplate[];
+};
+/**
+ * Represents the internal status of an MCP server connection.
+ * This is not part of the public configuration.
+ *
+ * @interface McpServerStatus
+ */
+interface McpServerStatus {
+    /**
+     * The unique identifier for the server.
+     * @property {string} id
+     */
+    id: string;
+    /**
+     * The current connection status of the server.
+     * @property {'connected' | 'disconnected' | 'error' | 'connecting'} status
+     */
+    status: 'connected' | 'disconnected' | 'error' | 'connecting';
+    /**
+     * The timestamp of the last successful connection.
+     * @property {Date} [lastConnected]
+     */
+    lastConnected?: Date;
+    /**
+     * The last error message received from the server.
+     * @property {string} [lastError]
+     */
+    lastError?: string;
+    /**
+     * The number of tools registered from this server.
+     * @property {number} toolCount
+     */
+    toolCount: number;
+}
+/**
+ * Defines the configuration for the McpManager.
+ *
+ * @interface McpManagerConfig
+ */
+interface McpManagerConfig {
+    /**
+     * Whether to enable MCP functionality. Defaults to false.
+     * @property {boolean} enabled
+     */
+    enabled: boolean;
+    /**
+     * An optional endpoint URL for discovering MCP servers.
+     * Defaults to the Zyntopia API if not provided.
+     * @property {string} [discoveryEndpoint]
+     */
+    discoveryEndpoint?: string;
+}
+
 /**
  * Represents the role of a message sender in a conversation.
+ *
+ * @enum {string}
  */
 declare enum MessageRole {
+    /** The end-user interacting with the agent. */
     USER = "USER",
+    /** The AI agent. */
     AI = "AI",
-    SYSTEM = "SYSTEM",// Added for system prompts, though not explicitly in checklist message interface
+    /** A system-level message providing context or instructions. */
+    SYSTEM = "SYSTEM",
+    /** A message containing the result of a tool execution. */
     TOOL = "TOOL"
 }
 /**
  * Represents a single message within a conversation thread.
+ *
+ * @interface ConversationMessage
  */
 interface ConversationMessage {
-    /** A unique identifier for this specific message. */
+    /**
+     * A unique identifier for this specific message.
+     * @property {string} messageId
+     */
     messageId: string;
-    /** The identifier of the conversation thread this message belongs to. */
+    /**
+     * The identifier of the conversation thread this message belongs to.
+     * @property {string} threadId
+     */
     threadId: string;
-    /** The role of the sender (User, AI, System, or Tool). */
+    /**
+     * The role of the sender (User, AI, System, or Tool).
+     * @property {MessageRole} role
+     */
     role: MessageRole;
-    /** The textual content of the message. */
+    /**
+     * The textual content of the message.
+     * @property {string} content
+     */
     content: string;
-    /** A Unix timestamp (in milliseconds) indicating when the message was created. */
+    /**
+     * A Unix timestamp (in milliseconds) indicating when the message was created.
+     * @property {number} timestamp
+     */
     timestamp: number;
-    /** Optional metadata associated with the message (e.g., related observation IDs, tool call info, UI state). */
+    /**
+     * Optional metadata associated with the message (e.g., related observation IDs, tool call info, UI state).
+     * @property {Record<string, any>} [metadata]
+     */
     metadata?: Record<string, any>;
 }
 /**
  * Represents the type of an observation record, capturing significant events during agent execution.
+ *
+ * @enum {string}
  */
 declare enum ObservationType {
+    /** The user's inferred intent. */
     INTENT = "INTENT",
+    /** The agent's step-by-step plan to address the intent. */
     PLAN = "PLAN",
+    /** The agent's internal monologue or reasoning process. */
     THOUGHTS = "THOUGHTS",
     /** Records the LLM's decision to call one or more tools (part of the plan). */
     TOOL_CALL = "TOOL_CALL",
@@ -447,49 +1006,89 @@ declare enum ObservationType {
 /**
  * Represents the different capabilities a model might possess.
  * Used for model selection and validation.
+ *
+ * @enum {string}
  */
 declare enum ModelCapability {
-    TEXT = "text",// Basic text generation/understanding
-    VISION = "vision",// Ability to process and understand images
-    STREAMING = "streaming",// Supports streaming responses chunk by chunk
-    TOOL_USE = "tool_use",// Capable of using tools/function calling
-    RAG = "rag",// Built-in or optimized for Retrieval-Augmented Generation
-    CODE = "code",// Specialized in understanding or generating code
+    /** Basic text generation/understanding. */
+    TEXT = "text",
+    /** Ability to process and understand images. */
+    VISION = "vision",
+    /** Supports streaming responses chunk by chunk. */
+    STREAMING = "streaming",
+    /** Capable of using tools/function calling. */
+    TOOL_USE = "tool_use",
+    /** Built-in or optimized for Retrieval-Augmented Generation. */
+    RAG = "rag",
+    /** Specialized in understanding or generating code. */
+    CODE = "code",
+    /** Advanced reasoning, planning, complex instruction following. */
     REASONING = "reasoning"
 }
 /**
  * Represents a recorded event during the agent's execution.
+ *
+ * @interface Observation
  */
 interface Observation {
-    /** A unique identifier for this specific observation record. */
+    /**
+     * A unique identifier for this specific observation record.
+     * @property {string} id
+     */
     id: string;
-    /** The identifier of the conversation thread this observation relates to. */
+    /**
+     * The identifier of the conversation thread this observation relates to.
+     * @property {string} threadId
+     */
     threadId: string;
-    /** An optional identifier for tracing a request across multiple systems or components. */
+    /**
+     * An optional identifier for tracing a request across multiple systems or components.
+     * @property {string} [traceId]
+     */
     traceId?: string;
-    /** A Unix timestamp (in milliseconds) indicating when the observation was recorded. */
+    /**
+     * A Unix timestamp (in milliseconds) indicating when the observation was recorded.
+     * @property {number} timestamp
+     */
     timestamp: number;
-    /** The category of the event being observed (e.g., PLAN, THOUGHTS, TOOL_EXECUTION). */
+    /**
+     * The category of the event being observed (e.g., PLAN, THOUGHTS, TOOL_EXECUTION).
+     * @property {ObservationType} type
+     */
     type: ObservationType;
-    /** A concise, human-readable title summarizing the observation (often generated based on type/metadata). */
+    /**
+     * A concise, human-readable title summarizing the observation (often generated based on type/metadata).
+     * @property {string} title
+     */
     title: string;
-    /** The main data payload of the observation, structure depends on the `type`. */
+    /**
+     * The main data payload of the observation, structure depends on the `type`.
+     * @property {any} content
+     */
     content: any;
-    /** Optional metadata providing additional context (e.g., source phase, related IDs, status). */
+    /**
+     * Optional metadata providing additional context (e.g., source phase, related IDs, status).
+     * @property {Record<string, any>} [metadata]
+     */
     metadata?: Record<string, any>;
 }
 /**
  * Represents a single event emitted from an asynchronous LLM stream (`ReasoningEngine.call`).
+ *
+ * @remarks
  * Allows for real-time delivery of tokens, metadata, errors, and lifecycle signals.
  * Adapters are responsible for translating provider-specific stream chunks into these standard events.
+ *
+ * @interface StreamEvent
  */
 interface StreamEvent {
     /**
-     * The type of the stream event:
+     * The type of the stream event.
      * - `TOKEN`: A chunk of text generated by the LLM.
      * - `METADATA`: Information about the LLM call (e.g., token counts, stop reason), typically sent once at the end.
      * - `ERROR`: An error occurred during the LLM call or stream processing. `data` will contain the Error object.
      * - `END`: Signals the successful completion of the stream. `data` is typically null.
+     * @property {'TOKEN' | 'METADATA' | 'ERROR' | 'END'} type
      */
     type: 'TOKEN' | 'METADATA' | 'ERROR' | 'END';
     /**
@@ -498,6 +1097,7 @@ interface StreamEvent {
      * - For `METADATA`: `LLMMetadata` object.
      * - For `ERROR`: `Error` object or error details.
      * - For `END`: null.
+     * @property {any} data
      */
     data: any;
     /**
@@ -513,24 +1113,43 @@ interface StreamEvent {
      * - `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).
      *
-     * Note: Not all adapters can reliably distinguish 'LLM_THINKING' vs 'LLM_RESPONSE'.
+     * @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]
      */
     tokenType?: 'LLM_THINKING' | 'LLM_RESPONSE' | 'AGENT_THOUGHT_LLM_THINKING' | 'AGENT_THOUGHT_LLM_RESPONSE' | 'FINAL_SYNTHESIS_LLM_THINKING' | 'FINAL_SYNTHESIS_LLM_RESPONSE';
-    /** The identifier of the conversation thread this event belongs to. */
+    /**
+     * The identifier of the conversation thread this event belongs to.
+     * @property {string} threadId
+     */
     threadId: string;
-    /** The identifier tracing the specific agent execution cycle this event is part of. */
+    /**
+     * The identifier tracing the specific agent execution cycle this event is part of.
+     * @property {string} traceId
+     */
     traceId: string;
-    /** Optional identifier linking the event to a specific UI tab/window. */
+    /**
+     * Optional identifier linking the event to a specific UI tab/window.
+     * @property {string} [sessionId]
+     */
     sessionId?: string;
 }
 /**
  * Represents a basic JSON Schema definition, focusing on object types commonly used for tool inputs/outputs.
  * This is a simplified representation and doesn't cover all JSON Schema features.
+ *
+ * @interface JsonObjectSchema
  */
 interface JsonObjectSchema {
+    /**
+     * @property {'object'} type
+     */
     type: 'object';
+    /**
+     * @property {object} properties
+     */
     properties: {
         [key: string]: {
             type: string;
@@ -557,39 +1176,82 @@ type JsonSchema = JsonObjectSchema | {
 /**
  * Structure for holding metadata about an LLM call, typically received via a `METADATA` `StreamEvent`
  * or parsed from a non-streaming response. Fields are optional as availability varies by provider and stream state.
+ *
+ * @interface LLMMetadata
  */
 interface LLMMetadata {
-    /** The number of tokens in the input prompt, if available. */
+    /**
+     * The number of tokens in the input prompt, if available.
+     * @property {number} [inputTokens]
+     */
     inputTokens?: number;
-    /** The number of tokens generated in the output response, if available. */
+    /**
+     * The number of tokens generated in the output response, if available.
+     * @property {number} [outputTokens]
+     */
     outputTokens?: number;
-    /** The number of tokens identified as part of the LLM's internal thinking process (if available from provider). */
+    /**
+     * The number of tokens identified as part of the LLM's internal thinking process (if available from provider).
+     * @property {number} [thinkingTokens]
+     */
     thinkingTokens?: number;
-    /** The time elapsed (in milliseconds) until the first token was generated in a streaming response, if applicable and available. */
+    /**
+     * The time elapsed (in milliseconds) until the first token was generated in a streaming response, if applicable and available.
+     * @property {number} [timeToFirstTokenMs]
+     */
     timeToFirstTokenMs?: number;
-    /** The total time elapsed (in milliseconds) for the entire generation process, if available. */
+    /**
+     * The total time elapsed (in milliseconds) for the entire generation process, if available.
+     * @property {number} [totalGenerationTimeMs]
+     */
     totalGenerationTimeMs?: number;
-    /** The reason the LLM stopped generating tokens (e.g., 'stop_sequence', 'max_tokens', 'tool_calls'), if available. */
+    /**
+     * The reason the LLM stopped generating tokens (e.g., 'stop_sequence', 'max_tokens', 'tool_calls'), if available.
+     * @property {string} [stopReason]
+     */
     stopReason?: string;
-    /** Optional raw usage data provided directly by the LLM provider for extensibility (structure depends on provider). */
+    /**
+     * Optional raw usage data provided directly by the LLM provider for extensibility (structure depends on provider).
+     * @property {any} [providerRawUsage]
+     */
     providerRawUsage?: any;
-    /** The trace ID associated with the LLM call, useful for correlating metadata with the specific request. */
+    /**
+     * The trace ID associated with the LLM call, useful for correlating metadata with the specific request.
+     * @property {string} [traceId]
+     */
     traceId?: string;
 }
 /**
  * Defines the schema for a tool, including its input parameters.
  * Uses JSON Schema format for inputSchema.
+ *
+ * @interface ToolSchema
  */
 interface ToolSchema {
-    /** A unique name identifying the tool (used in LLM prompts and registry lookups). Must be unique. */
+    /**
+     * A unique name identifying the tool (used in LLM prompts and registry lookups). Must be unique.
+     * @property {string} name
+     */
     name: string;
-    /** A clear description of what the tool does, intended for the LLM to understand its purpose and usage. */
+    /**
+     * A clear description of what the tool does, intended for the LLM to understand its purpose and usage.
+     * @property {string} description
+     */
     description: string;
-    /** A JSON Schema object defining the structure, types, and requirements of the input arguments the tool expects. */
+    /**
+     * A JSON Schema object defining the structure, types, and requirements of the input arguments the tool expects.
+     * @property {JsonSchema} inputSchema
+     */
     inputSchema: JsonSchema;
-    /** An optional JSON Schema object defining the expected structure of the data returned in the `output` field of a successful `ToolResult`. */
+    /**
+     * An optional JSON Schema object defining the expected structure of the data returned in the `output` field of a successful `ToolResult`.
+     * @property {JsonSchema} [outputSchema]
+     */
     outputSchema?: JsonSchema;
-    /** Optional array of examples demonstrating how to use the tool, useful for few-shot prompting of the LLM. */
+    /**
+     * Optional array of examples demonstrating how to use the tool, useful for few-shot prompting of the LLM.
+     * @property {Array<{ input: any; output?: any; description?: string }>} [examples]
+     */
     examples?: Array<{
         input: any;
         output?: any;
@@ -598,183 +1260,463 @@ interface ToolSchema {
 }
 /**
  * Represents the structured result of a tool execution.
+ *
+ * @interface ToolResult
  */
 interface ToolResult {
-    /** The unique identifier of the corresponding `ParsedToolCall` that initiated this execution attempt. */
+    /**
+     * The unique identifier of the corresponding `ParsedToolCall` that initiated this execution attempt.
+     * @property {string} callId
+     */
     callId: string;
-    /** The name of the tool that was executed. */
+    /**
+     * The name of the tool that was executed.
+     * @property {string} toolName
+     */
     toolName: string;
-    /** Indicates whether the tool execution succeeded or failed. */
+    /**
+     * Indicates whether the tool execution succeeded or failed.
+     * @property {'success' | 'error'} status
+     */
     status: 'success' | 'error';
-    /** The data returned by the tool upon successful execution. Structure may be validated against `outputSchema`. */
+    /**
+     * The data returned by the tool upon successful execution. Structure may be validated against `outputSchema`.
+     * @property {any} [output]
+     */
     output?: any;
-    /** A descriptive error message if the execution failed (`status` is 'error'). */
+    /**
+     * A descriptive error message if the execution failed (`status` is 'error').
+     * @property {string} [error]
+     */
     error?: string;
-    /** Optional metadata about the execution (e.g., duration, cost, logs). */
-    metadata?: Record<string, any>;
+    /**
+     * Optional metadata about the execution (e.g., duration, cost, logs).
+     * @property {object} [metadata]
+     */
+    metadata?: {
+        sources?: Array<{
+            sourceName: string;
+            url?: string;
+            [key: string]: any;
+        }>;
+        [key: string]: any;
+    };
+}
+/**
+ * Strategy for combining custom system prompt content across precedence levels.
+ *
+ * @typedef {'append' | 'prepend'} SystemPromptMergeStrategy
+ */
+type SystemPromptMergeStrategy = 'append' | 'prepend';
+/**
+ * Named preset for system prompts, supporting variables and a default merge strategy.
+ *
+ * @interface SystemPromptSpec
+ */
+interface SystemPromptSpec {
+    /**
+     * Optional explicit ID; when in a registry map, the key is typically the tag.
+     * @property {string} [id]
+     */
+    id?: string;
+    /**
+     * Template string. Supports simple {{variable}} placeholders and {{fragment:name}} for PromptManager fragments.
+     * @property {string} template
+     */
+    template: string;
+    /**
+     * Default variables applied if not provided at use time.
+     * @property {Record<string, any>} [defaultVariables]
+     */
+    defaultVariables?: Record<string, any>;
+    /**
+     * Default strategy to combine this spec with lower levels. Defaults to 'append'.
+     * @property {SystemPromptMergeStrategy} [mergeStrategy]
+     */
+    mergeStrategy?: SystemPromptMergeStrategy;
+}
+/**
+ * Registry of available system prompt presets (tags) at the instance level.
+ *
+ * @interface SystemPromptsRegistry
+ */
+interface SystemPromptsRegistry {
+    /**
+     * Tag to use when no other tag is specified.
+     * @property {string} [defaultTag]
+     */
+    defaultTag?: string;
+    /**
+     * Mapping of tag -> spec.
+     * @property {Record<string, SystemPromptSpec>} specs
+     */
+    specs: Record<string, SystemPromptSpec>;
+}
+/**
+ * Override provided at instance/thread/call level to select a tag and/or provide variables,
+ * or to provide freeform content and a merge strategy.
+ *
+ * @interface SystemPromptOverride
+ */
+interface SystemPromptOverride {
+    /**
+     * Preset tag from the registry (e.g., 'default', 'legal_advisor').
+     * @property {string} [tag]
+     */
+    tag?: string;
+    /**
+     * Variables to substitute in the selected template.
+     * @property {Record<string, any>} [variables]
+     */
+    variables?: Record<string, any>;
+    /**
+     * Freeform content to apply directly (escape hatch).
+     * @property {string} [content]
+     */
+    content?: string;
+    /**
+     * Merge behavior against previous level: append | prepend.
+     * @property {SystemPromptMergeStrategy} [strategy]
+     */
+    strategy?: SystemPromptMergeStrategy;
 }
 /**
  * Represents a parsed request from the LLM to call a specific tool.
+ *
+ * @interface ParsedToolCall
  */
 interface ParsedToolCall {
-    /** A unique identifier generated by the OutputParser for this specific tool call request within a plan. */
+    /**
+     * A unique identifier generated by the OutputParser for this specific tool call request within a plan.
+     * @property {string} callId
+     */
     callId: string;
-    /** The name of the tool the LLM intends to call. Must match a registered tool's schema name. */
+    /**
+     * The name of the tool the LLM intends to call. Must match a registered tool's schema name.
+     * @property {string} toolName
+     */
     toolName: string;
-    /** The arguments object, parsed from the LLM response, intended to be passed to the tool's `execute` method after validation. */
+    /**
+     * The arguments object, parsed from the LLM response, intended to be passed to the tool's `execute` method after validation.
+     * @property {any} arguments
+     */
     arguments: any;
 }
 /**
  * Configuration specific to a conversation thread.
+ *
+ * @interface ThreadConfig
  */
 interface ThreadConfig {
-    /** Default provider configuration for this thread. */
+    /**
+     * Default provider configuration for this thread.
+     * @property {RuntimeProviderConfig} providerConfig
+     */
     providerConfig: RuntimeProviderConfig;
-    /** An array of tool names (matching `ToolSchema.name`) that are permitted for use within this thread. */
+    /**
+     * An array of tool names (matching `ToolSchema.name`) that are permitted for use within this thread.
+     * @property {string[]} enabledTools
+     */
     enabledTools: string[];
-    /** The maximum number of past messages (`ConversationMessage` objects) to retrieve for context. */
+    /**
+     * The maximum number of past messages (`ConversationMessage` objects) to retrieve for context.
+     * @property {number} historyLimit
+     */
     historyLimit: number;
-    /** Optional system prompt string to be used for this thread, overriding instance or agent defaults. */
-    systemPrompt?: string;
+    /**
+     * Optional system prompt override to be used for this thread, overriding instance or agent defaults.
+     * @property {string | SystemPromptOverride} [systemPrompt]
+     */
+    systemPrompt?: string | SystemPromptOverride;
+    /**
+     * Optional: Defines the identity and high-level guidance for the agent for this specific thread.
+     * This overrides the instance-level persona.
+     * @property {Partial<AgentPersona>} [persona]
+     */
+    persona?: Partial<AgentPersona>;
 }
 /**
  * Represents non-configuration state associated with an agent or thread.
  * Could include user preferences, accumulated knowledge, etc. (Less defined for v1.0)
+ *
+ * @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.
+     * @property {any} data
+     */
     data: any;
-    /** An optional version number for the agent's state, useful for migrations or tracking changes. */
+    /**
+     * An optional version number for the agent's state, useful for migrations or tracking changes.
+     * @property {number} [version]
+     */
     version?: number;
-    /** Allows for other arbitrary properties to be stored in the agent's state. */
+    /**
+     * Allows for other arbitrary properties to be stored in the agent's state.
+     * @property {any} [key: string]
+     */
     [key: string]: any;
 }
 /**
  * Encapsulates the configuration and state for a specific thread.
+ *
+ * @interface ThreadContext
  */
 interface ThreadContext {
-    /** The configuration settings (`ThreadConfig`) currently active for the thread. */
+    /**
+     * The configuration settings (`ThreadConfig`) currently active for the thread.
+     * @property {ThreadConfig} config
+     */
     config: ThreadConfig;
-    /** The persistent state (`AgentState`) associated with the thread, or `null` if no state exists. */
+    /**
+     * The persistent state (`AgentState`) associated with the thread, or `null` if no state exists.
+     * @property {AgentState | null} state
+     */
     state: AgentState | null;
 }
 /**
  * Properties required to initiate an agent processing cycle.
+ *
+ * @interface AgentProps
  */
 interface AgentProps {
-    /** The user's input query or request to the agent. */
+    /**
+     * The user's input query or request to the agent.
+     * @property {string} query
+     */
     query: string;
-    /** The mandatory identifier for the conversation thread. All context is scoped to this ID. */
+    /**
+     * The mandatory identifier for the conversation thread. All context is scoped to this ID.
+     * @property {string} threadId
+     */
     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.
+     * @property {string} [sessionId]
+     */
     sessionId?: string;
-    /** An optional identifier for the user interacting with the agent. */
+    /**
+     * An optional identifier for the user interacting with the agent.
+     * @property {string} [userId]
+     */
     userId?: string;
-    /** An optional identifier used for tracing a request across multiple systems or services. */
+    /**
+     * An optional identifier used for tracing a request across multiple systems or services.
+     * @property {string} [traceId]
+     */
     traceId?: string;
-    /** Optional runtime options that can override default behaviors for this specific `process` call. */
+    /**
+     * Optional runtime options that can override default behaviors for this specific `process` call.
+     * @property {AgentOptions} [options]
+     */
     options?: AgentOptions;
 }
 /**
  * Options to override agent behavior at runtime.
+ *
+ * @interface AgentOptions
  */
 interface AgentOptions {
-    /** Override specific LLM parameters (e.g., temperature, max_tokens) for this call only. */
+    /**
+     * Override specific LLM parameters (e.g., temperature, max_tokens) for this call only.
+     * @property {Record<string, any>} [llmParams]
+     */
     llmParams?: Record<string, any>;
-    /** Override provider configuration for this specific call. */
+    /**
+     * Override provider configuration for this specific call.
+     * @property {RuntimeProviderConfig} [providerConfig]
+     */
     providerConfig?: RuntimeProviderConfig;
-    /** Force the use of specific tools, potentially overriding the thread's `enabledTools` for this call (use with caution). */
+    /**
+     * Force the use of specific tools, potentially overriding the thread's `enabledTools` for this call (use with caution).
+     * @property {string[]} [forceTools]
+     */
     forceTools?: string[];
-    /** Specify a particular reasoning model to use for this call, overriding the thread's default. */
+    /**
+     * Specify a particular reasoning model to use for this call, overriding the thread's default.
+     * @property {{ provider: string; model: string }} [overrideModel]
+     */
     overrideModel?: {
         provider: string;
         model: string;
     };
-    /** Request a streaming response for this specific agent process call. */
+    /**
+     * Request a streaming response for this specific agent process call.
+     * @property {boolean} [stream]
+     */
     stream?: boolean;
-    /** Override the prompt template used for this specific call. */
+    /**
+     * Override the prompt template used for this specific call.
+     * @property {string} [promptTemplateId]
+     */
     promptTemplateId?: string;
-    /** Optional system prompt string to override thread, instance, or agent defaults for this specific call. */
-    systemPrompt?: string;
+    /**
+     * Optional system prompt override/tag to override thread, instance, or agent defaults for this specific call.
+     * @property {string | SystemPromptOverride} [systemPrompt]
+     */
+    systemPrompt?: string | SystemPromptOverride;
+    /**
+     * Optional: Defines the identity and high-level guidance for the agent for this specific call.
+     * This overrides both the instance-level and thread-level persona.
+     * @property {Partial<AgentPersona>} [persona]
+     */
+    persona?: Partial<AgentPersona>;
 }
 /**
  * The final structured response returned by the agent core after processing.
+ *
+ * @interface AgentFinalResponse
  */
 interface AgentFinalResponse {
-    /** The final `ConversationMessage` generated by the AI, which has also been persisted. */
+    /**
+     * The final `ConversationMessage` generated by the AI, which has also been persisted.
+     * @property {ConversationMessage} response
+     */
     response: ConversationMessage;
-    /** Metadata summarizing the execution cycle that produced this response. */
+    /**
+     * Metadata summarizing the execution cycle that produced this response.
+     * @property {ExecutionMetadata} metadata
+     */
     metadata: ExecutionMetadata;
 }
 /**
  * Metadata summarizing an agent execution cycle, including performance metrics and outcomes.
+ *
+ * @interface ExecutionMetadata
  */
 interface ExecutionMetadata {
-    /** The thread ID associated with this execution cycle. */
+    /**
+     * The thread ID associated with this execution cycle.
+     * @property {string} threadId
+     */
     threadId: string;
-    /** The trace ID used during this execution, if provided. */
+    /**
+     * The trace ID used during this execution, if provided.
+     * @property {string} [traceId]
+     */
     traceId?: string;
-    /** The user ID associated with the execution, if provided. */
+    /**
+     * The user ID associated with the execution, if provided.
+     * @property {string} [userId]
+     */
     userId?: string;
-    /** The overall status of the execution ('success', 'error', or 'partial' if some steps failed but a response was generated). */
+    /**
+     * The overall status of the execution ('success', 'error', or 'partial' if some steps failed but a response was generated).
+     * @property {'success' | 'error' | 'partial'} status
+     */
     status: 'success' | 'error' | 'partial';
-    /** The total duration of the `agent.process()` call in milliseconds. */
+    /**
+     * The total duration of the `agent.process()` call in milliseconds.
+     * @property {number} totalDurationMs
+     */
     totalDurationMs: number;
-    /** The number of calls made to the `ReasoningEngine`. */
+    /**
+     * The number of calls made to the `ReasoningEngine`.
+     * @property {number} llmCalls
+     */
     llmCalls: number;
-    /** The number of tool execution attempts made by the `ToolSystem`. */
+    /**
+     * The number of tool execution attempts made by the `ToolSystem`.
+     * @property {number} toolCalls
+     */
     toolCalls: number;
-    /** An optional estimated cost for the LLM calls made during this execution. */
+    /**
+     * An optional estimated cost for the LLM calls made during this execution.
+     * @property {number} [llmCost]
+     */
     llmCost?: number;
-    /** A top-level error message if the overall status is 'error' or 'partial'. */
+    /**
+     * A top-level error message if the overall status is 'error' or 'partial'.
+     * @property {string} [error]
+     */
     error?: string;
-    /** Aggregated metadata from LLM calls made during the execution. */
+    /**
+     * Aggregated metadata from LLM calls made during the execution.
+     * @property {LLMMetadata} [llmMetadata]
+     */
     llmMetadata?: LLMMetadata;
 }
 /**
  * Context provided to a tool during its execution.
+ *
+ * @interface ExecutionContext
  */
 interface ExecutionContext {
-    /** The ID of the thread in which the tool is being executed. */
+    /**
+     * The ID of the thread in which the tool is being executed.
+     * @property {string} threadId
+     */
     threadId: string;
-    /** The trace ID for this execution cycle, if available. */
+    /**
+     * The trace ID for this execution cycle, if available.
+     * @property {string} [traceId]
+     */
     traceId?: string;
-    /** The user ID associated with the execution, if available. */
+    /**
+     * The user ID associated with the execution, if available.
+     * @property {string} [userId]
+     */
     userId?: string;
 }
 /**
  * Options for configuring an LLM call, including streaming and context information.
+ *
+ * @interface CallOptions
  */
 interface CallOptions {
-    /** The mandatory thread ID, used by the ReasoningEngine to fetch thread-specific configuration (e.g., model, params) via StateManager. */
+    /**
+     * The mandatory thread ID, used by the ReasoningEngine to fetch thread-specific configuration (e.g., model, params) via StateManager.
+     * @property {string} threadId
+     */
     threadId: string;
-    /** Optional trace ID for correlation. */
+    /**
+     * Optional trace ID for correlation.
+     * @property {string} [traceId]
+     */
     traceId?: string;
-    /** Optional user ID. */
+    /**
+     * Optional user ID.
+     * @property {string} [userId]
+     */
     userId?: string;
-    /** Optional session ID. */
+    /**
+     * Optional session ID.
+     * @property {string} [sessionId]
+     */
     sessionId?: string;
     /**
      * Request a streaming response from the LLM provider.
      * Adapters MUST check this flag.
+     * @property {boolean} [stream]
      */
     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]
      */
     callContext?: 'AGENT_THOUGHT' | 'FINAL_SYNTHESIS' | string;
-    /** An optional callback function invoked when the LLM streams intermediate 'thoughts' or reasoning steps.
+    /**
+     * 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.
      */
-    /** Carries the specific target provider and configuration for this call. */
+    /**
+     * Carries the specific target provider and configuration for this call.
+     * @property {RuntimeProviderConfig} providerConfig
+     */
     providerConfig: RuntimeProviderConfig;
-    /** Additional key-value pairs representing provider-specific parameters (e.g., `temperature`, `max_tokens`, `top_p`). These often override defaults set in `ThreadConfig`. */
+    /**
+     * Additional key-value pairs representing provider-specific parameters (e.g., `temperature`, `max_tokens`, `top_p`). These often override defaults set in `ThreadConfig`.
+     * @property {any} [key: string]
+     */
     [key: string]: any;
 }
 /**
  * Defines the standard roles for messages within the `ArtStandardPrompt` format.
+ *
+ * @remarks
  * These roles are chosen for broad compatibility across major LLM providers (like OpenAI, Anthropic, Gemini).
  * Provider Adapters are responsible for translating these standard roles into the specific formats
  * required by their respective APIs (e.g., 'assistant' might become 'model' for Gemini).
@@ -784,14 +1726,23 @@ interface CallOptions {
  * - `assistant`: Responses generated by the AI model. Can contain text content and/or `tool_calls`.
  * - `tool_request`: Represents the LLM's request to use tools (often implicitly part of an `assistant` message with `tool_calls`). Included for potential future explicit use.
  * - `tool_result`: The outcome (output or error) of executing a requested tool call.
+ *
+ * @typedef {'system' | 'user' | 'assistant' | 'tool_request' | 'tool_result' | 'tool'} ArtStandardMessageRole
  */
 type ArtStandardMessageRole = 'system' | 'user' | 'assistant' | 'tool_request' | 'tool_result' | 'tool';
 /**
  * Represents a single message in the standardized, provider-agnostic `ArtStandardPrompt` format.
+ *
+ * @remarks
  * This structure aims to capture common message elements used by various LLM APIs.
+ *
+ * @interface ArtStandardMessage
  */
 interface ArtStandardMessage {
-    /** The role indicating the source or type of the message. */
+    /**
+     * The role indicating the source or type of the message.
+     * @property {ArtStandardMessageRole} role
+     */
     role: ArtStandardMessageRole;
     /**
      * The primary content of the message. The type and interpretation depend on the `role`:
@@ -800,14 +1751,22 @@ interface ArtStandardMessage {
      * - `assistant`: string | null (The AI's text response, or null/empty if only making `tool_calls`).
      * - `tool_request`: object | null (Structured representation of the tool call, often implicitly handled via `assistant` message's `tool_calls`).
      * - `tool_result`: string (Stringified JSON output or error message from the tool execution).
+     * @property {string | object | null} content
      */
     content: string | object | null;
-    /** Optional name associated with the message. Primarily used for `tool_result` role to specify the name of the tool that was executed. */
+    /**
+     * Optional name associated with the message. Primarily used for `tool_result` role to specify the name of the tool that was executed.
+     * @property {string} [name]
+     */
     name?: string;
     /**
      * Optional array of tool calls requested by the assistant.
+     *
+     * @remarks
      * Only relevant for 'assistant' role messages that trigger tool usage.
      * Structure mirrors common provider formats (e.g., OpenAI).
+     *
+     * @property {Array<{ id: string; type: 'function'; function: { name: string; arguments: string; }; }>} [tool_calls]
      */
     tool_calls?: Array<{
         /** A unique identifier for this specific tool call request. */
@@ -826,170 +1785,839 @@ interface ArtStandardMessage {
      * Optional identifier linking a 'tool_result' message back to the specific 'tool_calls' entry
      * in the preceding 'assistant' message that requested it.
      * Required for 'tool_result' role.
+     * @property {string} [tool_call_id]
+     */
+    tool_call_id?: string;
+}
+/**
+ * Represents the entire prompt as an array of standardized messages (`ArtStandardMessage`).
+ *
+ * @remarks
+ * Constructed by agent logic (e.g., `PESAgent`) and optionally validated via
+ * `PromptManager.validatePrompt` before being sent to the `ReasoningEngine` and
+ * translated by a `ProviderAdapter` for provider-specific API formats.
+ *
+ * @typedef {ArtStandardMessage[]} ArtStandardPrompt
+ */
+type ArtStandardPrompt = ArtStandardMessage[];
+/**
+ * Represents the contextual data gathered by Agent Logic (e.g., `PESAgent`) to be injected
+ * into a Mustache blueprint/template by the `PromptManager.assemblePrompt` method.
+ *
+ * @remarks
+ * Contains standard fields commonly needed for prompts, plus allows for arbitrary
+ * additional properties required by specific agent blueprints. Agent logic is responsible
+ * for populating this context appropriately before calling `assemblePrompt`.
+ *
+ * @interface PromptContext
+ */
+interface PromptContext {
+    /**
+     * The user's current query or input relevant to this prompt generation step.
+     * @property {string} [query]
+     */
+    query?: string;
+    /**
+     * The conversation history, typically formatted as an array suitable for the blueprint
+     * (e.g., array of objects with `role` and `content`). Agent logic should pre-format this.
+     *
+     * @remarks
+     * While `ArtStandardPrompt` could be used, simpler structures might be preferred for blueprints.
+     *
+     * @property {Array<{ role: string; content: string; [key: string]: any }>} [history]
+     */
+    history?: Array<{
+        role: string;
+        content: string;
+        [key: string]: any;
+    }>;
+    /**
+     * The schemas of the tools available for use, potentially pre-formatted for the blueprint
+     * (e.g., with `inputSchemaJson` pre-stringified).
+     * @property {Array<ToolSchema & { inputSchemaJson?: string }>} [availableTools]
+     */
+    availableTools?: Array<ToolSchema & {
+        inputSchemaJson?: string;
+    }>;
+    /**
+     * The results from any tools executed in a previous step, potentially pre-formatted for the blueprint
+     * (e.g., with `outputJson` pre-stringified).
+     * @property {Array<ToolResult & { outputJson?: string }>} [toolResults]
+     */
+    toolResults?: Array<ToolResult & {
+        outputJson?: string;
+    }>;
+    /**
+     * The system prompt string to be used (resolved by agent logic from config or defaults).
+     * @property {string} [systemPrompt]
+     */
+    systemPrompt?: string;
+    /**
+     * Allows agent patterns (like PES) to pass any other custom data needed by their specific blueprints (e.g., `intent`, `plan`).
+     * @property {any} [key: string]
+     */
+    [key: string]: any;
+}
+/**
+ * Represents a Mustache template that can be rendered with a PromptContext to produce an ArtStandardPrompt.
+ * Used by the PromptManager.assemblePrompt method.
+ *
+ * @interface PromptBlueprint
+ */
+interface PromptBlueprint {
+    /**
+     * The Mustache template string that will be rendered with context data to produce a JSON string representing an ArtStandardPrompt
+     * @property {string} template
+     */
+    template: string;
+}
+/**
+ * Represents the prompt data formatted for a specific LLM provider.
+ * Can be a simple string or a complex object (e.g., for OpenAI Chat Completion API).
+ *
+ * @deprecated Use `ArtStandardPrompt` as the standard intermediate format. ProviderAdapters handle final formatting.
+ * @typedef {ArtStandardPrompt} FormattedPrompt
+ */
+type FormattedPrompt = ArtStandardPrompt;
+/**
+ * Options for filtering data retrieved from storage.
+ * Structure depends heavily on the underlying adapter's capabilities.
+ *
+ * @interface FilterOptions
+ */
+interface FilterOptions {
+    /**
+     * An object defining filter criteria (e.g., `{ threadId: 'abc', type: 'TOOL_EXECUTION' }`). Structure may depend on adapter capabilities.
+     * @property {Record<string, any>} [filter]
+     */
+    filter?: Record<string, any>;
+    /**
+     * An object defining sorting criteria (e.g., `{ timestamp: 'desc' }`).
+     * @property {Record<string, 'asc' | 'desc'>} [sort]
+     */
+    sort?: Record<string, 'asc' | 'desc'>;
+    /**
+     * The maximum number of records to return.
+     * @property {number} [limit]
+     */
+    limit?: number;
+    /**
+     * The number of records to skip (for pagination).
+     * @property {number} [skip]
+     */
+    skip?: number;
+}
+/**
+ * Options for retrieving conversation messages.
+ *
+ * @interface MessageOptions
+ */
+interface MessageOptions {
+    /**
+     * The maximum number of messages to retrieve.
+     * @property {number} [limit]
+     */
+    limit?: number;
+    /**
+     * Retrieve messages created before this Unix timestamp (milliseconds).
+     * @property {number} [beforeTimestamp]
+     */
+    beforeTimestamp?: number;
+    /**
+     * Retrieve messages created after this Unix timestamp (milliseconds).
+     * @property {number} [afterTimestamp]
+     */
+    afterTimestamp?: number;
+    /**
+     * Optionally filter messages by role (e.g., retrieve only 'AI' messages).
+     * @property {MessageRole[]} [roles]
+     */
+    roles?: MessageRole[];
+}
+/**
+ * Options for filtering observations.
+ *
+ * @interface ObservationFilter
+ */
+interface ObservationFilter {
+    /**
+     * An array of `ObservationType` enums to filter by. If provided, only observations matching these types are returned.
+     * @property {ObservationType[]} [types]
+     */
+    types?: ObservationType[];
+    /**
+     * Retrieve observations recorded before this Unix timestamp (milliseconds).
+     * @property {number} [beforeTimestamp]
+     */
+    beforeTimestamp?: number;
+    /**
+     * Retrieve observations recorded after this Unix timestamp (milliseconds).
+     * @property {number} [afterTimestamp]
+     */
+    afterTimestamp?: number;
+}
+/**
+ * Defines the strategy for saving AgentState.
+ *
+ * @remarks
+ * - 'explicit': AgentState is only saved when `StateManager.setAgentState()` is explicitly called by the agent.
+ *               `StateManager.saveStateIfModified()` will be a no-op for AgentState persistence.
+ * - 'implicit': AgentState is loaded by `StateManager.loadThreadContext()`, and if modified by the agent,
+ *               `StateManager.saveStateIfModified()` will attempt to automatically persist these changes
+ *               by comparing the current state with a snapshot taken at load time.
+ *               `StateManager.setAgentState()` will still work for explicit saves.
+ *
+ * @typedef {'explicit' | 'implicit'} StateSavingStrategy
+ */
+type StateSavingStrategy = 'explicit' | 'implicit';
+
+/**
+ * Configuration for creating an ART instance.
+ *
+ * @interface ArtInstanceConfig
+ */
+interface ArtInstanceConfig {
+    /**
+     * Configuration for the storage adapter.
+     * Can be a pre-configured `StorageAdapter` instance,
+     * or an object specifying the type and options for a built-in adapter.
+     *
+     * @example { type: 'indexedDB', dbName: 'MyArtDB' }
+     *
+     * @property {StorageAdapter | { type: 'memory' | 'indexedDB', dbName?: string, version?: number, objectStores?: any[] }} storage
+     */
+    storage: StorageAdapter | {
+        type: 'memory' | 'indexedDB';
+        dbName?: string;
+        version?: number;
+        objectStores?: any[];
+    };
+    /**
+     * Configuration for the ProviderManager, defining available LLM provider adapters.
+     * @property {PMConfig} providers
+     */
+    providers: ProviderManagerConfig;
+    /**
+     * The agent core implementation class to use.
+     * Defaults to `PESAgent` if not provided.
+     *
+     * @example MyCustomAgentClass
+     *
+     * @property {new (dependencies: any) => IAgentCore} [agentCore]
+     */
+    agentCore?: new (dependencies: any) => IAgentCore;
+    /**
+     * An optional array of tool executor instances to register at initialization.
+     * @property {IToolExecutor[]} [tools]
+     */
+    tools?: IToolExecutor[];
+    /**
+     * Defines the strategy for saving `AgentState`. Defaults to 'explicit'.
+     *
+     * @remarks
+     * - 'explicit': `AgentState` is only saved when `StateManager.setAgentState()` is explicitly called by the agent.
+     *               `StateManager.saveStateIfModified()` will be a no-op for `AgentState` persistence.
+     * - 'implicit': `AgentState` is loaded by `StateManager.loadThreadContext()`. If modified by the agent,
+     *               `StateManager.saveStateIfModified()` will attempt to automatically persist these changes.
+     *               `StateManager.setAgentState()` will still work for explicit saves in this mode.
+     *
+     * @property {StateSavingStrategy} [stateSavingStrategy]
+     */
+    stateSavingStrategy?: StateSavingStrategy;
+    /**
+     * Optional configuration for the framework's logger.
+     * @property {{ level?: LogLevel }} [logger]
+     */
+    logger?: {
+        /** Minimum log level to output. Defaults to 'info'. */
+        level?: LogLevel;
+    };
+    /**
+     * Optional: Defines the default identity and high-level guidance for the agent.
+     * This can be overridden at the thread or call level.
+     * @property {AgentPersona} [persona]
+     */
+    persona?: AgentPersona;
+    /**
+     * Optional configuration for MCP (Model Context Protocol) manager.
+     * Enables connection to external MCP servers for dynamic tool loading.
+     * @property {McpManagerConfig} [mcpConfig]
+     */
+    mcpConfig?: McpManagerConfig;
+    /**
+     * Optional configuration for authentication strategies.
+     * Used for secure connections to external services and MCP servers.
+     * @property {object} [authConfig]
+     */
+    authConfig?: {
+        /**
+         * Whether to enable authentication manager. Defaults to false.
+         * @property {boolean} [enabled]
+         */
+        enabled?: boolean;
+        /**
+         * Pre-configured authentication strategies to register at startup.
+         * @property {Array<{ id: string; strategy: any }>} [strategies]
+         */
+        strategies?: Array<{
+            id: string;
+            strategy: any;
+        }>;
+    };
+    /**
+     * Optional: Configuration for A2A services.
+     * @property {object} [a2aConfig]
+     */
+    a2aConfig?: {
+        /**
+         * The endpoint for discovering A2A agents.
+         * @property {string} [discoveryEndpoint]
+         */
+        discoveryEndpoint?: string;
+        /**
+         * The callback URL for receiving A2A task updates.
+         * @property {string} [callbackUrl]
+         */
+        callbackUrl?: string;
+    };
+}
+/**
+ * Represents the possible states of an A2A (Agent-to-Agent) task.
+ *
+ * @enum {string}
+ */
+declare enum A2ATaskStatus {
+    /** Task has been created but not yet assigned to an agent. */
+    PENDING = "PENDING",
+    /** Task has been assigned to an agent and is being processed. */
+    IN_PROGRESS = "IN_PROGRESS",
+    /** Task has been completed successfully. */
+    COMPLETED = "COMPLETED",
+    /** Task has failed during execution. */
+    FAILED = "FAILED",
+    /** Task has been cancelled before completion. */
+    CANCELLED = "CANCELLED",
+    /** Task is waiting for external dependencies or manual intervention. */
+    WAITING = "WAITING",
+    /** Task is being reviewed for quality assurance. */
+    REVIEW = "REVIEW"
+}
+/**
+ * Represents the priority level of an A2A task.
+ *
+ * @enum {string}
+ */
+declare enum A2ATaskPriority {
+    /** Low priority. */
+    LOW = "LOW",
+    /** Medium priority. */
+    MEDIUM = "MEDIUM",
+    /** High priority. */
+    HIGH = "HIGH",
+    /** Urgent priority. */
+    URGENT = "URGENT"
+}
+/**
+ * Represents agent information for A2A task assignment.
+ *
+ * @interface A2AAgentInfo
+ */
+interface A2AAgentInfo {
+    /**
+     * Unique identifier for the agent.
+     * @property {string} agentId
+     */
+    agentId: string;
+    /**
+     * Human-readable name for the agent.
+     * @property {string} agentName
+     */
+    agentName: string;
+    /**
+     * The type or role of the agent (e.g., 'reasoning', 'data-processing', 'synthesis').
+     * @property {string} agentType
+     */
+    agentType: string;
+    /**
+     * Base URL or endpoint for communicating with the agent.
+     * @property {string} [endpoint]
+     */
+    endpoint?: string;
+    /**
+     * Agent capabilities or specializations.
+     * @property {string[]} [capabilities]
+     */
+    capabilities?: string[];
+    /**
+     * Current load or availability status of the agent.
+     * @property {'available' | 'busy' | 'offline'} [status]
+     */
+    status?: 'available' | 'busy' | 'offline';
+    /**
+     * Authentication configuration for communicating with the agent.
+     * @property {object} [authentication]
+     */
+    authentication?: {
+        /**
+         * Type of authentication required.
+         * @property {'bearer' | 'api_key' | 'none'} type
+         */
+        type: 'bearer' | 'api_key' | 'none';
+        /**
+         * Bearer token for authorization (if type is 'bearer').
+         * @property {string} [token]
+         */
+        token?: string;
+        /**
+         * API key for authorization (if type is 'api_key').
+         * @property {string} [apiKey]
+         */
+        apiKey?: string;
+    };
+}
+/**
+ * Represents metadata about A2A task execution.
+ *
+ * @interface A2ATaskMetadata
+ */
+interface A2ATaskMetadata {
+    /**
+     * Timestamp when the task was created (Unix timestamp in milliseconds).
+     * @property {number} createdAt
+     */
+    createdAt: number;
+    /**
+     * Timestamp when the task was last updated (Unix timestamp in milliseconds).
+     * @property {number} updatedAt
+     */
+    updatedAt: number;
+    /**
+     * Timestamp when the task was started (if applicable).
+     * @property {number} [startedAt]
+     */
+    startedAt?: number;
+    /**
+     * Timestamp when the task was completed/failed (if applicable).
+     * @property {number} [completedAt]
+     */
+    completedAt?: number;
+    /**
+     * Timestamp when the task was delegated to a remote agent (if applicable).
+     * @property {number} [delegatedAt]
+     */
+    delegatedAt?: number;
+    /**
+     * Timestamp when the task was last updated (for compatibility).
+     * @property {number} [lastUpdated]
+     */
+    lastUpdated?: number;
+    /**
+     * The user or system that initiated this task.
+     * @property {string} [initiatedBy]
+     */
+    initiatedBy?: string;
+    /**
+     * Correlation ID for tracking related tasks across the system.
+     * @property {string} [correlationId]
+     */
+    correlationId?: string;
+    /**
+     * Number of retry attempts made for this task.
+     * @property {number} [retryCount]
+     */
+    retryCount?: number;
+    /**
+     * Maximum number of retry attempts allowed.
+     * @property {number} [maxRetries]
+     */
+    maxRetries?: number;
+    /**
+     * Timeout duration in milliseconds.
+     * @property {number} [timeoutMs]
+     */
+    timeoutMs?: number;
+    /**
+     * Estimated completion time in milliseconds (if provided by remote agent).
+     * @property {number} [estimatedCompletionMs]
+     */
+    estimatedCompletionMs?: number;
+    /**
+     * Tags or labels for categorizing tasks.
+     * @property {string[]} [tags]
+     */
+    tags?: string[];
+}
+/**
+ * Represents the result of an A2A task execution.
+ *
+ * @interface A2ATaskResult
+ */
+interface A2ATaskResult {
+    /**
+     * Whether the task execution was successful.
+     * @property {boolean} success
+     */
+    success: boolean;
+    /**
+     * The data returned by the task execution.
+     * @property {any} [data]
+     */
+    data?: any;
+    /**
+     * Error message if the task failed.
+     * @property {string} [error]
+     */
+    error?: string;
+    /**
+     * Additional metadata about the execution.
+     * @property {object} [metadata]
+     */
+    metadata?: {
+        sources?: Array<{
+            sourceName: string;
+            url?: string;
+            [key: string]: any;
+        }>;
+        [key: string]: any;
+    };
+    /**
+     * Execution duration in milliseconds.
+     * @property {number} [durationMs]
+     */
+    durationMs?: number;
+}
+/**
+ * Represents a task for Agent-to-Agent (A2A) communication and delegation.
+ * Used for asynchronous task delegation between AI agents in distributed systems.
+ *
+ * @interface A2ATask
+ */
+interface A2ATask {
+    /**
+     * Unique identifier for the task.
+     * @property {string} taskId
+     */
+    taskId: string;
+    /**
+     * The thread this task belongs to (top-level for efficient filtering).
+     * @property {string} threadId
+     */
+    threadId: string;
+    /**
+     * Current status of the task.
+     * @property {A2ATaskStatus} status
+     */
+    status: A2ATaskStatus;
+    /**
+     * The data payload containing task parameters and context.
+     * @property {object} payload
+     */
+    payload: {
+        /**
+         * The type of task to be executed (e.g., 'analyze', 'synthesize', 'transform').
+         * @property {string} taskType
+         */
+        taskType: string;
+        /**
+         * Input data required for task execution.
+         * @property {any} input
+         */
+        input: any;
+        /**
+         * Instructions or configuration for the task.
+         * @property {string} [instructions]
+         */
+        instructions?: string;
+        /**
+         * Additional parameters specific to the task type.
+         * @property {Record<string, any>} [parameters]
+         */
+        parameters?: Record<string, any>;
+    };
+    /**
+     * Information about the agent that created/requested this task.
+     * @property {A2AAgentInfo} sourceAgent
+     */
+    sourceAgent: A2AAgentInfo;
+    /**
+     * Information about the agent assigned to execute this task (if assigned).
+     * @property {A2AAgentInfo} [targetAgent]
+     */
+    targetAgent?: A2AAgentInfo;
+    /**
+     * Task priority level.
+     * @property {A2ATaskPriority} priority
+     */
+    priority: A2ATaskPriority;
+    /**
+     * Task execution metadata.
+     * @property {A2ATaskMetadata} metadata
+     */
+    metadata: A2ATaskMetadata;
+    /**
+     * The result of task execution (if completed).
+     * @property {A2ATaskResult} [result]
+     */
+    result?: A2ATaskResult;
+    /**
+     * Callback URL or identifier for task completion notifications.
+     * @property {string} [callbackUrl]
+     */
+    callbackUrl?: string;
+    /**
+     * Dependencies that must be completed before this task can start.
+     * @property {string[]} [dependencies]
+     */
+    dependencies?: string[];
+}
+/**
+ * Represents a request to create a new A2A task.
+ *
+ * @interface CreateA2ATaskRequest
+ */
+interface CreateA2ATaskRequest {
+    /**
+     * The type of task to be executed.
+     * @property {string} taskType
+     */
+    taskType: string;
+    /**
+     * Input data for the task.
+     * @property {any} input
+     */
+    input: any;
+    /**
+     * Instructions for task execution.
+     * @property {string} [instructions]
+     */
+    instructions?: string;
+    /**
+     * Task parameters.
+     * @property {Record<string, any>} [parameters]
+     */
+    parameters?: Record<string, any>;
+    /**
+     * Task priority.
+     * @property {A2ATaskPriority} [priority]
+     */
+    priority?: A2ATaskPriority;
+    /**
+     * Source agent information.
+     * @property {A2AAgentInfo} sourceAgent
+     */
+    sourceAgent: A2AAgentInfo;
+    /**
+     * Preferred target agent (if any).
+     * @property {A2AAgentInfo} [preferredTargetAgent]
+     */
+    preferredTargetAgent?: A2AAgentInfo;
+    /**
+     * Task dependencies.
+     * @property {string[]} [dependencies]
+     */
+    dependencies?: string[];
+    /**
+     * Callback URL for notifications.
+     * @property {string} [callbackUrl]
+     */
+    callbackUrl?: string;
+    /**
+     * Task timeout in milliseconds.
+     * @property {number} [timeoutMs]
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum retry attempts.
+     * @property {number} [maxRetries]
      */
-    tool_call_id?: string;
+    maxRetries?: number;
+    /**
+     * Task tags.
+     * @property {string[]} [tags]
+     */
+    tags?: string[];
 }
 /**
- * Represents the entire prompt as an array of standardized messages (`ArtStandardMessage`).
- * This is the standard format produced by `PromptManager.assemblePrompt` and consumed
- * by `ProviderAdapter.call` for translation into provider-specific API formats.
- */
-type ArtStandardPrompt = ArtStandardMessage[];
-/**
- * Represents the contextual data gathered by Agent Logic (e.g., `PESAgent`) to be injected
- * into a Mustache blueprint/template by the `PromptManager.assemblePrompt` method.
+ * Represents an update to an existing A2A task.
  *
- * Contains standard fields commonly needed for prompts, plus allows for arbitrary
- * additional properties required by specific agent blueprints. Agent logic is responsible
- * for populating this context appropriately before calling `assemblePrompt`.
+ * @interface UpdateA2ATaskRequest
  */
-interface PromptContext {
-    /** The user's current query or input relevant to this prompt generation step. */
-    query?: string;
+interface UpdateA2ATaskRequest {
     /**
-     * The conversation history, typically formatted as an array suitable for the blueprint
-     * (e.g., array of objects with `role` and `content`). Agent logic should pre-format this.
-     * Note: While `ArtStandardPrompt` could be used, simpler structures might be preferred for blueprints.
+     * Task ID to update.
+     * @property {string} taskId
      */
-    history?: Array<{
-        role: string;
-        content: string;
-        [key: string]: any;
-    }>;
+    taskId: string;
     /**
-     * The schemas of the tools available for use, potentially pre-formatted for the blueprint
-     * (e.g., with `inputSchemaJson` pre-stringified).
+     * New task status (if changing).
+     * @property {A2ATaskStatus} [status]
      */
-    availableTools?: Array<ToolSchema & {
-        inputSchemaJson?: string;
-    }>;
+    status?: A2ATaskStatus;
     /**
-     * The results from any tools executed in a previous step, potentially pre-formatted for the blueprint
-     * (e.g., with `outputJson` pre-stringified).
+     * Target agent assignment (if assigning/reassigning).
+     * @property {A2AAgentInfo} [targetAgent]
      */
-    toolResults?: Array<ToolResult & {
-        outputJson?: string;
-    }>;
-    /** The system prompt string to be used (resolved by agent logic from config or defaults). */
-    systemPrompt?: string;
-    /** Allows agent patterns (like PES) to pass any other custom data needed by their specific blueprints (e.g., `intent`, `plan`). */
-    [key: string]: any;
+    targetAgent?: A2AAgentInfo;
+    /**
+     * Task result (if completing).
+     * @property {A2ATaskResult} [result]
+     */
+    result?: A2ATaskResult;
+    /**
+     * Additional metadata updates.
+     * @property {Partial<A2ATaskMetadata>} [metadata]
+     */
+    metadata?: Partial<A2ATaskMetadata>;
 }
 /**
- * Represents the prompt data formatted for a specific LLM provider.
- * Can be a simple string or a complex object (e.g., for OpenAI Chat Completion API).
- * @deprecated Use `ArtStandardPrompt` as the standard intermediate format. ProviderAdapters handle final formatting.
- */
-type FormattedPrompt = ArtStandardPrompt;
-/**
- * Options for filtering data retrieved from storage.
- * Structure depends heavily on the underlying adapter's capabilities.
+ * Defines the default identity and high-level guidance for an agent.
+ * This is provided at the instance level and can be overridden by thread or call-specific prompts.
+ *
+ * @interface AgentPersona
  */
-interface FilterOptions {
-    /** An object defining filter criteria (e.g., `{ threadId: 'abc', type: 'TOOL_EXECUTION' }`). Structure may depend on adapter capabilities. */
-    filter?: Record<string, any>;
-    /** An object defining sorting criteria (e.g., `{ timestamp: 'desc' }`). */
-    sort?: Record<string, 'asc' | 'desc'>;
-    /** The maximum number of records to return. */
-    limit?: number;
-    /** The number of records to skip (for pagination). */
-    skip?: number;
+interface AgentPersona {
+    /**
+     * The name or identity of the agent (e.g., "Zoi").
+     * This will be used in the synthesis prompt.
+     * @property {string} name
+     */
+    name: string;
+    /**
+     * The default system prompt that provides high-level guidance.
+     * This serves as the base layer in the system prompt resolution hierarchy.
+     * @property {string} defaultSystemPrompt
+     */
+    prompts: StageSpecificPrompts;
 }
 /**
- * Options for retrieving conversation messages.
+ * Defines stage-specific system prompts for planning and synthesis.
+ *
+ * @interface StageSpecificPrompts
  */
-interface MessageOptions {
-    /** The maximum number of messages to retrieve. */
-    limit?: number;
-    /** Retrieve messages created before this Unix timestamp (milliseconds). */
-    beforeTimestamp?: number;
-    /** Retrieve messages created after this Unix timestamp (milliseconds). */
-    afterTimestamp?: number;
-    /** Optionally filter messages by role (e.g., retrieve only 'AI' messages). */
-    roles?: MessageRole[];
+interface StageSpecificPrompts {
+    /**
+     * System prompt to guide the planning phase.
+     * Focuses on reasoning, expertise, and tool selection.
+     * @property {string} [planning]
+     */
+    planning?: string;
+    /**
+     * System prompt to guide the synthesis phase.
+     * Focuses on tone, formatting, and final response structure.
+     * @property {string} [synthesis]
+     */
+    synthesis?: string;
 }
+
 /**
- * Options for filtering observations.
+ * Filter type for A2A task notifications.
+ * Allows filtering by task status, task type, agent, or priority.
  */
-interface ObservationFilter {
-    /** An array of `ObservationType` enums to filter by. If provided, only observations matching these types are returned. */
-    types?: ObservationType[];
-    /** Retrieve observations recorded before this Unix timestamp (milliseconds). */
-    beforeTimestamp?: number;
-    /** Retrieve observations recorded after this Unix timestamp (milliseconds). */
-    afterTimestamp?: number;
+interface A2ATaskFilter {
+    /** Filter by task status (single status or array of statuses) */
+    status?: A2ATaskStatus | A2ATaskStatus[];
+    /** Filter by task type (e.g., 'analyze', 'synthesize', 'transform') */
+    taskType?: string | string[];
+    /** Filter by source agent ID */
+    sourceAgentId?: string;
+    /** Filter by target agent ID */
+    targetAgentId?: string;
+    /** Filter by task priority */
+    priority?: A2ATaskPriority | string;
+    /** Filter by thread ID */
+    threadId?: string;
 }
 /**
- * Defines the strategy for saving AgentState.
- * - 'explicit': AgentState is only saved when `StateManager.setAgentState()` is explicitly called by the agent.
- *               `StateManager.saveStateIfModified()` will be a no-op for AgentState persistence.
- * - 'implicit': AgentState is loaded by `StateManager.loadThreadContext()`, and if modified by the agent,
- *               `StateManager.saveStateIfModified()` will attempt to automatically persist these changes
- *               by comparing the current state with a snapshot taken at load time.
- *               `StateManager.setAgentState()` will still work for explicit saves.
+ * Event data structure for A2A task updates.
+ * Contains the updated task and metadata about the change.
  */
-type StateSavingStrategy = 'explicit' | 'implicit';
-
+interface A2ATaskEvent {
+    /** The A2A task that was updated */
+    task: A2ATask;
+    /** The type of event that occurred */
+    eventType: 'created' | 'updated' | 'completed' | 'failed' | 'cancelled' | 'status_changed' | 'delegated';
+    /** Timestamp when the event occurred */
+    timestamp: number;
+    /** Previous status (if applicable) for status change events */
+    previousStatus?: A2ATaskStatus;
+    /** Additional metadata about the event */
+    metadata?: {
+        /** Whether this was an automatic update or manual */
+        automatic?: boolean;
+        /** The component that triggered the update */
+        source?: string;
+        /** Any additional context */
+        context?: Record<string, any>;
+    };
+}
 /**
- * Configuration for creating an ART instance.
+ * A specialized TypedSocket for handling A2A task status updates and events.
+ * Allows filtering by task status, type, agent, and other criteria.
+ * Can optionally fetch historical task data from a repository.
  */
-interface ArtInstanceConfig {
+declare class A2ATaskSocket extends TypedSocket<A2ATaskEvent, A2ATaskFilter> {
+    private taskRepository?;
+    constructor(taskRepository?: IA2ATaskRepository);
     /**
-     * Configuration for the storage adapter.
-     * Can be a pre-configured `StorageAdapter` instance,
-     * or an object specifying the type and options for a built-in adapter.
-     * Example: `{ type: 'indexedDB', dbName: 'MyArtDB' }`
+     * Notifies subscribers about a new A2A task event.
+     * @param event - The A2A task event data.
      */
-    storage: StorageAdapter | {
-        type: 'memory' | 'indexedDB';
-        dbName?: string;
-        version?: number;
-        objectStores?: any[];
-    };
-    /** Configuration for the ProviderManager, defining available LLM provider adapters. */
-    providers: ProviderManagerConfig;
+    notifyTaskEvent(event: A2ATaskEvent): void;
     /**
-     * The agent core implementation class to use.
-     * Defaults to `PESAgent` if not provided.
-     * Example: `MyCustomAgentClass`
+     * Convenience method to notify about a task creation.
+     * @param task - The newly created A2A task.
+     * @param metadata - Optional additional metadata about the creation.
      */
-    agentCore?: new (dependencies: any) => IAgentCore;
-    /** An optional array of tool executor instances to register at initialization. */
-    tools?: IToolExecutor[];
+    notifyTaskCreated(task: A2ATask, metadata?: A2ATaskEvent['metadata']): void;
     /**
-     * Defines the strategy for saving `AgentState`. Defaults to 'explicit'.
-     * - 'explicit': `AgentState` is only saved when `StateManager.setAgentState()` is explicitly called by the agent.
-     *               `StateManager.saveStateIfModified()` will be a no-op for `AgentState` persistence.
-     * - 'implicit': `AgentState` is loaded by `StateManager.loadThreadContext()`. If modified by the agent,
-     *               `StateManager.saveStateIfModified()` will attempt to automatically persist these changes.
-     *               `StateManager.setAgentState()` will still work for explicit saves in this mode.
+     * Convenience method to notify about a task update.
+     * @param task - The updated A2A task.
+     * @param previousStatus - The previous status of the task (if status changed).
+     * @param metadata - Optional additional metadata about the update.
      */
-    stateSavingStrategy?: StateSavingStrategy;
-    /** Optional configuration for the framework's logger. */
-    logger?: {
-        /** Minimum log level to output. Defaults to 'info'. */
-        level?: LogLevel;
-    };
+    notifyTaskUpdated(task: A2ATask, previousStatus?: A2ATaskStatus, metadata?: A2ATaskEvent['metadata']): void;
     /**
-     * Optional default system prompt string to be used for the entire ART instance.
-     * This can be overridden at the thread level or at the individual call level.
+     * Convenience method to notify about task delegation.
+     * @param task - The delegated A2A task.
+     * @param metadata - Optional additional metadata about the delegation.
      */
-    defaultSystemPrompt?: string;
-}
-
-type StreamEventTypeFilter = StreamEvent['type'] | Array<StreamEvent['type']>;
-/**
- * A dedicated socket for broadcasting LLM stream events (`StreamEvent`) to UI subscribers.
- * Extends the generic TypedSocket and implements filtering based on `StreamEvent.type`.
- */
-declare class LLMStreamSocket extends TypedSocket<StreamEvent, StreamEventTypeFilter> {
-    constructor();
+    notifyTaskDelegated(task: A2ATask, metadata?: A2ATaskEvent['metadata']): void;
     /**
-     * Notifies subscribers about a new LLM stream event.
-     * Filters based on event type if a filter is provided during subscription.
-     * @param event - The StreamEvent data.
+     * Convenience method to notify about task completion.
+     * @param task - The completed A2A task.
+     * @param metadata - Optional additional metadata about the completion.
      */
-    notifyStreamEvent(event: StreamEvent): void;
+    notifyTaskCompleted(task: A2ATask, metadata?: A2ATaskEvent['metadata']): void;
+    /**
+     * Convenience method to notify about task failure.
+     * @param task - The failed A2A task.
+     * @param metadata - Optional additional metadata about the failure.
+     */
+    notifyTaskFailed(task: A2ATask, metadata?: A2ATaskEvent['metadata']): void;
+    /**
+     * Retrieves historical A2A task events, optionally filtered by criteria.
+     * Note: This method constructs events from stored tasks, not from a dedicated event log.
+     * @param filter - Optional A2ATaskFilter to filter the tasks.
+     * @param options - Optional threadId and limit.
+     * @returns A promise resolving to an array of A2A task events.
+     */
+    getHistory(filter?: A2ATaskFilter, options?: {
+        threadId?: string;
+        limit?: number;
+    }): Promise<A2ATaskEvent[]>;
+    /**
+     * Converts an A2ATask to an A2ATaskEvent for historical data.
+     * @param task - The A2ATask to convert.
+     * @returns An A2ATaskEvent representing the current state of the task.
+     */
+    private taskToEvent;
+    /**
+     * Checks if an A2A task event matches the specified filter criteria.
+     * @param event - The A2A task event to check.
+     * @param filter - The filter criteria (optional).
+     * @returns True if the event matches the filter, false otherwise.
+     */
+    private matchesFilter;
 }
 
 /**
@@ -997,7 +2625,7 @@ declare class LLMStreamSocket extends TypedSocket<StreamEvent, StreamEventTypeFi
  * Allows filtering by ObservationType.
  * Can optionally fetch historical observations from a repository.
  */
-declare class ObservationSocket$1 extends TypedSocket<Observation, ObservationType | ObservationType[]> {
+declare class ObservationSocket extends TypedSocket<Observation, ObservationType | ObservationType[]> {
     private observationRepository?;
     constructor(observationRepository?: IObservationRepository);
     /**
@@ -1023,7 +2651,7 @@ declare class ObservationSocket$1 extends TypedSocket<Observation, ObservationTy
  * Allows filtering by MessageRole.
  * Can optionally fetch historical messages from a repository.
  */
-declare class ConversationSocket$1 extends TypedSocket<ConversationMessage, MessageRole | MessageRole[]> {
+declare class ConversationSocket extends TypedSocket<ConversationMessage, MessageRole | MessageRole[]> {
     private conversationRepository?;
     constructor(conversationRepository?: IConversationRepository);
     /**
@@ -1044,6 +2672,78 @@ declare class ConversationSocket$1 extends TypedSocket<ConversationMessage, Mess
     }): Promise<ConversationMessage[]>;
 }
 
+/**
+ * Central authentication manager for handling multiple authentication strategies.
+ * Manages registration and retrieval of different auth strategies for secure connections
+ * to remote services like MCP servers and A2A agents.
+ */
+declare class AuthManager {
+    private strategies;
+    constructor();
+    /**
+     * Registers an authentication strategy with the given ID.
+     * @param strategyId - Unique identifier for the strategy (e.g., 'default_zyntopia_auth', 'api_key_strategy')
+     * @param strategy - Implementation of IAuthStrategy
+     * @throws {ARTError} If strategyId is empty or null
+     */
+    registerStrategy(strategyId: string, strategy: IAuthStrategy): void;
+    /**
+     * Retrieves authentication headers from the specified strategy.
+     * @param strategyId - The ID of the registered strategy to use
+     * @returns Promise resolving to authentication headers
+     * @throws {ARTError} If strategy is not found or authentication fails
+     */
+    getHeaders(strategyId: string): Promise<Record<string, string>>;
+    /**
+     * Checks if a strategy with the given ID is registered.
+     * @param strategyId - The ID to check
+     * @returns True if the strategy exists, false otherwise
+     */
+    hasStrategy(strategyId: string): boolean;
+    /**
+     * Lists all registered strategy IDs.
+     * @returns Array of registered strategy IDs
+     */
+    getRegisteredStrategyIds(): string[];
+    /**
+     * Removes a registered strategy.
+     * @param strategyId - The ID of the strategy to remove
+     * @returns True if strategy was removed, false if it didn't exist
+     */
+    removeStrategy(strategyId: string): boolean;
+    /**
+     * Clears all registered strategies.
+     * Useful for testing or complete reconfiguration.
+     */
+    clearAllStrategies(): void;
+    /**
+     * Initiates the login flow for a specific strategy.
+     * @param {string} strategyId - The ID of the strategy to use for login.
+     * @returns {Promise<void>} A promise that resolves when the login process is initiated.
+     * @throws {ARTError} If the strategy is not found or does not support login.
+     */
+    login(strategyId: string): Promise<void>;
+    /**
+     * Handles the redirect from an OAuth provider.
+     * @param {string} strategyId - The ID of the strategy that initiated the redirect.
+     * @returns {Promise<void>} A promise that resolves when the redirect has been handled.
+     * @throws {ARTError} If the strategy is not found or does not support handling redirects.
+     */
+    handleRedirect(strategyId: string): Promise<void>;
+    /**
+     * Logs the user out of a specific strategy.
+     * @param {string} strategyId - The ID of the strategy to use for logout.
+     * @throws {ARTError} If the strategy is not found or does not support logout.
+     */
+    logout(strategyId: string): void;
+    /**
+     * Checks if the user is authenticated with a specific strategy.
+     * @param {string} strategyId - The ID of the strategy to check.
+     * @returns {Promise<boolean>} A promise that resolves to true if authenticated, false otherwise.
+     */
+    isAuthenticated(strategyId: string): Promise<boolean>;
+}
+
 /**
  * Interface for the central agent orchestrator.
  */
@@ -1100,6 +2800,28 @@ interface PromptManager {
      * @throws {ZodError} If validation fails (can be caught and wrapped in ARTError).
      */
     validatePrompt(prompt: ArtStandardPrompt): ArtStandardPrompt;
+    /**
+     * Assembles a prompt using a Mustache template (blueprint) and context data.
+     * Renders the template with the provided context and parses the result as an ArtStandardPrompt.
+     *
+     * @param blueprint - The Mustache template containing the prompt structure.
+     * @param context - The context data to inject into the template.
+     * @returns A promise resolving to the assembled ArtStandardPrompt.
+     * @throws {ARTError} If template rendering or JSON parsing fails.
+     */
+    assemblePrompt(blueprint: PromptBlueprint, context: PromptContext): Promise<ArtStandardPrompt>;
+}
+/**
+ * Resolves the final system prompt from base + instance/thread/call overrides
+ * using tag+variables and merge strategies.
+ */
+interface SystemPromptResolver {
+    resolve(input: {
+        base: string;
+        instance?: string | SystemPromptOverride;
+        thread?: string | SystemPromptOverride;
+        call?: string | SystemPromptOverride;
+    }, traceId?: string): Promise<string>;
 }
 /**
  * Interface for parsing structured output from LLM responses.
@@ -1174,6 +2896,16 @@ interface ToolRegistry {
     getAvailableTools(filter?: {
         enabledForThreadId?: string;
     }): Promise<ToolSchema[]>;
+    /**
+     * Unregisters a tool by its unique name.
+     * Implementations should silently succeed if the tool does not exist.
+     */
+    unregisterTool?(toolName: string): Promise<void>;
+    /**
+     * Unregisters multiple tools that match a predicate. Returns the number of tools removed.
+     * This is useful for removing all tools belonging to a specific MCP server by name prefix.
+     */
+    unregisterTools?(predicate: (schema: ToolSchema) => boolean): Promise<number>;
 }
 /**
  * Interface for the system responsible for orchestrating tool execution.
@@ -1245,6 +2977,34 @@ interface StateManager {
      * @throws {ARTError} If no ThreadConfig exists for the threadId, or if the repository fails.
      */
     setAgentState(threadId: string, state: AgentState): Promise<void>;
+    /**
+     * Enables specific tools for a conversation thread by adding them to the thread's enabled tools list.
+     * This method loads the current thread configuration, updates the enabledTools array,
+     * and persists the changes. Cache is invalidated to ensure fresh data on next load.
+     * @param threadId - The unique identifier of the thread.
+     * @param toolNames - Array of tool names to enable for this thread.
+     * @returns A promise that resolves when the tools are enabled and configuration is saved.
+     * @throws {ARTError} If no ThreadConfig exists for the threadId, or if the repository fails.
+     */
+    enableToolsForThread(threadId: string, toolNames: string[]): Promise<void>;
+    /**
+     * Disables specific tools for a conversation thread by removing them from the thread's enabled tools list.
+     * This method loads the current thread configuration, updates the enabledTools array,
+     * and persists the changes. Cache is invalidated to ensure fresh data on next load.
+     * @param threadId - The unique identifier of the thread.
+     * @param toolNames - Array of tool names to disable for this thread.
+     * @returns A promise that resolves when the tools are disabled and configuration is saved.
+     * @throws {ARTError} If no ThreadConfig exists for the threadId, or if the repository fails.
+     */
+    disableToolsForThread(threadId: string, toolNames: string[]): Promise<void>;
+    /**
+     * Gets the list of currently enabled tools for a specific thread.
+     * This is a convenience method that loads the thread context and returns the enabledTools array.
+     * @param threadId - The unique identifier of the thread.
+     * @returns A promise that resolves to an array of enabled tool names, or empty array if no tools are enabled.
+     * @throws {ARTError} If the thread context cannot be loaded.
+     */
+    getEnabledToolsForThread(threadId: string): Promise<string[]>;
 }
 /**
  * Interface for managing conversation history.
@@ -1319,29 +3079,18 @@ interface ITypedSocket<DataType, FilterType = any> {
         limit?: number;
     }): Promise<DataType[]>;
 }
-/**
- * TypedSocket specifically for Observation data.
- * FilterType is ObservationType or array of ObservationType.
- */
-interface ObservationSocket extends ITypedSocket<Observation, ObservationType | ObservationType[]> {
-}
-/**
- * TypedSocket specifically for ConversationMessage data.
- * FilterType is MessageRole or array of MessageRole.
- */
-interface ConversationSocket extends ITypedSocket<ConversationMessage, MessageRole | MessageRole[]> {
-}
-
 /**
  * Interface for the system providing access to UI communication sockets.
  */
 interface UISystem {
     /** Returns the singleton instance of the ObservationSocket. */
-    getObservationSocket(): ObservationSocket$1;
+    getObservationSocket(): ObservationSocket;
     /** Returns the singleton instance of the ConversationSocket. */
-    getConversationSocket(): ConversationSocket$1;
+    getConversationSocket(): ConversationSocket;
     /** Returns the singleton instance of the LLMStreamSocket. */
     getLLMStreamSocket(): LLMStreamSocket;
+    /** Returns the singleton instance of the A2ATaskSocket. */
+    getA2ATaskSocket(): A2ATaskSocket;
 }
 /**
  * Interface for a storage adapter, providing a generic persistence layer.
@@ -1401,10 +3150,92 @@ interface IStateRepository {
     setThreadContext(threadId: string, context: ThreadContext): Promise<void>;
 }
 /**
- * Represents the fully initialized and configured ART Framework client instance.
- * This object is the main entry point for interacting with the framework after setup.
- * It provides access to the core processing method and key subsystems.
+ * Interface for managing A2A (Agent-to-Agent) task persistence and retrieval.
+ */
+interface IA2ATaskRepository {
+    /**
+     * Creates a new A2A task in the repository.
+     * @param task - The A2ATask object to create.
+     * @returns A promise that resolves when the task is successfully stored.
+     * @throws {ARTError} If the task cannot be created (e.g., duplicate taskId, validation errors).
+     */
+    createTask(task: A2ATask): Promise<void>;
+    /**
+     * Retrieves an A2A task by its unique identifier.
+     * @param taskId - The unique identifier of the task.
+     * @returns A promise resolving to the A2ATask object if found, or null if not found.
+     * @throws {ARTError} If an error occurs during retrieval.
+     */
+    getTask(taskId: string): Promise<A2ATask | null>;
+    /**
+     * Updates an existing A2A task with new information.
+     * @param taskId - The unique identifier of the task to update.
+     * @param updates - Partial A2ATask object containing the fields to update.
+     * @returns A promise that resolves when the task is successfully updated.
+     * @throws {ARTError} If the task is not found or cannot be updated.
+     */
+    updateTask(taskId: string, updates: Partial<A2ATask>): Promise<void>;
+    /**
+     * Removes an A2A task from the repository.
+     * @param taskId - The unique identifier of the task to delete.
+     * @returns A promise that resolves when the task is successfully deleted.
+     * @throws {ARTError} If the task is not found or cannot be deleted.
+     */
+    deleteTask(taskId: string): Promise<void>;
+    /**
+     * Retrieves tasks associated with a specific thread.
+     * @param threadId - The thread identifier to filter tasks.
+     * @param filter - Optional filter criteria for task status, priority, or assigned agent.
+     * @returns A promise resolving to an array of A2ATask objects matching the criteria.
+     */
+    getTasksByThread(threadId: string, filter?: {
+        status?: A2ATaskStatus | A2ATaskStatus[];
+        priority?: A2ATaskPriority;
+        assignedAgentId?: string;
+    }): Promise<A2ATask[]>;
+    /**
+     * Retrieves tasks assigned to a specific agent.
+     * @param agentId - The agent identifier to filter tasks.
+     * @param filter - Optional filter criteria for task status or priority.
+     * @returns A promise resolving to an array of A2ATask objects assigned to the agent.
+     */
+    getTasksByAgent(agentId: string, filter?: {
+        status?: A2ATaskStatus | A2ATaskStatus[];
+        priority?: A2ATaskPriority;
+    }): Promise<A2ATask[]>;
+    /**
+     * Retrieves tasks based on their current status.
+     * @param status - The task status(es) to filter by.
+     * @param options - Optional query parameters like limit and pagination.
+     * @returns A promise resolving to an array of A2ATask objects with the specified status.
+     */
+    getTasksByStatus(status: A2ATaskStatus | A2ATaskStatus[], options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<A2ATask[]>;
+}
+/**
+ * Interface for an authentication strategy that can provide authorization headers.
+ * This enables pluggable security for remote service connections (MCP servers, A2A agents, etc.)
  */
+interface IAuthStrategy {
+    /**
+     * Asynchronously retrieves the authentication headers.
+     * This might involve checking a cached token, refreshing it if expired, and then returning it.
+     * @returns A promise that resolves to a record of header keys and values.
+     * @throws {ARTError} If authentication fails or cannot be obtained.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /** Optional: Initiates the login flow for the strategy. */
+    login?(): Promise<void>;
+    /** Optional: Handles the redirect from the authentication server. */
+    handleRedirect?(): Promise<void>;
+    /** Optional: Logs the user out. */
+    logout?(): void;
+    /** Optional: Checks if the user is authenticated. */
+    isAuthenticated?(): Promise<boolean>;
+}
+
 interface ArtInstance {
     /** The main method to process a user query using the configured Agent Core. */
     readonly process: IAgentCore['process'];
@@ -1418,6 +3249,206 @@ interface ArtInstance {
     readonly toolRegistry: ToolRegistry;
     /** Accessor for the Observation Manager, used for recording and retrieving observations. */
     readonly observationManager: ObservationManager;
+    /** Accessor for the Auth Manager, used for handling authentication. */
+    readonly authManager?: AuthManager | null;
+}
+
+/**
+ * @class McpClientController
+ * Controls the MCP client, including OAuth flow, connection, and tool calls.
+ */
+declare class McpClientController {
+    baseUrl: URL;
+    private scopes;
+    private client;
+    private transport;
+    private oauthDiscovery;
+    private tokenManager;
+    private sessionId;
+    private readonly protocolVersion;
+    /**
+     * Creates an instance of McpClientController.
+     * @private
+     * @param {string} baseUrl - The base URL of the MCP server.
+     * @param {string[]} [scopes] - The OAuth scopes to request.
+     */
+    private constructor();
+    /**
+     * Creates a new instance of McpClientController.
+     * @param {string} baseUrl - The base URL of the MCP server.
+     * @param {string[]} [scopes] - The OAuth scopes to request.
+     * @returns {McpClientController} A new instance of McpClientController.
+     */
+    static create(baseUrl: string, scopes?: string[]): McpClientController;
+    /**
+     * Discovers the authorization server metadata.
+     * @private
+     * @returns {Promise<void>}
+     */
+    private discoverAuthorizationServer;
+    /**
+     * Registers the client with the authorization server.
+     * @private
+     * @returns {Promise<string>} A promise that resolves to the client ID.
+     */
+    private registerClient;
+    /**
+     * Starts the OAuth flow by redirecting the user to the authorization server.
+     * @returns {Promise<void>}
+     */
+    startOAuth(): Promise<void>;
+    /**
+     * Handles the OAuth callback, exchanging the authorization code for an access token.
+     * @returns {Promise<boolean>} A promise that resolves to true if the callback was handled, false otherwise.
+     */
+    maybeHandleCallback(): Promise<boolean>;
+    /**
+     * Loads an existing session from session storage.
+     */
+    loadExistingSession(): void;
+    /**
+     * Checks if the user is authenticated.
+     * @returns {boolean} True if the user is authenticated, false otherwise.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Connects to the MCP server.
+     * @returns {Promise<void>}
+     */
+    connect(): Promise<void>;
+    /**
+     * Ensures that the client is connected to the MCP server.
+     * @returns {Promise<void>}
+     */
+    ensureConnected(): Promise<void>;
+    /**
+     * Lists the available tools on the MCP server.
+     * @returns {Promise<{ name: string; description?: string }[]>} A promise that resolves to a list of tools.
+     */
+    listTools(): Promise<{
+        name: string;
+        description?: string;
+    }[]>;
+    /**
+     * Calls a tool on the MCP server.
+     * @param {string} name - The name of the tool to call.
+     * @param {any} args - The arguments to pass to the tool.
+     * @returns {Promise<any>} A promise that resolves to the result of the tool call.
+     */
+    callTool(name: string, args: any): Promise<any>;
+    /**
+     * Logs out from the MCP server and clears the session.
+     * @returns {Promise<void>}
+     */
+    logout(): Promise<void>;
+}
+
+/**
+ * Manages MCP (Model Context Protocol) server connections and tool registration.
+ *
+ * @remarks
+ * The `McpManager` is responsible for:
+ * - Connecting to configured MCP servers.
+ * - Discovering available tools from servers.
+ * - Creating proxy tools that wrap MCP server tools.
+ * - Registering proxy tools with the {@link ToolRegistry}.
+ * - Managing server health and status.
+ * - Handling thread-specific tool activation/deactivation.
+ *
+ * This enables dynamic tool loading from external MCP servers while maintaining
+ * seamless integration with the ART Framework's tool system.
+ *
+ * @see {@link McpProxyTool} for the tool wrapper implementation.
+ * @see {@link McpClientController} for the underlying client implementation.
+ *
+ * @class McpManager
+ */
+declare class McpManager {
+    private configManager;
+    private toolRegistry;
+    private authManager?;
+    private activeConnections;
+    /**
+     * Creates an instance of McpManager.
+     *
+     * @param toolRegistry The tool registry to register proxy tools with.
+     * @param _stateManager The state manager (not currently used).
+     * @param authManager The authentication manager.
+     */
+    constructor(toolRegistry: ToolRegistry, _stateManager: StateManager, authManager?: AuthManager);
+    /**
+     * Initializes the McpManager, discovers and registers tools from configured servers.
+     *
+     * @param mcpConfig The MCP configuration.
+     * @param [mcpConfig.enabled=true] Whether MCP is enabled.
+     * @param mcpConfig.discoveryEndpoint The endpoint for discovering MCP servers.
+     * @returns A promise that resolves when initialization is complete.
+     */
+    initialize(mcpConfig?: {
+        enabled?: boolean;
+        discoveryEndpoint?: string;
+    }): Promise<void>;
+    /**
+     * Shuts down all active MCP connections.
+     *
+     * @returns A promise that resolves when all connections are shut down.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Gets an existing connection or creates a new one for a given server ID.
+     *
+     * @param serverId The ID of the server to connect to.
+     * @returns A promise that resolves to the MCP client controller.
+     */
+    getOrCreateConnection(serverId: string): Promise<McpClientController>;
+    /**
+     * Ensures that the application has CORS access to the target URL.
+     *
+     * @private
+     * @param targetUrl The URL to check for CORS access.
+     * @returns A promise that resolves when CORS access is confirmed or granted.
+     */
+    private ensureCorsAccess;
+    /**
+     * Searches a discovery service for available MCP servers.
+     *
+     * @param [discoveryEndpoint] The URL of the discovery service.
+     * @returns A promise resolving to an array of McpServerConfig.
+     */
+    discoverAvailableServers(discoveryEndpoint?: string): Promise<McpServerConfig[]>;
+    /**
+     * Converts a Zyntopia service entry to an McpServerConfig.
+     *
+     * @private
+     * @param service The service entry to convert.
+     * @returns The converted McpServerConfig or null if conversion fails.
+     */
+    private convertServiceToMcpCard;
+    /**
+     * Installs a server by persisting its config, discovering tools via MCP, and
+     * registering proxy tools. Returns the finalized config with accurate tools.
+     *
+     * @param server The server configuration to install.
+     * @returns A promise that resolves to the finalized server configuration.
+     */
+    installServer(server: McpServerConfig): Promise<McpServerConfig>;
+    /**
+     * Waits for the client to be authenticated.
+     *
+     * @private
+     * @param client The MCP client controller.
+     * @param timeoutMs The timeout in milliseconds.
+     * @returns A promise that resolves when the client is authenticated.
+     * @throws {ARTError} If the authentication window times out.
+     */
+    private waitForAuth;
+    /**
+     * Uninstalls a server: disconnects, removes registered proxy tools, and deletes config.
+     *
+     * @param serverId The ID of the server to uninstall.
+     * @returns A promise that resolves when the server is uninstalled.
+     */
+    uninstallServer(serverId: string): Promise<void>;
 }
 
 /**
@@ -1438,9 +3469,199 @@ interface ArtInstance {
 declare function createArtInstance(config: ArtInstanceConfig): Promise<ArtInstance>;
 
 /**
- * Defines the dependencies required by the PESAgent constructor.
- * These are typically provided by the AgentFactory during instantiation.
+ * Configuration for the AgentDiscoveryService
+ */
+interface AgentDiscoveryConfig {
+    /** Base URL for the discovery endpoint. If not provided, a default will be used. */
+    discoveryEndpoint?: string;
+    /** Timeout for discovery requests in milliseconds */
+    timeoutMs?: number;
+    /** Whether to cache discovered agents */
+    enableCaching?: boolean;
+    /** Cache TTL in milliseconds */
+    cacheTtlMs?: number;
+}
+/**
+ * Service for discovering A2A protocol compatible agents.
+ * Implements the A2A discovery standards for finding and identifying compatible agents.
+ */
+declare class AgentDiscoveryService {
+    private readonly config;
+    private agentCache;
+    /**
+     * Creates an instance of AgentDiscoveryService.
+     * @param {Partial<AgentDiscoveryConfig>} config - The configuration for the service.
+     * @see A2AAgentCard
+     */
+    constructor(config?: Partial<AgentDiscoveryConfig>);
+    /**
+     * Discovers all available A2A agents from the discovery endpoint.
+     * @param traceId - Optional trace ID for request tracking
+     * @returns Promise resolving to array of discovered A2A agents
+     * @throws {ARTError} If discovery fails or no agents are found
+     */
+    discoverAgents(traceId?: string): Promise<A2AAgentInfo[]>;
+    /**
+     * Finds the top K A2A agents for a specific task type, ranked by suitability.
+     * This method acts as a pre-filter, returning a list of the most promising candidates
+     * for an LLM to make the final selection from.
+     * @param taskType - The type of task (e.g., 'analysis', 'research', 'generation')
+     * @param topK - The maximum number of agents to return.
+     * @param traceId - Optional trace ID for request tracking.
+     * @returns Promise resolving to a ranked array of matching agents.
+     * @remarks TODO: Revisit and enhance the scoring algorithm.
+     */
+    findTopAgentsForTask(taskType: string, topK?: number, traceId?: string): Promise<A2AAgentInfo[]>;
+    /**
+     * Calculates semantic similarity score between capability and task type.
+     * This uses common word patterns to identify relationships without hardcoded mappings.
+     * @private
+     */
+    private calculateSemanticScore;
+    /**
+     * Finds agents by specific capabilities.
+     * @param capabilities - Array of required capabilities
+     * @param traceId - Optional trace ID for request tracking
+     * @returns Promise resolving to agents that have all specified capabilities
+     */
+    findAgentsByCapabilities(capabilities: string[], traceId?: string): Promise<A2AAgentInfo[]>;
+    /**
+     * Clears the agent cache.
+     */
+    clearCache(): void;
+    /**
+     * Gets cached agents if they exist and are not expired.
+     * @private
+     */
+    private getCachedAgents;
+    /**
+     * Sets agents in cache with current timestamp.
+     * @private
+     */
+    private setCachedAgents;
+    /**
+     * Transforms an A2A Agent Card to the ART framework's A2AAgentInfo format.
+     * @private
+     */
+    private transformToA2AAgentInfo;
+}
+
+/**
+ * Configuration options for the TaskDelegationService
+ */
+interface TaskDelegationConfig {
+    /** Default timeout for task delegation requests in milliseconds */
+    defaultTimeoutMs?: number;
+    /** Maximum number of retry attempts for failed requests */
+    maxRetries?: number;
+    /** Base delay between retry attempts in milliseconds */
+    retryDelayMs?: number;
+    /** Whether to use exponential backoff for retries */
+    useExponentialBackoff?: boolean;
+    /** The base callback URL for receiving A2A task updates. */
+    callbackUrl?: string;
+}
+/**
+ * Response structure for A2A task status queries
  */
+interface TaskStatusResponse {
+    /** The task ID */
+    taskId: string;
+    /** Current status of the task */
+    status: A2ATaskStatus;
+    /** Progress percentage (0-100) if available */
+    progress?: number;
+    /** Task result if completed */
+    result?: A2ATaskResult;
+    /** Error information if failed */
+    error?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Service responsible for delegating A2A tasks to remote agents.
+ * Implements the A2A protocol for task submission, tracking, and completion.
+ *
+ * This service handles:
+ * - Finding suitable agents for specific task types
+ * - Submitting tasks to remote agents via HTTP API
+ * - Tracking task status and handling updates
+ * - Managing task lifecycle according to A2A protocol
+ * - Error handling and retry logic
+ * - Integration with local task repository for persistence
+ */
+declare class TaskDelegationService {
+    private readonly config;
+    private readonly taskRepository;
+    /**
+     * Creates an instance of TaskDelegationService.
+     * @param {IA2ATaskRepository} taskRepository - The repository for persisting task status.
+     * @param {TaskDelegationConfig} [config={}] - Configuration for the service.
+     */
+    constructor(taskRepository: IA2ATaskRepository, config?: TaskDelegationConfig);
+    /**
+     * Delegates a list of A2A tasks to suitable remote agents.
+     * For each task, finds the best agent and submits the task.
+     *
+     * @param {A2ATask[]} tasks - Array of A2A tasks to delegate
+     * @param {string} [traceId] - Optional trace ID for request tracking
+     * @returns {Promise<A2ATask[]>} Promise resolving to array of successfully delegated tasks
+     */
+    delegateTasks(tasks: A2ATask[], traceId?: string): Promise<A2ATask[]>;
+    /**
+     * Delegates a single A2A task to a suitable remote agent.
+     *
+     * @param {A2ATask} task - The A2A task to delegate
+     * @param {string} [traceId] - Optional trace ID for request tracking
+     * @returns {Promise<A2ATask | null>} Promise resolving to the updated task or null if delegation failed
+     */
+    delegateTask(task: A2ATask, traceId?: string): Promise<A2ATask | null>;
+    /**
+     * Submits a task to a specific remote agent using A2A protocol.
+     *
+     * @private
+     * @param {A2ATask} task - The A2A task to submit
+     * @param {A2AAgentInfo} targetAgent - The target agent to submit the task to
+     * @param {string} [traceId] - Optional trace ID for request tracking
+     * @returns {Promise<TaskSubmissionResponse>} Promise resolving to the submission response
+     */
+    private submitTaskToAgent;
+    /**
+     * Checks the status of a delegated task from the remote agent.
+     *
+     * @param {A2ATask} task - The A2A task to check status for
+     * @param {string} [traceId] - Optional trace ID for request tracking
+     * @returns {Promise<TaskStatusResponse | null>} Promise resolving to the current task status
+     */
+    checkTaskStatus(task: A2ATask, traceId?: string): Promise<TaskStatusResponse | null>;
+    /**
+     * Updates a local A2A task based on remote status information.
+     *
+     * @param {A2ATask} task - The local A2A task to update
+     * @param {TaskStatusResponse} statusResponse - The status response from the remote agent
+     * @param {string} [traceId] - Optional trace ID for request tracking
+     * @returns {Promise<A2ATask>} Promise resolving to the updated task
+     */
+    updateTaskFromRemoteStatus(task: A2ATask, statusResponse: TaskStatusResponse, traceId?: string): Promise<A2ATask>;
+    /**
+     * Generates a callback URL for webhook notifications.
+     * This would typically point to an endpoint in the local system.
+     *
+     * @private
+     * @param {string} taskId - The task ID to generate callback URL for
+     * @returns {string} The callback URL string
+     */
+    private generateCallbackUrl;
+    /**
+     * Cancels a delegated task on the remote agent.
+     *
+     * @param {A2ATask} task - The A2A task to cancel
+     * @param {string} [traceId] - Optional trace ID for request tracking
+     * @returns {Promise<boolean>} Promise resolving to whether cancellation was successful
+     */
+    cancelTask(task: A2ATask, traceId?: string): Promise<boolean>;
+}
+
 interface PESAgentDependencies {
     /** Manages thread configuration and state. */
     stateManager: StateManager;
@@ -1449,7 +3670,6 @@ interface PESAgentDependencies {
      * This serves as a custom prompt part if no thread-specific or call-specific
      * system prompt is provided. It's appended to the agent's base system prompt.
      */
-    instanceDefaultCustomSystemPrompt?: string;
     /** Manages conversation history. */
     conversationManager: ConversationManager;
     /** Registry for available tools. */
@@ -1464,6 +3684,16 @@ interface PESAgentDependencies {
     toolSystem: ToolSystem;
     /** Provides access to UI communication sockets. */
     uiSystem: UISystem;
+    /** Repository for A2A tasks. */
+    a2aTaskRepository: IA2ATaskRepository;
+    /** Service for discovering A2A agents. */
+    agentDiscoveryService?: AgentDiscoveryService | null;
+    /** Service for delegating A2A tasks. */
+    taskDelegationService?: TaskDelegationService | null;
+    /** Resolver for standardized system prompt composition. */
+    systemPromptResolver: SystemPromptResolver;
+    /** Optional: Defines the default identity and high-level guidance for the agent. */
+    persona?: AgentPersona;
 }
 /**
  * Implements the Plan-Execute-Synthesize (PES) agent orchestration logic.
@@ -1475,7 +3705,6 @@ interface PESAgentDependencies {
  * 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.
  *
- * @implements {IAgentCore}
  * // @see {PromptManager} // Removed
  * @see {ReasoningEngine}
  * @see {ArtStandardPrompt}
@@ -1483,50 +3712,75 @@ interface PESAgentDependencies {
  */
 declare class PESAgent implements IAgentCore {
     private readonly deps;
-    /** The base system prompt inherent to this agent. */
-    private readonly defaultSystemPrompt;
-    /**
-     * Stores the instance-level default custom system prompt, passed during construction.
-     * Used in the system prompt hierarchy if no thread or call-level prompt is specified.
-     */
-    private readonly instanceDefaultCustomSystemPrompt?;
+    private readonly persona;
     /**
      * Creates an instance of the PESAgent.
-     * @param dependencies - An object containing instances of all required subsystems (managers, registries, etc.).
+     * @param {module:core/agents/pes-agent.PESAgentDependencies} dependencies - An object containing instances of all required subsystems (managers, registries, etc.).
      */
     constructor(dependencies: PESAgentDependencies);
     /**
      * Executes the full Plan-Execute-Synthesize cycle for a given user query.
      *
      * **Workflow:**
-     * 1.  **Initiation & Config:** Loads thread configuration. Resolves the final system prompt based on a hierarchy:
-     *     Call-level (`AgentProps.options.systemPrompt`) > Thread-level (`ThreadConfig.systemPrompt`) >
-     *     Instance-level (`ArtInstanceConfig.defaultSystemPrompt` via constructor) > Agent's base prompt.
-     *     The resolved custom part is appended to the agent's base prompt.
-     * 2.  **Data Gathering:** Gathers history, available tools, the resolved system prompt, and query.
-     * 3.  **Planning Prompt Construction:** Directly constructs the `ArtStandardPrompt` object/array for planning.
-     * 4.  **Planning LLM Call:** Sends the planning prompt object to the `reasoningEngine` (requesting streaming). Consumes the `StreamEvent` stream, buffers the output text, and handles potential errors.
-     * 5.  **Planning Output Parsing:** Parses the buffered planning output text to extract intent, plan, and tool calls using `outputParser.parsePlanningOutput`.
-     * 6.  **Tool Execution:** Executes identified tool calls via the `toolSystem`.
-     * 7.  **Data Gathering (Synthesis):** Gathers the original query, plan, tool results, history, etc.
-     * 8.  **Synthesis Prompt Construction:** Directly constructs the `ArtStandardPrompt` object/array for synthesis.
-     * 9.  **Synthesis LLM Call:** Sends the synthesis prompt object to the `reasoningEngine` (requesting streaming). Consumes the `StreamEvent` stream, buffers the final response text, and handles potential errors.
-     * 10. **Finalization:** Saves the final AI message, updates state if needed, records observations, and returns the result.
-     *
-     * **Error Handling:**
-     * - Errors during critical phases (planning/synthesis LLM call) will throw an `ARTError`. Prompt construction errors are less likely but possible if data is malformed.
-     * - Errors during tool execution or synthesis LLM call might result in a 'partial' success status, potentially using the error message as the final response content.
+     * 1.  **Initiation & Config:** Loads thread configuration and resolves system prompt
+     * 2.  **Data Gathering:** Gathers history, available tools
+     * 3.  **Planning:** LLM call for planning and parsing
+     * 4.  **A2A Discovery & Delegation:** Identifies and delegates A2A tasks to remote agents
+     * 5.  **Tool Execution:** Executes identified local tool calls
+     * 6.  **Synthesis:** LLM call for final response generation including A2A results
+     * 7.  **Finalization:** Saves messages and cleanup
      *
      * @param {AgentProps} props - The input properties containing the user query, threadId, userId, traceId, etc.
      * @returns {Promise<AgentFinalResponse>} A promise resolving to the final response, including the AI message and execution metadata.
-     * @throws {ARTError} If a critical error occurs that prevents the agent from completing the process (e.g., config loading, planning failure).
-     * @see {AgentProps}
-     * @see {AgentFinalResponse}
-     * // @see {PromptContext} // Removed - context is implicit in object construction
-     * @see {ArtStandardPrompt}
-     * @see {StreamEvent}
+     * @throws {ARTError} If a critical error occurs that prevents the agent from completing the process.
      */
     process(props: AgentProps): Promise<AgentFinalResponse>;
+    /**
+     * Loads thread configuration and resolves the system prompt hierarchy.
+     * @private
+     */
+    private _loadConfiguration;
+    /**
+     * Gathers conversation history for the current thread.
+     * @private
+     */
+    private _gatherHistory;
+    /**
+     * Gathers available tools for the current thread.
+     * @private
+     */
+    private _gatherTools;
+    /**
+     * Performs the planning phase including LLM call and output parsing.
+     * @private
+     */
+    private _performPlanning;
+    /**
+     * Delegates A2A tasks identified in the planning phase.
+     * @private
+     */
+    private _delegateA2ATasks;
+    /**
+     * Waits for A2A tasks to complete with configurable timeout.
+     * Polls task status periodically and updates local repository with results.
+     * @private
+     */
+    private _waitForA2ACompletion;
+    /**
+     * Executes local tools identified during planning.
+     * @private
+     */
+    private _executeLocalTools;
+    /**
+     * Performs the synthesis phase including LLM call for final response generation.
+     * @private
+     */
+    private _performSynthesis;
+    /**
+     * Finalizes the agent execution by saving the final message and performing cleanup.
+     * @private
+     */
+    private _finalize;
     /**
      * Formats conversation history messages for direct inclusion in ArtStandardPrompt.
      * Converts internal MessageRole to ArtStandardMessageRole.
@@ -1546,12 +3800,21 @@ declare class PESAgent implements IAgentCore {
  * - Simple demos or examples where persistence isn't needed.
  * - Ephemeral agents that don't require long-term memory.
  *
- * @implements {StorageAdapter}
+ * It provides a simple key-value store for various data types used within the
+ * ART framework, such as conversation history, agent state, and observations.
+ *
+ * @see {@link StorageAdapter} for the interface definition.
  */
 declare class InMemoryStorageAdapter implements StorageAdapter {
     private storage;
     /**
-     * Initializes the adapter. This is a no-op for the in-memory adapter.
+     * Creates an instance of InMemoryStorageAdapter.
+     * @see StorageAdapter
+     */
+    constructor();
+    /**
+     * Initializes the adapter. This is a no-op for the in-memory adapter
+     * and is provided for interface compatibility.
      * @param _config - Optional configuration (ignored by this adapter).
      * @returns A promise that resolves immediately.
      */
@@ -1629,7 +3892,8 @@ interface IndexedDBConfig {
  * **Important:** The `init()` method *must* be called and awaited before performing
  * any other database operations (get, set, delete, query).
  *
- * @implements {StorageAdapter}
+ * @see {@link StorageAdapter} for the interface it implements.
+ * @see {@link IndexedDBConfig} for configuration options.
  */
 declare class IndexedDBStorageAdapter implements StorageAdapter {
     private db;
@@ -1640,7 +3904,8 @@ declare class IndexedDBStorageAdapter implements StorageAdapter {
     /**
      * Creates an instance of IndexedDBStorageAdapter.
      * Note: The database connection is not opened until `init()` is called.
-     * @param config - Configuration options including database name, version, and required object stores.
+     * @param {module:integrations/storage/indexedDB.IndexedDBConfig} config - Configuration options including database name, version, and required object stores.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
      */
     constructor(config: IndexedDBConfig);
     /**
@@ -1702,6 +3967,8 @@ declare class IndexedDBStorageAdapter implements StorageAdapter {
      * @param filterOptions - Options for filtering, sorting, skipping, and limiting results.
      * @returns A promise resolving to an array of deep copies of the matching items.
      * @throws {Error} If the database is not initialized, the store doesn't exist, or a database error occurs.
+     * @remarks TODO: Implement more advanced querying using IndexedDB indexes and cursors.
+     * This will improve performance for large datasets.
      */
     query<T>(collection: string, filterOptions: FilterOptions): Promise<T[]>;
     /**
@@ -1720,6 +3987,112 @@ declare class IndexedDBStorageAdapter implements StorageAdapter {
     clearAll(): Promise<void>;
 }
 
+interface SupabaseConfig {
+    /** Supabase project URL, e.g., https://xyzcompany.supabase.co */
+    url: string;
+    /** Supabase anon or service key. Prefer service key on server-side only. */
+    apiKey: string;
+    /** Optional schema name (default 'public'). */
+    schema?: string;
+    /**
+     * Table names to use. These map ART collections to Supabase.
+     * If you customize collection names in repositories, adjust accordingly.
+     */
+    tables?: {
+        conversations?: string;
+        observations?: string;
+        state?: string;
+        a2a_tasks?: string;
+    };
+    /**
+     * Optional: pass a pre-initialized Supabase client (from @supabase/supabase-js)
+     * Useful in environments where you already manage the client and auth.
+     */
+    client?: any;
+}
+/**
+ * A Supabase-backed StorageAdapter implementation.
+ *
+ * Expectations/assumptions:
+ * - Each collection maps to a table with a primary key column named 'id' (text/uuid).
+ * - We store JSON columns for flexible data where needed. However, repositories
+ *   store fully shaped rows; this adapter just persists and retrieves whole objects.
+ * - For query(), we implement basic equality filters per FilterOptions.filter keys,
+ *   plus limit/skip and a single-key sort.
+ */
+declare class SupabaseStorageAdapter implements StorageAdapter {
+    private client;
+    private config;
+    private schema;
+    private tables;
+    /**
+     * Creates an instance of SupabaseStorageAdapter.
+     * @see SupabaseConfig
+     */
+    constructor(config: SupabaseConfig);
+    /**
+     * Configures the adapter with the provided Supabase settings.
+     * @private
+     * @param {SupabaseConfig} config - The configuration for the adapter.
+     */
+    private configure;
+    /**
+     * Initializes the Supabase client if it hasn't been provided already.
+     * @returns {Promise<void>} A promise that resolves when the client is initialized.
+     */
+    init(): Promise<void>;
+    /**
+     * Maps a collection name to a Supabase table name.
+     * @private
+     * @param {string} collection - The name of the collection.
+     * @returns {string} The name of the Supabase table.
+     */
+    private tableForCollection;
+    /**
+     * Retrieves a single item from a collection by its ID.
+     * @template T
+     * @param {string} collection - The name of the collection.
+     * @param {string} id - The ID of the item to retrieve.
+     * @returns {Promise<T | null>} A promise that resolves with the item, or null if not found.
+     */
+    get<T>(collection: string, id: string): Promise<T | null>;
+    /**
+     * Saves (upserts) an item in a collection.
+     * @template T
+     * @param {string} collection - The name of the collection.
+     * @param {string} id - The ID of the item to save.
+     * @param {T} data - The data to save.
+     * @returns {Promise<void>} A promise that resolves when the item is saved.
+     */
+    set<T>(collection: string, id: string, data: T): Promise<void>;
+    /**
+     * Deletes an item from a collection by its ID.
+     * @param {string} collection - The name of the collection.
+     * @param {string} id - The ID of the item to delete.
+     * @returns {Promise<void>} A promise that resolves when the item is deleted.
+     */
+    delete(collection: string, id: string): Promise<void>;
+    /**
+     * Queries items in a collection.
+     * @template T
+     * @param {string} collection - The name of the collection.
+     * @param {FilterOptions} filterOptions - The options for filtering, sorting, and pagination.
+     * @returns {Promise<T[]>} A promise that resolves with an array of items.
+     */
+    query<T>(collection: string, filterOptions: FilterOptions): Promise<T[]>;
+    /**
+     * Clears all items from a collection.
+     * @param {string} collection - The name of the collection.
+     * @returns {Promise<void>} A promise that resolves when the collection is cleared.
+     */
+    clearCollection(collection: string): Promise<void>;
+    /**
+     * Clears all items from all collections.
+     * @returns {Promise<void>} A promise that resolves when all collections are cleared.
+     */
+    clearAll(): Promise<void>;
+}
+
 /**
  * Configuration options required for the `GeminiAdapter`.
  */
@@ -1742,6 +4115,7 @@ declare class GeminiAdapter implements ProviderAdapter {
      * Creates an instance of GeminiAdapter.
      * @param {GeminiAdapterOptions} options - Configuration options for the adapter.
      * @throws {Error} If `apiKey` is missing in the options.
+     * @see https://ai.google.dev/api/rest
      */
     constructor(options: GeminiAdapterOptions);
     /**
@@ -1763,6 +4137,7 @@ declare class GeminiAdapter implements ProviderAdapter {
      * @see {CallOptions}
      * @see {StreamEvent}
      * @see {LLMMetadata}
+     * @see https://ai.google.dev/api/rest/v1beta/models/generateContent
      */
     call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
     /**
@@ -1804,7 +4179,7 @@ interface OpenAIAdapterOptions {
  * Handles formatting requests and parsing responses for OpenAI.
  * Uses raw `fetch` for now.
  *
- * @implements {ProviderAdapter}
+ * @see {@link ProviderAdapter} for the interface definition.
  */
 declare class OpenAIAdapter implements ProviderAdapter {
     readonly providerName = "openai";
@@ -1813,8 +4188,9 @@ declare class OpenAIAdapter implements ProviderAdapter {
     private apiBaseUrl;
     /**
      * Creates an instance of the OpenAIAdapter.
-     * @param options - Configuration options including the API key and optional model/baseURL overrides.
+     * @param {OpenAIAdapterOptions} options - Configuration options including the API key and optional model/baseURL overrides.
      * @throws {Error} If the API key is missing.
+     * @see https://platform.openai.com/docs/api-reference
      */
     constructor(options: OpenAIAdapterOptions);
     /**
@@ -1824,6 +4200,7 @@ declare class OpenAIAdapter implements ProviderAdapter {
      * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
      * @param {CallOptions} options - Call options, including `threadId`, `traceId`, `stream` preference, and any OpenAI-specific parameters (like `temperature`, `max_tokens`) passed through.
      * @returns {Promise<AsyncIterable<StreamEvent>>} A promise resolving to an AsyncIterable of StreamEvent objects.
+     * @see https://platform.openai.com/docs/api-reference/chat/create
      */
     call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
     /**
@@ -1865,7 +4242,8 @@ interface AnthropicAdapterOptions {
  *
  * Handles formatting requests, parsing responses, streaming, and tool use.
  *
- * @implements {ProviderAdapter}
+ * @see {@link ProviderAdapter} for the interface definition.
+ * @see {@link AnthropicAdapterOptions} for configuration options.
  */
 declare class AnthropicAdapter implements ProviderAdapter {
     readonly providerName = "anthropic";
@@ -1891,26 +4269,40 @@ declare class AnthropicAdapter implements ProviderAdapter {
      */
     call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
     /**
-     * Prepares request options. Currently a placeholder for potential future additions
-     * like Anthropic beta headers for specific models or features (e.g., prompt caching).
-     * The user's example code shows more advanced beta header logic.
+     * Prepares request options, adding Anthropic beta headers if applicable for features like prompt caching.
+     * This allows opting into experimental features on a per-request basis.
+     * @private
+     * @param {string} modelId - The model ID being used for the request, to determine which beta features may apply.
+     * @returns {Anthropic.RequestOptions} The request options object, potentially with custom headers.
      */
     private getRequestOptions;
     /**
      * Translates the provider-agnostic `ArtStandardPrompt` into the Anthropic SDK Messages format.
+     * It handles system prompts, message merging for consecutive roles, and validates message structure.
      *
      * @private
      * @param {ArtStandardPrompt} artPrompt - The input `ArtStandardPrompt` array.
-     * @returns {{ systemPrompt?: string; messages: AnthropicSDKMessageParam[] }}
-     * @throws {ARTError} If translation encounters an issue.
+     * @returns {{ systemPrompt?: string; messages: Anthropic.Messages.MessageParam[] }} An object containing the extracted system prompt and the array of Anthropic-formatted messages.
+     * @throws {ARTError} If translation encounters an issue, such as multiple system messages or invalid message roles.
      */
     private translateToAnthropicSdk;
     /**
-     * Maps a single ArtStandardMessage to Anthropic SDK's content format (string or AnthropicSDKContentBlockParam[]).
+     * Maps a single `ArtStandardMessage` to Anthropic SDK's content format.
+     * This can be a simple string or an array of `ContentBlockParam` for complex content
+     * like tool calls and tool results.
+     *
+     * @private
+     * @param {ArtStandardMessage} artMsg - The ART standard message to map.
+     * @returns {string | AnthropicSDKContentBlockParam[]} The translated content for the Anthropic API.
+     * @throws {ARTError} If tool call arguments are not valid JSON or if a tool result is missing its ID.
      */
     private mapArtMessageToAnthropicContent;
     /**
-     * Translates ART ToolSchema array to Anthropic's tool format.
+     * Translates an array of `ToolSchema` from the ART framework format to Anthropic's specific tool format.
+     * @private
+     * @param {ToolSchema[]} artTools - An array of ART tool schemas.
+     * @returns {AnthropicSDKTool[]} An array of tools formatted for the Anthropic API.
+     * @throws {ARTError} If a tool's `inputSchema` is invalid.
      */
     private translateArtToolsToAnthropic;
 }
@@ -1931,14 +4323,11 @@ interface OpenRouterAdapterOptions {
     appName?: string;
 }
 /**
- * Implements the `ProviderAdapter` interface for interacting with the OpenRouter API,
- * which provides access to various LLMs through an OpenAI-compatible interface.
+ * This adapter provides a unified interface for various LLM providers through OpenRouter,
+ * handling prompt conversion and response parsing into the ART `StreamEvent` format.
  *
- * Handles formatting requests and parsing responses for OpenRouter's chat completions endpoint.
- * Handles formatting requests and parsing responses for OpenRouter's chat completions endpoint.
- * Note: Streaming is **not yet implemented** for this adapter. Calls requesting streaming will yield an error and end.
- *
- * @implements {ProviderAdapter}
+ * @see {@link ProviderAdapter} for the interface it implements.
+ * @see {@link OpenRouterAdapterOptions} for configuration options.
  */
 declare class OpenRouterAdapter implements ProviderAdapter {
     readonly providerName = "openrouter";
@@ -1949,8 +4338,9 @@ declare class OpenRouterAdapter implements ProviderAdapter {
     private appName?;
     /**
      * Creates an instance of the OpenRouterAdapter.
-     * @param options - Configuration options including the API key, the specific OpenRouter model identifier, and optional headers/baseURL.
+     * @param {OpenRouterAdapterOptions} options - Configuration options including the API key, the specific OpenRouter model identifier, and optional headers/baseURL.
      * @throws {Error} If the API key or model identifier is missing.
+     * @see https://openrouter.ai/docs
      */
     constructor(options: OpenRouterAdapterOptions);
     /**
@@ -1962,6 +4352,7 @@ declare class OpenRouterAdapter implements ProviderAdapter {
      * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
      * @param {CallOptions} options - Call options, including `threadId`, `traceId`, `stream`, and any OpenAI-compatible generation parameters.
      * @returns {Promise<AsyncIterable<StreamEvent>>} A promise resolving to an AsyncIterable of StreamEvent objects. If streaming is requested, it yields an error event and ends.
+     * @see https://openrouter.ai/docs#api-reference-chat-completions
      */
     call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
     /**
@@ -1988,13 +4379,11 @@ interface DeepSeekAdapterOptions {
     apiBaseUrl?: string;
 }
 /**
- * Implements the `ProviderAdapter` interface for interacting with the DeepSeek API,
- * which uses an OpenAI-compatible Chat Completions endpoint.
- *
- * Handles formatting requests and parsing responses for DeepSeek models.
- * Note: Streaming is **not yet implemented** for this adapter. Calls requesting streaming will yield an error and end.
+ * This adapter provides a consistent interface for ART agents to use DeepSeek models,
+ * handling the conversion of standard ART prompts to the DeepSeek API format and
+ * parsing the responses into the ART `StreamEvent` format.
  *
- * @implements {ProviderAdapter}
+ * @see {@link ProviderAdapter} for the interface it implements.
  */
 declare class DeepSeekAdapter implements ProviderAdapter {
     readonly providerName = "deepseek";
@@ -2003,8 +4392,9 @@ declare class DeepSeekAdapter implements ProviderAdapter {
     private apiBaseUrl;
     /**
      * Creates an instance of the DeepSeekAdapter.
-     * @param options - Configuration options including the API key and optional model/baseURL overrides.
+     * @param {DeepSeekAdapterOptions} options - Configuration options including the API key and optional model/baseURL overrides.
      * @throws {Error} If the API key is missing.
+     * @see https://platform.deepseek.com/api-docs
      */
     constructor(options: DeepSeekAdapterOptions);
     /**
@@ -2016,6 +4406,7 @@ declare class DeepSeekAdapter implements ProviderAdapter {
      * @param {ArtStandardPrompt} prompt - The standardized prompt messages.
      * @param {CallOptions} options - Call options, including `threadId`, `traceId`, `stream`, and any OpenAI-compatible generation parameters.
      * @returns {Promise<AsyncIterable<StreamEvent>>} A promise resolving to an AsyncIterable of StreamEvent objects. If streaming is requested, it yields an error event and ends.
+     * @see https://platform.deepseek.com/api-docs/api/create-chat-completion/index.html
      */
     call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
     /**
@@ -2056,7 +4447,8 @@ interface OllamaAdapterOptions {
  *
  * Handles formatting requests, parsing responses, streaming, and tool use.
  *
- * @implements {ProviderAdapter}
+ * @see {@link ProviderAdapter} for the interface definition.
+ * @see {@link OllamaAdapterOptions} for configuration options.
  */
 declare class OllamaAdapter implements ProviderAdapter {
     readonly providerName = "ollama";
@@ -2079,20 +4471,33 @@ declare class OllamaAdapter implements ProviderAdapter {
     call(prompt: ArtStandardPrompt, options: CallOptions): Promise<AsyncIterable<StreamEvent>>;
     /**
      * Translates the provider-agnostic `ArtStandardPrompt` into the OpenAI API's `OpenAIMessage[]` format.
-     * This is a common utility function that can be shared or adapted from other OpenAI-compatible adapters.
+     * This method can handle model-specific formatting, such as merging consecutive messages for certain models.
+     * @private
+     * @param {ArtStandardPrompt} artPrompt - The input `ArtStandardPrompt` array.
+     * @param {string} [modelIdForTransform] - The model ID, used to determine if special formatting is needed.
+     * @returns {OpenAIMessage[]} The `OpenAIMessage[]` array formatted for the OpenAI API.
      */
     private translateToOpenAI;
+    /**
+     * Maps a single `ArtStandardMessage` to an `OpenAIMessage`.
+     * @private
+     * @param {ArtStandardMessage} message - The message to map.
+     * @returns {OpenAIMessage} The mapped message.
+     * @throws {ARTError} If an unsupported or invalid message role is encountered.
+     */
     private mapArtMessageToOpenAIMessage;
     /**
-     * Translates ART ToolSchema array to OpenAI's tool format.
+     * Translates an array of `ToolSchema` from the ART framework format to OpenAI's specific tool format.
+     * @private
+     * @param {ToolSchema[]} artTools - An array of ART tool schemas.
+     * @returns {OpenAI.Chat.Completions.ChatCompletionTool[]} An array of tools formatted for the OpenAI API.
+     * @throws {ARTError} If a tool's schema is invalid.
      */
     private translateArtToolsToOpenAI;
     /**
-     * Optional method for graceful shutdown.
-     * For Ollama, which is typically a separate local server, this adapter
-     * doesn't manage persistent connections that need explicit closing.
-     * The OpenAI client used internally might have its own cleanup, but
-     * it's generally handled by garbage collection.
+     * Optional method for graceful shutdown. For Ollama, which is typically a separate
+     * local server, this adapter doesn't manage persistent connections that need explicit closing.
+     * @returns {Promise<void>} A promise that resolves when the shutdown is complete.
      */
     shutdown(): Promise<void>;
 }
@@ -2101,7 +4506,13 @@ declare class OllamaAdapter implements ProviderAdapter {
  * An ART Framework tool that safely evaluates mathematical expressions using the mathjs library.
  * It supports basic arithmetic, variables via a scope, complex numbers, and a predefined list of safe functions.
  *
- * @implements {IToolExecutor}
+ * This tool is designed to be used within the ART framework's `ToolSystem`.
+ * It provides a safe way to perform mathematical calculations by leveraging
+ * the `mathjs` library. The tool validates the input expression to ensure it's a
+ * single, valid mathematical expression before evaluation.
+ *
+ * @see {@link IToolExecutor} for the interface it implements.
+ * @see {@link ToolSystem} for the system that manages and executes tools.
  */
 declare class CalculatorTool implements IToolExecutor {
     /** The unique name identifier for this tool. */
@@ -2128,25 +4539,217 @@ declare class CalculatorTool implements IToolExecutor {
     execute(input: any, context: ExecutionContext): Promise<ToolResult>;
 }
 
+/**
+ * Configuration for the PKCE OAuth 2.0 authentication strategy.
+ */
+interface PKCEOAuthConfig {
+    /** The OAuth 2.0 authorization endpoint URL. */
+    authorizationEndpoint: string;
+    /** The OAuth 2.0 token endpoint URL. */
+    tokenEndpoint: string;
+    /** The client ID for the application. */
+    clientId: string;
+    /** The redirect URI for the application. */
+    redirectUri: string;
+    /** The scopes to request (space-separated). */
+    scopes: string;
+    /** Optional: The resource parameter to specify the target audience (for MCP servers). */
+    resource?: string;
+    /** Open login in a new tab (default true for ART MCP flows). */
+    openInNewTab?: boolean;
+    /** BroadcastChannel name used to receive auth codes from callback tab (default 'art-auth'). */
+    channelName?: string;
+}
+/**
+ * Implements the OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange).
+ * This is the recommended, most secure method for authenticating users in browser-based applications.
+ */
+declare class PKCEOAuthStrategy implements IAuthStrategy {
+    private config;
+    private cachedToken;
+    private codeVerifierForPendingLogin;
+    private loginWaiter;
+    private channel?;
+    /**
+     * Creates an instance of PKCEOAuthStrategy.
+     * @param {PKCEOAuthConfig} config - The configuration for the PKCE OAuth 2.0 strategy.
+     */
+    constructor(config: PKCEOAuthConfig);
+    /**
+     * Initiates the PKCE login flow by redirecting the user to the authorization endpoint.
+     * @returns {Promise<void>} A promise that resolves when the login process is complete.
+     */
+    login(): Promise<void>;
+    /**
+     * Handles the redirect from the authorization server.
+     * This method should be called on the redirect URI page.
+     * It exchanges the authorization code for an access token.
+     * @returns {Promise<void>} A promise that resolves when the redirect has been handled.
+     */
+    handleRedirect(): Promise<void>;
+    /**
+     * Gets the authentication headers, automatically handling token refresh if needed.
+     * @returns {Promise<Record<string, string>>} A promise that resolves to the authentication headers.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * Clears the cached token.
+     */
+    logout(): void;
+    /**
+     * Checks if there is a valid, non-expired token.
+     * @returns {Promise<boolean>} A promise that resolves to true if the token is valid, false otherwise.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Generates a random string for the code verifier.
+     * @returns {string} The generated code verifier.
+     */
+    private generateCodeVerifier;
+    /**
+     * Generates a code challenge from a code verifier.
+     * @param {string} verifier - The code verifier.
+     * @returns {Promise<string>} A promise that resolves to the code challenge.
+     */
+    private generateCodeChallenge;
+    /**
+     * Encodes a byte array into a base64 URL-safe string.
+     * @param {Uint8Array} bytes - The byte array to encode.
+     * @returns {string} The base64 URL-safe encoded string.
+     */
+    private base64UrlEncode;
+    /**
+     * Refreshes the access token using the refresh token.
+     * @returns {Promise<void>} A promise that resolves when the token has been refreshed.
+     */
+    private refreshToken;
+    /**
+     * Exchanges an authorization code for an access token.
+     * @param {string} code - The authorization code.
+     * @returns {Promise<void>} A promise that resolves when the token exchange is complete.
+     */
+    private exchangeCodeForToken;
+}
+
+/**
+ * A proxy tool that wraps an MCP server tool and implements the {@link IToolExecutor} interface.
+ *
+ * @remarks
+ * This allows MCP server tools to be used seamlessly within the ART Framework.
+ *
+ * @see {@link McpManager} for the system that manages these proxy tools.
+ * @see {@link IToolExecutor} for the interface it implements.
+ *
+ * @class McpProxyTool
+ */
+declare class McpProxyTool implements IToolExecutor {
+    readonly schema: ToolSchema;
+    private card;
+    private toolDefinition;
+    private mcpManager;
+    /**
+     * Creates an instance of McpProxyTool.
+     *
+     * @param card Configuration for the MCP server hosting this tool.
+     * @param toolDefinition The tool definition from the MCP server.
+     * @param mcpManager The MCP manager for managing connections.
+     */
+    constructor(card: McpServerConfig, toolDefinition: McpToolDefinition, mcpManager: McpManager);
+    /**
+     * Executes the tool by making a request to the MCP server.
+     *
+     * @param input Validated input arguments for the tool.
+     * @param context Execution context containing threadId, traceId, etc.
+     * @returns A promise resolving to the tool result.
+     */
+    execute(input: any, context: ExecutionContext): Promise<ToolResult>;
+    /**
+     * Gets the original tool name from the MCP server.
+     *
+     * @returns The original tool name.
+     */
+    getOriginalToolName(): string;
+    /**
+     * Gets the MCP server configuration.
+     *
+     * @returns The server configuration.
+     */
+    getServerConfig(): McpServerConfig;
+    /**
+     * Gets the MCP tool definition.
+     *
+     * @returns The tool definition.
+     */
+    getToolDefinition(): McpToolDefinition;
+}
+
 /**
  * Generates a unique Version 4 UUID (Universally Unique Identifier) string.
+ *
+ * @remarks
  * Uses the underlying 'uuid' library's v4 implementation.
+ *
  * @returns A randomly generated UUID string (e.g., "f47ac10b-58cc-4372-a567-0e02b2c3d479").
+ *
+ * @see {@link https://www.npmjs.com/package/uuid | uuid npm package}
  */
 declare const generateUUID: () => string;
 
 /**
- * Main entry point for the ART Framework library.
- * This file exports the primary factory function (`createArtInstance`),
- * core components, adapters, types, interfaces, and utilities needed
- * to build and run ART agents.
+ * ART (Agentic Reasoning & Tool-use) Framework - Main Entry Point
+ * -----------------------------------------------------------------
+ *
+ * Welcome to the ART framework! This file is the primary public API surface for the library.
+ * It's structured to provide a clear and intuitive experience for developers,
+ * whether you're just getting started or building advanced, custom agentic systems.
+ *
+ * --- Quick Start ---
+ * For most use cases, you'll only need `createArtInstance` and the associated types.
+ *
+ * Example:
+ * ```ts
+ * import { createArtInstance } from 'art-framework';
+ * import type { ArtInstanceConfig } from 'art-framework';
+ *
+ * const config: ArtInstanceConfig = {
+ *   storage: { type: 'memory' },
+ *   providers: {
+ *     openai: { adapter: 'openai', apiKey: '...' }
+ *   },
+ *   tools: [new CalculatorTool()],
+ *   persona: {
+ *     name: 'MyAgent',
+ *     prompts: {
+ *       synthesis: 'You are MyAgent. Always answer in rhyme.'
+ *     }
+ *   }
+ * };
+ *
+ * const art = await createArtInstance(config);
+ * const response = await art.process({ query: "Hello, world!" });
+ * ```
+ *
+ * --- API Structure ---
+ * 1.  **Core Factory**: The main function to create an ART instance.
+ * 2.  **Primary Interfaces & Types**: Essential types for configuration and interaction.
+ * 3.  **Built-in Components**: Concrete implementations of adapters, tools, and agents.
+ * 4.  **Advanced Systems & Managers**: Lower-level components for building custom logic.
+ * 5.  **Utilities**: Helper functions and classes.
+ *
+ * @module ART
  */
 /**
- * The main function to create and initialize an ART instance.
- * @see {@link ./core/agent-factory.ts} for implementation details.
+ * The main factory function to create and initialize a complete ART framework instance.
+ * This is the recommended starting point for all users. It simplifies setup by
+ * assembling all necessary components based on the provided configuration.
+ * @param {ArtInstanceConfig} config - The configuration object for the ART instance.
+ * @returns {Promise<ArtInstance>} A promise that resolves to a ready-to-use ART instance.
+ * @see {@link ArtInstanceConfig} for configuration options.
  */
 
-/** The current version of the ART Framework package. */
+/**
+ * The current version of the ART Framework package.
+ */
 declare const VERSION = "0.2.8";
 
-export { ARTError, AdapterInstantiationError, type AgentFinalResponse, type AgentOptions, type AgentProps, type AgentState, AnthropicAdapter, ApiQueueTimeoutError, type ArtInstance, type ArtInstanceConfig, type ArtStandardMessage, type ArtStandardMessageRole, ArtStandardMessageSchema, type ArtStandardPrompt, ArtStandardPromptSchema, type AvailableProviderEntry, CalculatorTool, type CallOptions, type ConversationManager, type ConversationMessage, type ConversationSocket, DeepSeekAdapter, ErrorCode, type ExecutionContext, type ExecutionMetadata, type FilterOptions, type FormattedPrompt, GeminiAdapter, type IAgentCore, 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 ManagedAdapterAccessor, type MessageOptions, MessageRole, ModelCapability, type Observation, type ObservationFilter, type ObservationManager, type ObservationSocket, ObservationType, OllamaAdapter, type OllamaAdapterOptions, OpenAIAdapter, OpenRouterAdapter, type OutputParser, PESAgent, type ParsedToolCall, type PromptContext, type PromptManager, type ProviderAdapter, type ProviderManagerConfig, type ReasoningEngine, type RuntimeProviderConfig, type StateManager, type StateSavingStrategy, type StorageAdapter, type StreamEvent, type ThreadConfig, type ThreadContext, type ToolRegistry, type ToolResult, type ToolSchema, type ToolSystem, TypedSocket, type UISystem, UnknownProviderError, type UnsubscribeFunction, VERSION, createArtInstance, generateUUID };
+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, 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, 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 Observation, type ObservationFilter, type ObservationManager, ObservationSocket, ObservationType, OllamaAdapter, type OllamaAdapterOptions, OpenAIAdapter, type OpenAIAdapterOptions, OpenRouterAdapter, type OpenRouterAdapterOptions, type OutputParser, PESAgent, type PKCEOAuthConfig, PKCEOAuthStrategy, type ParsedToolCall, type PromptBlueprint, type PromptContext, type PromptManager, type ProviderAdapter, type ProviderManagerConfig, type ReasoningEngine, type RuntimeProviderConfig, type StageSpecificPrompts, type 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 ToolRegistry, type ToolResult, type ToolSchema, type ToolSystem, TypedSocket, type UISystem, UnknownProviderError, type UnsubscribeFunction, type UpdateA2ATaskRequest, VERSION, createArtInstance, generateUUID };