/**
 * Session population utilities for testing compaction, reflection, and observation.
 *
 * Populates sessions with deterministic random messages to reach target token
 * counts, enabling efficient stress testing of the full memory pipeline.
 */
import type { Message } from "../../sdk/ai/types.js";
export interface PopulateSessionOptions {
    /** Seed for reproducible sequences. Default: 42. */
    seed?: number;
    /**
     * Target total tokens in the session.
     * Messages are generated until this approximate token count is reached.
     * Token estimation: 4 chars ≈ 1 token.
     * Default: 20000.
     */
    targetTokens?: number;
    /**
     * Average tokens per user message. Default: 200.
     */
    avgUserTokens?: number;
    /**
     * Average tokens per assistant message. Default: 400.
     */
    avgAssistantTokens?: number;
    /**
     * Ratio of user:assistant messages. Higher = more user messages per assistant.
     * Default: 0.8 (80% user, 20% assistant).
     */
    userMessageRatio?: number;
    /**
     * Include tool result messages between assistant turns. Default: false.
     */
    includeToolResults?: boolean;
    /**
     * Callback for each generated message. Useful for progress reporting.
     */
    onMessage?: (index: number, totalEstimated: number, role: string, charCount: number) => void;
}
export interface PopulateResult {
    /** Total messages generated. */
    messageCount: number;
    /** Estimated total tokens (chars / 4). */
    estimatedTokens: number;
    /** Total characters generated. */
    totalChars: number;
    /** Breakdown by role. */
    breakdown: {
        user: number;
        assistant: number;
        toolResult: number;
    };
}
interface SessionInjector {
    appendMessage(message: Message): void | Promise<void>;
}
/**
 * Generate an array of random messages totaling approximately `targetTokens` tokens.
 *
 * Does NOT require a session — returns the message array for injection into
 * any session or storage system.
 *
 * Token estimation: Math.ceil(text.length / 4).
 */
export declare function generateRandomMessages(options?: PopulateSessionOptions): {
    messages: Message[];
    result: PopulateResult;
};
/**
 * Populate a session-like object with random messages.
 *
 * The injector must implement `appendMessage(message)`.
 * This works with any session manager that exposes message-append capability.
 *
 * @example
 * ```typescript
 * const injector = {
 *   appendMessage(msg: Message) { sessionManager.appendMessage(msg); }
 * };
 * const result = await populateSession(injector, { targetTokens: 20000, seed: 42 });
 * console.log(`Populated ${result.messageCount} messages, ~${result.estimatedTokens} tokens`);
 * ```
 */
export declare function populateSession(injector: SessionInjector, options?: PopulateSessionOptions): Promise<PopulateResult>;
/**
 * Create an in-memory message array injector. Useful for testing without a real session.
 */
export declare function createInMemoryInjector(): {
    messages: Message[];
    injector: SessionInjector;
};
export {};
//# sourceMappingURL=populate.d.ts.map