agentfootprint/dist/esm/strategies/flushDeadline.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * strategies/flushDeadline — flush a handle, stop waiting at a deadline, and
 * name the strategy that did not finish.
 *
 * A sink's `flush()` waits for its own in-flight delivery. One that never
 * settles — a hung network mount under `appendFile`, a network call with no
 * timeout — would hold a shutdown forever, and a slow one for as long as it is
 * slow. The deadline belongs to the caller that must finish,
 * `RunnerBase · shutdown`, never to the sink: nothing can cancel an in-flight
 * write, and pretending otherwise would be worse than saying we stopped
 * waiting (the `withinBound` law in hosting/standingAgent.ts).
 *
 * A missed deadline is REPORTED, through the stuck strategy's own `_onError`
 * (the console when it has none), and names it — the same rule as every
 * delivery failure: telemetry that fails invisibly is indistinguishable from
 * telemetry that works. A deadline cannot tell a slow delivery from a stuck
 * one, so the report says both.
 */
import type { BaseStrategy, StrategyHandle } from './types.js';
/** How long `shutdown()` waits for each handle's flush unless told otherwise:
 *  30 s, the same number footprintjs's `drainObservers` uses as its default. */
export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
/** Remember the strategy behind a handle. Called once, where the handle is
 *  built (`strategies/attach.ts · makeStrategyHandle`). */
export declare function rememberStrategyOf(handle: object, strategy: BaseStrategy): void;
/** The deadline a `shutdown({ timeoutMs })` asked for. Throws a `TypeError`
 *  when it is not a positive number of milliseconds — called from the async
 *  `shutdown()`, so its caller sees a REJECTED promise, never a sync throw.
 *
 *  The refusal names the field and the shape it takes, NEVER the value: a
 *  value of the wrong type can be anything a caller had at hand, and an error
 *  message is copied into logs, reports and traces. */
export declare function shutdownTimeoutOf(timeoutMs: number | undefined): number;
/**
 * Flush one handle, but wait no longer than `timeoutMs`. On a missed deadline
 * the strategy is reported by name and this resolves `'stuck'`; its flush
 * keeps running — it is not, and cannot be, cancelled.
 *
 * The deadline is armed by `lib/longTimeout.ts · setLongTimeout`: `Infinity`
 * arms no timer at all, and a finite deadline of ANY length fires when asked —
 * past the ~24.8 days one host timer holds, it is waited in chained chunks,
 * never dropped and never fired after 1 ms. Whatever is armed is cleared as
 * soon as the flush settles, so a healthy shutdown leaves no timer behind.
 * It is NOT unref'd: it is bounded, and it is what lets the code after
 * `await agent.shutdown()` run when the stuck write holds nothing else open.
 */
export declare function flushWithinDeadline(handle: StrategyHandle, timeoutMs: number): Promise<'flushed' | 'stuck'>;