@axiom-lattice/protocols 2.1.6 → 2.1.8

package/src/ScheduleLatticeProtocol.ts

@@ -0,0 +1,394 @@
+/**
+ * ScheduleLatticeProtocol
+ *
+ * Schedule Lattice protocol for delayed and recurring task execution management
+ * Supports persistence and recovery after service restart
+ * Supports both one-time delayed tasks and cron-style recurring tasks
+ */
+
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * Schedule service type enumeration
+ */
+export enum ScheduleType {
+  MEMORY = "memory",
+  POSTGRES = "postgres",
+  REDIS = "redis",
+}
+
+/**
+ * Schedule execution type - one-time or recurring
+ */
+export enum ScheduleExecutionType {
+  ONCE = "once", // Execute once at specified time
+  CRON = "cron", // Recurring based on cron expression
+}
+
+/**
+ * Task status enumeration
+ */
+export enum ScheduledTaskStatus {
+  PENDING = "pending", // Waiting to be executed
+  RUNNING = "running", // Currently executing
+  COMPLETED = "completed", // Successfully completed (for ONCE type)
+  FAILED = "failed", // Execution failed
+  CANCELLED = "cancelled", // Manually cancelled
+  PAUSED = "paused", // Paused (for CRON type)
+}
+
+/**
+ * Schedule configuration interface
+ */
+export interface ScheduleConfig {
+  name: string;
+  description: string;
+  type: ScheduleType;
+  storage?: ScheduleStorage; // Optional storage for persistence
+  options?: Record<string, any>;
+}
+
+/**
+ * Scheduled task definition - fully serializable
+ * Supports both one-time and cron-style recurring tasks
+ */
+export interface ScheduledTaskDefinition {
+  taskId: string;
+  taskType: string; // Maps to a registered handler
+  payload: Record<string, any>; // JSON-serializable data passed to handler
+
+  // Context fields for querying
+  assistantId?: string; // Which assistant created/owns this task
+  threadId?: string; // Which thread this task belongs to
+
+  // Execution configuration
+  executionType: ScheduleExecutionType;
+
+  // For ONCE type - execute at specific time or after delay
+  executeAt?: number; // Timestamp when to execute
+  delayMs?: number; // Original delay in milliseconds (for reference)
+
+  // For CRON type - recurring schedule
+  cronExpression?: string; // Cron format: "0 9 * * *" (min hour day month weekday)
+  timezone?: string; // Timezone: "Asia/Shanghai", defaults to system timezone
+  nextRunAt?: number; // Next calculated execution time
+  lastRunAt?: number; // Last execution time
+
+  // Execution tracking
+  status: ScheduledTaskStatus;
+  runCount: number; // How many times executed
+  maxRuns?: number; // Max executions (null/undefined = infinite for cron, 1 for once)
+
+  // Error handling
+  retryCount: number; // Current retry count
+  maxRetries: number; // Maximum retry attempts
+  lastError?: string; // Last error message if failed
+
+  // Timestamps
+  createdAt: number;
+  updatedAt: number;
+  expiresAt?: number; // When to stop (for cron, optional)
+
+  metadata?: Record<string, any>; // Additional metadata
+}
+
+/**
+ * Task handler function type
+ */
+export type TaskHandler = (
+  payload: Record<string, any>,
+  taskInfo: ScheduledTaskDefinition
+) => void | Promise<void>;
+
+/**
+ * Options for scheduling a one-time task
+ */
+export interface ScheduleOnceOptions {
+  executeAt?: number; // Absolute timestamp to execute
+  delayMs?: number; // OR relative delay from now
+  maxRetries?: number; // Max retry attempts (default: 0)
+  assistantId?: string; // Which assistant created/owns this task
+  threadId?: string; // Which thread this task belongs to
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Options for scheduling a cron task
+ */
+export interface ScheduleCronOptions {
+  cronExpression: string; // Cron expression: "0 9 * * *"
+  timezone?: string; // Timezone: "Asia/Shanghai"
+  maxRuns?: number; // Max executions (undefined = infinite)
+  expiresAt?: number; // Stop after this timestamp
+  maxRetries?: number; // Max retry attempts per run (default: 0)
+  assistantId?: string; // Which assistant created/owns this task
+  threadId?: string; // Which thread this task belongs to
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Schedule storage interface for persistence
+ */
+export interface ScheduleStorage {
+  /**
+   * Save a new task
+   */
+  save(task: ScheduledTaskDefinition): Promise<void>;
+
+  /**
+   * Get task by ID
+   */
+  get(taskId: string): Promise<ScheduledTaskDefinition | null>;
+
+  /**
+   * Update task
+   */
+  update(
+    taskId: string,
+    updates: Partial<ScheduledTaskDefinition>
+  ): Promise<void>;
+
+  /**
+   * Delete task
+   */
+  delete(taskId: string): Promise<void>;
+
+  /**
+   * Get all pending/active tasks (for recovery)
+   * Returns tasks with status: PENDING or PAUSED
+   */
+  getActiveTasks(): Promise<ScheduledTaskDefinition[]>;
+
+  /**
+   * Get tasks by type
+   */
+  getTasksByType(taskType: string): Promise<ScheduledTaskDefinition[]>;
+
+  /**
+   * Get tasks by status
+   */
+  getTasksByStatus(
+    status: ScheduledTaskStatus
+  ): Promise<ScheduledTaskDefinition[]>;
+
+  /**
+   * Get tasks by execution type
+   */
+  getTasksByExecutionType(
+    executionType: ScheduleExecutionType
+  ): Promise<ScheduledTaskDefinition[]>;
+
+  /**
+   * Get tasks by assistant ID
+   */
+  getTasksByAssistantId(
+    assistantId: string
+  ): Promise<ScheduledTaskDefinition[]>;
+
+  /**
+   * Get tasks by thread ID
+   */
+  getTasksByThreadId(threadId: string): Promise<ScheduledTaskDefinition[]>;
+
+  /**
+   * Get all tasks (with optional filters)
+   */
+  getAllTasks(filters?: {
+    status?: ScheduledTaskStatus;
+    executionType?: ScheduleExecutionType;
+    taskType?: string;
+    assistantId?: string;
+    threadId?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<ScheduledTaskDefinition[]>;
+
+  /**
+   * Count tasks (with optional filters)
+   */
+  countTasks(filters?: {
+    status?: ScheduledTaskStatus;
+    executionType?: ScheduleExecutionType;
+    taskType?: string;
+    assistantId?: string;
+    threadId?: string;
+  }): Promise<number>;
+
+  /**
+   * Delete completed/cancelled tasks older than specified time
+   * Useful for cleanup
+   */
+  deleteOldTasks(olderThanMs: number): Promise<number>;
+}
+
+/**
+ * Schedule client interface
+ */
+export interface ScheduleClient {
+  // ===== Handler Registration =====
+
+  /**
+   * Register a handler for a task type
+   * Must be called before scheduling tasks of this type
+   */
+  registerHandler(taskType: string, handler: TaskHandler): void;
+
+  /**
+   * Unregister a handler
+   */
+  unregisterHandler(taskType: string): boolean;
+
+  /**
+   * Check if a handler is registered
+   */
+  hasHandler(taskType: string): boolean;
+
+  /**
+   * Get all registered handler types
+   */
+  getHandlerTypes(): string[];
+
+  // ===== One-time Task Scheduling =====
+
+  /**
+   * Schedule a one-time task
+   * @param taskId - Unique identifier for the task
+   * @param taskType - Type of task (must have a registered handler)
+   * @param payload - Data to pass to the handler (must be JSON-serializable)
+   * @param options - Execution options (executeAt or delayMs required)
+   */
+  scheduleOnce(
+    taskId: string,
+    taskType: string,
+    payload: Record<string, any>,
+    options: ScheduleOnceOptions
+  ): Promise<boolean>;
+
+  // ===== Cron Task Scheduling =====
+
+  /**
+   * Schedule a recurring cron task
+   * @param taskId - Unique identifier for the task
+   * @param taskType - Type of task (must have a registered handler)
+   * @param payload - Data to pass to the handler (must be JSON-serializable)
+   * @param options - Cron options (cronExpression required)
+   */
+  scheduleCron(
+    taskId: string,
+    taskType: string,
+    payload: Record<string, any>,
+    options: ScheduleCronOptions
+  ): Promise<boolean>;
+
+  // ===== Task Management =====
+
+  /**
+   * Cancel a scheduled task
+   */
+  cancel(taskId: string): Promise<boolean>;
+
+  /**
+   * Pause a cron task (only for CRON type)
+   */
+  pause(taskId: string): Promise<boolean>;
+
+  /**
+   * Resume a paused cron task (only for CRON type)
+   */
+  resume(taskId: string): Promise<boolean>;
+
+  /**
+   * Check if a task exists
+   */
+  has(taskId: string): Promise<boolean>;
+
+  /**
+   * Get task information
+   */
+  getTask(taskId: string): Promise<ScheduledTaskDefinition | null>;
+
+  /**
+   * Get remaining time until next execution
+   * Returns -1 if task not found or already executed
+   */
+  getRemainingTime(taskId: string): Promise<number>;
+
+  /**
+   * Get count of active tasks (pending + paused)
+   */
+  getActiveTaskCount(): Promise<number>;
+
+  /**
+   * Get all active task IDs
+   */
+  getActiveTaskIds(): Promise<string[]>;
+
+  /**
+   * Cancel all active tasks
+   */
+  cancelAll(): Promise<void>;
+
+  // ===== Recovery =====
+
+  /**
+   * Restore active tasks from storage (call on service startup)
+   * Re-schedules all pending tasks with their remaining time
+   * Re-schedules all cron tasks for their next run
+   * @returns Number of tasks restored
+   */
+  restore(): Promise<number>;
+
+  // ===== Storage =====
+
+  /**
+   * Set the storage backend
+   */
+  setStorage(storage: ScheduleStorage): void;
+
+  /**
+   * Get current storage backend
+   */
+  getStorage(): ScheduleStorage | null;
+}
+
+/**
+ * Schedule Lattice protocol interface
+ */
+export interface ScheduleLatticeProtocol
+  extends BaseLatticeProtocol<ScheduleConfig, ScheduleClient> {
+  // Handler registration
+  registerHandler: (taskType: string, handler: TaskHandler) => void;
+  unregisterHandler: (taskType: string) => boolean;
+  hasHandler: (taskType: string) => boolean;
+  getHandlerTypes: () => string[];
+
+  // One-time task scheduling
+  scheduleOnce: (
+    taskId: string,
+    taskType: string,
+    payload: Record<string, any>,
+    options: ScheduleOnceOptions
+  ) => Promise<boolean>;
+
+  // Cron task scheduling
+  scheduleCron: (
+    taskId: string,
+    taskType: string,
+    payload: Record<string, any>,
+    options: ScheduleCronOptions
+  ) => Promise<boolean>;
+
+  // Task management
+  cancel: (taskId: string) => Promise<boolean>;
+  pause: (taskId: string) => Promise<boolean>;
+  resume: (taskId: string) => Promise<boolean>;
+  has: (taskId: string) => Promise<boolean>;
+  getTask: (taskId: string) => Promise<ScheduledTaskDefinition | null>;
+  getRemainingTime: (taskId: string) => Promise<number>;
+  getActiveTaskCount: () => Promise<number>;
+  getActiveTaskIds: () => Promise<string[]>;
+  cancelAll: () => Promise<void>;
+
+  // Recovery
+  restore: () => Promise<number>;
+}

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./AgentLatticeProtocol";
 export * from "./MemoryLatticeProtocol";
 export * from "./UILatticeProtocol";
 export * from "./QueueLatticeProtocol";
+export * from "./ScheduleLatticeProtocol";
 export * from "./EmbeddingsLatticeProtocol";
 export * from "./VectorStoreLatticeProtocol";
 export * from "./MessageProtocol";