@sema-agent/core/dist/core/media-byte-cap.d.ts

Stateless, task-oriented AI agent core

import type { AgentMessage } from "../internal/harness-types.js";
/**
 * Aggregate MEDIA (image) byte budget — the multimodal sibling of {@link AGGREGATE_TOOL_RESULT_BUDGET_CHARS}
 * (which only counts TEXT, design/64 §17.2). batch-C added image reads (`Read` → `ImageContent`); each is bounded
 * per-image (`MAX_IMAGE_READ_BYTES`), but N images accumulate ACROSS turns in the context and would otherwise grow
 * the request unboundedly (a real gap — CC 2.1.196 added the same cap, `tengu_media_byte_cap`, validating it).
 *
 * This caps the SUM of inline image bytes across the whole message list: while over budget, the OLDEST images are
 * stripped (replaced with a short text marker) until it fits — recent media (most relevant) is kept. Like the text
 * budget it is a REQUEST-ONLY, NON-DESTRUCTIVE transform (returns a new array; the durable session keeps the full
 * image, and the model can re-`Read` the file if it still needs it) applied in the `harness.on("context")` hook,
 * and DETERMINISTIC (same messages + limit → same strip set → byte-identical request → prompt-cache safe).
 */
/** Default aggregate inline-media budget (bytes). Generous — only the pathological "N parallel huge image reads"
 *  case strips. Bounds the request while leaving normal multimodal use untouched. Overridable per-deployment. */
export declare const AGGREGATE_MEDIA_BUDGET_BYTES: number;
/** Telemetry for one strip pass (mirrors CC's `tengu_media_byte_cap_stripped` fields). */
export interface MediaStripInfo {
    totalBytes: number;
    limitBytes: number;
    removedCount: number;
    removedBytes: number;
}
/**
 * Cap the aggregate inline-image bytes across `messages` to `limitBytes`, stripping OLDEST images first. Returns the
 * SAME array when already within budget or the limit is non-positive/non-finite (no allocation, no-op). Otherwise a
 * shallow-cloned array with the stripped messages replaced (originals untouched). `onStripped` fires once if anything
 * was removed.
 */
export declare function capAggregateMediaBytes(messages: AgentMessage[], opts: {
    limitBytes: number;
    onStripped?: (info: MediaStripInfo) => void;
}): AgentMessage[];