import type { ChatMessage, CondensePolicy } from '@genesislcap/foundation-ai';
/**
 * Tool-context condensation: collapse stale tool payloads out of the history
 * sent to the model, while leaving stored history untouched.
 *
 * The driver owns the registry (tool handlers populate it via `condenseWhen`)
 * and the cadence (this runs before every provider call). This module owns the
 * pure application: given the registry + the current loop iteration, produce a
 * rewritten copy of the history with stale args/results replaced by stubs. Kept
 * pure (no driver/session state, no logging) so it unit-tests in isolation —
 * the one-time `context.condensed` signal is delivered via an `onCondensed`
 * callback rather than reaching into the debug-event log directly.
 *
 * @packageDocumentation
 */
/**
 * Below this serialized size a tool payload isn't worth condensing — the stub
 * would save little and cost a breadcrumb. A driver-level floor so the public
 * `condenseWhen` API needs no per-policy threshold field.
 */
export declare const CONDENSE_MIN_CHARS = 1000;
/** Key the collapsed args are stored under — a tool-call's args must stay a Record. */
export declare const CONDENSED_ARGS_KEY = "condensed";
/**
 * A `condenseWhen` policy registered against a tool-call id, with its age clock
 * and report-once flags. The driver holds these in a `Map<toolCallId, …>`;
 * {@link applyCondensation} reads them and flips the `reported*` flags so the
 * `context.condensed` signal fires once per payload, not once per provider call.
 */
export interface RegisteredCondensePolicy {
    policy: CondensePolicy;
    /**
     * Monotonic model-call sequence (`modelCallSeq`) when `condenseWhen` was called
     * — the origin of the age clock. Driver-lifetime and NOT reset per turn, so age
     * is measured consistently across turn boundaries (the field name is historical;
     * it is not the per-turn loop iteration).
     */
    iteration: number;
    /** Turn (`sendMessage`) sequence when the call was made — the `turnEnd` clock. */
    turn: number;
    /** Agent-activation sequence when the call was made — the `agentEnd` clock. */
    activation: number;
    /** App-controlled phase epoch when the call was made — the `phaseEnd` clock. */
    phaseEpoch: number;
    /** `context.condensed` already emitted for the args payload (fire-once). */
    reportedArgs?: boolean;
    /** `context.condensed` already emitted for the response payload (fire-once). */
    reportedResponse?: boolean;
}
/**
 * The driver's live state at the moment of a provider call — the clocks every
 * trigger is evaluated against. Passed by the driver; kept as an interface so the
 * transform stays a pure function of (history, policies, clocks).
 */
export interface CondenseContext {
    /** Monotonic model-call sequence now — the `age` clock. */
    modelCall: number;
    /** Monotonic turn (`sendMessage`) sequence now — the `turnEnd` clock. */
    turn: number;
    /** Whether the agent activation that made a call has since ended — the `agentEnd` clock. */
    activationEnded: (activation: number) => boolean;
    /**
     * Whether a later phase epoch is current than the one a call was made in — the
     * `phaseEnd` clock. True once `endPhase()` has been called since the call.
     */
    phaseEnded: (phaseEpoch: number) => boolean;
}
/**
 * Structured detail for a `context.condensed` meta-event. The index signature
 * lets it satisfy `recordMetaEvent`'s `Record<string, unknown>` detail param
 * while the named fields stay strictly typed.
 */
export interface CondensedEventDetail {
    [key: string]: unknown;
    /** Tool-loop iteration the collapsed call was made on. */
    turn: number;
    toolCallId: string;
    tool: string;
    target: 'args' | 'response';
    /** Human-readable trigger, e.g. `superseded:Foo.tsx` or `age:3`. */
    trigger: string;
    /** Length of the replacement stub. */
    stubLen: number;
    /** Estimated input tokens saved this collapse (char/4 — no tokenizer in-stack). */
    tokensSaved: number;
}
/**
 * Collapse stale tool payloads (declared via `condenseWhen`) out of the
 * model-bound history. Pure over the `history` array — it emits new message
 * objects and never mutates the input messages (mirroring the agent-masking
 * transform). It DOES, however, flip the `reported*` flag on the matching
 * `policies` entry the first time a payload collapses — the report-once gate that
 * keeps `onCondensed` firing once per (tool call, payload) even though the
 * collapse itself re-runs before every provider call.
 *
 * Triggers (a policy may list several via `on: Trigger[]` — the FIRST to fire
 * collapses the payload; all are monotonic, so the collapse never reverts):
 * - `superseded` — among all registered calls sharing a `by` key, the LAST in
 *   history order survives; every earlier one's targeted payload collapses. A
 *   re-call with the same key becomes the new survivor and re-arms the rest.
 * - `age` — the result is first visible one model-call after the call, so `turns`
 *   is how many model-calls may see the full result before it collapses
 *   (fires when `modelCall − callModelCall > turns`): `turns: 1` is seen once,
 *   then collapses. The clock is monotonic across turns.
 * - `turnEnd` — collapses once the turn (`sendMessage`) that made the call has
 *   ended (fires when `turn > callTurn`): full for the rest of that request,
 *   gone on every later one.
 * - `agentEnd` — collapses once the agent activation that made the call has ended
 *   (a swap to another agent, or `releaseAgent`/`completeSubAgent`): kept across
 *   all of the agent's turns, dropped when its flow finishes.
 * - `phaseEnd` — collapses once the app advances its phase epoch via `endPhase()`
 *   after the call (a sub-`agentEnd` boundary the author declares), OR at
 *   `agentEnd` as a backstop if no boundary is ever declared.
 *
 * The tool-call/result envelope is never removed (providers reject orphaned
 * calls/results) — only the args object or the result content is replaced.
 *
 * @param history - The to-model history copy to rewrite (not mutated).
 * @param policies - The driver's registry, keyed by tool-call id. Its entries'
 *   `reported*` flags are flipped as payloads first collapse.
 * @param ctx - The driver's live clocks (model-call / turn / agent-activation).
 * @param onCondensed - Invoked once per payload at its full→stub transition.
 */
export declare function applyCondensation(history: ChatMessage[], policies: Map<string, RegisteredCondensePolicy>, ctx: CondenseContext, onCondensed: (detail: CondensedEventDetail) => void): ChatMessage[];
//# sourceMappingURL=condense-history.d.ts.map