/**
 * @fileoverview The per-surface byte budget shared by the record-list tools
 * (`gdelt_search_articles`, `gdelt_get_tv_clips`): how records are charged against it, how many
 * fit, and the continuation a page cut to it hands back.
 * @module mcp-server/tools/response-budget
 */
import { type GdeltWindow, type WindowContinuation } from './date-range.js';
/**
 * Bytes a response's records may occupy on each surface — the `structuredContent` JSON and the
 * `content[]` text. Heading, enrichment, and trailer ride on top of it.
 */
export declare const RESPONSE_BYTE_BUDGET = 48000;
/**
 * What one record adds to each surface: its JSON array element plus the joining comma, and its
 * rendered block plus the joining newline. Charged at the larger of the two, so one running
 * total bounds both surfaces. `rendered` must come from the renderer `format()` uses, so the
 * charge is exact rather than estimated.
 */
export declare function recordCharge(record: object, rendered: string): number;
/**
 * How many leading records fit the budget, in upstream order: stops at the first record whose
 * charge would cross it, and never returns fewer than one when any record exists — a single
 * record larger than the whole budget is still emitted, alone.
 */
export declare function fitToBudget(charges: readonly number[]): number;
/** A page `fitToBudget` cut short, described for its continuation notice. */
export type CutPage = {
    noun: {
        singular: string;
        plural: string;
    };
    /** Field a caller de-duplicates re-assembled records on. */
    dedupeKey: string;
    sort: string;
    /** The window the call ran against, when known. */
    window: GdeltWindow | undefined;
    /** Raw timestamp of each emitted record, in emitted order. */
    emittedStamps: readonly string[];
    /** Charge of each emitted record, in emitted order. */
    emittedCharges: readonly number[];
    /** Charge of the first withheld record. */
    nextCharge: number;
    /** Raw timestamp of each withheld record, in upstream order. */
    withheldStamps: readonly string[];
    /** Records the upstream returned into the budget, emitted plus withheld. */
    fetchedCount: number;
    maxRecords: number;
    ceiling: number;
    /** True when the upstream answered with `maxRecords` records, so more may exist. */
    capHit: boolean;
    /** How this API's window divides for a sort with no resume point. */
    halve: (window: GdeltWindow | undefined) => WindowContinuation;
    /** A sentence appended whenever the notice offers a way to continue (e.g. what maxRecords to continue with). */
    continueNote?: string;
};
/**
 * The notice and continuation windows for a page cut to the budget. The notice never offers a
 * larger `maxRecords` as the way to fit more into this response — the budget, not the cap, cut
 * the page; an API may add a `continueNote` about the maxRecords its continuation calls need.
 *
 * Under `dateDesc`/`dateAsc` the last emitted record is a resume point: the notice hands back
 * one window from it, provided a call on that window emits at least one record this page did
 * not (it would first re-return every emitted record inside the window, then the first withheld
 * one). When it would not, the window skips past that second instead. Other sorts have no
 * resume point and get the halves the page's API divides its window into.
 */
export declare function planCutNotice(page: CutPage): {
    notice: string;
    windows?: GdeltWindow[];
};
//# sourceMappingURL=response-budget.d.ts.map