import type { Usage } from "@caupulican/pi-ai";
import { type PiOkfType } from "../context/okf-memory.ts";
import { REFLECTION_SYSTEM_PROMPT } from "../provider-prompt-contracts.ts";
export { REFLECTION_SYSTEM_PROMPT };
export type StopReason = "stop" | "toolUse" | "aborted" | "error" | string;
export interface IsolatedCompletionResult {
    text: string;
    usage: Usage;
    stopReason: StopReason;
}
export type ReflectionTrigger = "complex" | "corrective" | "durable" | "session-end" | "none";
export interface DemandSignals {
    trigger: ReflectionTrigger;
    toolCallCount: number;
    hadCorrection: boolean;
    contextHeadroomPct: number;
    usefulLately: number;
}
export interface DemandPlan {
    act: "skip" | "reflect";
    reason: string;
    tokenBudget: number;
}
/**
 * Pure zero-I/O heuristic to decide whether the current turn justifies a reflection run
 * and determine the token budget under the cheap-tool net-negative doctrine.
 */
export declare function decideDemand(signals: DemandSignals): DemandPlan;
export interface ReflectionInput {
    recentTurnText: string;
    existingMemory: string;
    plan: DemandPlan;
    complete: (systemPrompt: string, userPrompt: string) => Promise<IsolatedCompletionResult>;
}
export type ReflectionWrite = {
    kind: "memory_add";
    section: "MEMORY" | "USER";
    text: string;
} | {
    kind: "okf_add";
    type: PiOkfType;
    title: string;
    description: string;
    scope: "project";
    text: string;
    tags?: string[];
    evidenceRefs: string[];
} | {
    kind: "okf_organize";
    type: PiOkfType;
    title: string;
    description: string;
    scope: "project";
    text: string;
    sourceText: string;
    tags?: string[];
    evidenceRefs: string[];
} | {
    kind: "memory_replace";
    target: string;
    text: string;
} | {
    kind: "memory_remove";
    target: string;
} | {
    kind: "promote_skill";
    name: string;
    description: string;
    body: string;
};
export interface ReflectionResult {
    writes: ReflectionWrite[];
    usage: Usage;
    rationale: string;
}
/** Maximum number of durable writes accepted from one isolated reflection response. */
export declare const MAX_REFLECTION_WRITES = 32;
/** Maximum number of response entries inspected while looking for accepted writes. */
export declare const MAX_REFLECTION_SCAN_ENTRIES: number;
/**
 * STATIC reflection system prompt (Hermes-parity #33). It is byte-identical across every reflection
 * pass — the variable parts (existing memory snapshot + the turn transcript) live in the USER prompt —
 * so the provider prompt-cache reuses this prefix instead of re-billing it each pass (cost guard).
 * Do NOT interpolate per-call data into this constant or caching breaks.
 */
export declare class ReflectionEngine {
    /**
     * Build the reflection prompt, call the injected isolated complete(),
     * parse the response, confront existing memory, and return memory writes.
     * Zero direct I/O.
     */
    reflect(input: ReflectionInput): Promise<ReflectionResult>;
}
//# sourceMappingURL=reflection-engine.d.ts.map