@axiom-lattice/protocols 2.1.7 → 2.1.8

package/src/AgentLatticeProtocol.ts

@@ -18,6 +18,17 @@ export enum AgentType {
   SEQUENTIAL = "sequential",
 }
 
+/**
+ * Runtime configuration that will be injected into LangGraphRunnableConfig.configurable
+ * Tools can access these values via config.configurable.runConfig
+ */
+export interface AgentRunConfig {
+  /** Database key for SQL tools (registered via sqlDatabaseManager) */
+  databaseKey?: string;
+  /** Any additional runtime configuration */
+  [key: string]: any;
+}
+
 /**
  * Base agent configuration shared by all agent types
  */
@@ -28,6 +39,11 @@ interface BaseAgentConfig {
   prompt: string; // Prompt
   schema?: ZodObject<any, any, any, any, any>; // Input validation schema
   modelKey?: string; // Model key to use
+  /**
+   * Runtime configuration to inject into tool execution context
+   * Will be available in tools via config.configurable.runConfig
+   */
+  runConfig?: AgentRunConfig;
 }
 
 /**

package/src/ScheduleLatticeProtocol.ts

@@ -1,7 +1,9 @@
 /**
  * ScheduleLatticeProtocol
  *
- * Schedule Lattice protocol for delayed task execution management
+ * 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";
@@ -11,87 +13,342 @@ import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
  */
 export enum ScheduleType {
   MEMORY = "memory",
-  // Future implementations can add more types like REDIS, DATABASE, etc.
+  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; // Schedule name
-  description: string; // Schedule description
-  type: ScheduleType; // Schedule service type
-  options?: Record<string, any>; // Additional options
+  name: string;
+  description: string;
+  type: ScheduleType;
+  storage?: ScheduleStorage; // Optional storage for persistence
+  options?: Record<string, any>;
 }
 
 /**
- * Scheduled task information interface
+ * Scheduled task definition - fully serializable
+ * Supports both one-time and cron-style recurring tasks
  */
-export interface ScheduledTaskInfo {
+export interface ScheduledTaskDefinition {
   taskId: string;
-  scheduledAt: number;
-  timeoutMs: number;
-  remainingMs: number;
+  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 function to be executed after the specified timeout
+   * 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 callback - Function to execute when timeout expires
-   * @param timeoutMs - Delay in milliseconds before execution
-   * @returns true if registered successfully
+   * @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)
    */
-  register: (
+  scheduleOnce(
     taskId: string,
-    callback: () => void | Promise<void>,
-    timeoutMs: number
-  ) => boolean;
+    taskType: string,
+    payload: Record<string, any>,
+    options: ScheduleOnceOptions
+  ): Promise<boolean>;
+
+  // ===== Cron Task Scheduling =====
 
   /**
-   * Cancel a scheduled task by its ID
-   * @param taskId - The task identifier to cancel
-   * @returns true if task was found and cancelled, false otherwise
+   * 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)
    */
-  cancel: (taskId: string) => boolean;
+  scheduleCron(
+    taskId: string,
+    taskType: string,
+    payload: Record<string, any>,
+    options: ScheduleCronOptions
+  ): Promise<boolean>;
+
+  // ===== Task Management =====
 
   /**
-   * Check if a task is currently scheduled
-   * @param taskId - The task identifier to check
+   * Cancel a scheduled task
    */
-  has: (taskId: string) => boolean;
+  cancel(taskId: string): Promise<boolean>;
 
   /**
-   * Get the remaining time in milliseconds for a scheduled task
-   * @param taskId - The task identifier
-   * @returns Remaining time in ms, or -1 if task not found
+   * Pause a cron task (only for CRON type)
    */
-  getRemainingTime: (taskId: string) => number;
+  pause(taskId: string): Promise<boolean>;
 
   /**
-   * Get the count of currently scheduled tasks
+   * Resume a paused cron task (only for CRON type)
    */
-  getTaskCount: () => number;
+  resume(taskId: string): Promise<boolean>;
 
   /**
-   * Get all scheduled task IDs
+   * Check if a task exists
    */
-  getTaskIds: () => string[];
+  has(taskId: string): Promise<boolean>;
 
   /**
-   * Cancel all scheduled tasks
+   * Get task information
    */
-  cancelAll: () => void;
+  getTask(taskId: string): Promise<ScheduledTaskDefinition | null>;
 
   /**
-   * Get task information
-   * @param taskId - The task identifier
-   * @returns Task info or null if not found
+   * 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
    */
-  getTaskInfo?: (taskId: string) => ScheduledTaskInfo | null;
+  getStorage(): ScheduleStorage | null;
 }
 
 /**
@@ -99,17 +356,39 @@ export interface ScheduleClient {
  */
 export interface ScheduleLatticeProtocol
   extends BaseLatticeProtocol<ScheduleConfig, ScheduleClient> {
-  // Schedule operations
-  register: (
+  // 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,
-    callback: () => void | Promise<void>,
-    timeoutMs: number
-  ) => boolean;
-  cancel: (taskId: string) => boolean;
-  has: (taskId: string) => boolean;
-  getRemainingTime: (taskId: string) => number;
-  getTaskCount: () => number;
-  getTaskIds: () => string[];
-  cancelAll: () => void;
-  getTaskInfo?: (taskId: string) => ScheduledTaskInfo | null;
+    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>;
 }