@elizaos/plugin-cron 2.0.0-alpha.3

package/dist/index-CcftVpZH.d.ts

@@ -0,0 +1,553 @@
+import { UUID, IAgentRuntime } from '@elizaos/core';
+
+/**
+ * @module types
+ * @description Type definitions for the cron scheduling plugin
+ */
+
+/**
+ * One-time schedule that runs at a specific timestamp
+ */
+interface CronScheduleAt {
+    kind: "at";
+    /** ISO 8601 timestamp for one-time execution */
+    at: string;
+}
+/**
+ * Interval-based schedule that runs repeatedly at fixed intervals
+ */
+interface CronScheduleEvery {
+    kind: "every";
+    /** Interval in milliseconds (minimum enforced by config) */
+    everyMs: number;
+    /** Optional anchor timestamp for interval calculation */
+    anchorMs?: number;
+}
+/**
+ * Cron expression-based schedule supporting standard 5-field or 6-field (with seconds) format
+ */
+interface CronScheduleCron {
+    kind: "cron";
+    /** Cron expression (e.g., "0 9 * * 1-5" for 9am weekdays) */
+    expr: string;
+    /** IANA timezone (e.g., "America/New_York"). Defaults to UTC if not specified */
+    tz?: string;
+}
+/**
+ * Union type for all schedule variants
+ */
+type CronSchedule = CronScheduleAt | CronScheduleEvery | CronScheduleCron;
+/**
+ * Payload that sends a prompt to the agent for processing
+ */
+interface CronPayloadPrompt {
+    kind: "prompt";
+    /** The prompt text to send to the agent */
+    text: string;
+    /** Optional model override (provider/model format or alias) */
+    model?: string;
+    /** Thinking level for reasoning models */
+    thinking?: "none" | "low" | "medium" | "high";
+    /** Execution timeout in seconds (overrides default) */
+    timeoutSeconds?: number;
+}
+/**
+ * Payload that invokes a specific action by name
+ */
+interface CronPayloadAction {
+    kind: "action";
+    /** Name of the action to invoke (must be registered with the runtime) */
+    actionName: string;
+    /** Parameters to pass to the action handler */
+    params?: Record<string, unknown>;
+    /** Optional room context for action execution */
+    roomId?: UUID;
+}
+/**
+ * Payload that emits a custom event
+ */
+interface CronPayloadEvent {
+    kind: "event";
+    /** Event name to emit */
+    eventName: string;
+    /** Event payload data */
+    payload?: Record<string, unknown>;
+}
+/**
+ * Union type for all payload variants
+ */
+type CronPayload$1 = CronPayloadPrompt | CronPayloadAction | CronPayloadEvent;
+/**
+ * Status of a job execution
+ */
+type CronJobStatus = "ok" | "error" | "skipped" | "timeout";
+/**
+ * Runtime state of a cron job, tracking execution history and next run
+ */
+interface CronJobState {
+    /** Next scheduled run time (ms since epoch) */
+    nextRunAtMs?: number;
+    /** Currently running since (ms since epoch), undefined if not running */
+    runningAtMs?: number;
+    /** Last completed run time (ms since epoch) */
+    lastRunAtMs?: number;
+    /** Status of the last run */
+    lastStatus?: CronJobStatus;
+    /** Error message from the last run if it failed */
+    lastError?: string;
+    /** Duration of the last run in milliseconds */
+    lastDurationMs?: number;
+    /** Total number of successful runs */
+    runCount: number;
+    /** Total number of failed runs */
+    errorCount: number;
+}
+/**
+ * Complete definition of a cron job
+ */
+interface CronJob$1 {
+    /** Unique job identifier (UUID v4) */
+    id: string;
+    /** Human-readable name for the job */
+    name: string;
+    /** Optional description explaining what the job does */
+    description?: string;
+    /** Whether the job is active and will be scheduled */
+    enabled: boolean;
+    /** If true, the job is deleted after successful execution (for one-shot jobs) */
+    deleteAfterRun?: boolean;
+    /** Timestamp when the job was created (ms since epoch) */
+    createdAtMs: number;
+    /** Timestamp when the job was last updated (ms since epoch) */
+    updatedAtMs: number;
+    /** Schedule configuration defining when the job runs */
+    schedule: CronSchedule;
+    /** Payload configuration defining what the job does */
+    payload: CronPayload$1;
+    /** Runtime state tracking execution history */
+    state: CronJobState;
+    /** Optional tags for filtering and grouping jobs */
+    tags?: string[];
+    /** Optional metadata for extensibility */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for creating a new cron job (id, timestamps, and state are auto-generated)
+ */
+type CronJobCreate$1 = Omit<CronJob$1, "id" | "createdAtMs" | "updatedAtMs" | "state"> & {
+    /** Optional partial state to initialize (e.g., for migration) */
+    state?: Partial<CronJobState>;
+};
+/**
+ * Input for updating an existing cron job (id and createdAt are immutable)
+ */
+type CronJobPatch$1 = Partial<Omit<CronJob$1, "id" | "createdAtMs" | "state">> & {
+    /** Optional partial state updates */
+    state?: Partial<CronJobState>;
+};
+/**
+ * Filter options for listing cron jobs
+ */
+interface CronJobFilter {
+    /** If true, include disabled jobs in results */
+    includeDisabled?: boolean;
+    /** Filter by tags (matches if job has any of these tags) */
+    tags?: string[];
+    /** Filter by enabled status */
+    enabled?: boolean;
+}
+/**
+ * Configuration options for the cron service
+ */
+interface CronServiceConfig {
+    /** Minimum interval for 'every' schedules in ms (default: 10000) */
+    minIntervalMs: number;
+    /** Maximum number of jobs per agent (default: 100) */
+    maxJobsPerAgent: number;
+    /** Default execution timeout in ms (default: 300000 = 5 minutes) */
+    defaultTimeoutMs: number;
+    /** Whether to run missed jobs on startup (default: false) */
+    catchUpMissedJobs: boolean;
+    /** How far back to look for missed jobs in ms (default: 3600000 = 1 hour) */
+    catchUpWindowMs: number;
+    /** Timer check interval for managing job scheduling in ms (default: 1000) */
+    timerCheckIntervalMs: number;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CRON_CONFIG: CronServiceConfig;
+/**
+ * Payload for cron-related events
+ */
+interface CronEventData {
+    /** Job ID */
+    jobId: string;
+    /** Job name */
+    jobName: string;
+    /** Job schedule */
+    schedule: CronSchedule;
+    /** Execution result (only for CRON_FIRED event) */
+    result?: {
+        status: CronJobStatus;
+        durationMs: number;
+        output?: string;
+        error?: string;
+    };
+}
+/**
+ * Result of executing a cron job
+ */
+interface CronExecutionResult {
+    /** Whether execution was successful */
+    status: CronJobStatus;
+    /** Duration of execution in milliseconds */
+    durationMs: number;
+    /** Output from the execution (for prompt payloads) */
+    output?: string;
+    /** Error message if execution failed */
+    error?: string;
+}
+/**
+ * Context provided during job execution
+ */
+interface CronExecutionContext {
+    /** The job being executed */
+    job: CronJob$1;
+    /** Timestamp when execution started */
+    startedAtMs: number;
+    /** Abort signal for timeout handling */
+    signal: AbortSignal;
+}
+
+/**
+ * @module otto/types
+ * @description Otto-specific cron type definitions
+ *
+ * These extend the base plugin-cron types with Otto-specific features:
+ * - Session targeting (main vs isolated)
+ * - Wake modes (heartbeat integration)
+ * - Delivery configuration (channel routing)
+ */
+
+type CronSessionTarget = "main" | "isolated";
+type CronWakeMode = "next-heartbeat" | "now";
+type CronMessageChannel = string | "last";
+type CronDeliveryMode = "none" | "announce";
+type CronDelivery = {
+    mode: CronDeliveryMode;
+    channel?: CronMessageChannel;
+    to?: string;
+    bestEffort?: boolean;
+};
+type CronDeliveryPatch = Partial<CronDelivery>;
+type CronPayload = {
+    kind: "systemEvent";
+    text: string;
+} | {
+    kind: "agentTurn";
+    message: string;
+    /** Optional model override (provider/model or alias). */
+    model?: string;
+    thinking?: string;
+    timeoutSeconds?: number;
+    allowUnsafeExternalContent?: boolean;
+    deliver?: boolean;
+    channel?: CronMessageChannel;
+    to?: string;
+    bestEffortDeliver?: boolean;
+};
+type CronPayloadPatch = {
+    kind: "systemEvent";
+    text?: string;
+} | {
+    kind: "agentTurn";
+    message?: string;
+    model?: string;
+    thinking?: string;
+    timeoutSeconds?: number;
+    allowUnsafeExternalContent?: boolean;
+    deliver?: boolean;
+    channel?: CronMessageChannel;
+    to?: string;
+    bestEffortDeliver?: boolean;
+};
+type CronJob = {
+    id: string;
+    agentId?: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    deleteAfterRun?: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    schedule: CronSchedule;
+    sessionTarget: CronSessionTarget;
+    wakeMode: CronWakeMode;
+    payload: CronPayload;
+    delivery?: CronDelivery;
+    state: CronJobState;
+};
+type CronStoreFile = {
+    version: 1;
+    jobs: CronJob[];
+};
+type CronJobCreate = Omit<CronJob, "id" | "createdAtMs" | "updatedAtMs" | "state"> & {
+    state?: Partial<CronJobState>;
+};
+type CronJobPatch = Partial<Omit<CronJob, "id" | "createdAtMs" | "state" | "payload">> & {
+    payload?: CronPayloadPatch;
+    delivery?: CronDeliveryPatch;
+    state?: Partial<CronJobState>;
+};
+
+/**
+ * @module otto/delivery
+ * @description Delivery plan resolution for cron jobs
+ */
+
+type CronDeliveryPlan = {
+    mode: CronDeliveryMode;
+    channel: CronMessageChannel;
+    to?: string;
+    source: "delivery" | "payload";
+    requested: boolean;
+};
+declare function resolveCronDeliveryPlan(job: CronJob): CronDeliveryPlan;
+
+/**
+ * @module otto/detect
+ * @description Lightweight Otto payload detection. No heavy dependencies.
+ */
+/**
+ * Check if a job payload uses Otto-specific kinds (systemEvent or agentTurn)
+ * rather than base plugin kinds (prompt, action, event).
+ */
+declare function isOttoPayload(payload: Record<string, unknown>): boolean;
+
+/**
+ * @module otto/executor
+ * @description Otto-specific job executor.
+ *
+ * Handles the two Otto payload kinds:
+ *
+ *  - systemEvent: pushes text to the heartbeat system events queue and
+ *    optionally triggers an immediate heartbeat wake.
+ *
+ *  - agentTurn:  creates an isolated room (cron:<jobId>), sends the
+ *    message via messageService.handleMessage() so the agent processes
+ *    it through its normal pipeline, captures the response, and delivers
+ *    it to the configured channel via sendMessageToTarget().
+ *
+ * This module follows the same connector pattern as Discord/Telegram –
+ * it is an "internal connector" that manufactures Memory objects and
+ * calls handleMessage().
+ */
+
+/**
+ * Execute an Otto job. Called from the main CronService when the payload
+ * kind is systemEvent or agentTurn.
+ */
+declare function executeOttoJob(runtime: IAgentRuntime, job: CronJob, config: CronServiceConfig): Promise<CronExecutionResult>;
+
+/**
+ * @module otto/job-utils
+ * @description Utility functions for cron job manipulation
+ *
+ * These functions handle job creation, patching, and validation,
+ * including backward-compatible legacy delivery field handling.
+ */
+
+/**
+ * Validates that the job spec is valid for the given session target
+ */
+declare function assertSupportedJobSpec(job: Pick<CronJob, "sessionTarget" | "payload">): void;
+/**
+ * Validates that delivery config is only used with isolated sessions
+ */
+declare function assertDeliverySupport(job: Pick<CronJob, "sessionTarget" | "delivery">): void;
+/**
+ * Normalizes a name field - trims and ensures non-empty
+ */
+declare function normalizeRequiredName(name: unknown): string;
+/**
+ * Normalizes an optional text field
+ */
+declare function normalizeOptionalText(text: unknown): string | undefined;
+/**
+ * Normalizes an optional agent ID
+ */
+declare function normalizeOptionalAgentId(agentId: unknown): string | undefined;
+/**
+ * Applies a patch to a job in place, handling legacy delivery fields
+ */
+declare function applyJobPatch(job: CronJob, patch: CronJobPatch): void;
+
+/**
+ * @module otto/normalize
+ * @description Input normalization utilities for cron jobs
+ */
+
+type UnknownRecord$1 = Record<string, unknown>;
+type NormalizeOptions = {
+    applyDefaults?: boolean;
+    /**
+     * Optional function to sanitize agent IDs.
+     * If not provided, basic trimming is applied.
+     */
+    sanitizeAgentId?: (raw: string) => string;
+};
+declare function normalizeCronJobInput(raw: unknown, options?: NormalizeOptions): UnknownRecord$1 | null;
+declare function normalizeCronJobCreate(raw: unknown, options?: NormalizeOptions): CronJobCreate | null;
+declare function normalizeCronJobPatch(raw: unknown, options?: NormalizeOptions): CronJobPatch | null;
+
+/**
+ * @module otto/parse
+ * @description Timestamp parsing utilities for cron schedules
+ */
+declare function parseAbsoluteTimeMs(input: string): number | null;
+
+/**
+ * @module otto/payload-migration
+ * @description Legacy payload migration utilities
+ */
+type UnknownRecord = Record<string, unknown>;
+declare function migrateLegacyCronPayload(payload: UnknownRecord): boolean;
+
+/**
+ * @module otto/run-log
+ * @description Cron job run log management
+ */
+type CronRunLogEntry = {
+    ts: number;
+    jobId: string;
+    action: "finished";
+    status?: "ok" | "error" | "skipped";
+    error?: string;
+    summary?: string;
+    runAtMs?: number;
+    durationMs?: number;
+    nextRunAtMs?: number;
+};
+declare function resolveCronRunLogPath(params: {
+    storePath: string;
+    jobId: string;
+}): string;
+declare function appendCronRunLog(filePath: string, entry: CronRunLogEntry, opts?: {
+    maxBytes?: number;
+    keepLines?: number;
+}): Promise<void>;
+declare function readCronRunLogEntries(filePath: string, opts?: {
+    limit?: number;
+    jobId?: string;
+}): Promise<CronRunLogEntry[]>;
+
+/**
+ * @module otto/store
+ * @description Cron job store management
+ */
+
+/**
+ * Resolves the cron store path.
+ * If a path is provided, it will be resolved (with ~ expansion).
+ * If no path is provided, returns undefined (caller should use their own default).
+ */
+declare function resolveCronStorePath(storePath?: string): string | undefined;
+declare function loadCronStore(storePath: string): Promise<CronStoreFile>;
+declare function saveCronStore(storePath: string, store: CronStoreFile): Promise<void>;
+
+/**
+ * @module otto/validate-timestamp
+ * @description Timestamp validation for cron schedules
+ */
+
+type TimestampValidationError = {
+    ok: false;
+    message: string;
+};
+type TimestampValidationSuccess = {
+    ok: true;
+};
+type TimestampValidationResult = TimestampValidationSuccess | TimestampValidationError;
+/**
+ * Validates at timestamps in cron schedules.
+ * Rejects timestamps that are:
+ * - More than 1 minute in the past
+ * - More than 10 years in the future
+ */
+declare function validateScheduleTimestamp(schedule: CronSchedule, nowMs?: number): TimestampValidationResult;
+
+/**
+ * @module otto
+ * @description Otto-specific cron utilities and types
+ *
+ * This module provides Otto-specific extensions to the base plugin-cron:
+ * - Extended types with session targeting, wake modes, and delivery
+ * - Input normalization with backward compatibility
+ * - Job utilities for patching and validation
+ * - Run log management
+ * - Store utilities
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   normalizeCronJobCreate,
+ *   normalizeCronJobPatch,
+ *   validateScheduleTimestamp,
+ * } from '@elizaos/plugin-cron/otto';
+ *
+ * // Normalize input from API/CLI
+ * const normalized = normalizeCronJobCreate(rawInput);
+ *
+ * // Validate timestamp for "at" schedules
+ * const validation = validateScheduleTimestamp(schedule);
+ * if (!validation.ok) {
+ *   throw new Error(validation.message);
+ * }
+ * ```
+ */
+
+type index_CronDelivery = CronDelivery;
+type index_CronDeliveryMode = CronDeliveryMode;
+type index_CronDeliveryPatch = CronDeliveryPatch;
+type index_CronDeliveryPlan = CronDeliveryPlan;
+type index_CronJob = CronJob;
+type index_CronJobCreate = CronJobCreate;
+type index_CronJobPatch = CronJobPatch;
+type index_CronMessageChannel = CronMessageChannel;
+type index_CronPayload = CronPayload;
+type index_CronPayloadPatch = CronPayloadPatch;
+type index_CronRunLogEntry = CronRunLogEntry;
+type index_CronSchedule = CronSchedule;
+type index_CronSessionTarget = CronSessionTarget;
+type index_CronStoreFile = CronStoreFile;
+type index_CronWakeMode = CronWakeMode;
+type index_TimestampValidationError = TimestampValidationError;
+type index_TimestampValidationResult = TimestampValidationResult;
+type index_TimestampValidationSuccess = TimestampValidationSuccess;
+declare const index_appendCronRunLog: typeof appendCronRunLog;
+declare const index_applyJobPatch: typeof applyJobPatch;
+declare const index_assertDeliverySupport: typeof assertDeliverySupport;
+declare const index_assertSupportedJobSpec: typeof assertSupportedJobSpec;
+declare const index_executeOttoJob: typeof executeOttoJob;
+declare const index_isOttoPayload: typeof isOttoPayload;
+declare const index_loadCronStore: typeof loadCronStore;
+declare const index_migrateLegacyCronPayload: typeof migrateLegacyCronPayload;
+declare const index_normalizeCronJobCreate: typeof normalizeCronJobCreate;
+declare const index_normalizeCronJobInput: typeof normalizeCronJobInput;
+declare const index_normalizeCronJobPatch: typeof normalizeCronJobPatch;
+declare const index_normalizeOptionalAgentId: typeof normalizeOptionalAgentId;
+declare const index_normalizeOptionalText: typeof normalizeOptionalText;
+declare const index_normalizeRequiredName: typeof normalizeRequiredName;
+declare const index_parseAbsoluteTimeMs: typeof parseAbsoluteTimeMs;
+declare const index_readCronRunLogEntries: typeof readCronRunLogEntries;
+declare const index_resolveCronDeliveryPlan: typeof resolveCronDeliveryPlan;
+declare const index_resolveCronRunLogPath: typeof resolveCronRunLogPath;
+declare const index_resolveCronStorePath: typeof resolveCronStorePath;
+declare const index_saveCronStore: typeof saveCronStore;
+declare const index_validateScheduleTimestamp: typeof validateScheduleTimestamp;
+declare namespace index {
+  export { type index_CronDelivery as CronDelivery, type index_CronDeliveryMode as CronDeliveryMode, type index_CronDeliveryPatch as CronDeliveryPatch, type index_CronDeliveryPlan as CronDeliveryPlan, type index_CronJob as CronJob, type index_CronJobCreate as CronJobCreate, type index_CronJobPatch as CronJobPatch, type index_CronMessageChannel as CronMessageChannel, type index_CronPayload as CronPayload, type index_CronPayloadPatch as CronPayloadPatch, type index_CronRunLogEntry as CronRunLogEntry, type index_CronSchedule as CronSchedule, type index_CronSessionTarget as CronSessionTarget, type index_CronStoreFile as CronStoreFile, type index_CronWakeMode as CronWakeMode, type index_TimestampValidationError as TimestampValidationError, type index_TimestampValidationResult as TimestampValidationResult, type index_TimestampValidationSuccess as TimestampValidationSuccess, index_appendCronRunLog as appendCronRunLog, index_applyJobPatch as applyJobPatch, index_assertDeliverySupport as assertDeliverySupport, index_assertSupportedJobSpec as assertSupportedJobSpec, index_executeOttoJob as executeOttoJob, index_isOttoPayload as isOttoPayload, index_loadCronStore as loadCronStore, index_migrateLegacyCronPayload as migrateLegacyCronPayload, index_normalizeCronJobCreate as normalizeCronJobCreate, index_normalizeCronJobInput as normalizeCronJobInput, index_normalizeCronJobPatch as normalizeCronJobPatch, index_normalizeOptionalAgentId as normalizeOptionalAgentId, index_normalizeOptionalText as normalizeOptionalText, index_normalizeRequiredName as normalizeRequiredName, index_parseAbsoluteTimeMs as parseAbsoluteTimeMs, index_readCronRunLogEntries as readCronRunLogEntries, index_resolveCronDeliveryPlan as resolveCronDeliveryPlan, index_resolveCronRunLogPath as resolveCronRunLogPath, index_resolveCronStorePath as resolveCronStorePath, index_saveCronStore as saveCronStore, index_validateScheduleTimestamp as validateScheduleTimestamp };
+}
+
+export { resolveCronDeliveryPlan as $, type CronPayload as A, type CronPayloadPatch as B, type CronJob$1 as C, DEFAULT_CRON_CONFIG as D, type CronRunLogEntry as E, type CronSessionTarget as F, type CronStoreFile as G, type CronWakeMode as H, type TimestampValidationResult as I, type TimestampValidationSuccess as J, appendCronRunLog as K, applyJobPatch as L, assertDeliverySupport as M, assertSupportedJobSpec as N, executeOttoJob as O, isOttoPayload as P, loadCronStore as Q, migrateLegacyCronPayload as R, normalizeCronJobCreate as S, type TimestampValidationError as T, normalizeCronJobInput as U, normalizeCronJobPatch as V, normalizeOptionalAgentId as W, normalizeOptionalText as X, normalizeRequiredName as Y, parseAbsoluteTimeMs as Z, readCronRunLogEntries as _, type CronServiceConfig as a, resolveCronRunLogPath as a0, resolveCronStorePath as a1, saveCronStore as a2, validateScheduleTimestamp as a3, type CronExecutionResult as b, type CronSchedule as c, type CronJobCreate$1 as d, type CronJobPatch$1 as e, type CronJobFilter as f, type CronEventData as g, type CronExecutionContext as h, type CronJobState as i, type CronJobStatus as j, type CronPayload$1 as k, type CronPayloadAction as l, type CronPayloadEvent as m, type CronPayloadPrompt as n, type CronScheduleAt as o, type CronScheduleCron as p, type CronScheduleEvery as q, index as r, type CronDelivery as s, type CronDeliveryMode as t, type CronDeliveryPatch as u, type CronDeliveryPlan as v, type CronJob as w, type CronJobCreate as x, type CronJobPatch as y, type CronMessageChannel as z };