/** * CodeAgent - Code generation, execution, review, and refactoring * * Python parity with praisonaiagents/agent/code_agent.py */ /** * Configuration for CodeAgent. * Python parity with CodeConfig dataclass. */ export interface CodeConfig { /** * Advisory isolation hint passed through to `executor` (default: true). * * This flag does NOT by itself enable, disable, or sandbox any execution. * It used to: `sandbox: false` was the only setting under which `execute()` * ran anything, and what it ran was in-process `eval()` of model-generated * code. The option that reads as the safety toggle was the dangerous one, so * that path is gone. Code now runs only when an `executor` is supplied * explicitly, and the executor decides what `sandbox` means for it. */ sandbox?: boolean; /** * Explicit code runner. Without one, `execute()` runs nothing and says so. * * Executing model-generated code is opt-in by naming a runner, never by * flipping a boolean. `createSubprocessExecutor()` in this module is a * ready-made out-of-process runner; pass your own to target a container, * a VM, or a remote sandbox service. */ executor?: CodeExecutor; /** Execution timeout in seconds */ timeout?: number; /** List of allowed programming languages */ allowedLanguages?: string[]; /** Maximum output length in characters */ maxOutputLength?: number; /** Working directory for code execution */ workingDirectory?: string; /** Environment variables for execution */ environment?: Record; } /** * Context handed to a {@link CodeExecutor}. */ export interface CodeExecutorContext { /** Advisory isolation hint from `CodeConfig.sandbox`. */ sandbox: boolean; /** Execution timeout in seconds. */ timeout: number; /** Working directory for execution. */ workingDirectory: string; /** Extra environment variables for execution. */ environment: Record; /** Maximum output length in characters. */ maxOutputLength: number; } /** * A pluggable code runner. Supplying one is the only way to make * `CodeAgent.execute()` run code. */ export type CodeExecutor = (code: string, language: string, context: CodeExecutorContext) => Promise; /** * Result of code execution. */ export interface CodeExecutionResult { /** Whether execution was successful */ success: boolean; /** Standard output from execution */ output: string; /** Error message if execution failed */ error?: string; /** Exit code from execution */ exitCode: number; /** Execution time in seconds */ executionTime: number; } /** * Configuration for creating a CodeAgent. */ export interface CodeAgentConfig { /** Agent name */ name?: string; /** LLM model (default: gpt-4o-mini) */ llm?: string; /** Code configuration (bool, object, or CodeConfig) */ code?: boolean | CodeConfig; /** System instructions */ instructions?: string; /** Enable verbose output */ verbose?: boolean; } /** * Agent for code generation, execution, review, and refactoring. * * This agent provides capabilities for: * - Generating code from natural language descriptions * - Executing code in a sandboxed environment * - Reviewing code for issues and improvements * - Refactoring and fixing code * - Explaining code functionality * * @example * ```typescript * import { CodeAgent } from 'praisonai'; * * const agent = new CodeAgent({ name: 'Coder' }); * * // Generate code * const code = await agent.generate('Write a function to calculate fibonacci'); * * // Execute code * const result = await agent.execute("console.log('Hello, World!')"); * * // Review code * const review = await agent.review(code); * ``` */ export declare class CodeAgent { readonly name: string; private readonly llm; private readonly instructions?; private readonly verbose; private readonly codeConfig; private readonly agent; constructor(config: CodeAgentConfig); private buildSystemPrompt; /** * Generate code from natural language description. * * @param prompt - Natural language description of desired code * @param language - Target programming language (default: python) * @returns Generated code as string */ generate(prompt: string, language?: string): Promise; /** * Alias for generate() method. */ generateCode(prompt: string, language?: string): Promise; /** * Execute code in a sandboxed environment. * * @param code - Code to execute * @param language - Programming language (default: python) * @returns Execution result */ execute(code: string, language?: string): Promise; /** * Alias for execute() method. */ executeCode(code: string, language?: string): Promise; /** * Review code for issues and improvements. * * @param code - Code to review * @param language - Programming language * @returns Review feedback */ review(code: string, language?: string): Promise; /** * Alias for review() method. */ reviewCode(code: string, language?: string): Promise; /** * Refactor code for better quality. * * @param code - Code to refactor * @param instructions - Specific refactoring instructions * @returns Refactored code */ refactor(code: string, instructions?: string): Promise; /** * Fix bugs in code. * * @param code - Code with bugs * @param errorMessage - Optional error message to help identify the bug * @returns Fixed code */ fix(code: string, errorMessage?: string): Promise; /** * Explain code functionality. * * @param code - Code to explain * @returns Explanation of the code */ explain(code: string): Promise; } /** * Create a CodeAgent instance. * * @param config - CodeAgent configuration * @returns CodeAgent instance */ export declare function createCodeAgent(config: CodeAgentConfig): CodeAgent; /** * Build an out-of-process code executor for {@link CodeConfig.executor}. * * Importing and passing this function is an explicit, visible decision to run * model-generated code. That is the point: execution is granted by naming a * runner, never by flipping a boolean that reads as a safety toggle. * * The code runs in a child process with its own cwd, environment and timeout, * so it cannot reach into the host process the way the removed in-process * `eval()` path could. A child process is *not* a security sandbox -- it shares * the host filesystem, network and user. For untrusted code use a container, * microVM or remote sandbox service and pass that as the executor instead. * * @example * ```typescript * import { CodeAgent, createSubprocessExecutor } from 'praisonai'; * * const agent = new CodeAgent({ * code: { executor: createSubprocessExecutor(), allowedLanguages: ['python'] }, * }); * const result = await agent.execute('print(2 + 2)', 'python'); * ``` */ export declare function createSubprocessExecutor(interpreters?: Record): CodeExecutor;