@sema-agent/core/dist/core/runner/compaction-knobs.d.ts

Stateless, task-oriented AI agent core

/**
 * The run loop's three compaction knobs: the consecutive-failure breaker trip, the anti-thrash
 * regrowth factor and the effective-compaction epsilon. They were declared at the turn-boundary lane and the driver
 * reached DOWN for them; the recovery lane (the forced-compaction pass the prompt-too-long and guard-chain arms
 * share) reads the same three, and a lane may not name a sibling lane — so the three values sank to the machinery
 * stratum, where the two lanes and the driver all reach down for them. Values verbatim, comments included.
 *
 * No `run-` family prefix, for the reason initial-run-state.ts gives: a module the lanes stand on is not a driven
 * lane, and the prefix would put it under the phase-api gate and the run-lanes glob.
 */
/**
 * §17.4: stop attempting within-task compaction after this many CONSECUTIVE
 * failures in one task — a never-recovering summary gateway must not burn an API call at every turn
 * boundary (CC: MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3). Reset on any success; an open breaker also
 * skips the end-of-task attempt in `finish()` (teardown unaffected). Per-task scope.
 *
 * This used to say "a flaky/never-recovering gateway", and the word `flaky` was not true. Because
 * any success zeroes the counter, a gateway that alternates never reaches three CONSECUTIVE failures and
 * the breaker never opens; it keeps paying for a call at every failed boundary, indefinitely.
 *
 * The behaviour is right and stays: a gateway succeeding half the time is compacting half the time, and
 * opening the breaker on it would disable compaction outright and let the context overflow — trading a
 * wasted call for a failed task. What was wrong is the comment claiming a guarantee the code does not
 * make. An alternating gateway is deliberately NOT caught here; if that ever needs catching it wants a
 * different signal (a failure RATE over a window), not a consecutive counter.
 */
export declare const MAX_CONSECUTIVE_COMPACTION_FAILURES = 3;
/**
 * §25.2 anti-thrash (LONGRUN-1b, search [84]): after a compaction, the context must regrow past
 * (tokensBefore − freed) × this factor — the post-compaction size in trigger units — before another
 * summary call fires. An EFFECTIVE compaction (freed large) leaves the floor far below the threshold,
 * so behavior is unchanged; an INEFFECTIVE one (small window, chunky turns, large summary ⇒ freed
 * small, still at/over the threshold) raises the floor so attempts space out instead of firing at
 * every boundary (measured: 26/39 boundaries, +135% wall). The floor binds only when post-compaction
 * size > threshold/1.5 ≈ compaction freed <33% headroom. Degrades gracefully: the retained summary
 * chain keeps early facts; only the un-summarized tail falls back to trim.
 */
export declare const COMPACTION_REGROWTH_FACTOR = 1.5;
/**
 * A compaction that frees fewer than this many (structural) tokens is
 * treated as NO-EFFECTIVE-COMPACTION and does NOT raise the anti-thrash floor. Guards against a reused
 * provider summary (or a pathological LLM summary) that reclaims no headroom yet suppresses the next real
 * summary by inflating the floor to trigger×factor.
 */
export declare const COMPACTION_FREED_EPSILON = 256;