import type { AgentDefinition } from '@levelcode/common/templates/initial-agents-dir/types/agent-definition';
/**
 * Agent definition with source file path metadata.
 */
export type LoadedAgentDefinition = AgentDefinition & {
    /** The file path this agent was loaded from */
    _sourceFilePath: string;
};
/**
 * Loaded agent definitions keyed by agent ID.
 */
export type LoadedAgents = Record<string, LoadedAgentDefinition>;
/**
 * Resolves environment variable references in MCP server configs.
 * Values starting with `$` are treated as env var references (e.g., `'$NOTION_TOKEN'`).
 *
 * @param env - The env object from MCP config with possible $VAR_NAME references
 * @param agentId - The agent ID for error messages
 * @param mcpServerName - The MCP server name for error messages
 * @returns Resolved env object with all $VAR_NAME values replaced with actual values
 * @throws Error if a referenced environment variable is missing
 */
export declare function resolveMcpEnv(env: Record<string, string> | undefined, agentId: string, mcpServerName: string): Record<string, string>;
/**
 * Resolves all MCP server env references in an agent definition.
 * Mutates the mcpServers object to replace $VAR_NAME references with resolved values.
 *
 * @param agent - The agent definition to process
 * @throws Error if any referenced environment variable is missing
 */
export declare function resolveAgentMcpEnv(agent: AgentDefinition): void;
/**
 * Validation error for an agent that failed validation.
 */
export type AgentValidationError = {
    /** The agent's ID */
    agentId: string;
    /** The source file path where the agent was loaded from */
    filePath: string;
    /** The validation error message */
    message: string;
};
/**
 * Result returned by loadLocalAgents when validate: true.
 * Contains both the valid agents and any validation errors.
 */
export type LoadLocalAgentsResult = {
    /** Valid agent definitions that passed validation */
    agents: LoadedAgents;
    /** Validation errors for agents that failed validation */
    validationErrors: AgentValidationError[];
};
/**
 * Load agent definitions from `.agents` directories.
 *
 * By default, searches for agents in:
 * - `{cwd}/.agents`
 * - `{cwd}/../.agents`
 * - `{homedir}/.agents`
 *
 * Agent files can be `.ts`, `.tsx`, `.js`, `.mjs`, or `.cjs`.
 * TypeScript files are loaded natively by Bun's runtime.
 *
 * @param options.agentsPath - Optional path to a specific agents directory
 * @param options.verbose - Whether to log errors during loading
 * @param options.validate - Whether to validate agents after loading
 * @returns When validate is false/omitted: Record of agent definitions keyed by agent ID.
 *          When validate is true: Object with valid agents and validation errors.
 *
 * @example
 * ```typescript
 * // Load from default locations
 * const agents = await loadLocalAgents({ verbose: true })
 *
 * // Load from a specific directory
 * const agents = await loadLocalAgents({ agentsPath: './my-agents' })
 *
 * // Load and validate agents - returns both valid agents and errors
 * const { agents, validationErrors } = await loadLocalAgents({ validate: true })
 * if (validationErrors.length > 0) {
 *   console.error('Some agents failed validation:', validationErrors)
 * }
 *
 * // Access source file path for debugging
 * for (const agent of Object.values(agents)) {
 *   console.log(`${agent.id} loaded from ${agent._sourceFilePath}`)
 * }
 *
 * // Use with client.run()
 * const result = await client.run({
 *   agent: 'my-agent',
 *   agentDefinitions: Object.values(agents),
 *   prompt: 'Hello',
 * })
 * ```
 */
export declare function loadLocalAgents(options: {
    agentsPath?: string;
    verbose?: boolean;
    validate: true;
}): Promise<LoadLocalAgentsResult>;
export declare function loadLocalAgents(options: {
    agentsPath?: string;
    verbose?: boolean;
    validate?: false;
}): Promise<LoadedAgents>;
