@struktoai/mirage-core/dist/utils/clock.d.ts

A Unified Virtual Filesystem For AI Agents

/** Wall time for timestamps and monotonic time for durations, in seconds. */
export interface Clock {
    /** Seconds since the unix epoch. */
    now(): number;
    /** Seconds from an arbitrary origin that never moves backwards. */
    monotonic(): number;
    /** Wait `seconds` on this clock; zero or less returns at once. */
    sleep(seconds: number): Promise<void>;
}
/** Platform clock used when no clock is supplied. */
export declare class SystemClock implements Clock {
    /** Marks a platform clock, so two copies of this module still agree. */
    readonly platform = true;
    /** Seconds since the unix epoch. */
    now(): number;
    /** Seconds from an arbitrary origin that never moves backwards. */
    monotonic(): number;
    /** Wait `seconds` of real time; zero or less returns at once. */
    sleep(seconds: number): Promise<void>;
}
/**
 * Clock advanced explicitly by the caller. Readings have no side effects.
 * A sleep advances the clock by its length and returns without waiting, so
 * a wait costs no real time. Waits do not overlap: two tasks that each sleep
 * 30 seconds advance it by 60.
 */
export declare class ManualClock implements Clock {
    private wall;
    private mono;
    /** @param start initial wall time in seconds; monotonic starts at zero. */
    constructor(start?: number);
    /** Seconds on the virtual wall clock. */
    now(): number;
    /** Seconds on the virtual monotonic clock. */
    monotonic(): number;
    /**
     * Move the clock forward by `seconds`.
     *
     * @param seconds how far forward to move; must not be negative, since
     *   a monotonic reading may not go back.
     */
    advance(seconds: number): void;
    /**
     * Advance by `seconds` and yield once. Zero, a negative or NaN advances
     * nothing.
     */
    sleep(seconds: number): Promise<void>;
}
/** Whether `clock` reads the platform clock, so any two such agree. */
export declare function isSystemClock(clock: Clock): boolean;
/**
 * `base` shifted by a fixed offset: it starts at the instant it is built for
 * and ticks at `base`'s rate, as a workspace's `system_time` does. Monotonic
 * time and waits are `base`'s. Mirrors Python's `ShiftedClock`.
 */
export declare class ShiftedClock implements Clock {
    readonly base: Clock;
    readonly offset: number;
    /**
     * @param base the clock it ticks with.
     * @param offset seconds added to `base`'s wall time.
     */
    constructor(base: Clock, offset: number);
    /** `base` shifted so that it reads `start` seconds now. */
    static starting(base: Clock, start: number): ShiftedClock;
    /** Seconds since the unix epoch, shifted. */
    now(): number;
    /** `base`'s monotonic seconds. */
    monotonic(): number;
    /** Wait `seconds` on `base`. */
    sleep(seconds: number): Promise<void>;
}
/**
 * Seconds since the unix epoch a `system_time` names: an ISO 8601 instant
 * with an offset (`Z` or `+08:00`), from 1970 through 2261, the years a
 * guest's nanosecond clock holds. Mirrors Python's `parse_system_time`.
 *
 * @throws Error when it is not one.
 */
export declare function parseSystemTime(text: string): number;
/**
 * `fn` run on a workspace's system clock, which `systemNow` reads. Mirrors
 * Python's `run_with_system_clock`.
 */
export declare function runWithSystemClock<T>(clock: Clock | null, fn: () => Promise<T>): Promise<T>;
/**
 * The running workspace's system clock, null for the host's. A browser
 * cannot tell one task's binding from another's, so there it is the newest
 * live one. Mirrors Python's `bound_system_clock`.
 */
export declare function boundSystemClock(): Clock | null;
/**
 * Seconds since the unix epoch on the running workspace's system clock: what
 * the agent sees as now. Mirrors Python's `system_now`.
 */
export declare function systemNow(): number;
/** `systemNow` as a `Date`. */
export declare function systemDate(): Date;
//# sourceMappingURL=clock.d.ts.map