evoltagent 1.1.2 → 1.1.4

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { ChildProcess } from 'child_process';
+
 /**
  * Post-run hooks for agent output processing
  *
@@ -41,7 +43,7 @@ type PostProcessor = (response: string) => Promise<any>;
  */
 
 interface Message$1 {
-    role: 'system' | 'user' | 'assistant';
+    role: 'system' | 'user' | 'assistant' | 'tool';
     content: string;
     images?: string | string[];
     type?: string;
@@ -50,11 +52,6 @@ interface ToolCall {
     type: 'system' | 'user';
     extractedResult: () => string;
 }
-interface ModelResponse$1 {
-    type: 'system' | 'user' | 'TaskCompletion';
-    extractedResult: () => string | any[] | Record<string, any>;
-    rawContentFromLlm?: string;
-}
 interface ToolDescription {
     desc: string;
     execute: (...args: any[]) => Promise<any>;
@@ -90,19 +87,6 @@ interface ModelConfig {
     stream?: boolean;
     [key: string]: any;
 }
-interface AgentConfig {
-    name: string;
-    profile: string;
-    system?: string;
-    tools?: string[];
-    subAgents?: any[];
-    mcpServerNames?: string[];
-    modelConfig?: string | ModelConfig;
-    verbose?: boolean | number;
-    useFunctionCalling?: boolean;
-    postProcessor?: PostProcessor;
-    toolcallManagerPoolSize?: number;
-}
 interface EnvironmentConfig {
     workspace?: string;
     [key: string]: any;
@@ -401,156 +385,42 @@ declare class GitTool {
 }
 
 /**
- * Main Agent class with tool use capabilities
+ * Image reading utilities
  *
- * Converts Python's agent.py to TypeScript
+ * Corresponds to Python's utils/read_image.py
  */
-
 /**
- * Main Agent class
+ * OpenAI vision API format for image content
  */
-declare class Agent {
-    name: string;
-    private profile;
-    private system;
-    private tools;
-    private functionCallingTools;
-    private mcpServerNames;
-    private modelConfig;
-    private verbose;
-    private model;
-    private history;
-    private subAgents;
-    private toolcallManagerPoolSize;
-    private postProcessor;
-    private useFunctionCalling;
-    constructor(config: AgentConfig);
-    /**
-     * Get the current system prompt
-     */
-    get systemPrompt(): string;
-    /**
-     * Set the system prompt and update history
-     */
-    set systemPrompt(value: string);
-    /**
-     * Set the system prompt with system tools descriptions
-     * @private
-     */
-    private setSystem;
-    /**
-     * Set up function calling tools for OpenAI-style function calling
-     * @private
-     */
-    private setFunctionCallingTools;
-    /**
-     * Agent loop - processes user input and handles tool calls
-     * @private
-     */
-    private _agentLoop;
-    /**
-     * Run the agent with given instruction
-     */
-    run(instruction: string, images?: string | string[]): Promise<string | any>;
-    /**
-     * Get agent profile
-     */
-    getProfile(): string;
-    /**
-     * Get tools
-     */
-    getTools(): string[];
-    /**
-     * Get function calling tools schemas
-     */
-    getFunctionCallingTools(): any[];
-    /**
-     * Get MCP server names
-     */
-    getMcpServerNames(): string[];
-    /**
-     * Get model config (string or ModelConfig object)
-     */
-    getModelConfig(): string | ModelConfig;
-    /**
-     * Get model name (for backward compatibility)
-     */
-    getModelName(): string;
-    /**
-     * Get verbose setting
-     */
-    getVerbose(): boolean | number;
-    /**
-     * Get sub-agents
-     */
-    getSubAgents(): any[];
+interface ImageContent {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
 }
-
 /**
- * Model abstraction layer using official SDKs
+ * Check if the file is a supported image format
  *
- * Provides a unified interface for multiple LLM providers:
- * - OpenAI (and compatible APIs like DeepSeek)
- * - Anthropic Claude
- * - Google Gemini
+ * @param imagePath - Path or URL to the image
+ * @returns true if the image format is supported (jpeg, jpg, png, gif, webp), false otherwise (svg, etc.)
  */
-
+declare function isSupportedImageFile(imagePath: string): boolean;
 /**
- * Model response interface
+ * Synchronously read image and convert to base64 format
+ *
+ * @param imagePath - Image path or URL
+ * @returns OpenAI vision API format image content
+ * @throws Error if image file not found or URL request fails
  */
-interface ModelResponse {
-    type: 'system' | 'user' | 'TaskCompletion';
-    extractedResult: () => string | any[] | Record<string, any>;
-    rawContentFromLlm?: string;
-}
+declare function readImage(imagePath: string): ImageContent;
 /**
- * Model class for interacting with LLM providers
- * Uses official SDKs for better reliability and type safety
+ * Asynchronously read image and convert to base64 format
+ *
+ * @param imagePath - Image path or URL
+ * @returns OpenAI vision API format image content
+ * @throws Error if image file not found or URL request fails
  */
-declare class Model {
-    private modelName;
-    private config;
-    private openaiClient?;
-    private anthropicClient?;
-    private geminiClient?;
-    constructor(model?: string | ModelConfig);
-    /**
-     * Initialize the appropriate SDK client based on provider
-     */
-    private _initializeClient;
-    /**
-     * Asynchronous chat completion
-     */
-    achat(messages: any[], tools?: any[], stream?: boolean): Promise<ModelResponse[]>;
-    /**
-     * Call OpenAI-compatible API (OpenAI, DeepSeek, etc.)
-     */
-    private _callOpenAICompatible;
-    /**
-     * Call Anthropic API
-     */
-    private _callAnthropic;
-    /**
-     * Call Google Gemini API
-     */
-    private _callGemini;
-    /**
-     * Convert OpenAI format messages to Gemini format
-     */
-    private _convertMessagesToGeminiFormat;
-    /**
-     * Get model configuration
-     */
-    getConfig(): ModelConfig;
-    /**
-     * Get model name
-     */
-    getName(): string;
-    /**
-     * Check if model supports tool calling
-     */
-    supportsToolCalling(): boolean;
-}
+declare function areadImage(imagePath: string): Promise<ImageContent>;
 
 /**
  * Message class for conversation history
@@ -562,11 +432,16 @@ declare class Model {
  * Message class representing a single message in conversation
  */
 declare class Message implements Message$1 {
-    role: 'system' | 'user' | 'assistant';
+    role: 'system' | 'user' | 'assistant' | 'tool';
     content: string;
     images?: string | string[];
+    imagesContent?: ImageContent[];
+    tag?: string;
+    isFunctionCall?: boolean;
+    toolCallId?: string;
+    toolName?: string;
     type?: string;
-    constructor(role: 'system' | 'user' | 'assistant', content: string, images?: string | string[], type?: string);
+    constructor(role: 'system' | 'user' | 'assistant' | 'tool', content: string, images?: string | string[], type?: string);
     /**
      * Create message from user input
      */
@@ -579,10 +454,36 @@ declare class Message implements Message$1 {
      * Create system message
      */
     static fromSystemMsg(content: string): Message;
+    /**
+     * Check if message is truthy based on content
+     */
+    isTruthy(): boolean;
+    /**
+     * Format the content with pre/post content and optional tag wrapping
+     */
+    private _formatForContent;
+    /**
+     * Ensure text content is not empty to avoid API errors
+     */
+    private static _ensureNonEmptyText;
+    /**
+     * Format message for OpenAI API
+     *
+     * This is the recommended method replacing toChatMessage.
+     *
+     * @param preContent - Content to prepend
+     * @param postContent - Content to append
+     * @returns Formatted message object for API
+     */
+    formatForApi(preContent?: string, postContent?: string): Record<string, any>;
     /**
      * Convert to plain object for API calls
      */
     toObject(): any;
+    /**
+     * Convert to dictionary representation
+     */
+    toDict(): Record<string, any>;
     /**
      * Check if message contains images
      */
@@ -595,8 +496,18 @@ declare class Message implements Message$1 {
      * Convert to string representation
      */
     toString(): string;
+    /**
+     * Merge two messages into one
+     *
+     * @param other - Message to merge with
+     * @returns New merged Message
+     */
+    merge(other: Message): Message;
     /**
      * Convert to OpenAI Vision API format with base64-encoded images
+     *
+     * @deprecated Use formatForApi instead. Will be removed in 0.2.2.
+     *
      * This method handles:
      * - HTTP/HTTPS URLs: Downloads and converts to base64
      * - Local file paths: Reads file and converts to base64
@@ -618,56 +529,96 @@ declare class Message implements Message$1 {
 }
 
 /**
- * Toolcall class and types
+ * ImageTool - Tool for reading images from paths or URLs
  *
- * Extracted from src/utils/toolUtil.ts to mirror Python evolt/schemas/toolcall.py
+ * Corresponds to Python's tools/image_tool.py
  */
+
 /**
- * Toolcall execution state
+ * Tool for reading images from paths or URLs
  */
-type ToolcallState = 'pending' | 'running' | 'success' | 'failed';
+declare class ImageTool {
+    /**
+     * Read and analyze an image (JPEG, JPG, PNG, GIF, WebP) from image path or URL.
+     *
+     * Note: SVG format is not supported by the AI model.
+     *
+     * @param imagePath - Image path or URL
+     * @param instruction - Instruction for analyzing the image
+     * @returns Message containing image content in base64 format
+     */
+    readImage(imagePath: string, instruction?: string): Promise<Message>;
+    /**
+     * Read images (JPEG, JPG, PNG, GIF, WebP) from image paths or URLs.
+     *
+     * Note: SVG format is not supported by the AI model and will be automatically filtered out.
+     *
+     * @param imagePaths - List of image paths or URLs
+     * @param instruction - Instruction for reading the images
+     * @returns Message containing multiple image contents in base64 format
+     */
+    readImages(imagePaths: string[], instruction?: string): Promise<Message>;
+}
+
 /**
- * Toolcall type
+ * PatchTool - Tool for applying patches to files
+ *
+ * Corresponds to Python's tools/patch_tool.py
  */
-type ToolcallType = 'system' | 'user' | 'TaskCompletion';
 /**
- * Toolcall class representing a single tool call
+ * Tool for applying patches to files
  */
-declare class Toolcall {
-    name: string;
-    input: Record<string, any>;
-    isExtractedSuccess: boolean;
-    failedExtractedReason?: string;
-    executedState: ToolcallState;
-    executedContent?: string;
-    toolCallId: string;
-    type: ToolcallType;
-    rawContentFromLlm?: string;
-    constructor(config: {
-        name: string;
-        input?: Record<string, any>;
-        isExtractedSuccess?: boolean;
-        failedExtractedReason?: string;
-        executedState?: ToolcallState;
-        executedContent?: string;
-        toolCallId?: string;
-        type?: ToolcallType;
-        rawContentFromLlm?: string;
-    });
+declare class PatchTool {
     /**
-     * Toolcall extraction result description
+     * Write patch content to file
+     *
+     * @param patchPath - Path to the patch file
+     * @param patchContent - Content of the patch in unified diff format
+     * @returns Success message
      */
-    extractedResult(): string | Record<string, any> | Record<string, any>[];
+    writePatchFile(patchPath: string, patchContent: string): Promise<string>;
     /**
-     * Toolcall execution result: Feedback to LLM
+     * Apply a patch to a file
+     *
+     * @param patchPath - Path to the patch file
+     * @param patchContent - Optional patch content to write before applying
+     * @returns Success message
      */
-    executedResult(): string | Record<string, any>;
+    applyPatch(patchPath: string, patchContent?: string): Promise<string>;
+    /**
+     * Validate patch format
+     */
+    private _validatePatchFormat;
+    /**
+     * Convert git diff format to unified diff format
+     */
+    private _convertGitDiffToUnifiedDiff;
+    /**
+     * Extract target file path from patch content
+     */
+    private _extractTargetFile;
+    /**
+     * Determine working directory for applying patch
+     */
+    private _determineWorkDir;
+    /**
+     * Apply patch using patch command or manual fallback
+     */
+    private _applyPatch;
+    /**
+     * Execute patch command
+     */
+    private _executePatchCommand;
+    /**
+     * Manually apply patch by parsing unified diff format
+     */
+    private _applyPatchManually;
 }
 
 /**
  * Message history management
  *
- * Converts Python's message_history.py to TypeScript
+ * Converts Python's runtime/memory/message_history.py to TypeScript
  */
 
 /**
@@ -731,77 +682,1410 @@ declare class MessageHistory {
 }
 
 /**
- * Base environment for agent management
+ * AgentConfig - Configuration interface for Agent
  *
- * Converts Python's environment/base.py to TypeScript
+ * Corresponds to Python's core/agent_config.py
+ * Separates configuration from business logic.
  */
 
 /**
- * Instruction type enumeration
- */
-declare enum InstructionType {
-    VALID = "valid",
-    QUIT = "quit",
-    SEND_TO_ALL = "sendToAll",
-    NO_AGENT_NAME = "noAgentName",
-    NO_AVAILABLE_AGENT_NAME = "noAvailableAgentName"
+ * Tool Executor Protocol interface
+ * Will be fully defined in runtime/executors
+ */
+interface ToolExecutorProtocol$1 {
+    start(): Promise<void>;
+    shutdown(options?: {
+        wait?: boolean;
+    }): Promise<void>;
+    submit(toolcall: any): Promise<void>;
+    submitMany(toolcalls: Iterable<any>, options?: {
+        parallel?: boolean;
+    }): Promise<void>;
+    observe(options?: {
+        wait?: boolean;
+        timeout?: number;
+        maxItems?: number;
+    }): Promise<any[]>;
+    waitAll(): Promise<void>;
+    status(): Record<string, any>;
+    clear(): void;
 }
 /**
- * Environment for the agent
+ * Configuration interface for Agent
+ *
+ * This interface encapsulates all configuration parameters for an Agent,
+ * separating configuration management from business logic.
  */
-declare class BaseEnvironment {
+interface AgentConfig {
     /**
-     * List of agents in the environment
+     * Agent identifier for logging and tracking
      */
-    agents: Agent[];
+    name: string;
     /**
-     * Assign skills to agent with their names
+     * Profile of the agent, used as base for system prompt
      */
-    agentSkills: Record<string, string[]>;
-    constructor(agents?: Agent[], agentSkills?: Record<string, string[]>);
+    profile: string;
     /**
-     * Set agent skills after initialization
+     * Custom system prompt (overrides profile if provided)
      */
-    private setAgentSkills;
+    system?: string;
     /**
-     * Check if instruction has agent name
+     * List of tool names available to the agent
      */
-    hasAgentName(instruction: string): boolean;
+    tools?: string[];
+    /**
+     * List of sub-agents that can be called as tools
+     */
+    subAgents?: any[];
+    /**
+     * MCP server names for external tool integration
+     */
+    mcpServerNames?: string[];
+    /**
+     * Whether to use function calling mode
+     */
+    useFunctionCalling?: boolean;
+    /**
+     * User defined model name, which is the key of models in config.yaml
+     * Replaces the legacy modelConfig parameter
+     */
+    udfModelName?: string;
+    /**
+     * Legacy model config (string name or ModelConfig object)
+     * @deprecated Use udfModelName instead
+     */
+    modelConfig?: string | any;
+    /**
+     * Logging verbosity level
+     * 0: off, 1: agent messages, 2: all messages
+     */
+    verbose?: boolean | number;
+    /**
+     * Execute tool calls in parallel
+     * @default false
+     */
+    parallelExecution?: boolean;
+    /**
+     * Tool call observation timeout in seconds
+     * @default 60.0
+     */
+    observeTimeout?: number;
+    /**
+     * Workspace directory for file operations
+     */
+    workspaceDir?: string;
+    /**
+     * Auto-shutdown executor when agent completes
+     * Warning: Don't set to true in multi-agent mode as agents share executors
+     * @default false
+     */
+    autoShutdownExecutor?: boolean;
+    /**
+     * Post-processor for final output
+     */
+    postProcessor?: PostProcessor;
+    /**
+     * Custom tool executor
+     */
+    executor?: ToolExecutorProtocol$1;
+    /**
+     * Pre-initialized message history
+     */
+    chatHistoryMessage?: any;
+    /**
+     * Custom agent ID (auto-generated if not provided)
+     */
+    agentId?: string;
+    /**
+     * Skill names to load and inject into system prompt
+     */
+    skills?: string[];
+    /**
+     * Paths to rule files for future injection (reserved)
+     */
+    rulePaths?: string[];
+    /**
+     * Spec content or path for future injection (reserved)
+     */
+    spec?: string;
+    /**
+     * Few-shot examples
+     */
+    fewShot?: string;
+    /**
+     * Tool call manager pool size
+     * @default 5
+     */
+    toolcallManagerPoolSize?: number;
+}
+
+/**
+ * Main Agent class with tool use capabilities
+ *
+ * Converts Python's core/agent.py to TypeScript
+ */
+
+/**
+ * Main Agent class
+ */
+declare class Agent {
+    name: string;
+    private profile;
+    private system;
+    private tools;
+    private functionCallingTools;
+    private mcpServerNames;
+    private modelConfig;
+    private verbose;
+    private model;
+    private history;
+    private subAgents;
+    private toolcallManagerPoolSize;
+    private postProcessor;
+    private useFunctionCalling;
+    agentId: string;
+    workspaceDir: string;
+    executor: ToolExecutorProtocol$1 | null;
+    autoShutdownExecutor: boolean;
+    private parallelExecution;
+    private observeTimeout;
+    private skills;
+    constructor(config: AgentConfig);
+    /**
+     * Get the current system prompt
+     */
+    get systemPrompt(): string;
+    /**
+     * Set the system prompt and update history
+     */
+    set systemPrompt(value: string);
+    /**
+     * Set the system prompt with system tools descriptions
+     * @private
+     */
+    private setSystem;
+    /**
+     * Set up function calling tools for OpenAI-style function calling
+     * @private
+     */
+    private setFunctionCallingTools;
+    /**
+     * Agent loop - processes user input and handles tool calls
+     * @private
+     */
+    private _agentLoop;
+    /**
+     * Run the agent with given instruction
+     */
+    run(instruction: string, images?: string | string[]): Promise<string | any>;
+    /**
+     * Get agent profile
+     */
+    getProfile(): string;
+    /**
+     * Get tools
+     */
+    getTools(): string[];
+    /**
+     * Get function calling tools schemas
+     */
+    getFunctionCallingTools(): any[];
+    /**
+     * Get MCP server names
+     */
+    getMcpServerNames(): string[];
+    /**
+     * Get model config (string or ModelConfig object)
+     */
+    getModelConfig(): string | ModelConfig;
+    /**
+     * Get model name (for backward compatibility)
+     */
+    getModelName(): string;
+    /**
+     * Get verbose setting
+     */
+    getVerbose(): boolean | number;
+    /**
+     * Get sub-agents
+     */
+    getSubAgents(): any[];
+    /**
+     * Get agent ID
+     */
+    getAgentId(): string;
+    /**
+     * Get workspace directory
+     */
+    getWorkspaceDir(): string;
+    /**
+     * Get parallel execution setting
+     */
+    getParallelExecution(): boolean;
+    /**
+     * Get observe timeout setting
+     */
+    getObserveTimeout(): number;
+    /**
+     * Get skills
+     */
+    getSkills(): string[];
+    /**
+     * Get executor
+     */
+    getExecutor(): ToolExecutorProtocol$1 | null;
+    /**
+     * Set executor
+     */
+    setExecutor(executor: ToolExecutorProtocol$1): void;
+    /**
+     * Get chat history message
+     */
+    get chatHistoryMessage(): MessageHistory;
+}
+
+/**
+ * Model abstraction layer using official SDKs
+ *
+ * Provides a unified interface for multiple LLM providers:
+ * - OpenAI (and compatible APIs like DeepSeek)
+ * - Anthropic Claude
+ * - Google Gemini
+ */
+
+/**
+ * Model response interface
+ */
+interface ModelResponse {
+    type: 'system' | 'user' | 'TaskCompletion';
+    extractedResult: () => string | any[] | Record<string, any>;
+    rawContentFromLlm?: string;
+}
+/**
+ * Model class for interacting with LLM providers
+ * Uses official SDKs for better reliability and type safety
+ */
+declare class Model {
+    private modelName;
+    private config;
+    private openaiClient?;
+    private anthropicClient?;
+    private geminiClient?;
+    constructor(model?: string | ModelConfig);
+    /**
+     * Initialize the appropriate SDK client based on provider
+     */
+    private _initializeClient;
+    /**
+     * Asynchronous chat completion
+     */
+    achat(messages: any[], tools?: any[], stream?: boolean): Promise<ModelResponse[]>;
+    /**
+     * Call OpenAI-compatible API (OpenAI, DeepSeek, etc.)
+     */
+    private _callOpenAICompatible;
+    /**
+     * Call Anthropic API
+     */
+    private _callAnthropic;
+    /**
+     * Call Google Gemini API
+     */
+    private _callGemini;
+    /**
+     * Convert OpenAI format messages to Gemini format
+     */
+    private _convertMessagesToGeminiFormat;
+    /**
+     * Get model configuration
+     */
+    getConfig(): ModelConfig;
+    /**
+     * Get model name
+     */
+    getName(): string;
+    /**
+     * Check if model supports tool calling
+     */
+    supportsToolCalling(): boolean;
+}
+
+/**
+ * Toolcall class and types
+ *
+ * Extracted from src/utils/toolUtil.ts to mirror Python evolt/schemas/toolcall.py
+ */
+/**
+ * Toolcall execution state
+ */
+type ToolcallState = 'pending' | 'running' | 'success' | 'failed';
+/**
+ * Toolcall type
+ */
+type ToolcallType = 'system' | 'user' | 'TaskCompletion';
+/**
+ * Toolcall class representing a single tool call
+ */
+declare class Toolcall {
+    name: string;
+    input: Record<string, any>;
+    isExtractedSuccess: boolean;
+    failedExtractedReason?: string;
+    executedState: ToolcallState;
+    executedContent?: string;
+    toolCallId: string;
+    type: ToolcallType;
+    rawContentFromLlm?: string;
+    constructor(config: {
+        name: string;
+        input?: Record<string, any>;
+        isExtractedSuccess?: boolean;
+        failedExtractedReason?: string;
+        executedState?: ToolcallState;
+        executedContent?: string;
+        toolCallId?: string;
+        type?: ToolcallType;
+        rawContentFromLlm?: string;
+    });
+    /**
+     * Toolcall extraction result description
+     */
+    extractedResult(): string | Record<string, any> | Record<string, any>[];
+    /**
+     * Toolcall execution result: Feedback to LLM
+     */
+    executedResult(): string | Record<string, any>;
+}
+
+/**
+ * Feedback class for environment evaluation results
+ *
+ * Corresponds to Python's schemas/feedback.py
+ * Used by ReflexionOrchestrator for environment feedback
+ */
+
+/**
+ * Feedback class representing evaluation results from an Environment
+ *
+ * Used in Reflexion loops where:
+ * - Actor Agent generates/improves implementation
+ * - Environment evaluates the implementation
+ * - Feedback is returned with pass/fail status and detailed feedback message
+ */
+declare class Feedback {
+    /**
+     * Whether the test/evaluation passed
+     */
+    isPassing: boolean;
+    /**
+     * Detailed feedback message
+     */
+    feedback: Message;
+    constructor(isPassing?: boolean, feedback?: Message);
+    /**
+     * Validate the feedback
+     */
+    private _validate;
+    /**
+     * Convert feedback to a Message, optionally with pre/post content
+     *
+     * @param preContent - Content to prepend to the feedback
+     * @param postContent - Content to append to the feedback
+     * @returns Combined Message
+     */
+    toMessage(preContent?: string, postContent?: string): Message;
+    /**
+     * Merge two messages into one
+     */
+    private _mergeMessages;
+    /**
+     * Format feedback for API calls
+     *
+     * @param preContent - Content to prepend
+     * @param postContent - Content to append
+     * @returns Formatted object for API
+     */
+    formatForApi(preContent?: string, postContent?: string): Record<string, any>;
+    /**
+     * Create a passing feedback
+     */
+    static pass(content: string): Feedback;
+    /**
+     * Create a failing feedback
+     */
+    static fail(content: string): Feedback;
+}
+
+/**
+ * Base orchestrator for multi-agent management
+ *
+ * Renamed from BaseEnvironment to BaseOrchestrator in 0.2.x
+ * Converts Python's runtime/orchestrator/base.py to TypeScript
+ */
+
+/**
+ * Instruction type enumeration
+ */
+declare enum InstructionType {
+    VALID = "valid",
+    QUIT = "quit",
+    SEND_TO_ALL = "sendToAll",
+    NO_AGENT_NAME = "noAgentName",
+    NO_AVAILABLE_AGENT_NAME = "noAvailableAgentName"
+}
+/**
+ * Base orchestrator for multi-agent coordination
+ *
+ * Renamed from BaseEnvironment in Python 0.2.x.
+ * The old "Environment" name now refers to evaluation environments used by Reflexion.
+ */
+declare class BaseOrchestrator {
+    /**
+     * List of agents in the orchestrator
+     */
+    agents: Agent[];
+    /**
+     * Assign skills to agent with their names
+     */
+    agentSkills: Record<string, string[]>;
+    /**
+     * Whether to always wait for human input
+     */
+    alwaysWaitHumanInput: boolean;
+    /**
+     * Maximum number of rounds for agent execution
+     */
+    maxRounds: number;
+    constructor(options?: {
+        agents?: Agent[];
+        agentSkills?: Record<string, string[]>;
+        alwaysWaitHumanInput?: boolean;
+        maxRounds?: number;
+    });
+    /**
+     * Set agent skills after initialization
+     */
+    private setAgentSkills;
+    /**
+     * Check if instruction has agent name
+     */
+    hasAgentName(instruction: string): boolean;
     /**
      * Post process instruction
      */
-    postProcessInstruction(instruction: string, agentNames: string[]): [InstructionType, string];
+    postProcessInstruction(instruction: string, agentNames: string[]): [InstructionType, string];
+    /**
+     * Shutdown all agent executors
+     */
+    shutdownAllExecutors(options?: {
+        wait?: boolean;
+    }): Promise<void>;
+    /**
+     * Run with a single goal until completion (non-interactive mode)
+     */
+    runGoal(goal: string): Promise<void>;
+    /**
+     * Run the orchestrator (interactive mode)
+     */
+    run(instruction?: string): Promise<void>;
+}
+/**
+ * @deprecated Use BaseOrchestrator instead. This alias is kept for backward compatibility.
+ */
+declare const BaseEnvironment: typeof BaseOrchestrator;
+
+/**
+ * Coding orchestrator for multi-agent management
+ *
+ * Renamed from CodingEnvironment to CodingOrchestrator in 0.2.x
+ * Converts Python's runtime/orchestrator/coding.py to TypeScript
+ */
+
+/**
+ * Orchestrator for coding tasks
+ *
+ * Renamed from CodingEnvironment in Python 0.2.x.
+ * Extends BaseOrchestrator with workspace directory management.
+ */
+declare class CodingOrchestrator extends BaseOrchestrator {
+    /**
+     * Workspace directory
+     */
+    workspaceDir: string;
+    constructor(options?: {
+        agents?: Agent[];
+        agentSkills?: Record<string, string[]>;
+        workspaceDir?: string;
+        alwaysWaitHumanInput?: boolean;
+        maxRounds?: number;
+    });
+    /**
+     * Set workspace directory after initialization
+     */
+    private setWorkspaceDir;
+}
+/**
+ * @deprecated Use CodingOrchestrator instead. This alias is kept for backward compatibility.
+ */
+declare const CodingEnvironment: typeof CodingOrchestrator;
+
+/**
+ * Abstract Environment class for Reflexion evaluation
+ *
+ * This is a NEW concept in 0.2.x, different from the old BaseEnvironment
+ * (which has been renamed to BaseOrchestrator).
+ *
+ * The Environment is used by ReflexionOrchestrator to:
+ * 1. Evaluate implementations against test cases
+ * 2. Provide feedback on whether tests pass or fail
+ * 3. Support iterative improvement cycles
+ *
+ * Corresponds to Python's runtime/environment/base.py
+ */
+
+/**
+ * Environment options
+ */
+interface EnvironmentOptions {
+    /**
+     * Path to the initial implementation file
+     */
+    initImpl: string;
+    /**
+     * Path to the improved implementation file
+     * Must be different from initImpl
+     */
+    improvedImpl: string;
+    /**
+     * Arguments passed to step() for initial implementation
+     */
+    initStepKwargs?: Record<string, any>;
+    /**
+     * Arguments passed to step() for improved implementation
+     */
+    improvedStepKwargs?: Record<string, any>;
+}
+/**
+ * Abstract Environment class for Reflexion evaluation
+ *
+ * Subclasses should implement:
+ * - hasImpl(): Check if implementation exists
+ * - step(): Execute and evaluate implementation, returning Feedback
+ */
+declare abstract class Environment {
+    /**
+     * Arguments for the step method (initial implementation)
+     */
+    initStepKwargs: Record<string, any>;
+    /**
+     * Arguments for the step method (improved implementation)
+     */
+    improvedStepKwargs: Record<string, any>;
+    /**
+     * Path to the initial implementation file
+     */
+    initImpl: string;
+    /**
+     * Path to the improved implementation file
+     */
+    improvedImpl: string;
+    constructor(options: EnvironmentOptions);
+    /**
+     * Initialize the improved implementation by copying from init
+     */
+    private _initImprovedImpl;
+    /**
+     * Check if the initial implementation exists
+     */
+    abstract hasImpl(): boolean;
+    /**
+     * Check if the improved implementation exists
+     */
+    hasImprovedImpl(): boolean;
+    /**
+     * Execute and evaluate the implementation
+     *
+     * This method should:
+     * 1. Run the implementation (or tests against it)
+     * 2. Determine if it passes or fails
+     * 3. Return a Feedback object with results
+     *
+     * @param args - Additional arguments
+     * @returns Feedback with isPassing status and feedback message
+     */
+    abstract step(...args: any[]): Promise<Feedback>;
+    /**
+     * Shutdown the environment
+     *
+     * Called when the evaluation is complete or interrupted.
+     * Override to clean up resources.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Evaluate the environment on a benchmark
+     *
+     * TODO: Add benchmark support for self-evolving
+     *
+     * @returns Whether the benchmark passed
+     */
+    bench(): Promise<boolean>;
+}
+
+/**
+ * Reflexion Orchestrator
+ *
+ * Orchestrator for self-improvement loops using actor-critic pattern.
+ *
+ * Corresponds to Python's runtime/orchestrator/reflexion.py
+ */
+
+/**
+ * Configuration for the critic agent
+ */
+interface CriticAgentConfig extends Partial<AgentConfig> {
+    name?: string;
+    profile?: string;
+    tools?: string[];
+    udfModelName?: string;
+    workspaceDir?: string;
+    fewShot?: string;
+    verbose?: boolean | number;
+    saveSelfReflection?: boolean;
+    postContent?: string;
+}
+/**
+ * Configuration for the actor agent
+ */
+interface ActorAgentConfig extends Partial<AgentConfig> {
+    name?: string;
+    profile?: string;
+    tools?: string[];
+    udfModelName?: string;
+    workspaceDir?: string;
+    fewShot?: string;
+    verbose?: boolean | number;
+}
+/**
+ * Options for ReflexionOrchestrator
+ */
+interface ReflexionOrchestratorOptions {
+    /**
+     * The task description
+     */
+    task: string;
+    /**
+     * The type of task (e.g., "coding", "writing")
+     */
+    taskType: string;
+    /**
+     * The type of feedback expected
+     */
+    feedbackType: string;
+    /**
+     * The evaluation environment
+     */
+    environment: Environment;
+    /**
+     * Configuration for the critic agent
+     */
+    criticAgentConfig?: CriticAgentConfig;
+    /**
+     * Configuration for the actor agent
+     */
+    actorAgentConfig?: ActorAgentConfig;
+    /**
+     * Maximum number of reflection rounds
+     */
+    maxIterations?: number;
+}
+/**
+ * Result of a reflexion run
+ */
+interface ReflexionResult {
+    success: boolean;
+    iterations: number;
+    finalOutput: string;
+}
+/**
+ * Reflexion Orchestrator for self-improvement loops
+ *
+ * Implements the Reflexion pattern:
+ * 1. Environment evaluates current implementation
+ * 2. Critic agent generates self-reflection based on feedback
+ * 3. Actor agent improves implementation based on reflection
+ * 4. Repeat until passing or max iterations reached
+ */
+declare class ReflexionOrchestrator {
+    private task;
+    private taskType;
+    private feedbackType;
+    private environment;
+    private criticAgentConfig;
+    private actorAgentConfig;
+    private maxIterations;
+    constructor(options: ReflexionOrchestratorOptions);
+    /**
+     * Create system prompt for critic agent
+     */
+    private createCriticSystemPrompt;
+    /**
+     * Create system prompt for actor agent
+     */
+    private createActorSystemPrompt;
+    /**
+     * Build history message for critic agent
+     */
+    private buildCriticHistoryMessage;
+    /**
+     * Build history message for actor agent
+     */
+    private buildActorHistoryMessage;
+    /**
+     * Run the reflexion loop
+     */
+    run(): Promise<ReflexionResult>;
+}
+
+/**
+ * Tool Executor Protocol definitions
+ *
+ * Corresponds to Python's runtime/executors/base.py
+ *
+ * This module defines the protocol interfaces for tool execution:
+ * - GeneratedToolcallProtocol: Represents a parsed tool call from LLM output
+ * - ExecutedToolcallProtocol: Represents the result of executing a tool call
+ * - ToolExecutorProtocol: Interface for tool execution backends
+ */
+/**
+ * Source of the tool call
+ */
+type ToolcallSource = 'chat' | 'function_call';
+/**
+ * Protocol for a generated tool call (parsed from LLM output)
+ */
+interface GeneratedToolcallProtocol {
+    /**
+     * Name of the tool to execute
+     */
+    toolName: string;
+    /**
+     * Arguments for the tool
+     */
+    toolArguments: Record<string, any>;
+    /**
+     * Unique identifier for this tool call
+     */
+    toolCallId: string;
+    /**
+     * Source of the tool call (chat = XML extraction, function_call = OpenAI function calling)
+     */
+    source: ToolcallSource;
+    /**
+     * Whether the tool call was successfully parsed
+     */
+    isSuccess: boolean;
+    /**
+     * Reason for failure if isSuccess is false
+     */
+    failedReason?: string;
+    /**
+     * Raw content from LLM that generated this tool call
+     */
+    rawContentFromLlm?: string;
     /**
-     * Run with a single goal until completion (non-interactive mode)
+     * Idempotency key for deduplication
      */
-    runGoal(goal: string): Promise<void>;
+    idempotencyKey: string;
+}
+/**
+ * Protocol for an executed tool call (result)
+ */
+interface ExecutedToolcallProtocol {
+    /**
+     * The original tool call metadata
+     */
+    metadata: GeneratedToolcallProtocol;
+    /**
+     * Whether the tool execution was successful
+     */
+    isSuccess: boolean;
+    /**
+     * Result of the tool execution (can be any type)
+     */
+    result: any;
+}
+/**
+ * Status information returned by executor.status()
+ */
+interface ExecutorStatus {
+    /**
+     * Number of pending tasks in queue
+     */
+    pending: number;
+    /**
+     * Number of currently running tasks
+     */
+    running: number;
+    /**
+     * Number of completed tasks
+     */
+    finished: number;
+    /**
+     * Number of failed tasks
+     */
+    failed: number;
+    /**
+     * Total tasks submitted
+     */
+    totalSubmitted: number;
+    /**
+     * Whether the executor is running
+     */
+    isRunning: boolean;
+}
+/**
+ * Protocol interface for tool executors
+ *
+ * Tool executors are responsible for:
+ * 1. Managing a pool of concurrent tool executions
+ * 2. Tracking execution status and results
+ * 3. Providing idempotency (avoiding duplicate executions)
+ */
+interface ToolExecutorProtocol {
     /**
-     * Run the environment (interactive mode)
+     * Initialize executor resources
      */
-    run(): Promise<void>;
+    start(): Promise<void>;
+    /**
+     * Shutdown executor and optionally wait for running tasks
+     *
+     * @param options.wait - Whether to wait for running tasks to complete
+     */
+    shutdown(options?: {
+        wait?: boolean;
+    }): Promise<void>;
+    /**
+     * Submit a tool call for background execution (non-blocking)
+     *
+     * @param toolcall - The tool call to execute
+     */
+    submit(toolcall: GeneratedToolcallProtocol): Promise<void>;
+    /**
+     * Submit multiple tool calls
+     *
+     * @param toolcalls - Tool calls to execute
+     * @param options.parallel - Whether to execute in parallel (default: true)
+     */
+    submitMany(toolcalls: Iterable<GeneratedToolcallProtocol>, options?: {
+        parallel?: boolean;
+    }): Promise<void>;
+    /**
+     * Observe finished executions
+     *
+     * @param options.wait - Whether to wait for results
+     * @param options.timeout - Timeout in seconds
+     * @param options.maxItems - Maximum number of items to return
+     * @returns List of executed tool calls
+     */
+    observe(options?: {
+        wait?: boolean;
+        timeout?: number;
+        maxItems?: number;
+    }): Promise<ExecutedToolcallProtocol[]>;
+    /**
+     * Wait until all submitted tool calls are finished
+     */
+    waitAll(): Promise<void>;
+    /**
+     * Return executor runtime status
+     */
+    status(): ExecutorStatus;
+    /**
+     * Clear finished execution results
+     */
+    clear(): void;
 }
+/**
+ * Helper function to create a GeneratedToolcallProtocol from basic info
+ */
+declare function createGeneratedToolcall(options: {
+    toolName: string;
+    toolArguments: Record<string, any>;
+    toolCallId?: string;
+    source?: ToolcallSource;
+    rawContentFromLlm?: string;
+}): GeneratedToolcallProtocol;
+/**
+ * Helper function to create an ExecutedToolcallProtocol
+ */
+declare function createExecutedToolcall(metadata: GeneratedToolcallProtocol, isSuccess: boolean, result: any): ExecutedToolcallProtocol;
+
+/**
+ * Tool execution utilities
+ *
+ * Corresponds to Python's runtime/executors/utils.py
+ */
+
+/**
+ * Execute a single tool and handle errors
+ *
+ * @param generatedToolcall - The tool call to execute
+ * @param toolStore - Tool store(s) containing the tool implementations
+ * @returns Executed tool call result
+ */
+declare function _executeSingleTool(generatedToolcall: GeneratedToolcallProtocol, toolStore: ToolStore | ToolStore[]): Promise<ExecutedToolcallProtocol>;
+/**
+ * Execute multiple tools sequentially
+ *
+ * @param toolcalls - Tool calls to execute
+ * @param toolStore - Tool store(s) containing the tool implementations
+ * @returns Array of executed tool call results
+ */
+declare function executeToolsSequential(toolcalls: GeneratedToolcallProtocol[], toolStore: ToolStore | ToolStore[]): Promise<ExecutedToolcallProtocol[]>;
+/**
+ * Execute multiple tools in parallel
+ *
+ * @param toolcalls - Tool calls to execute
+ * @param toolStore - Tool store(s) containing the tool implementations
+ * @param maxConcurrency - Maximum concurrent executions (default: 5)
+ * @returns Array of executed tool call results
+ */
+declare function executeToolsParallel(toolcalls: GeneratedToolcallProtocol[], toolStore: ToolStore | ToolStore[], maxConcurrency?: number): Promise<ExecutedToolcallProtocol[]>;
 
 /**
- * Coding environment for agent management
+ * LocalToolExecutor - Local tool executor implementation
  *
- * Converts Python's environment/coding.py to TypeScript
+ * Implements ToolExecutorProtocol for local execution:
+ * - Background async tool call execution
+ * - Configurable concurrency limits
+ * - Task queue management
+ * - Execution result observation
+ * - Background process management
+ *
+ * Corresponds to Python's runtime/executors/local_executor.py
+ */
+
+/**
+ * Get current executor from context
+ */
+declare function getCurrentExecutor(): LocalToolExecutor | null;
+/**
+ * Set current executor in context
  */
+declare function setCurrentExecutor(executor: LocalToolExecutor | null): void;
+/**
+ * Local tool executor implementation
+ *
+ * Implements ToolExecutorProtocol for local execution.
+ */
+declare class LocalToolExecutor implements ToolExecutorProtocol {
+    private poolSize;
+    private toolStores;
+    private semaphore;
+    private pendingTasks;
+    private runningTasks;
+    private finishedResults;
+    private successTasks;
+    private failedTasks;
+    private totalSubmitted;
+    private totalFinished;
+    private totalFailed;
+    private started;
+    private isShutdown;
+    private backgroundProcesses;
+    constructor(poolSize?: number, toolStores?: ToolStore[]);
+    start(): Promise<void>;
+    shutdown(options?: {
+        wait?: boolean;
+    }): Promise<void>;
+    submit(toolcall: GeneratedToolcallProtocol): Promise<void>;
+    submitMany(toolcalls: Iterable<GeneratedToolcallProtocol>, options?: {
+        parallel?: boolean;
+    }): Promise<void>;
+    observe(options?: {
+        wait?: boolean;
+        timeout?: number;
+        maxItems?: number;
+    }): Promise<ExecutedToolcallProtocol[]>;
+    waitAll(): Promise<void>;
+    status(): ExecutorStatus;
+    clear(): void;
+    private _executeToolcall;
+    registerBackgroundProcess(process: ChildProcess, command: string, cwd: string): string;
+    listBackgroundProcesses(): string;
+    stopBackgroundProcess(processId: string, force?: boolean): Promise<string>;
+    cleanupBackgroundProcesses(): Promise<string>;
+}
 
 /**
- * Environment for coding
+ * Agent State Store Protocol and Record Model
+ *
+ * Defines the interface for agent state persistence backends.
+ *
+ * Corresponds to Python's runtime/state/store.py
+ */
+/**
+ * Record type for state persistence
  */
-declare class CodingEnvironment extends BaseEnvironment {
+type StateRecordType = 'message' | 'tool_call' | 'instruction' | 'system' | 'completion';
+/**
+ * A single state record for persistence
+ */
+interface StateRecord {
     /**
-     * Workspace directory
+     * Session identifier
      */
-    workspaceDir: string;
-    constructor(agents?: Agent[], agentSkills?: Record<string, string[]>, workspaceDir?: string);
+    sessionId: string;
     /**
-     * Set workspace directory after initialization
+     * Agent name
      */
-    private setWorkspaceDir;
+    agentName: string;
+    /**
+     * Unix timestamp when the record was created
+     */
+    timestamp: number;
+    /**
+     * Record type
+     */
+    type: StateRecordType;
+    /**
+     * The actual payload data (serialized message or toolcall)
+     */
+    data: Record<string, any>;
+}
+/**
+ * Session metadata information
+ */
+interface SessionMeta {
+    /**
+     * Session identifier
+     */
+    sessionId: string;
+    /**
+     * Session creation timestamp (Unix timestamp)
+     */
+    timestamp: number;
+    /**
+     * First instruction content for display (optional)
+     */
+    firstInstruction?: string;
+    /**
+     * List of agent names that have records in this session
+     */
+    agents: string[];
+}
+/**
+ * Protocol interface for agent state persistence backends
+ *
+ * All implementations must provide async append, getAll, and clear methods.
+ * The sessionId + agentName combination uniquely identifies a record set.
+ */
+interface AgentStateStore {
+    /**
+     * Append a single state record
+     *
+     * @param sessionId - Session identifier
+     * @param agentName - Agent name
+     * @param record - Record data containing type, data, and timestamp
+     */
+    append(sessionId: string, agentName: string, record: Omit<StateRecord, 'sessionId' | 'agentName'>): Promise<void>;
+    /**
+     * Get all records for a session/agent combination
+     *
+     * @param sessionId - Session identifier
+     * @param agentName - Agent name
+     * @returns List of StateRecord objects ordered by timestamp
+     */
+    getAll(sessionId: string, agentName: string): Promise<StateRecord[]>;
+    /**
+     * Clear all records for a session/agent combination
+     *
+     * @param sessionId - Session identifier
+     * @param agentName - Agent name
+     */
+    clear(sessionId: string, agentName: string): Promise<void>;
+    /**
+     * Export records to a JSON file
+     *
+     * @param sessionId - Session identifier
+     * @param agentName - Agent name
+     * @param filename - Output file path
+     */
+    exportJson(sessionId: string, agentName: string, filename: string): void;
+    /**
+     * Import records from a JSON file
+     *
+     * @param filename - Input file path
+     */
+    importJson(filename: string): void;
+    /**
+     * Delete the last n records for a session/agent combination
+     *
+     * Records are ordered by timestamp, and the last n records
+     * (most recent) will be deleted.
+     *
+     * @param sessionId - Session identifier
+     * @param agentName - Agent name
+     * @param n - Number of records to delete from the end
+     * @returns Number of records actually deleted
+     */
+    deleteLastN(sessionId: string, agentName: string, n: number): Promise<number>;
+    /**
+     * Check if a session exists (regardless of agent)
+     *
+     * This method checks if any records exist for the given sessionId,
+     * without filtering by agentName. Useful for distinguishing between
+     * "session does not exist" and "session exists but agent has no records".
+     *
+     * @param sessionId - Session identifier
+     * @returns True if any records exist for this sessionId, False otherwise
+     */
+    sessionExists(sessionId: string): Promise<boolean>;
+    /**
+     * List all available sessions
+     *
+     * @returns List of SessionMeta objects containing session metadata
+     */
+    listSessions(): SessionMeta[];
+    /**
+     * Get list of agent names that have records in a session
+     *
+     * @param sessionId - Session identifier
+     * @returns List of unique agent names in this session
+     */
+    getAgentsInSession(sessionId: string): Promise<string[]>;
+}
+/**
+ * Create a StateRecord from data
+ */
+declare function createStateRecord(sessionId: string, agentName: string, type: StateRecordType, data: Record<string, any>): StateRecord;
+
+/**
+ * JSONL Agent State Store Implementation
+ *
+ * File-based persistence using JSON Lines format for append-friendly storage.
+ *
+ * Corresponds to Python's runtime/state/jsonl_store.py
+ */
+
+/**
+ * JSONL file-based state store implementation
+ *
+ * Stores records as JSON Lines (one JSON object per line) for efficient
+ * append operations. Each session gets its own file named by session_id.
+ *
+ * File naming: {session_id}.jsonl
+ */
+declare class JsonlAgentStateStore implements AgentStateStore {
+    private storageDir;
+    private maxSessions;
+    private sessionFileMap;
+    /**
+     * Create a new JSONL state store
+     *
+     * @param storageDir - Directory to store JSONL files. Defaults to ~/.evolt/state/
+     * @param maxSessions - Maximum number of session files to keep. Older sessions are automatically cleaned up.
+     */
+    constructor(storageDir?: string, maxSessions?: number);
+    /**
+     * Load existing session_id to file mappings from disk
+     */
+    private _loadSessionMap;
+    /**
+     * Get existing file path for session or create a new one
+     */
+    private _getOrCreateFilePath;
+    /**
+     * Cleanup old session files to maintain max_sessions limit
+     */
+    private _cleanupOldSessions;
+    /**
+     * Get the latest record timestamp from a session file
+     */
+    private _getLatestTimestamp;
+    append(sessionId: string, agentName: string, record: Omit<StateRecord, 'sessionId' | 'agentName'>): Promise<void>;
+    getAll(sessionId: string, agentName: string): Promise<StateRecord[]>;
+    clear(sessionId: string, agentName: string): Promise<void>;
+    exportJson(sessionId: string, agentName: string, filename: string): void;
+    importJson(filename: string): void;
+    deleteLastN(sessionId: string, agentName: string, n: number): Promise<number>;
+    sessionExists(sessionId: string): Promise<boolean>;
+    listSessions(): SessionMeta[];
+    getAgentsInSession(sessionId: string): Promise<string[]>;
 }
 
+/**
+ * Persistence Context Management
+ *
+ * Provides:
+ * - Process-level session_id management (shared across all agents)
+ * - Agent name tracking (per async context)
+ * - Global store management for single-store-per-process pattern
+ *
+ * Corresponds to Python's runtime/state/context.py
+ */
+
+/**
+ * Use a specific session_id for restoring a historical session.
+ *
+ * @param sessionId - The session ID to restore from.
+ * @param options.skipExecutorRestore - If true, skip restoring executor state (tool calls).
+ *
+ * @throws Error if session_id has already been set
+ */
+declare function useSessionId(sessionId: string, options?: {
+    skipExecutorRestore?: boolean;
+}): void;
+/**
+ * Get current session_id, or auto-create one if not set.
+ *
+ * The same session_id is shared across the entire process runtime.
+ * Auto-created sessions will not attempt to restore.
+ */
+declare function getOrCreateSessionId(): string;
+/**
+ * Get current session_id, or null if not set (will not auto-create).
+ */
+declare function getSessionId(): string | null;
+/**
+ * Check if this is a new session (auto-created, no restore needed).
+ */
+declare function isNewSession(): boolean;
+/**
+ * Reset session_id (for testing or when starting a new session).
+ */
+declare function resetSessionId(): void;
+/**
+ * Check if executor restore should be skipped during session recovery.
+ */
+declare function shouldSkipExecutorRestore(): boolean;
+/**
+ * Enable the global state store for persistence.
+ *
+ * Call this once at application startup to set up persistence.
+ * All agents will automatically use this store.
+ *
+ * @param store - A pre-configured store instance. If not provided, creates a default JSONL store.
+ * @param options.backend - Store backend type: "jsonl". Used if store is null.
+ * @param options.storageDir - Directory for state storage. Defaults to ~/.evolt/state.
+ * @returns The configured global store instance.
+ */
+declare function enableStateStore(store?: AgentStateStore | null, options?: {
+    backend?: 'jsonl';
+    storageDir?: string;
+}): AgentStateStore | null;
+/**
+ * Get the global persistence store.
+ *
+ * @returns The global store instance, or null if not configured.
+ */
+declare function getGlobalStore(): AgentStateStore | null;
+/**
+ * Check if persistence is enabled globally.
+ *
+ * @returns True if a global store is configured.
+ */
+declare function isPersistenceEnabled(): boolean;
+/**
+ * Set the current agent name.
+ *
+ * @param agentName - Agent name to set
+ */
+declare function setAgentName(agentName: string): void;
+/**
+ * Get the current agent name.
+ *
+ * @returns Current agent name, or null if not set
+ */
+declare function getAgentName(): string | null;
+/**
+ * Reset the agent name.
+ */
+declare function resetAgentName(): void;
+
+/**
+ * Persistent State Decorator
+ *
+ * Decorator for automatically persisting state changes after successful
+ * function execution.
+ *
+ * Corresponds to Python's runtime/state/decorator.py
+ */
+
+/**
+ * Decorator to persist state after successful function execution.
+ *
+ * This decorator records state changes to the persistence store after
+ * the decorated function completes successfully.
+ *
+ * @param recordType - Type of record to create ("message" or "tool_call")
+ *
+ * @example
+ * ```typescript
+ * class MyClass {
+ *   @persistentState("message")
+ *   async addMessage(message: Message): Promise<void> {
+ *     // ... add message logic ...
+ *   }
+ * }
+ * ```
+ */
+declare function persistentState(recordType: StateRecordType): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Decorator to handle session state for Agent.run method.
+ *
+ * This decorator manages the session lifecycle:
+ * 1. Get or create session_id
+ * 2. Set agent_name context
+ * 3. Try restore from state store (if applicable)
+ * 4. On success, record completion event
+ *
+ * @example
+ * ```typescript
+ * class Agent {
+ *   @agentAutoRestore
+ *   async run(instruction: string): Promise<string> {
+ *     // ... run logic ...
+ *   }
+ * }
+ * ```
+ */
+declare function agentAutoRestore(target: any, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+
+/**
+ * Tools prompts and output format templates
+ *
+ * Converts Python's prompts/tools.py to TypeScript
+ */
+declare const REFLECT_OUTPUT_FORMAT_PROMPT = "**Reflection Prompt: Output Format Error**  \nYour output does not follow the required XML format:  \n<OutputFormat>  \n<ToolName.method_name><arg1_name>value1</arg1_name><arg2_name>value2</arg2_name></ToolName.method_name>  \n</OutputFormat>  \n\nYour erroneous output:  \n{output_text}  \n\nPlease analyze the format discrepancies and re-output, ensuring:  \n\n- Use the correct XML tag structure  \n- All tags are properly closed  \n- Parameter values are placed within the corresponding tags  \n\nRe-output:  \n";
+/**
+ * Simplified output format prompt (aligned with Python 0.2.2)
+ *
+ * This version removes the task classification (Generative/Analytical/Operational)
+ * and uses a unified react-style format.
+ */
+declare const OUTPUT_FORMAT_PROMPT = "<OutputFormat>\n\nYou should use one tool or multiple tools (depends on your task), follow the format below, replace the <ToolName.method_name> and <args_name> with the actual tool name.\n\nThought: ...\nAction: <ToolName1.method_name1><args_name1>args_value1</args_name1><args_name2>args_value2</args_name2>...</ToolName1.method_name1>\n\n**YOUR OUTPUT MUST INCLUDE THE ACTUAL <args_name> AND <args_value>!!!**\n**If the task is completed, simply return the completion information like <TaskCompletion>your_completion_information</TaskCompletion>, No any tool call should be included.**\n</OutputFormat>\n";
+/**
+ * Tools prompt template (new name aligned with Python 0.2.2)
+ *
+ * Placeholders:
+ * - {available_tools}: List of available tool names
+ * - {desc_of_tools}: Descriptions of available tools
+ * - {output_format}: Output format instructions
+ */
+declare const TOOLS_PROMPT = "\n## Tools And Tool Calls Format\n\nTools are represented by a predefined XML-like syntax structure. This structure encapsulates parameter lists within tags such as `<ToolName.method_name>`. \nBy identifying and matching keywords inside these tags, the system automatically parses the target tool name and its corresponding input parameter values to execute subsequent tool calls.\n\n### Available Tools\n{available_tools}\n\n### Description of Available Tools\n{desc_of_tools}\n\n### Output Format\n{output_format}\n";
+/**
+ * System tools prompt template (legacy name, kept for backward compatibility)
+ *
+ * @deprecated Use TOOLS_PROMPT instead. This is an alias with camelCase placeholders.
+ *
+ * Placeholders:
+ * - {availableSystemTools}: List of available tool names
+ * - {descOfSystemTools}: Descriptions of available tools
+ * - {outputFormat}: Output format instructions
+ */
+declare const SYSTEM_TOOLS_PROMPT = "\n## System Tools And System Tools Call Format\n\nSystem Tools are represented by a predefined XML-like syntax structure. This structure encapsulates parameter lists within tags such as `<ToolName.method_name>`.\nBy identifying and matching keywords inside these tags, the system automatically parses the target tool name and its corresponding input parameter values to execute subsequent tool calls.\n\n### Available System Tools\n{availableSystemTools}\n\n### Description of Available System Tools\n{descOfSystemTools}\n\n### System Tools Output Format\n{outputFormat}\n";
+
 /**
  * Model configuration loader
  *
@@ -1005,6 +2289,35 @@ declare function getSettings(): AppSettings;
  */
 declare function updateSettings(newSettings: Partial<AppSettings>): void;
 
+/**
+ * Deprecated decorator for marking methods as deprecated
+ *
+ * Corresponds to Python's utils/deprecated.py
+ */
+interface DeprecatedOptions {
+    version?: string;
+    replacement?: string;
+}
+/**
+ * Decorator to mark a method as deprecated.
+ * Logs a warning when the method is called.
+ *
+ * @param options - Configuration options
+ * @param options.version - Version in which the method will be removed
+ * @param options.replacement - Suggested replacement method
+ *
+ * @example
+ * ```typescript
+ * class MyClass {
+ *   @deprecated({ version: '0.2.2', replacement: 'formatForApi' })
+ *   oldMethod() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+declare function deprecated(options?: DeprecatedOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+
 /**
  * Winston logger configuration
  *
@@ -1049,4 +2362,4 @@ declare const _default: {
     getDisableLog: () => boolean;
 };
 
-export { Agent, type AgentConfig, ApiTool, type AppSettings, BaseEnvironment, CodingEnvironment, CommandLineTool, DEFAULT_CONFIG, DEFAULT_SETTINGS, ENV_VARS, ERROR_MESSAGES, type EnvironmentConfig, EvoltError, ExtendStateMachineTool, FileEditor, FunctionCallingStore, GitTool, LOG_LEVELS, MESSAGE_ROLES, Message, MessageHistory, Model, type ModelConfig, ModelError, type ModelResponse$1 as ModelResponse, type PostProcessor, ReflectTool, Reply2HumanTool, SKILLS_DIR, SkillsTool, SystemToolStore, TOOL_CALL_TYPES, TOOL_CONSTANTS, ThinkTool, TodoListTool, type ToolCall, type ToolDescription, ToolExecutionError, type ToolStore, Toolcall, type ToolcallState, type ToolcallType, UserToolStore, WORKSPACE_DIR, WriteUIDesignDocument, ensureDir, fileExists, getCacheDir, getConfigDir, getConfigPath, getFileExtension, getLogsDir, getSettings, getSkillsDir, getTempFilePath, getWorkspaceDir, getWorkspacePath, initializeSettings, isInWorkspace, loadModelConfig, _default as logger, normalizePath, registerAgentAsTool, settings, tools, updateSettings };
+export { type ActorAgentConfig, Agent, type AgentConfig, type AgentStateStore, ApiTool, type AppSettings, BaseEnvironment, BaseOrchestrator, CodingEnvironment, CodingOrchestrator, CommandLineTool, type CriticAgentConfig, DEFAULT_CONFIG, DEFAULT_SETTINGS, ENV_VARS, ERROR_MESSAGES, Environment, type EnvironmentConfig, type EnvironmentOptions, EvoltError, type ExecutedToolcallProtocol, type ExecutorStatus, ExtendStateMachineTool, Feedback, FileEditor, FunctionCallingStore, type GeneratedToolcallProtocol, GitTool, type ImageContent, ImageTool, InstructionType, JsonlAgentStateStore, LOG_LEVELS, LocalToolExecutor, MESSAGE_ROLES, Message, MessageHistory, Model, type ModelConfig, ModelError, type ModelResponse, OUTPUT_FORMAT_PROMPT, PatchTool, type PostProcessor, REFLECT_OUTPUT_FORMAT_PROMPT, ReflectTool, ReflexionOrchestrator, type ReflexionOrchestratorOptions, type ReflexionResult, Reply2HumanTool, SKILLS_DIR, SYSTEM_TOOLS_PROMPT, type SessionMeta, SkillsTool, type StateRecord, type StateRecordType, SystemToolStore, TOOLS_PROMPT, TOOL_CALL_TYPES, TOOL_CONSTANTS, ThinkTool, TodoListTool, type ToolCall, type ToolDescription, ToolExecutionError, type ToolExecutorProtocol$1 as ToolExecutorProtocol, type ToolStore, Toolcall, type ToolcallSource, type ToolcallState, type ToolcallType, UserToolStore, WORKSPACE_DIR, WriteUIDesignDocument, _executeSingleTool, agentAutoRestore, areadImage, createExecutedToolcall, createGeneratedToolcall, createStateRecord, deprecated, enableStateStore, ensureDir, executeToolsParallel, executeToolsSequential, fileExists, getAgentName, getCacheDir, getConfigDir, getConfigPath, getCurrentExecutor, getFileExtension, getGlobalStore, getLogsDir, getOrCreateSessionId, getSessionId, getSettings, getSkillsDir, getTempFilePath, getWorkspaceDir, getWorkspacePath, initializeSettings, isInWorkspace, isNewSession, isPersistenceEnabled, isSupportedImageFile, loadModelConfig, _default as logger, normalizePath, persistentState, readImage, registerAgentAsTool, resetAgentName, resetSessionId, setAgentName, setCurrentExecutor, settings, shouldSkipExecutorRestore, tools, updateSettings, useSessionId };