/** * Tool-run log batcher (2026-11). * * WHY: the auto-answer/research runner used to POST one `/tools/runs/:id/events` * call per stdout chunk. That is not just chatty HTTP — each append rewrote the * run's whole log array, so database egress grew quadratically with run length. * The server now stores lines append-only, but the HTTP round trips are still * wasteful at one per chunk. * * This coalesces chunks into one request every `intervalMs` (or sooner when * `maxLines` is reached) and guarantees a final flush before the run reports * terminal. Order within a stream is preserved; stdout/stderr are kept as * separate entries so the console still colours them. * * The flush function is injected and failure-tolerant by design: logging must * never fail a run. */ export interface ToolLogChunk { stream: string; text: string; } export interface ToolLogBatcherOptions { /** Flush cadence. Default 1500 ms — below a human's perception of "live". */ intervalMs?: number; /** Flush early once this many chunks are pending. Default 100. */ maxLines?: number; /** Hard cap on buffered text while the network is down. Default 200_000 chars. */ maxBufferedChars?: number; } export declare class ToolLogBatcher { private readonly send; private readonly opts; private pending; private bufferedChars; private timer; private inFlight; private closed; constructor(send: (lines: ToolLogChunk[]) => Promise, opts?: ToolLogBatcherOptions); private get intervalMs(); private get maxLines(); private get maxBufferedChars(); /** * Split one chunk into wire-sized pieces on a line boundary when possible. * * The server caps a stored line at 2000 chars. Sending a 12 KB chunk as one * line would silently truncate it, so the batcher splits first — the download * endpoint is only "the full log" if nothing was dropped on the way in. */ private static split; /** Buffer one chunk. Never throws; never blocks the caller. */ push(stream: string, text: string): void; private arm; /** Send everything buffered. Serialised — never two requests at once. */ flush(): Promise; /** Final flush; after this, `push` is a no-op. */ close(): Promise; }