/**
 * Module-level append-only timeline of meta/lifecycle events, keyed by session
 * identity (the same `stateKey` space used by the driver registry and the
 * session store).
 *
 * Why a module registry rather than the redux store or the driver:
 * - **Survives the pop-in/pop-out element churn.** A single session can be
 *   emitted from up to two element instances (an `expand` bubble + a `collapse`
 *   panel) sharing one driver; keying by `stateKey` unifies them into one
 *   timeline.
 * - **Survives driver rebuilds.** The driver is torn down and recreated when the
 *   host swaps the agents array (see `agentsChanged` / `deleteDriver`), so a
 *   driver-owned buffer would lose the timeline mid-session. The `stateKey`
 *   outlives the driver.
 * - **Stays out of redux reactivity.** These appends never drive the UI, so
 *   there's no reason to pay immutable-reducer cost or flood the Redux DevTools
 *   action log with debug noise.
 *
 * Surfaced in `getDebugLog().timeline`, merged chronologically with messages and
 * turn snapshots. Ring-buffered — the oldest non-`high` events are evicted first
 * while `high`-importance failure events are retained — so a long-lived session
 * stays bounded in normal use without ever dropping a failure signal.
 *
 * @internal
 */
import type { TurnFailureReason } from '@genesislcap/foundation-ai';
/**
 * Catalogue of meta event names. This is the documented surface — extend it as
 * new events are wired in (Tier 2/3 lifecycle, interaction, provider events).
 */
export type MetaEventType = 'assistant.connected' | 'assistant.disconnected' | 'assistant.popout' | 'assistant.popin' | 'driver.created' | 'driver.wired' | 'driver.unwired' | 'state.changed' | 'turn.start' | 'turn.end' | 'turn.retry' | 'turn.error' | 'tool.failed' | 'tool.unresolved' | 'subagent.started' | 'subagent.completed' | 'subagent.failed' | 'agent.handoff' | 'agent.pinned' | 'agent.unpinned' | 'provider.selected' | 'interaction.requested' | 'interaction.resolved' | 'external-diagnostics.folded' | 'context.updated' | 'context.threshold-crossed' | 'context.compacted' | 'context.condensed' | 'panel.toggled' | 'attachment.added' | 'file.read-failed' | 'suggestions.failed' | 'session.cleared' | 'session.switched' | 'session.switch-deferred' | 'persistence.toggled' | 'persistence.saved' | 'persistence.suppressed' | 'persistence.not-resumable' | 'persistence.restored' | 'persistence.restore-orphan';
/**
 * How much a reader should care about an event — lets a consumer (or an AI
 * agent) filter the timeline: skip `low` UI/bookkeeping noise, skim `normal`
 * session flow, or jump straight to `high` problem/limit signals when triaging.
 */
export type MetaEventImportance = 'high' | 'normal' | 'low';
/**
 * Importance is intrinsic to the event *type*, not the instance, so it's
 * defined once here and stamped automatically by {@link recordMetaEvent} — call
 * sites never pass it. The `Record` is exhaustive: adding a `MetaEventType`
 * without a level here is a compile error.
 *
 * - `high`   — failures and hard limits you almost always want to see.
 * - `normal` — meaningful session flow you read to follow what happened.
 * - `low`    — frequent UI / bookkeeping noise, usually safe to skip.
 */
export declare const META_EVENT_IMPORTANCE: Record<MetaEventType, MetaEventImportance>;
/** One entry in the meta-event timeline. */
export interface MetaEvent {
    /** Monotonic counter across the session's lifetime (does not reset on driver rebuild). */
    index: number;
    /** ISO timestamp, matching the format used elsewhere in the debug log. */
    timestamp: string;
    /** Event name — see {@link MetaEventType}. */
    type: MetaEventType;
    /** How much to care about this event — see {@link META_EVENT_IMPORTANCE}. */
    importance: MetaEventImportance;
    /** Optional structured payload. */
    detail?: Record<string, unknown>;
}
/**
 * Append a meta event to the timeline for `key`. Once the buffer exceeds
 * {@link DEFAULT_MAX_META_EVENTS}, evicts the oldest *non-`high`* event;
 * `high`-importance events are never evicted. An empty `key` is bucketed under
 * `''`, matching how drivers/stores handle an absent session identity, so
 * callers never need to guard.
 */
export declare function recordMetaEvent(key: string, type: MetaEventType, detail?: Record<string, unknown>): void;
/**
 * Why a turn failed or was retried — stamped as `detail.reason` on `turn.error`
 * and `turn.retry` events, and (since PTC-0) surfaced at the driver's loop
 * boundary via {@link ChatDriverResult.failureReason}. Re-exported from
 * `@genesislcap/foundation-ai` — where it lives alongside `ChatDriverResult` so
 * the boundary field and this log surface can never drift apart — under its
 * historical name so existing importers are unaffected. Enumerated so the set
 * stays in sync with the README and call sites can't drift to ad-hoc strings.
 */
export type { TurnFailureReason };
/**
 * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`
 * is typed so the high-importance triage surface stays consistent; pass any
 * diagnostic specifics (attempt counts, offending tool names, etc.) in `detail`.
 */
export declare function recordTurnError(key: string, reason: TurnFailureReason, detail?: Record<string, unknown>): void;
/**
 * Record a recoverable retry *within* a turn (`turn.retry`, importance `normal`)
 * — e.g. one malformed/empty attempt that will be retried, as distinct from the
 * final attempt that bails out as a `turn.error`. Include `attempt`/`maxAttempts`
 * in `detail` so the timeline shows which try this was.
 */
export declare function recordTurnRetry(key: string, reason: TurnFailureReason, detail?: Record<string, unknown>): void;
/** Returns the meta-event timeline for `key`, or an empty array if none recorded. */
export declare function getMetaEvents(key: string): ReadonlyArray<MetaEvent>;
/**
 * Merge pre-built meta events into the timeline for `targetKey`, **preserving each
 * event's original `timestamp`** (so it interleaves chronologically on export)
 * while re-indexing onto the target buffer's monotonic counter. Used to fold a
 * sub-agent's harvested events into the parent session — see
 * `ChatDriver.invokeSubAgent`. Unlike {@link recordMetaEvent} it does not stamp a
 * fresh timestamp; the same non-`high` eviction policy is applied once after the
 * batch so the buffer stays bounded.
 */
export declare function mergeMetaEvents(targetKey: string, events: readonly MetaEvent[]): void;
/**
 * Drop the entire timeline for `key`. Used to discard a sub-agent's transient
 * per-invocation session once its events have been harvested into the parent, so
 * the module registry doesn't accumulate one orphaned bucket per sub-agent run.
 */
export declare function clearSession(key: string): void;
/**
 * Human/agent-facing guide emitted as the first key of the exported debug log,
 * so whoever opens the JSON (often an AI agent) knows how to read it without
 * reverse-engineering the shape. Kept here next to the event catalogue it
 * describes so the two stay in sync.
 */
export declare const DEBUG_LOG_README: readonly string[];
/**
 * Removes all entries. Exposed for test isolation only — not part of the
 * public API.
 *
 * @internal
 */
export declare function clearMetaEventRegistry(): void;
//# sourceMappingURL=debug-event-log.d.ts.map