/** * Heartbeat — runs an agent on a schedule, delivers results via callback. * * Python parity: praisonaiagents/agent/heartbeat.py (`HeartbeatConfig`, * `Heartbeat`). Standalone wrapper; does NOT modify the Agent class. * * Python runs a thread that ticks, sleeps `interval` seconds, and repeats. * Here the loop is a chain of `setTimeout` calls that are `unref()`'d, so a * running heartbeat never keeps the Node process alive on its own, and * `stop()` clears the pending timer immediately. * * @example * const hb = new Heartbeat(agent, { schedule: 'every 30m', prompt: 'Report status' }); * await hb.start(); // resolves when stop() is called * hb.start(false); // background: returns after scheduling the first tick */ /** The slice of an agent the heartbeat needs: a name and `start(prompt)`. */ export interface HeartbeatAgent { name?: string; start(prompt: string): unknown; } /** Python `on_error`: "retry" | "skip" | callable(error). */ export type HeartbeatOnError = 'retry' | 'skip' | ((error: unknown) => void); /** Options accepted by {@link HeartbeatConfig} and {@link Heartbeat}; the Python dataclass fields. */ export interface HeartbeatOptions { /** * Human-friendly schedule. Python: `schedule: str = "hourly"`. Supported: * keywords `hourly` | `daily` | `weekly`; intervals `every 30m`, `*\/30m`, * `30m`, `every 6h`, `*\/10s`, `2 hours`; raw seconds `"3600"`. * See {@link parseHeartbeatSchedule}. */ schedule?: string; /** Prompt sent each tick. Python: `prompt: Optional[str] = None` (null = "Run your scheduled check."). */ prompt?: string | null; /** Receives each tick's result text. Python: `on_result: Optional[Callable] = None` (null = log it). */ onResult?: ((result: string) => void) | null; /** Error policy. Python: `on_error: Union[str, Callable] = "retry"`. */ onError?: HeartbeatOnError; /** Consecutive failures before the retry counter resets. Python: `max_retries: int = 3`. */ maxRetries?: number; } /** * Configuration for the Heartbeat scheduler. * * Python parity: `HeartbeatConfig` dataclass in agent/heartbeat.py, same * fields and defaults. */ export declare class HeartbeatConfig { readonly schedule: string; readonly prompt: string | null; readonly onResult: ((result: string) => void) | null; readonly onError: HeartbeatOnError; readonly maxRetries: number; constructor(config?: HeartbeatOptions); } /** * Convert a heartbeat schedule string to an interval in seconds. * * Python parity: `Heartbeat._resolve_interval` in agent/heartbeat.py, using * the interval grammar of scheduler/parser.py. Accepted forms: * - keywords: `hourly`, `daily`, `weekly` * - intervals: `every 30m`, `*\/30m`, `30m`, `every 6h`, `*\/10s`, `2 hours` * - raw positive seconds: `3600` * * Deviation from Python, on purpose: Python silently falls back to hourly * for anything it cannot parse (including `cron:` and `at:` forms, which the * heartbeat cannot run). Here an unrecognised or non-positive schedule throws * so a misspelled schedule is caught at construction instead of running at * the wrong cadence. * * @throws {Error} when the schedule is empty, unrecognised, or resolves to zero seconds. */ export declare function parseHeartbeatSchedule(schedule: string): number; /** * Standalone heartbeat coordinator: runs an agent on a schedule and delivers * results via callback. Does NOT add any params to the Agent class. * * Python parity: `Heartbeat(agent, schedule="hourly", prompt=None, * on_result=None, on_error="retry", max_retries=3)` in agent/heartbeat.py. * The keyword parameters travel in `options` (see {@link HeartbeatOptions}). */ export declare class Heartbeat { readonly agent: HeartbeatAgent; readonly config: HeartbeatConfig; private _running; private _timer; private _tickInFlight; private _retries; private readonly _intervalSeconds; private _stopped; private _resolveStopped; constructor(agent: HeartbeatAgent, options?: HeartbeatOptions); /** Interval between ticks in seconds, as resolved from `config.schedule`. */ get intervalSeconds(): number; /** Python `is_running`. */ get isRunning(): boolean; /** * Start the heartbeat loop. The first tick runs immediately, then every * interval, as in Python. * * @param blocking Python `start(blocking=True)`. When true the returned * promise resolves only after {@link stop} is called and any in-flight * tick has finished (the async counterpart of a blocking loop). When * false the promise resolves as soon as the loop is scheduled, and the * heartbeat keeps running in the background. */ start(blocking?: boolean): Promise; /** Stop the heartbeat loop; clears the pending timer so nothing fires again. */ stop(): void; private _settleStopped; /** One iteration of Python's `_loop`: tick, handle the outcome, sleep. */ private _loop; private _handleError; /** Execute one heartbeat tick — run the agent and return its result text. */ private _tick; /** Deliver the result via callback or log. */ private _deliver; }