/**
 * Reflector module for the observational memory system.
 *
 * The Reflector condenses observations when they grow too large. It runs
 * on the utility model and uses progressive compression: starting with
 * no compression guidance (level 0) and escalating through levels 1-4
 * if the output exceeds the target token threshold.
 *
 * References:
 *   - observational-memory-architecture.md (Reflector System section)
 *   - compaction-strategy.md
 */
import type { CompleteFn } from '../compaction.js';
import type { ReflectorOutput } from './types.js';
/**
 * Build the full reflector system prompt.
 *
 * Starts with the base reflector prompt, then appends compression level
 * guidance and optional consumer instructions.
 *
 * @param compressionLevel - Compression level (0-4). Level 0 adds no
 *   compression guidance.
 * @param customInstruction - Optional consumer-provided instruction to
 *   append to the prompt.
 * @returns The assembled system prompt string.
 */
export declare function buildReflectorPrompt(compressionLevel: number, customInstruction?: string): string;
/**
 * Build the message array to send to the reflector LLM.
 *
 * Creates two user messages: one containing the observations to reflect on,
 * and one with the output instruction.
 *
 * @param observations - The full observation text to consolidate.
 * @returns An array of message objects for the LLM call.
 */
export declare function buildReflectorMessages(observations: string): unknown[];
/**
 * Parse the raw LLM output from the reflector.
 *
 * Extracts content from `<observations>` tags if present, strips any
 * analysis/thinking tags, and trims whitespace.
 *
 * @param raw - The raw string output from the reflector LLM call.
 * @returns The cleaned observation text.
 */
export declare function parseReflectorOutput(raw: string): string;
/**
 * Check whether the reflector output is within the target token budget.
 *
 * @param output - The parsed reflector output text.
 * @param targetTokens - The maximum allowed token count.
 * @returns `true` if estimated tokens are at or below the target.
 */
export declare function validateCompression(output: string, targetTokens: number): boolean;
/**
 * Compute the effective reflection threshold by clamping to both the
 * primary model's context window and the utility model's context window.
 *
 * The threshold is the smaller of:
 * - `reflectionThreshold` as a percentage of the primary context window
 * - 50% of the utility model's context window (to ensure the reflector
 *   input fits within the utility model)
 *
 * @param contextWindow - The primary model's context window size in tokens.
 * @param reflectionThreshold - Fraction of the context window (e.g. 0.20).
 * @param utilityModelContextWindow - The utility model's context window
 *   size in tokens.
 * @returns The effective reflection threshold in tokens.
 */
export declare function computeEffectiveReflectionThreshold(contextWindow: number, reflectionThreshold: number, utilityModelContextWindow: number): number;
/**
 * Run the reflector with progressive compression retry.
 *
 * Starts at compression level 0 and escalates if the output exceeds the
 * reflection threshold. Retries up to 3 times, incrementing the
 * compression level each time (capped at level 4).
 *
 * Even if the final attempt does not validate, the best result is returned.
 * The observation slot will be larger than ideal, but the next reflection
 * cycle will try again.
 *
 * @param complete - The LLM completion function.
 * @param observations - The full observation text to consolidate.
 * @param config - Configuration with reflectionThreshold (in tokens) and
 *   optional reflectorInstruction.
 * @returns The reflector output with consolidated observations and the
 *   compression level that was applied.
 */
export declare function runReflector(complete: CompleteFn, observations: string, config: {
    reflectionThreshold: number;
    reflectorInstruction?: string;
}): Promise<ReflectorOutput>;
//# sourceMappingURL=reflector.d.ts.map