@sema-agent/core/dist/core/mods/kernel/budget.d.ts

Stateless, task-oriented AI agent core

/**
 * The self budget every handler runs under (CC form): a pausable timer that stops while the handler waits
 * on `next` or on a `$` call, plus the budget constants and the bad-value fallback for `budgetMs`.
 */
/** A handler's own time when its registration declares none (CC 2.1.296 `kSe` (cli296.js:239763)). */
export declare const DEFAULT_MOD_BUDGET_MS = 10000;
/** A `.catch`'s own time (CC 2.1.296 `z3e` (cli296.js:239763)). */
export declare const CATCH_BUDGET_MS = 1000;
/** How long after its budget ran out a handler that still has not settled is reported as a runaway (CC 2.1.296 `TFe` (cli296.js:239763)). */
export declare const RUNAWAY_AFTER_MS = 5000;
/** How long an observation dispatch still waits after the task is cancelled. */
export declare const POST_ABORT_GRACE_MS = 1000;
/** `setTimeout`'s ceiling; above it the platform clamps to about 1 ms. */
export declare const MAX_TIMER_MS = 2147483647;
/** What `next.budget` reads: the handler's budget and what is left of it. */
export interface ModBudgetReading {
    readonly ms: number;
    readonly remainingMs: number;
}
/**
 * `budgetMs` as a usable budget: the declared value when it is one, the default when absent, and the
 * default LOUDLY (one report) when it is garbage. A bad value is never a refusal.
 */
export declare function resolveModBudgetMs(supplied: unknown, report: (err: Error) => void, name: string): number;
export interface SelfBudget {
    /** Resolves once, when the budget runs out (never rejects). */
    readonly expired: Promise<"expired">;
    isExpired(): boolean;
    /** Stop the clock; nested pauses need as many resumes. */
    pause(): void;
    resume(): void;
    /** Stop for good (the handler settled). */
    clear(): void;
    /** The handler's own time so far. */
    usedMs(): number;
    reading(): ModBudgetReading;
}
/** Start a budget of `ms`; `onExpire` runs once when it runs out. A zero budget runs out on the next timer turn. */
export declare function createSelfBudget(ms: number, onExpire: () => void): SelfBudget;
/** Run `onRunaway` once if `settled` has not settled `RUNAWAY_AFTER_MS` after a budget ran out. */
export declare function watchRunaway(settled: Promise<unknown>, onRunaway: () => void): void;
/** Let a host process exit with a watch still pending (a no-op where timers are plain numbers). */
export declare function unrefTimer(timer: unknown): void;