import type { Checkpoint } from "../state/checkpointStore.js";
import { type TraceSink } from "./sinks.js";
import type { TraceConfig } from "./types.js";
/**
 * Decide which file (if any) a trace writer should target for a given run.
 *
 * - `traceFile` set: use it verbatim. This is a fixed, process-wide path —
 *   useful for tests and single-run inspection, but NOT safe with concurrent
 *   runs of the same agent (they'd interleave into one file). Documented.
 * - `traceFile` unset, `traceDir` set: derive `${traceDir}/${runId}.agencytrace`.
 *   Each run gets its own file, naturally supporting concurrent runs without
 *   any shared state.
 * - Neither set: returns null (no file output; callback-only or disabled).
 */
export declare function resolveTraceFilePath(traceConfig: TraceConfig, runId: string): string | null;
/**
 * Scan an existing trace file to learn what a prior writer in the same run
 * already emitted, so that a freshly-constructed `TraceWriter` can avoid
 * writing a duplicate header or re-emitting chunks that are already on disk.
 *
 * Best-effort: malformed lines (e.g. a partial JSON line from a crashed prior
 * writer) are skipped, not propagated. Returns `{ hasHeader: false,
 * chunkHashes: new Set() }` for empty or non-existent files. Only `header` and
 * `chunk` line types affect the result; other types (`source`, `static-state`,
 * `manifest`, `footer`) are ignored — they don't need cross-writer dedup
 * because either they're never emitted at runtime (`source`) or they're
 * already gated to once per run elsewhere (`static-state` via
 * `globals.markInitialized`; `manifest`/`footer` are per-checkpoint /
 * per-close events that shouldn't be deduped).
 *
 * Uses streaming line I/O (`createReadStream` + `readline`) so peak memory
 * stays at roughly one line, not the full file content. Each parsed chunk
 * line becomes GC-eligible after we extract its `hash` — the chunk's `data`
 * payload (potentially large) is never retained.
 */
export declare function scanExistingTraceFile(filePath: string): Promise<{
    hasHeader: boolean;
    chunkHashes: Set<string>;
}>;
export declare class TraceWriter {
    private store;
    private sinks;
    private checkpointCount;
    private chunkCount;
    private program;
    private runId;
    private headerWritten;
    constructor(runId: string, program: string, sinks: TraceSink[], options?: {
        seenHashes?: Set<string>;
        headerWritten?: boolean;
    });
    writeHeader(): Promise<void>;
    writeStaticState(values: Record<string, unknown>): Promise<void>;
    writeCheckpoint(checkpoint: Checkpoint): Promise<void>;
    /** Flush and close all sinks without emitting a footer.
     *  Used when execution is pausing for an interrupt. */
    pause(): Promise<void>;
    /** Emit a footer and close all sinks.
     *  Used when the agent run is truly finished. */
    close(): Promise<void>;
    private writeLine;
    static create({ runId, traceConfig, }: {
        runId: string;
        traceConfig: TraceConfig;
    }): Promise<TraceWriter | null>;
}