/**
 * RunOptions interface and validation for @a5c-ai/agent-mux.
 *
 * Defines the full set of options accepted by `AgentMuxClient.run()`
 * and the validation logic that enforces spec constraints.
 */
import type { AgentName, Attachment, InputRequiredEvent, ApprovalRequestEvent, McpServerConfig, RetryPolicy } from './types.js';
import type { RuntimeHooks } from './runtime-hooks.js';
import type { InvocationMode } from './invocation.js';
export { PROHIBITED_PROFILE_FIELDS, validateProfileData, } from './run-options-validation.js';
/**
 * Full configuration for a single agent run.
 *
 * Only `agent` and `prompt` are required; all other fields are optional
 * and fall back to profile, client, or global defaults.
 */
export interface RunOptions {
    /** The agent to invoke. */
    agent: AgentName;
    /** The prompt to send to the agent. */
    prompt: string | string[];
    /** System prompt text to inject. */
    systemPrompt?: string;
    /** How to combine the system prompt with the agent's default. */
    systemPromptMode?: 'prepend' | 'append' | 'replace';
    /** File or data attachments to include with the prompt. */
    attachments?: Attachment[];
    /** Model identifier (agent-specific). */
    model?: string;
    /** Thinking effort level. */
    thinkingEffort?: 'low' | 'medium' | 'high' | 'max';
    /** Thinking budget in tokens. Must be >= 1024. */
    thinkingBudgetTokens?: number;
    /** Override thinking behavior entirely (agent-specific). */
    thinkingOverride?: Record<string, unknown>;
    /** Sampling temperature. Must be in [0, 2]. */
    temperature?: number;
    /** Top-P nucleus sampling. Must be in [0, 1]. */
    topP?: number;
    /** Top-K sampling. Must be an integer >= 1. */
    topK?: number;
    /** Maximum tokens for the response. Must be >= 1. */
    maxTokens?: number;
    /** Maximum output tokens (alias). Must be >= 1. */
    maxOutputTokens?: number;
    /** Resume an existing session by ID. Mutually exclusive with forkSessionId and noSession. */
    sessionId?: string;
    /** Fork from an existing session. Mutually exclusive with sessionId and noSession. */
    forkSessionId?: string;
    /** Start with no session context. Mutually exclusive with sessionId and forkSessionId. */
    noSession?: boolean;
    /** Enable streaming. */
    stream?: boolean | 'auto';
    /** Output format. */
    outputFormat?: 'text' | 'json' | 'jsonl';
    /** Force headless one-shot prompt delivery instead of stdin-driven interactive transport. */
    nonInteractive?: boolean;
    /**
     * Spawn the harness with a real PTY (via node-pty) so it gets a TTY for
     * interactive features (colors, prompt input, tool approval UIs).
     * Output is tee'd through the event parser so hooks still fire.
     */
    interactive?: boolean;
    /** Working directory for the agent process. Must be an absolute path. */
    cwd?: string;
    /** Additional environment variables for the agent process. */
    env?: Record<string, string>;
    /** Overall run timeout in milliseconds. Must be a non-negative integer. */
    timeout?: number;
    /** Inactivity timeout in milliseconds. Must be a non-negative integer. */
    inactivityTimeout?: number;
    /** Maximum number of agent turns. Must be >= 1. */
    maxTurns?: number;
    /** Approval mode for tool calls and file operations. */
    approvalMode?: 'yolo' | 'prompt' | 'deny';
    /** Callback invoked when the agent requires user input. Returns the input text. */
    onInputRequired?: (event: InputRequiredEvent) => Promise<string>;
    /** Callback invoked when the agent requests tool call approval. Returns the decision. */
    onApprovalRequest?: (event: ApprovalRequestEvent) => Promise<'approve' | 'deny'>;
    /** In-process runtime hooks for this run only. */
    hooks?: RuntimeHooks;
    /** Skills to load for this run. */
    skills?: string[];
    /** Path or content for the agents doc. */
    agentsDoc?: string;
    /** MCP server configurations for this run. */
    mcpServers?: McpServerConfig[];
    /** Retry policy for transient failures. */
    retryPolicy?: RetryPolicy;
    /** Explicit run ID (ULID format, 26 Crockford base32 chars). */
    runId?: string;
    /** Tags for run indexing and filtering. */
    tags?: string[];
    /** Project ID for multi-project setups. */
    projectId?: string;
    /** Named profile to apply as a base layer. Must match `^[a-zA-Z0-9_-]{1,64}$`. */
    profile?: string;
    /** Whether to collect all events in memory. */
    collectEvents?: boolean;
    /** Grace period in milliseconds for cleanup on abort. */
    gracePeriodMs?: number;
    /** Invocation mode — how to spawn the underlying process (local, docker, ssh, k8s). */
    invocation?: InvocationMode;
    /** Provider configuration for model/provider selection. */
    providerConfig?: import('./provider-config.js').ProviderConfig;
    /** Named provider profile from ~/.amux/providers.json. */
    providerProfile?: string;
}
/**
 * Handle returned by `AgentMuxClient.run()`.
 *
 * Full implementation lives in run-handle.ts. Re-exported here for
 * backwards compatibility with imports from run-options.
 */
export type { RunHandle } from './run-handle.js';
/**
 * Validate RunOptions according to the spec validation order.
 *
 * Validation order:
 * 1. Session mutual exclusivity
 * 2. Required fields (agent, prompt non-empty)
 * 3. Range validation for numeric/enum fields
 * 4. Attachment validation
 * 5. McpServerConfig validation
 *
 * @throws ValidationError if any fields are invalid.
 */
export declare function validateRunOptions(options: RunOptions): void;