/**
 * Bounded writer for persisted tool-output files.
 *
 * Every temp file a tool spills to disk goes through here so no single file can
 * exceed {@link MAX_PERSISTED_OUTPUT_BYTES}. Once the cap is reached the writer
 * stops consuming input and appends {@link PERSISTED_OUTPUT_TRUNCATION_MARKER},
 * so the file stays readable and its size stays bounded even when the producing
 * command never stops.
 */
import { Buffer } from "node:buffer";
/** Trim a buffer to at most `maxBytes` without splitting a valid UTF-8 sequence. */
export declare function truncateBufferAtUtf8Boundary(buffer: Buffer, maxBytes: number): Buffer;
/**
 * Length of the longest prefix of `buffer` that does not end mid-character.
 * Invalid UTF-8 remains complete raw binary; only a valid partial tail waits.
 */
export declare function completeUtf8PrefixLength(buffer: Buffer): number;
/**
 * Cap an in-memory string destined for a persisted-output file.
 *
 * Returns the input unchanged when it already fits; otherwise the returned text
 * is the leading portion plus {@link PERSISTED_OUTPUT_TRUNCATION_MARKER}, and the
 * whole result stays within `maxBytes`.
 */
export declare function capPersistedText(text: string, maxBytes?: number): string;
export interface PersistedOutputFileOptions {
    /** Byte cap for this file. Defaults to {@link MAX_PERSISTED_OUTPUT_BYTES}. */
    maxBytes?: number;
}
/**
 * A write stream that refuses to grow past its byte cap.
 *
 * Marker space cannot simply be subtracted up front: input that lands *exactly*
 * on the cap is not truncated and must be preserved whole. So the writer keeps a
 * short trailing buffer — everything past `maxBytes - markerBytes` — unwritten
 * until it knows which case it is in. Input that stays within the cap has that
 * tail flushed on close; input that exceeds it gets the UTF-8-safe prefix plus
 * the marker, and the file lands at the cap. Flushes are cut at character
 * boundaries, so the file never ends mid-character.
 *
 * Mirrors the subset of `WriteStream` the spill-file call sites use: `write`, a
 * fire-and-forget `end`, and an awaitable `close`. A stream error is captured by
 * a listener installed at construction, so a spill file that fails to write can
 * never surface as an uncaught exception on the fire-and-forget path.
 */
export declare class PersistedOutputFile {
    readonly path: string;
    private stream;
    private readonly maxBytes;
    /** Bytes that may be written before the marker's reserved space is needed. */
    private readonly safeLimit;
    private writtenBytes;
    private pending;
    private capReached;
    private failure;
    constructor(path: string, options?: PersistedOutputFileOptions);
    /** Whether the cap was reached and the marker written. */
    get truncated(): boolean;
    /** The write error this file failed with, if any. */
    get error(): Error | undefined;
    /** Total input bytes accepted so far, including the unflushed tail. */
    private get acceptedBytes();
    write(chunk: Buffer | string): void;
    /**
     * Write at most `room` pending bytes, never ending mid-character.
     *
     * Both cuts matter. Cutting at `room` uses the boundary walk; flushing the
     * whole buffer still holds back an incomplete trailing sequence, because its
     * continuation bytes arrive in the *next* chunk — and if the cap intervenes
     * first, a lead byte already on disk would sit orphaned before the marker.
     */
    private flushUpTo;
    /** Release the trailing buffer once the input is known to fit within the cap. */
    private flushRemainder;
    /** Close without waiting for the flush to complete. */
    end(): void;
    /** Close and wait for the flush, rejecting on a write error. */
    close(): Promise<void>;
}
//# sourceMappingURL=persisted-output-file.d.ts.map