/**
 * Debug instrumentation.
 *
 * Writes NDJSON event records to ~/.compact-agent/debug/<sessionId>.jsonl
 * for offline analysis. Designed so that with `level === 'off'` (the
 * default), every emit() call is a single boolean check + early return —
 * zero file I/O and negligible CPU on the hot path.
 *
 * Levels (each includes everything below it):
 *
 *   off    — no logging (default; for end users)
 *   info   — high-signal milestones: session start/end, API request/
 *            response summary, tool call summary, hook block, stream
 *            loop detection, mode/perm/model change
 *   debug  — info + per-tool argument previews, per-chunk stream stats,
 *            per-keypress trace at REPL, slash command dispatch
 *   trace  — debug + raw API payloads (truncated), full tool I/O,
 *            internal state transitions
 *
 * Toggling:
 *
 *   - CLI flag:     compact-agent --debug [level]
 *   - Env var:      COMPACT_AGENT_DEBUG=trace
 *   - Slash cmd:    /debug on [level]   /debug off   /debug tail [n]
 *
 * The event log is append-only. Each session gets its own file so
 * concurrent compact-agent instances don't fight over a single sink.
 * Files are subject to the same 24h GC window as the gateguard state.
 *
 * Design notes:
 *
 *   - We deliberately don't use console.error or any third-party logger.
 *     console.error pollutes the user's REPL view; a third-party logger
 *     adds startup time + a transitive dep. Direct fs.appendFileSync to
 *     an NDJSON file is the lowest-overhead path that's also trivially
 *     consumable by jq / Python / another agent.
 *
 *   - We DO accept the cost of synchronous appendFileSync — debug
 *     instrumentation is rarely on the hot path of perf-sensitive code,
 *     and the cost of one syscall per event (only when level >= info)
 *     is dwarfed by the cost of the API call the event describes.
 *
 *   - Stack traces are NOT captured automatically. Each emit() takes an
 *     explicit `data` object — callers include whatever they need.
 *     Auto-traces would balloon the log file for limited extra value.
 */
export type DebugLevel = 'off' | 'info' | 'debug' | 'trace';
/**
 * Initialize debug at session start. Resolves level from (in priority order):
 *   1. explicit `level` arg (passed in from --debug flag parsing)
 *   2. $COMPACT_AGENT_DEBUG env var
 *   3. existing state.level (typically 'off')
 *
 * Sets the log file path under ~/.compact-agent/debug/<sessionId>.jsonl
 * but doesn't touch the filesystem until the first emit (lazy create).
 */
export declare function initDebug(sessionId: string, explicitLevel?: DebugLevel | string): void;
/**
 * Emit a debug event. The fastest path is the early-return when the
 * configured level is below the event's level — a single integer compare.
 *
 * `data` is shallow-cloned to a JSON-safe form. Functions, BigInts, and
 * circular refs are stripped via the replacer to keep emit cheap and
 * crash-free regardless of what callers throw in.
 */
export declare function emit(eventLevel: Exclude<DebugLevel, 'off'>, eventName: string, data?: Record<string, unknown>): void;
/**
 * Public read-only state snapshot for /debug status output.
 */
export declare function getDebugStatus(): {
    level: DebugLevel;
    logPath: string | null;
    eventCount: number;
    uptimeMs: number;
};
/**
 * Change the active debug level at runtime. Called from /debug on/off.
 * If transitioning OFF → non-off, we ensure the log dir exists; if
 * transitioning to OFF we leave the file alone (it's append-only and
 * read by external tools).
 */
export declare function setDebugLevel(level: DebugLevel): void;
/**
 * Read the last N events from the current session's log. Used by
 * /debug tail. Returns lines as JSON strings (one per event); the
 * caller can pretty-print or pass through to jq.
 */
export declare function tailDebug(n: number): string[];
/**
 * True if any non-off level is active. Use this to gate expensive
 * data preparation that you don't want to run when debug is off:
 *
 *   if (isDebugActive()) {
 *     emit('debug', 'event-name', { detail: computeExpensiveDetail() });
 *   }
 */
export declare function isDebugActive(): boolean;