@elizaos/plugin-cron 2.0.0-alpha.3

package/dist/index.d.ts

@@ -0,0 +1,561 @@
+import { IAgentRuntime, TaskWorker, Service, Plugin } from '@elizaos/core';
+import { C as CronJob, a as CronServiceConfig, b as CronExecutionResult, c as CronSchedule, d as CronJobCreate, e as CronJobPatch, f as CronJobFilter } from './index-CcftVpZH.js';
+export { g as CronEventData, h as CronExecutionContext, i as CronJobState, j as CronJobStatus, k as CronPayload, l as CronPayloadAction, m as CronPayloadEvent, n as CronPayloadPrompt, o as CronScheduleAt, p as CronScheduleCron, q as CronScheduleEvery, D as DEFAULT_CRON_CONFIG, r as otto } from './index-CcftVpZH.js';
+
+/**
+ * @module constants
+ * @description Constants for the cron plugin
+ */
+declare const CRON_SERVICE_TYPE = "CRON";
+declare const CRON_JOB_COMPONENT_PREFIX = "cron_job";
+declare const CRON_JOB_INDEX_COMPONENT = "cron_job_index";
+declare const CronEvents: {
+    readonly CRON_FIRED: "CRON_FIRED";
+    readonly CRON_CREATED: "CRON_CREATED";
+    readonly CRON_UPDATED: "CRON_UPDATED";
+    readonly CRON_DELETED: "CRON_DELETED";
+    readonly CRON_FAILED: "CRON_FAILED";
+};
+declare const CronActions: {
+    readonly CREATE_CRON: "CREATE_CRON";
+    readonly UPDATE_CRON: "UPDATE_CRON";
+    readonly DELETE_CRON: "DELETE_CRON";
+    readonly LIST_CRONS: "LIST_CRONS";
+    readonly RUN_CRON: "RUN_CRON";
+};
+
+/**
+ * @module job-executor
+ * @description Executes cron job payloads with timeout and error handling
+ *
+ * Execution strategies by payload type:
+ * - prompt: Uses runtime.useModel() to process the prompt
+ * - action: Finds and invokes the named action via runtime.processActions()
+ * - event: Emits an event via runtime.emitEvent()
+ */
+
+/**
+ * Executes a cron job payload
+ * @param runtime The agent runtime
+ * @param job The cron job to execute
+ * @param config Service configuration
+ * @returns Execution result
+ */
+declare function executeJob(runtime: IAgentRuntime, job: CronJob, config: CronServiceConfig): Promise<CronExecutionResult>;
+/**
+ * Validates that a job can be executed
+ * @returns Error message if invalid, null if valid
+ */
+declare function validateJobExecutability(runtime: IAgentRuntime, job: CronJob): string | null;
+
+/**
+ * @module heartbeat/config
+ * @description Configuration for the heartbeat worker.
+ *
+ * Reads heartbeat settings from the agent's runtime settings,
+ * supporting the same config shape as the Otto docs:
+ *   agents.defaults.heartbeat.every
+ *   agents.defaults.heartbeat.activeHours
+ *   agents.defaults.heartbeat.target
+ *   agents.defaults.heartbeat.prompt
+ */
+
+interface ActiveHours {
+    start: string;
+    end: string;
+}
+interface HeartbeatConfig {
+    /** Interval between heartbeats in milliseconds. */
+    everyMs: number;
+    /** Optional active hours window. Heartbeats outside this window are skipped. */
+    activeHours: ActiveHours | null;
+    /** Delivery target. "last" uses the agent's last delivery route. */
+    target: string;
+    /** Name of the workspace file to read as heartbeat instructions. */
+    promptFile: string;
+    /** If true the heartbeat worker is enabled. */
+    enabled: boolean;
+}
+/**
+ * Resolve heartbeat config from runtime settings.
+ *
+ * Looks for the `heartbeat` key in the character settings object,
+ * which matches the Otto config shape:
+ *   heartbeat: { every: "30m", activeHours: { start, end }, target, prompt }
+ */
+declare function resolveHeartbeatConfig(runtime: IAgentRuntime): HeartbeatConfig;
+/**
+ * Check whether the current local time falls inside the active hours window.
+ * Returns true if no active hours are configured (always active).
+ */
+declare function isWithinActiveHours(activeHours: ActiveHours | null): boolean;
+
+/**
+ * @module heartbeat/queue
+ * @description In-memory queue for system events destined for the next heartbeat tick.
+ *
+ * Cron main-session jobs push text here via pushSystemEvent().
+ * The heartbeat worker drains the queue on each tick and includes
+ * the events in the heartbeat prompt so the agent can act on them.
+ */
+interface SystemEvent {
+    text: string;
+    source: string;
+    ts: number;
+}
+/**
+ * Push a system event for delivery on the next heartbeat tick.
+ */
+declare function pushSystemEvent(agentId: string, text: string, source: string): void;
+/**
+ * Drain all pending system events for an agent.
+ * Returns the events and clears the queue.
+ */
+declare function drainSystemEvents(agentId: string): SystemEvent[];
+/**
+ * Peek at pending event count without draining.
+ */
+declare function pendingEventCount(agentId: string): number;
+
+/**
+ * @module heartbeat/worker
+ * @description Heartbeat TaskWorker for periodic agent wakeup.
+ *
+ * Registers as an Eliza TaskWorker named "heartbeat".
+ * On each tick the worker:
+ *   1. Checks active hours
+ *   2. Drains the system events queue
+ *   3. Reads HEARTBEAT.md from the workspace
+ *   4. Sends a message into a heartbeat room via messageService.handleMessage()
+ *   5. Captures the agent's response
+ *   6. Suppresses HEARTBEAT_OK; otherwise delivers via sendMessageToTarget()
+ */
+
+declare const HEARTBEAT_WORKER_NAME = "heartbeat";
+/**
+ * The heartbeat TaskWorker. Register this with the runtime and create
+ * a recurring task to drive periodic heartbeats.
+ */
+declare const heartbeatWorker: TaskWorker;
+/**
+ * Register the heartbeat worker and create the recurring task.
+ */
+declare function startHeartbeat(runtime: IAgentRuntime): Promise<void>;
+/**
+ * Trigger an immediate heartbeat. Creates a one-shot "immediate" task
+ * that the TaskService will pick up on the next 1-second tick.
+ */
+declare function wakeHeartbeatNow(runtime: IAgentRuntime): Promise<void>;
+
+/**
+ * @module schedule-utils
+ * @description Utility functions for computing next run times and validating schedules
+ *
+ * Uses the 'croner' library for cron expression parsing which supports:
+ * - Standard 5-field cron expressions (minute hour day month weekday)
+ * - Extended 6-field expressions with seconds
+ * - Timezone support via IANA timezone names
+ */
+
+/**
+ * Validates a complete schedule
+ * @param schedule The schedule to validate
+ * @param config Service configuration
+ * @returns Error message if invalid, null if valid
+ */
+declare function validateSchedule(schedule: CronSchedule, config: CronServiceConfig): string | null;
+/**
+ * Computes the next run time for a schedule
+ * @param schedule The schedule configuration
+ * @param nowMs Current time in milliseconds since epoch
+ * @returns Next run time in ms, or undefined if the schedule has no more runs
+ */
+declare function computeNextRunAtMs(schedule: CronSchedule, nowMs: number): number | undefined;
+/**
+ * Formats a schedule for human-readable display
+ * @param schedule The schedule to format
+ * @returns Human-readable description
+ */
+declare function formatSchedule(schedule: CronSchedule): string;
+/**
+ * Parses a human-readable duration string to milliseconds
+ * Supports formats like "5m", "2h", "1d", "30s"
+ * @param duration Duration string
+ * @returns Milliseconds (always > 0), or null if invalid or zero
+ */
+declare function parseDuration(duration: string): number | null;
+/**
+ * Creates a schedule from a human-readable description
+ * Supports:
+ * - "in 5 minutes" / "in 2 hours" -> 'at' schedule
+ * - "every 5 minutes" / "every hour" -> 'every' schedule
+ * - "at 9am" / "at 2024-12-31" -> 'at' schedule
+ * - Cron expressions (detected by field count)
+ *
+ * @param description Human-readable schedule description
+ * @param nowMs Current time for relative calculations
+ * @returns CronSchedule or undefined if parsing failed
+ */
+declare function parseScheduleDescription(description: string, nowMs?: number): CronSchedule | undefined;
+
+/**
+ * @module timer-manager
+ * @description Manages timers for cron job scheduling
+ *
+ * Uses a periodic check interval that:
+ * 1. Identifies jobs that are due
+ * 2. Fires callbacks for due jobs
+ * 3. Recalculates next run times
+ *
+ * Croner is used for parsing cron expressions, but timing is managed
+ * internally via setInterval for consistent behavior across schedule types.
+ */
+
+/**
+ * Callback invoked when a job is due for execution
+ */
+type JobDueCallback = (jobId: string) => Promise<void>;
+/**
+ * Timer manager for cron job scheduling
+ */
+declare class TimerManager {
+    private readonly config;
+    private readonly onJobDue;
+    private readonly trackedJobs;
+    private checkInterval;
+    private running;
+    constructor(config: CronServiceConfig, onJobDue: JobDueCallback);
+    /**
+     * Starts the timer manager
+     */
+    start(): void;
+    /**
+     * Stops the timer manager and cleans up all timers
+     */
+    stop(): void;
+    /**
+     * Adds or updates a job in the timer manager
+     * @param job The job to track
+     */
+    trackJob(job: CronJob): void;
+    /**
+     * Removes a job from tracking
+     * @param jobId The job ID to remove
+     */
+    untrackJob(jobId: string): void;
+    /**
+     * Marks a job as currently executing (to prevent overlapping executions)
+     * @param jobId The job ID
+     */
+    markExecuting(jobId: string): void;
+    /**
+     * Marks a job as finished executing and recalculates next run
+     * @param jobId The job ID
+     * @param updatedJob The job with updated state (optional)
+     */
+    markFinished(jobId: string, updatedJob?: CronJob): void;
+    /**
+     * Gets the next scheduled run time for a job
+     * @param jobId The job ID
+     * @returns Next run time in ms, or undefined
+     */
+    getNextRunAtMs(jobId: string): number | undefined;
+    /**
+     * Gets all tracked job IDs
+     */
+    getTrackedJobIds(): string[];
+    /**
+     * Gets the count of tracked jobs
+     */
+    getTrackedJobCount(): number;
+    /**
+     * Checks if a specific job is currently executing
+     */
+    isJobExecuting(jobId: string): boolean;
+    /**
+     * Forces an immediate check for due jobs
+     */
+    checkNow(): void;
+    /**
+     * Starts the periodic check interval
+     */
+    private startCheckInterval;
+    /**
+     * Stops the periodic check interval
+     */
+    private stopCheckInterval;
+    /**
+     * Performs a check for all due jobs
+     */
+    private performCheck;
+    /**
+     * Clears all tracked jobs
+     */
+    private clearAllJobs;
+}
+
+/**
+ * @module cron-service
+ * @description Main service for cron job management
+ *
+ * The CronService handles:
+ * - Job CRUD operations
+ * - Timer management for scheduling
+ * - Job execution coordination
+ * - Event emission for job lifecycle
+ * - Persistence via component storage
+ */
+
+/**
+ * Cron scheduling service for ElizaOS
+ *
+ * Provides the ability to schedule recurring or one-time jobs that
+ * execute prompts, actions, or emit events on a defined schedule.
+ */
+declare class CronService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private cronConfig;
+    private storage;
+    private timerManager;
+    private initialized;
+    constructor(runtime?: IAgentRuntime, config?: Partial<CronServiceConfig>);
+    /**
+     * Starts the cron service
+     */
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    /**
+     * Initializes the service, loading existing jobs and starting timers
+     */
+    private initialize;
+    /**
+     * Stops the cron service
+     */
+    stop(): Promise<void>;
+    /**
+     * Gets the service configuration
+     */
+    getConfig(): CronServiceConfig;
+    /**
+     * Creates a new cron job
+     * @param input Job creation input
+     * @returns The created job
+     * @throws Error if validation fails or max jobs exceeded
+     */
+    createJob(input: CronJobCreate): Promise<CronJob>;
+    /**
+     * Updates an existing cron job
+     * @param jobId The job ID to update
+     * @param patch The fields to update
+     * @returns The updated job
+     * @throws Error if job not found or validation fails
+     */
+    updateJob(jobId: string, patch: CronJobPatch): Promise<CronJob>;
+    /**
+     * Deletes a cron job
+     * @param jobId The job ID to delete
+     * @returns true if deleted, false if not found
+     */
+    deleteJob(jobId: string): Promise<boolean>;
+    /**
+     * Gets a job by ID
+     * @param jobId The job ID
+     * @returns The job or null if not found
+     */
+    getJob(jobId: string): Promise<CronJob | null>;
+    /**
+     * Lists all jobs, optionally filtered
+     * @param filter Optional filter criteria
+     * @returns Array of matching jobs
+     */
+    listJobs(filter?: CronJobFilter): Promise<CronJob[]>;
+    /**
+     * Gets the count of jobs
+     */
+    getJobCount(): Promise<number>;
+    /**
+     * Manually runs a job immediately
+     * @param jobId The job ID to run
+     * @param mode 'force' to run even if disabled, 'due' to only run if due
+     * @returns Execution result
+     */
+    runJob(jobId: string, mode?: "force" | "due"): Promise<CronExecutionResult & {
+        ran: boolean;
+    }>;
+    /**
+     * Handles a job becoming due (called by timer manager)
+     */
+    private handleJobDue;
+    /**
+     * Internal job execution with state management
+     */
+    private executeJobInternal;
+    /**
+     * Handles catch-up for jobs that may have been missed while the service was stopped
+     */
+    private handleMissedJobs;
+    /**
+     * Emits a cron event
+     */
+    private emitCronEvent;
+    /**
+     * Gets the service status
+     */
+    getStatus(): Promise<{
+        initialized: boolean;
+        jobCount: number;
+        trackedJobCount: number;
+        config: CronServiceConfig;
+    }>;
+    /**
+     * Performs a health check
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        issues: string[];
+    }>;
+}
+
+/**
+ * @module cron-storage
+ * @description Component-based persistence for cron job data using ElizaOS Components
+ *
+ * Storage strategy:
+ * - Each job is stored as a separate component with type "cron_job:{jobId}"
+ * - An index component "cron_job_index" tracks all job IDs for efficient listing
+ * - All components are scoped to the agent (entityId = agentId)
+ * - Index operations are serialized using an async mutex to prevent race conditions
+ */
+
+/**
+ * Storage interface for cron job operations
+ */
+interface CronStorage {
+    /**
+     * Retrieves a job by ID
+     * @returns The job or null if not found
+     */
+    getJob(jobId: string): Promise<CronJob | null>;
+    /**
+     * Saves a job (creates or updates)
+     */
+    saveJob(job: CronJob): Promise<void>;
+    /**
+     * Deletes a job by ID
+     * @returns true if the job was deleted, false if it didn't exist
+     */
+    deleteJob(jobId: string): Promise<boolean>;
+    /**
+     * Lists all jobs, optionally filtered
+     * @param filter Optional filter criteria
+     * @returns Array of matching jobs, sorted by next run time
+     */
+    listJobs(filter?: CronJobFilter): Promise<CronJob[]>;
+    /**
+     * Gets the total count of jobs for the agent
+     */
+    getJobCount(): Promise<number>;
+    /**
+     * Checks if a job exists
+     */
+    hasJob(jobId: string): Promise<boolean>;
+}
+/**
+ * Creates a storage instance for cron job operations
+ * @param runtime The agent runtime to use for component storage
+ */
+declare function getCronStorage(runtime: IAgentRuntime): CronStorage;
+
+/**
+ * @module plugin-cron
+ * @description ElizaOS plugin for cron job scheduling
+ *
+ * This plugin provides:
+ * - Scheduled job execution (cron expressions, intervals, one-time)
+ * - CRUD operations for managing jobs
+ * - Multiple payload types: prompts, actions, events
+ * - Persistent storage via Eliza components
+ * - Natural language job creation
+ *
+ * Key features:
+ * - Standard cron expression support (via croner)
+ * - Timezone-aware scheduling
+ * - Automatic catch-up for missed jobs
+ * - Job lifecycle events
+ *
+ * @example
+ * ```typescript
+ * import { cronPlugin } from '@elizaos/plugin-cron';
+ *
+ * const character = createCharacter({
+ *   name: 'Scheduler',
+ *   plugins: [cronPlugin],
+ * });
+ * ```
+ */
+
+/**
+ * Cron scheduling plugin for ElizaOS
+ *
+ * Provides the ability to schedule recurring or one-time jobs that
+ * execute prompts, actions, or emit events on a defined schedule.
+ *
+ * Usage:
+ * ```typescript
+ * import { cronPlugin } from '@elizaos/plugin-cron';
+ *
+ * const agent = {
+ *   character: myCharacter,
+ *   plugins: [cronPlugin],
+ * };
+ * ```
+ *
+ * Once loaded, the plugin provides:
+ * - `CronService` - Core service for job management
+ * - Actions: CREATE_CRON, UPDATE_CRON, DELETE_CRON, LIST_CRONS, RUN_CRON
+ * - Provider: cronContext for injecting job info into prompts
+ *
+ * Creating jobs programmatically:
+ * ```typescript
+ * const cronService = runtime.getService<CronService>('CRON');
+ *
+ * // Create an interval job
+ * await cronService.createJob({
+ *   name: 'Hourly check',
+ *   enabled: true,
+ *   schedule: { kind: 'every', everyMs: 3600000 },
+ *   payload: { kind: 'prompt', text: 'Check system status' },
+ * });
+ *
+ * // Create a cron expression job
+ * await cronService.createJob({
+ *   name: 'Daily report',
+ *   enabled: true,
+ *   schedule: { kind: 'cron', expr: '0 9 * * *', tz: 'America/New_York' },
+ *   payload: { kind: 'prompt', text: 'Generate daily report' },
+ * });
+ *
+ * // Create a one-shot job
+ * await cronService.createJob({
+ *   name: 'Reminder',
+ *   enabled: true,
+ *   deleteAfterRun: true,
+ *   schedule: { kind: 'at', at: '2024-12-31T23:59:00Z' },
+ *   payload: { kind: 'prompt', text: 'Happy New Year!' },
+ * });
+ * ```
+ */
+/**
+ * Custom event names for cross-plugin communication.
+ * Other plugins (e.g. plugin-webhooks) can emit these to trigger
+ * heartbeat behaviour without a direct import dependency.
+ */
+declare const CronPluginEvents: {
+    /** Request an immediate heartbeat tick. Payload: { text?: string } */
+    readonly HEARTBEAT_WAKE: "HEARTBEAT_WAKE";
+    /** Enqueue a system event for the next heartbeat. Payload: { text: string } */
+    readonly HEARTBEAT_SYSTEM_EVENT: "HEARTBEAT_SYSTEM_EVENT";
+};
+declare const cronPlugin: Plugin;
+
+export { type ActiveHours, CRON_JOB_COMPONENT_PREFIX, CRON_JOB_INDEX_COMPONENT, CRON_SERVICE_TYPE, CronActions, CronEvents, CronExecutionResult, CronJob, CronJobCreate, CronJobFilter, CronJobPatch, CronPluginEvents, CronSchedule, CronService, CronServiceConfig, type CronStorage, HEARTBEAT_WORKER_NAME, type HeartbeatConfig, type SystemEvent, TimerManager, computeNextRunAtMs, cronPlugin, cronPlugin as default, drainSystemEvents, executeJob, formatSchedule, getCronStorage, heartbeatWorker, isWithinActiveHours, parseDuration, parseScheduleDescription, pendingEventCount, pushSystemEvent, resolveHeartbeatConfig, startHeartbeat, validateJobExecutability, validateSchedule, wakeHeartbeatNow };