import type { Config } from "./config.js"; import type { Events } from "./events.js"; import type { JobRecord, JobStatus, JobStore } from "./jobs.js"; import type { Logger } from "./logger.js"; import type { JobQueue } from "./queue.js"; import type { SkillRegistry } from "./registry.js"; import type { NormalizedSchedule, Skill } from "./skills.js"; /** How often the scheduler compares the wall clock with the next due slot. */ export declare const SCHEDULER_TICK_MS = 15000; /** `catch_up: none` still fires a slot this recent, so ordinary tick timing never loses one. */ export declare const CATCH_UP_GRACE_MS: number; /** `catch_up: all` fires at most this many missed slots, oldest first; older ones are skipped. */ export declare const CATCH_UP_MAX_SLOTS = 24; export interface ScheduleState { /** The most recent slot the scheduler has dealt with (fired or skipped); slots at or before it are never revisited. */ last_slot?: string; last_fired_at?: string; last_job?: string; last_status?: JobStatus; /** Slots that were due but not run (still in flight, caught up, too old, paused, or already fired by an earlier process). */ skipped?: number; /** Set while the schedule is paused (`skillhook schedules pause`, `POST /schedules//pause`, the cloud's `schedule.pause`). Lives here, not in the skill's file, so a repository pull or a restart keeps it. */ paused?: SchedulePause; } /** Who paused a schedule, why, and until when (absent: until someone resumes it). */ export interface SchedulePause { at: string; by?: string; reason?: string; until?: string; } export type ScheduleStates = Record; export interface ScheduleStatus { skill: string; cron: string; timezone: string; catch_up: NormalizedSchedule["catch_up"]; overlap: NormalizedSchedule["overlap"]; enabled: boolean; webhook: boolean; next_due: string | null; last_slot: string | null; last_fired_at: string | null; last_job: string | null; last_status: JobStatus | null; skipped: number; /** Set while the schedule is paused; its slots pass without a job and are not caught up on resume. */ paused: SchedulePause | null; } export type SkipReason = "in_flight" | "caught_up" | "too_old" | "duplicate"; export interface TickResult { fired: JobRecord[]; skipped: { skill: string; slot: string; reason: SkipReason; }[]; } export declare function scheduleStateFile(jobsDir: string): string; export declare function readScheduleStates(jobsDir: string): ScheduleStates; /** The payload of a scheduled run: the hook's static `payload` plus what fired. `{{payload.scheduled_for}}` is the slot as an ISO instant. */ export declare function buildSchedulePayload(skill: Skill, slot: Date, options?: { firedAt?: Date; caughtUp?: boolean; manual?: boolean; }): Record; /** The pause in force at `now`: none once its `until` has passed. */ export declare function activePause(state: ScheduleState | undefined, now?: Date): SchedulePause | undefined; export declare function scheduleStatus(skill: Skill, state: ScheduleState | undefined, now?: Date): ScheduleStatus | undefined; /** Thrown by `pause` / `resume` for a skill that does not exist or has no schedule. */ export declare class ScheduleControlError extends Error { readonly code: "not_found" | "conflict" | "invalid_args"; constructor(code: "not_found" | "conflict" | "invalid_args", message: string); } export interface PauseOptions { by?: string; reason?: string; /** An ISO-8601 instant in the future; absent pauses until someone resumes. */ until?: string; } /** Validates a pause request against the registry and builds the record; shared by the server and the offline CLI. */ export declare function buildPause(registry: SkillRegistry, name: string, options: PauseOptions, now?: Date): SchedulePause; /** * Pause or resume with no server running: the state file is written directly (a running server owns it in memory, so * the CLI goes through `POST /schedules//pause` instead). Returns the schedule's new status. */ export declare function setPauseOffline(input: { registry: SkillRegistry; jobsDir: string; }, name: string, pause: PauseOptions | null, now?: Date): ScheduleStatus; /** Every scheduled skill with its persisted state: what `skillhook schedules list` and the MCP tool show when no server is running. */ export declare function listSchedules(input: { registry: SkillRegistry; jobsDir: string; }, now?: Date): ScheduleStatus[]; /** Slots strictly after `after` and at or before `until`, newest first, at most `limit` of them. */ export declare function dueSlots(schedule: NormalizedSchedule, after: Date, until: Date, limit?: number): Date[]; export interface SchedulerDeps { registry: SkillRegistry; store: JobStore; queue: JobQueue; config: Config; logger: Logger; /** The clock; tests pass a fixed one. */ now?: () => Date; tickMs?: number; /** Where `schedule.registered`, `schedule.fired` and `schedule.skipped` are published. */ events?: Events; } export declare class Scheduler { private readonly deps; private states; private timer; private readonly file; private readonly onFinished; constructor(deps: SchedulerDeps); /** Ticks now and then every `tickMs`; the timer never keeps the process alive. */ start(): void; stop(): void; private now; private save; /** Enabled skills with a schedule; a registry that fails to list (unreadable config) skips this tick rather than crashing the server. */ private scheduled; private safeTick; status(now?: Date): ScheduleStatus[]; /** Stops the schedule from firing (webhooks still run) until `resume`, or until `options.until`. Slots that pass while paused are not caught up. */ pause(name: string, options?: PauseOptions, now?: Date): ScheduleStatus; resume(name: string, options?: { by?: string; }, now?: Date): ScheduleStatus; /** One pass over every schedule. Exported for tests; the server calls it on its timer. */ tick(now?: Date): TickResult; private fire; }