framework/dist/quota-poller.d.ts

The (AI) Framework: turnkey, zero-config AI orchestration that wraps a coding-agent CLI (Claude Code) as a black box and takes you from an idea to a running app. Vite for AI.

import { type DriverQuota } from './driver/index.js';
/**
 * How often to read the quota when everything is healthy. A read spawns the
 * whole agent CLI (~5s), and the agent's own usage fetch is refused upstream if
 * asked too often, so this is deliberately slow: the boundary moves over days,
 * which a 5-minute sample rate resolves comfortably.
 */
export declare const DEFAULT_POLL_MS: number;
/** Longest gap between reads once backoff has stretched it. */
export declare const MAX_POLL_MS: number;
/**
 * What the poller currently believes about the account's quota.
 *
 * `latest` is the last attempt as it came back; `lastGood` is the last real
 * reading. The two are separate so a transient blip doesn't blank a number that
 * was accurate a minute ago — a bar going empty reads as "nothing used", which
 * is the one thing this feature must never imply.
 */
export interface QuotaEnvelope {
    /** The most recent attempt, exactly as it came back. `undefined` before the first. */
    latest: DriverQuota | undefined;
    /** The most recent successful reading, retained across transient failures. */
    lastGood: (DriverQuota & {
        available: true;
    }) | undefined;
    /** When {@link lastGood} was read, epoch ms. */
    lastGoodAt: number | undefined;
    /** When the last failure happened, epoch ms. */
    lastFailureAt: number | undefined;
}
/** Options for {@link QuotaPoller}. */
export interface QuotaPollerOptions {
    /** Read the quota once. Normally `driver.readQuota`. */
    read: () => Promise<DriverQuota>;
    /** Healthy interval. Default {@link DEFAULT_POLL_MS}. */
    intervalMs?: number;
    /** Ceiling for the backed-off interval. Default {@link MAX_POLL_MS}. */
    maxIntervalMs?: number;
    /** Clock, injectable for tests. */
    now?: () => number;
}
/**
 * Keeps a recent quota reading on hand (#525).
 *
 * Polling is slow by design and backs *off* on failure rather than retrying
 * into it: the agent's usage fetch is refused upstream when asked too often,
 * and the penalty window is minutes long, so an eager retry loop would keep the
 * number permanently unavailable — the opposite of the goal.
 */
export declare class QuotaPoller {
    private readonly opts;
    private envelope;
    private timer;
    private running;
    private currentIntervalMs;
    private stopped;
    private readonly now;
    constructor(opts: QuotaPollerOptions);
    /** What we currently believe. */
    current(): QuotaEnvelope;
    /** The gap before the next read, which grows while the fetch keeps being refused. */
    get intervalMs(): number;
    /** Whether the poller has given up (an authoritative failure, or {@link stop}). */
    get isStopped(): boolean;
    /**
     * Read once, now, and fold the result in. Safe to call on demand (e.g. right
     * after a turn settles) alongside the timer.
     */
    poll(): Promise<DriverQuota>;
    /**
     * Begin polling, starting with a read right now rather than one interval from
     * now: a poller whose first reading lands five minutes in is no use to an agent
     * that just started, and the session's own measurement needs a baseline. Not
     * awaited — the read takes ~5s and nothing should wait on it. Idempotent.
     */
    start(): void;
    /** Stop polling. Idempotent. */
    stop(): void;
    private onGood;
    private onBad;
    private schedule;
}
//# sourceMappingURL=quota-poller.d.ts.map