@axiom-lattice/protocols 2.1.7 → 2.1.9

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/AgentLatticeProtocol.ts","../src/MemoryLatticeProtocol.ts","../src/UILatticeProtocol.ts","../src/QueueLatticeProtocol.ts","../src/ScheduleLatticeProtocol.ts"],"sourcesContent":["/**\n * AgentLatticeProtocol\n *\n * 智能体Lattice的协议，定义了智能体的行为和组合方式\n */\n\nimport { CompiledStateGraph } from \"@langchain/langgraph\";\nimport z, { ZodObject, ZodSchema } from \"zod\";\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * 智能体类型枚举\n */\nexport enum AgentType {\n  REACT = \"react\",\n  DEEP_AGENT = \"deep_agent\",\n  PLAN_EXECUTE = \"plan_execute\",\n  SEQUENTIAL = \"sequential\",\n}\n\n/**\n * Base agent configuration shared by all agent types\n */\ninterface BaseAgentConfig {\n  key: string; // Unique key\n  name: string; // Name\n  description: string; // Description\n  prompt: string; // Prompt\n  schema?: ZodObject<any, any, any, any, any>; // Input validation schema\n  modelKey?: string; // Model key to use\n}\n\n/**\n * REACT agent configuration\n */\nexport interface ReactAgentConfig extends BaseAgentConfig {\n  type: AgentType.REACT;\n  tools?: string[]; // Tool list\n}\n\n/**\n * DEEP_AGENT configuration - only this type supports subAgents\n */\nexport interface DeepAgentConfig extends BaseAgentConfig {\n  type: AgentType.DEEP_AGENT;\n  tools?: string[]; // Tool list\n  subAgents?: string[]; // Sub-agent list (unique to DEEP_AGENT)\n  internalSubAgents?: AgentConfig[]; // Internal sub-agent list (unique to DEEP_AGENT)\n}\n\n/**\n * PLAN_EXECUTE agent configuration\n */\nexport interface PlanExecuteAgentConfig extends BaseAgentConfig {\n  type: AgentType.PLAN_EXECUTE;\n  tools?: string[]; // Tool list\n}\n\n/**\n * SEQUENTIAL agent configuration\n */\nexport interface SequentialAgentConfig extends BaseAgentConfig {\n  type: AgentType.SEQUENTIAL;\n}\n\n/**\n * Agent configuration union type\n * Different agent types have different configuration options\n */\nexport type AgentConfig =\n  | ReactAgentConfig\n  | DeepAgentConfig\n  | PlanExecuteAgentConfig\n  | SequentialAgentConfig;\n\n/**\n * Agent configuration with tools property\n */\nexport type AgentConfigWithTools =\n  | ReactAgentConfig\n  | DeepAgentConfig\n  | PlanExecuteAgentConfig;\n\n/**\n * Type guard to check if config has tools property\n */\nexport function hasTools(config: AgentConfig): config is AgentConfigWithTools {\n  return config.type !== AgentType.SEQUENTIAL;\n}\n\n/**\n * Type guard to check if config is DeepAgentConfig (has subAgents)\n */\nexport function isDeepAgentConfig(\n  config: AgentConfig\n): config is DeepAgentConfig {\n  return config.type === AgentType.DEEP_AGENT;\n}\n\n/**\n * Get tools from config safely\n */\nexport function getToolsFromConfig(config: AgentConfig): string[] {\n  if (hasTools(config)) {\n    return config.tools || [];\n  }\n  return [];\n}\n\n/**\n * Get subAgents from config safely (only DeepAgentConfig has subAgents)\n */\nexport function getSubAgentsFromConfig(config: AgentConfig): string[] {\n  if (isDeepAgentConfig(config)) {\n    return config.subAgents || [];\n  }\n  return [];\n}\n\n/**\n * 智能体客户端类型\n */\nexport type AgentClient = CompiledStateGraph<any, any, any, any, any>;\n\n/**\n * Graph构建选项\n */\nexport interface GraphBuildOptions {\n  overrideTools?: string[];\n  overrideModel?: string;\n  metadata?: Record<string, any>;\n}\n\n/**\n * 智能体Lattice协议接口\n */\nexport interface AgentLatticeProtocol\n  extends BaseLatticeProtocol<AgentConfig, AgentClient> {\n  // 智能体执行函数\n  invoke: (input: any, options?: any) => Promise<any>;\n\n  // 构建智能体图\n  buildGraph: (options?: GraphBuildOptions) => Promise<AgentClient>;\n}\n","/**\n * MemoryLatticeProtocol\n *\n * 记忆Lattice的协议，用于管理智能体的上下文和记忆\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * 记忆类型枚举\n */\nexport enum MemoryType {\n  SHORT_TERM = \"short_term\",\n  LONG_TERM = \"long_term\",\n  EPISODIC = \"episodic\",\n  SEMANTIC = \"semantic\",\n  WORKING = \"working\",\n}\n\n/**\n * 记忆配置接口\n */\nexport interface MemoryConfig {\n  name: string; // 名称\n  description: string; // 描述\n  type: MemoryType; // 记忆类型\n  ttl?: number; // 生存时间\n  capacity?: number; // 容量限制\n}\n\n/**\n * 记忆客户端接口\n */\nexport interface MemoryClient {\n  add: (key: string, value: any) => Promise<void>;\n  get: (key: string) => Promise<any>;\n  update: (key: string, value: any) => Promise<void>;\n  delete: (key: string) => Promise<void>;\n  search: (query: string, options?: any) => Promise<any[]>;\n  clear: () => Promise<void>;\n}\n\n/**\n * 记忆Lattice协议接口\n */\nexport interface MemoryLatticeProtocol\n  extends BaseLatticeProtocol<MemoryConfig, MemoryClient> {\n  // 记忆操作方法\n  add: (key: string, value: any) => Promise<void>;\n  get: (key: string) => Promise<any>;\n  update: (key: string, value: any) => Promise<void>;\n  delete: (key: string) => Promise<void>;\n  search: (query: string, options?: any) => Promise<any[]>;\n  clear: () => Promise<void>;\n}\n","/**\n * UILatticeProtocol\n *\n * UI Lattice的协议，用于定义用户界面组件\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * UI组件类型枚举\n */\nexport enum UIComponentType {\n  CONTAINER = \"container\",\n  INPUT = \"input\",\n  BUTTON = \"button\",\n  LIST = \"list\",\n  TABLE = \"table\",\n  CHART = \"chart\",\n  FORM = \"form\",\n  CARD = \"card\",\n  MODAL = \"modal\",\n  CUSTOM = \"custom\",\n}\n\n/**\n * UI配置接口\n */\nexport interface UIConfig {\n  name: string; // 组件名称\n  description: string; // 组件描述\n  type: UIComponentType; // 组件类型\n  props?: Record<string, any>; // 组件属性\n  children?: string[]; // 子组件列表\n}\n\n/**\n * UI组件接口\n * 使用泛型以适应不同的UI框架(React, Vue等)\n */\nexport interface UIComponent<T = any> {\n  render: (props?: any) => T;\n  addEventListener: (event: string, handler: Function) => void;\n  removeEventListener: (event: string, handler: Function) => void;\n}\n\n/**\n * UI Lattice协议接口\n */\nexport interface UILatticeProtocol<T = any>\n  extends BaseLatticeProtocol<UIConfig, UIComponent<T>> {\n  // UI渲染方法\n  render: (props?: any) => T;\n\n  // 事件处理\n  addEventListener: (event: string, handler: Function) => void;\n  removeEventListener: (event: string, handler: Function) => void;\n}\n","/**\n * QueueLatticeProtocol\n *\n * Queue Lattice protocol for task queue management\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * Queue service type enumeration\n */\nexport enum QueueType {\n  MEMORY = \"memory\",\n  REDIS = \"redis\",\n}\n\n/**\n * Queue configuration interface\n */\nexport interface QueueConfig {\n  name: string; // Queue name\n  description: string; // Queue description\n  type: QueueType; // Queue service type\n  queueName?: string; // Specific queue name (e.g., \"tasks\")\n  options?: Record<string, any>; // Additional options (e.g., Redis connection options)\n}\n\n/**\n * Queue operation result interface\n */\nexport interface QueueResult<T = any> {\n  data: T | null;\n  error: any | null;\n}\n\n/**\n * Queue client interface\n */\nexport interface QueueClient {\n  push: (item: any) => Promise<QueueResult<number>>;\n  pop: () => Promise<QueueResult<any>>;\n  createQueue?: () => Promise<{ success: boolean; queue_name?: string; error?: any }>;\n}\n\n/**\n * Queue Lattice protocol interface\n */\nexport interface QueueLatticeProtocol\n  extends BaseLatticeProtocol<QueueConfig, QueueClient> {\n  // Queue operations\n  push: (item: any) => Promise<QueueResult<number>>;\n  pop: () => Promise<QueueResult<any>>;\n  createQueue?: () => Promise<{ success: boolean; queue_name?: string; error?: any }>;\n}\n\n\n\n","/**\n * ScheduleLatticeProtocol\n *\n * Schedule Lattice protocol for delayed task execution management\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * Schedule service type enumeration\n */\nexport enum ScheduleType {\n  MEMORY = \"memory\",\n  // Future implementations can add more types like REDIS, DATABASE, etc.\n}\n\n/**\n * Schedule configuration interface\n */\nexport interface ScheduleConfig {\n  name: string; // Schedule name\n  description: string; // Schedule description\n  type: ScheduleType; // Schedule service type\n  options?: Record<string, any>; // Additional options\n}\n\n/**\n * Scheduled task information interface\n */\nexport interface ScheduledTaskInfo {\n  taskId: string;\n  scheduledAt: number;\n  timeoutMs: number;\n  remainingMs: number;\n}\n\n/**\n * Schedule client interface\n */\nexport interface ScheduleClient {\n  /**\n   * Register a function to be executed after the specified timeout\n   * @param taskId - Unique identifier for the task\n   * @param callback - Function to execute when timeout expires\n   * @param timeoutMs - Delay in milliseconds before execution\n   * @returns true if registered successfully\n   */\n  register: (\n    taskId: string,\n    callback: () => void | Promise<void>,\n    timeoutMs: number\n  ) => boolean;\n\n  /**\n   * Cancel a scheduled task by its ID\n   * @param taskId - The task identifier to cancel\n   * @returns true if task was found and cancelled, false otherwise\n   */\n  cancel: (taskId: string) => boolean;\n\n  /**\n   * Check if a task is currently scheduled\n   * @param taskId - The task identifier to check\n   */\n  has: (taskId: string) => boolean;\n\n  /**\n   * Get the remaining time in milliseconds for a scheduled task\n   * @param taskId - The task identifier\n   * @returns Remaining time in ms, or -1 if task not found\n   */\n  getRemainingTime: (taskId: string) => number;\n\n  /**\n   * Get the count of currently scheduled tasks\n   */\n  getTaskCount: () => number;\n\n  /**\n   * Get all scheduled task IDs\n   */\n  getTaskIds: () => string[];\n\n  /**\n   * Cancel all scheduled tasks\n   */\n  cancelAll: () => void;\n\n  /**\n   * Get task information\n   * @param taskId - The task identifier\n   * @returns Task info or null if not found\n   */\n  getTaskInfo?: (taskId: string) => ScheduledTaskInfo | null;\n}\n\n/**\n * Schedule Lattice protocol interface\n */\nexport interface ScheduleLatticeProtocol\n  extends BaseLatticeProtocol<ScheduleConfig, ScheduleClient> {\n  // Schedule operations\n  register: (\n    taskId: string,\n    callback: () => void | Promise<void>,\n    timeoutMs: number\n  ) => boolean;\n  cancel: (taskId: string) => boolean;\n  has: (taskId: string) => boolean;\n  getRemainingTime: (taskId: string) => number;\n  getTaskCount: () => number;\n  getTaskIds: () => string[];\n  cancelAll: () => void;\n  getTaskInfo?: (taskId: string) => ScheduledTaskInfo | null;\n}\n"],"mappings":";AAaO,IAAK,YAAL,kBAAKA,eAAL;AACL,EAAAA,WAAA,WAAQ;AACR,EAAAA,WAAA,gBAAa;AACb,EAAAA,WAAA,kBAAe;AACf,EAAAA,WAAA,gBAAa;AAJH,SAAAA;AAAA,GAAA;AAyEL,SAAS,SAAS,QAAqD;AAC5E,SAAO,OAAO,SAAS;AACzB;AAKO,SAAS,kBACd,QAC2B;AAC3B,SAAO,OAAO,SAAS;AACzB;AAKO,SAAS,mBAAmB,QAA+B;AAChE,MAAI,SAAS,MAAM,GAAG;AACpB,WAAO,OAAO,SAAS,CAAC;AAAA,EAC1B;AACA,SAAO,CAAC;AACV;AAKO,SAAS,uBAAuB,QAA+B;AACpE,MAAI,kBAAkB,MAAM,GAAG;AAC7B,WAAO,OAAO,aAAa,CAAC;AAAA,EAC9B;AACA,SAAO,CAAC;AACV;;;AC1GO,IAAK,aAAL,kBAAKC,gBAAL;AACL,EAAAA,YAAA,gBAAa;AACb,EAAAA,YAAA,eAAY;AACZ,EAAAA,YAAA,cAAW;AACX,EAAAA,YAAA,cAAW;AACX,EAAAA,YAAA,aAAU;AALA,SAAAA;AAAA,GAAA;;;ACAL,IAAK,kBAAL,kBAAKC,qBAAL;AACL,EAAAA,iBAAA,eAAY;AACZ,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,YAAS;AACT,EAAAA,iBAAA,UAAO;AACP,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,UAAO;AACP,EAAAA,iBAAA,UAAO;AACP,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,YAAS;AAVC,SAAAA;AAAA,GAAA;;;ACAL,IAAK,YAAL,kBAAKC,eAAL;AACL,EAAAA,WAAA,YAAS;AACT,EAAAA,WAAA,WAAQ;AAFE,SAAAA;AAAA,GAAA;;;ACAL,IAAK,eAAL,kBAAKC,kBAAL;AACL,EAAAA,cAAA,YAAS;AADC,SAAAA;AAAA,GAAA;","names":["AgentType","MemoryType","UIComponentType","QueueType","ScheduleType"]}
+{"version":3,"sources":["../src/AgentLatticeProtocol.ts","../src/MemoryLatticeProtocol.ts","../src/UILatticeProtocol.ts","../src/QueueLatticeProtocol.ts","../src/ScheduleLatticeProtocol.ts","../src/LoggerLatticeProtocol.ts"],"sourcesContent":["/**\n * AgentLatticeProtocol\n *\n * 智能体Lattice的协议，定义了智能体的行为和组合方式\n */\n\nimport { CompiledStateGraph } from \"@langchain/langgraph\";\nimport z, { ZodObject, ZodSchema } from \"zod\";\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * 智能体类型枚举\n */\nexport enum AgentType {\n  REACT = \"react\",\n  DEEP_AGENT = \"deep_agent\",\n  PLAN_EXECUTE = \"plan_execute\",\n  SEQUENTIAL = \"sequential\",\n}\n\n/**\n * Runtime configuration that will be injected into LangGraphRunnableConfig.configurable\n * Tools can access these values via config.configurable.runConfig\n */\nexport interface AgentRunConfig {\n  /** Database key for SQL tools (registered via sqlDatabaseManager) */\n  databaseKey?: string;\n  /** Any additional runtime configuration */\n  [key: string]: any;\n}\n\n/**\n * Base agent configuration shared by all agent types\n */\ninterface BaseAgentConfig {\n  key: string; // Unique key\n  name: string; // Name\n  description: string; // Description\n  prompt: string; // Prompt\n  schema?: ZodObject<any, any, any, any, any>; // Input validation schema\n  modelKey?: string; // Model key to use\n  /**\n   * Runtime configuration to inject into tool execution context\n   * Will be available in tools via config.configurable.runConfig\n   */\n  runConfig?: AgentRunConfig;\n}\n\n/**\n * REACT agent configuration\n */\nexport interface ReactAgentConfig extends BaseAgentConfig {\n  type: AgentType.REACT;\n  tools?: string[]; // Tool list\n}\n\n/**\n * DEEP_AGENT configuration - only this type supports subAgents\n */\nexport interface DeepAgentConfig extends BaseAgentConfig {\n  type: AgentType.DEEP_AGENT;\n  tools?: string[]; // Tool list\n  subAgents?: string[]; // Sub-agent list (unique to DEEP_AGENT)\n  internalSubAgents?: AgentConfig[]; // Internal sub-agent list (unique to DEEP_AGENT)\n}\n\n/**\n * PLAN_EXECUTE agent configuration\n */\nexport interface PlanExecuteAgentConfig extends BaseAgentConfig {\n  type: AgentType.PLAN_EXECUTE;\n  tools?: string[]; // Tool list\n}\n\n/**\n * SEQUENTIAL agent configuration\n */\nexport interface SequentialAgentConfig extends BaseAgentConfig {\n  type: AgentType.SEQUENTIAL;\n}\n\n/**\n * Agent configuration union type\n * Different agent types have different configuration options\n */\nexport type AgentConfig =\n  | ReactAgentConfig\n  | DeepAgentConfig\n  | PlanExecuteAgentConfig\n  | SequentialAgentConfig;\n\n/**\n * Agent configuration with tools property\n */\nexport type AgentConfigWithTools =\n  | ReactAgentConfig\n  | DeepAgentConfig\n  | PlanExecuteAgentConfig;\n\n/**\n * Type guard to check if config has tools property\n */\nexport function hasTools(config: AgentConfig): config is AgentConfigWithTools {\n  return config.type !== AgentType.SEQUENTIAL;\n}\n\n/**\n * Type guard to check if config is DeepAgentConfig (has subAgents)\n */\nexport function isDeepAgentConfig(\n  config: AgentConfig\n): config is DeepAgentConfig {\n  return config.type === AgentType.DEEP_AGENT;\n}\n\n/**\n * Get tools from config safely\n */\nexport function getToolsFromConfig(config: AgentConfig): string[] {\n  if (hasTools(config)) {\n    return config.tools || [];\n  }\n  return [];\n}\n\n/**\n * Get subAgents from config safely (only DeepAgentConfig has subAgents)\n */\nexport function getSubAgentsFromConfig(config: AgentConfig): string[] {\n  if (isDeepAgentConfig(config)) {\n    return config.subAgents || [];\n  }\n  return [];\n}\n\n/**\n * 智能体客户端类型\n */\nexport type AgentClient = CompiledStateGraph<any, any, any, any, any>;\n\n/**\n * Graph构建选项\n */\nexport interface GraphBuildOptions {\n  overrideTools?: string[];\n  overrideModel?: string;\n  metadata?: Record<string, any>;\n}\n\n/**\n * 智能体Lattice协议接口\n */\nexport interface AgentLatticeProtocol\n  extends BaseLatticeProtocol<AgentConfig, AgentClient> {\n  // 智能体执行函数\n  invoke: (input: any, options?: any) => Promise<any>;\n\n  // 构建智能体图\n  buildGraph: (options?: GraphBuildOptions) => Promise<AgentClient>;\n}\n","/**\n * MemoryLatticeProtocol\n *\n * 记忆Lattice的协议，用于管理智能体的上下文和记忆\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * 记忆类型枚举\n */\nexport enum MemoryType {\n  SHORT_TERM = \"short_term\",\n  LONG_TERM = \"long_term\",\n  EPISODIC = \"episodic\",\n  SEMANTIC = \"semantic\",\n  WORKING = \"working\",\n}\n\n/**\n * 记忆配置接口\n */\nexport interface MemoryConfig {\n  name: string; // 名称\n  description: string; // 描述\n  type: MemoryType; // 记忆类型\n  ttl?: number; // 生存时间\n  capacity?: number; // 容量限制\n}\n\n/**\n * 记忆客户端接口\n */\nexport interface MemoryClient {\n  add: (key: string, value: any) => Promise<void>;\n  get: (key: string) => Promise<any>;\n  update: (key: string, value: any) => Promise<void>;\n  delete: (key: string) => Promise<void>;\n  search: (query: string, options?: any) => Promise<any[]>;\n  clear: () => Promise<void>;\n}\n\n/**\n * 记忆Lattice协议接口\n */\nexport interface MemoryLatticeProtocol\n  extends BaseLatticeProtocol<MemoryConfig, MemoryClient> {\n  // 记忆操作方法\n  add: (key: string, value: any) => Promise<void>;\n  get: (key: string) => Promise<any>;\n  update: (key: string, value: any) => Promise<void>;\n  delete: (key: string) => Promise<void>;\n  search: (query: string, options?: any) => Promise<any[]>;\n  clear: () => Promise<void>;\n}\n","/**\n * UILatticeProtocol\n *\n * UI Lattice的协议，用于定义用户界面组件\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * UI组件类型枚举\n */\nexport enum UIComponentType {\n  CONTAINER = \"container\",\n  INPUT = \"input\",\n  BUTTON = \"button\",\n  LIST = \"list\",\n  TABLE = \"table\",\n  CHART = \"chart\",\n  FORM = \"form\",\n  CARD = \"card\",\n  MODAL = \"modal\",\n  CUSTOM = \"custom\",\n}\n\n/**\n * UI配置接口\n */\nexport interface UIConfig {\n  name: string; // 组件名称\n  description: string; // 组件描述\n  type: UIComponentType; // 组件类型\n  props?: Record<string, any>; // 组件属性\n  children?: string[]; // 子组件列表\n}\n\n/**\n * UI组件接口\n * 使用泛型以适应不同的UI框架(React, Vue等)\n */\nexport interface UIComponent<T = any> {\n  render: (props?: any) => T;\n  addEventListener: (event: string, handler: Function) => void;\n  removeEventListener: (event: string, handler: Function) => void;\n}\n\n/**\n * UI Lattice协议接口\n */\nexport interface UILatticeProtocol<T = any>\n  extends BaseLatticeProtocol<UIConfig, UIComponent<T>> {\n  // UI渲染方法\n  render: (props?: any) => T;\n\n  // 事件处理\n  addEventListener: (event: string, handler: Function) => void;\n  removeEventListener: (event: string, handler: Function) => void;\n}\n","/**\n * QueueLatticeProtocol\n *\n * Queue Lattice protocol for task queue management\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * Queue service type enumeration\n */\nexport enum QueueType {\n  MEMORY = \"memory\",\n  REDIS = \"redis\",\n}\n\n/**\n * Queue configuration interface\n */\nexport interface QueueConfig {\n  name: string; // Queue name\n  description: string; // Queue description\n  type: QueueType; // Queue service type\n  queueName?: string; // Specific queue name (e.g., \"tasks\")\n  options?: Record<string, any>; // Additional options (e.g., Redis connection options)\n}\n\n/**\n * Queue operation result interface\n */\nexport interface QueueResult<T = any> {\n  data: T | null;\n  error: any | null;\n}\n\n/**\n * Queue client interface\n */\nexport interface QueueClient {\n  push: (item: any) => Promise<QueueResult<number>>;\n  pop: () => Promise<QueueResult<any>>;\n  createQueue?: () => Promise<{ success: boolean; queue_name?: string; error?: any }>;\n}\n\n/**\n * Queue Lattice protocol interface\n */\nexport interface QueueLatticeProtocol\n  extends BaseLatticeProtocol<QueueConfig, QueueClient> {\n  // Queue operations\n  push: (item: any) => Promise<QueueResult<number>>;\n  pop: () => Promise<QueueResult<any>>;\n  createQueue?: () => Promise<{ success: boolean; queue_name?: string; error?: any }>;\n}\n\n\n\n","/**\n * ScheduleLatticeProtocol\n *\n * Schedule Lattice protocol for delayed and recurring task execution management\n * Supports persistence and recovery after service restart\n * Supports both one-time delayed tasks and cron-style recurring tasks\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * Schedule service type enumeration\n */\nexport enum ScheduleType {\n  MEMORY = \"memory\",\n  POSTGRES = \"postgres\",\n  REDIS = \"redis\",\n}\n\n/**\n * Schedule execution type - one-time or recurring\n */\nexport enum ScheduleExecutionType {\n  ONCE = \"once\", // Execute once at specified time\n  CRON = \"cron\", // Recurring based on cron expression\n}\n\n/**\n * Task status enumeration\n */\nexport enum ScheduledTaskStatus {\n  PENDING = \"pending\", // Waiting to be executed\n  RUNNING = \"running\", // Currently executing\n  COMPLETED = \"completed\", // Successfully completed (for ONCE type)\n  FAILED = \"failed\", // Execution failed\n  CANCELLED = \"cancelled\", // Manually cancelled\n  PAUSED = \"paused\", // Paused (for CRON type)\n}\n\n/**\n * Schedule configuration interface\n */\nexport interface ScheduleConfig {\n  name: string;\n  description: string;\n  type: ScheduleType;\n  storage?: ScheduleStorage; // Optional storage for persistence\n  options?: Record<string, any>;\n}\n\n/**\n * Scheduled task definition - fully serializable\n * Supports both one-time and cron-style recurring tasks\n */\nexport interface ScheduledTaskDefinition {\n  taskId: string;\n  taskType: string; // Maps to a registered handler\n  payload: Record<string, any>; // JSON-serializable data passed to handler\n\n  // Context fields for querying\n  assistantId?: string; // Which assistant created/owns this task\n  threadId?: string; // Which thread this task belongs to\n\n  // Execution configuration\n  executionType: ScheduleExecutionType;\n\n  // For ONCE type - execute at specific time or after delay\n  executeAt?: number; // Timestamp when to execute\n  delayMs?: number; // Original delay in milliseconds (for reference)\n\n  // For CRON type - recurring schedule\n  cronExpression?: string; // Cron format: \"0 9 * * *\" (min hour day month weekday)\n  timezone?: string; // Timezone: \"Asia/Shanghai\", defaults to system timezone\n  nextRunAt?: number; // Next calculated execution time\n  lastRunAt?: number; // Last execution time\n\n  // Execution tracking\n  status: ScheduledTaskStatus;\n  runCount: number; // How many times executed\n  maxRuns?: number; // Max executions (null/undefined = infinite for cron, 1 for once)\n\n  // Error handling\n  retryCount: number; // Current retry count\n  maxRetries: number; // Maximum retry attempts\n  lastError?: string; // Last error message if failed\n\n  // Timestamps\n  createdAt: number;\n  updatedAt: number;\n  expiresAt?: number; // When to stop (for cron, optional)\n\n  metadata?: Record<string, any>; // Additional metadata\n}\n\n/**\n * Task handler function type\n */\nexport type TaskHandler = (\n  payload: Record<string, any>,\n  taskInfo: ScheduledTaskDefinition\n) => void | Promise<void>;\n\n/**\n * Options for scheduling a one-time task\n */\nexport interface ScheduleOnceOptions {\n  executeAt?: number; // Absolute timestamp to execute\n  delayMs?: number; // OR relative delay from now\n  maxRetries?: number; // Max retry attempts (default: 0)\n  assistantId?: string; // Which assistant created/owns this task\n  threadId?: string; // Which thread this task belongs to\n  metadata?: Record<string, any>;\n}\n\n/**\n * Options for scheduling a cron task\n */\nexport interface ScheduleCronOptions {\n  cronExpression: string; // Cron expression: \"0 9 * * *\"\n  timezone?: string; // Timezone: \"Asia/Shanghai\"\n  maxRuns?: number; // Max executions (undefined = infinite)\n  expiresAt?: number; // Stop after this timestamp\n  maxRetries?: number; // Max retry attempts per run (default: 0)\n  assistantId?: string; // Which assistant created/owns this task\n  threadId?: string; // Which thread this task belongs to\n  metadata?: Record<string, any>;\n}\n\n/**\n * Schedule storage interface for persistence\n */\nexport interface ScheduleStorage {\n  /**\n   * Save a new task\n   */\n  save(task: ScheduledTaskDefinition): Promise<void>;\n\n  /**\n   * Get task by ID\n   */\n  get(taskId: string): Promise<ScheduledTaskDefinition | null>;\n\n  /**\n   * Update task\n   */\n  update(\n    taskId: string,\n    updates: Partial<ScheduledTaskDefinition>\n  ): Promise<void>;\n\n  /**\n   * Delete task\n   */\n  delete(taskId: string): Promise<void>;\n\n  /**\n   * Get all pending/active tasks (for recovery)\n   * Returns tasks with status: PENDING or PAUSED\n   */\n  getActiveTasks(): Promise<ScheduledTaskDefinition[]>;\n\n  /**\n   * Get tasks by type\n   */\n  getTasksByType(taskType: string): Promise<ScheduledTaskDefinition[]>;\n\n  /**\n   * Get tasks by status\n   */\n  getTasksByStatus(\n    status: ScheduledTaskStatus\n  ): Promise<ScheduledTaskDefinition[]>;\n\n  /**\n   * Get tasks by execution type\n   */\n  getTasksByExecutionType(\n    executionType: ScheduleExecutionType\n  ): Promise<ScheduledTaskDefinition[]>;\n\n  /**\n   * Get tasks by assistant ID\n   */\n  getTasksByAssistantId(\n    assistantId: string\n  ): Promise<ScheduledTaskDefinition[]>;\n\n  /**\n   * Get tasks by thread ID\n   */\n  getTasksByThreadId(threadId: string): Promise<ScheduledTaskDefinition[]>;\n\n  /**\n   * Get all tasks (with optional filters)\n   */\n  getAllTasks(filters?: {\n    status?: ScheduledTaskStatus;\n    executionType?: ScheduleExecutionType;\n    taskType?: string;\n    assistantId?: string;\n    threadId?: string;\n    limit?: number;\n    offset?: number;\n  }): Promise<ScheduledTaskDefinition[]>;\n\n  /**\n   * Count tasks (with optional filters)\n   */\n  countTasks(filters?: {\n    status?: ScheduledTaskStatus;\n    executionType?: ScheduleExecutionType;\n    taskType?: string;\n    assistantId?: string;\n    threadId?: string;\n  }): Promise<number>;\n\n  /**\n   * Delete completed/cancelled tasks older than specified time\n   * Useful for cleanup\n   */\n  deleteOldTasks(olderThanMs: number): Promise<number>;\n}\n\n/**\n * Schedule client interface\n */\nexport interface ScheduleClient {\n  // ===== Handler Registration =====\n\n  /**\n   * Register a handler for a task type\n   * Must be called before scheduling tasks of this type\n   */\n  registerHandler(taskType: string, handler: TaskHandler): void;\n\n  /**\n   * Unregister a handler\n   */\n  unregisterHandler(taskType: string): boolean;\n\n  /**\n   * Check if a handler is registered\n   */\n  hasHandler(taskType: string): boolean;\n\n  /**\n   * Get all registered handler types\n   */\n  getHandlerTypes(): string[];\n\n  // ===== One-time Task Scheduling =====\n\n  /**\n   * Schedule a one-time task\n   * @param taskId - Unique identifier for the task\n   * @param taskType - Type of task (must have a registered handler)\n   * @param payload - Data to pass to the handler (must be JSON-serializable)\n   * @param options - Execution options (executeAt or delayMs required)\n   */\n  scheduleOnce(\n    taskId: string,\n    taskType: string,\n    payload: Record<string, any>,\n    options: ScheduleOnceOptions\n  ): Promise<boolean>;\n\n  // ===== Cron Task Scheduling =====\n\n  /**\n   * Schedule a recurring cron task\n   * @param taskId - Unique identifier for the task\n   * @param taskType - Type of task (must have a registered handler)\n   * @param payload - Data to pass to the handler (must be JSON-serializable)\n   * @param options - Cron options (cronExpression required)\n   */\n  scheduleCron(\n    taskId: string,\n    taskType: string,\n    payload: Record<string, any>,\n    options: ScheduleCronOptions\n  ): Promise<boolean>;\n\n  // ===== Task Management =====\n\n  /**\n   * Cancel a scheduled task\n   */\n  cancel(taskId: string): Promise<boolean>;\n\n  /**\n   * Pause a cron task (only for CRON type)\n   */\n  pause(taskId: string): Promise<boolean>;\n\n  /**\n   * Resume a paused cron task (only for CRON type)\n   */\n  resume(taskId: string): Promise<boolean>;\n\n  /**\n   * Check if a task exists\n   */\n  has(taskId: string): Promise<boolean>;\n\n  /**\n   * Get task information\n   */\n  getTask(taskId: string): Promise<ScheduledTaskDefinition | null>;\n\n  /**\n   * Get remaining time until next execution\n   * Returns -1 if task not found or already executed\n   */\n  getRemainingTime(taskId: string): Promise<number>;\n\n  /**\n   * Get count of active tasks (pending + paused)\n   */\n  getActiveTaskCount(): Promise<number>;\n\n  /**\n   * Get all active task IDs\n   */\n  getActiveTaskIds(): Promise<string[]>;\n\n  /**\n   * Cancel all active tasks\n   */\n  cancelAll(): Promise<void>;\n\n  // ===== Recovery =====\n\n  /**\n   * Restore active tasks from storage (call on service startup)\n   * Re-schedules all pending tasks with their remaining time\n   * Re-schedules all cron tasks for their next run\n   * @returns Number of tasks restored\n   */\n  restore(): Promise<number>;\n\n  // ===== Storage =====\n\n  /**\n   * Set the storage backend\n   */\n  setStorage(storage: ScheduleStorage): void;\n\n  /**\n   * Get current storage backend\n   */\n  getStorage(): ScheduleStorage | null;\n}\n\n/**\n * Schedule Lattice protocol interface\n */\nexport interface ScheduleLatticeProtocol\n  extends BaseLatticeProtocol<ScheduleConfig, ScheduleClient> {\n  // Handler registration\n  registerHandler: (taskType: string, handler: TaskHandler) => void;\n  unregisterHandler: (taskType: string) => boolean;\n  hasHandler: (taskType: string) => boolean;\n  getHandlerTypes: () => string[];\n\n  // One-time task scheduling\n  scheduleOnce: (\n    taskId: string,\n    taskType: string,\n    payload: Record<string, any>,\n    options: ScheduleOnceOptions\n  ) => Promise<boolean>;\n\n  // Cron task scheduling\n  scheduleCron: (\n    taskId: string,\n    taskType: string,\n    payload: Record<string, any>,\n    options: ScheduleCronOptions\n  ) => Promise<boolean>;\n\n  // Task management\n  cancel: (taskId: string) => Promise<boolean>;\n  pause: (taskId: string) => Promise<boolean>;\n  resume: (taskId: string) => Promise<boolean>;\n  has: (taskId: string) => Promise<boolean>;\n  getTask: (taskId: string) => Promise<ScheduledTaskDefinition | null>;\n  getRemainingTime: (taskId: string) => Promise<number>;\n  getActiveTaskCount: () => Promise<number>;\n  getActiveTaskIds: () => Promise<string[]>;\n  cancelAll: () => Promise<void>;\n\n  // Recovery\n  restore: () => Promise<number>;\n}\n","/**\n * LoggerLatticeProtocol\n *\n * Logger Lattice protocol for logging management\n */\n\nimport { BaseLatticeProtocol } from \"./BaseLatticeProtocol\";\n\n/**\n * Logger service type enumeration\n */\nexport enum LoggerType {\n  PINO = \"pino\",\n  CONSOLE = \"console\",\n  CUSTOM = \"custom\",\n}\n\n/**\n * Logger context interface\n */\nexport interface LoggerContext {\n  \"x-user-id\"?: string;\n  \"x-tenant-id\"?: string;\n  \"x-request-id\"?: string;\n  \"x-task-id\"?: string;\n  \"x-thread-id\"?: string;\n  [key: string]: any;\n}\n\n/**\n * Pino logger file transport options\n */\nexport interface PinoFileOptions {\n  file?: string; // Log file path (e.g., \"./logs/app.log\" or \"./logs/app\")\n  frequency?: \"daily\" | \"hourly\" | \"minutely\" | string; // Log rotation frequency\n  mkdir?: boolean; // Create directory if not exists\n  size?: string; // Max file size (e.g., \"10M\", \"100K\")\n  maxFiles?: number; // Maximum number of log files to keep\n}\n\n/**\n * Logger configuration interface\n */\nexport interface LoggerConfig {\n  name: string; // Logger name\n  description?: string; // Logger description\n  type: LoggerType; // Logger service type\n  serviceName?: string; // Service name (e.g., \"lattice-gateway\")\n  loggerName?: string; // Logger instance name (e.g., \"fastify-server\")\n  context?: LoggerContext; // Initial context\n  // File logging options (for PINO type)\n  file?: string | PinoFileOptions; // Log file path or detailed file options\n  // Additional options (e.g., pino config, custom logger settings)\n  options?: Record<string, any>;\n}\n\n/**\n * Logger client interface\n */\nexport interface LoggerClient {\n  info: (msg: string, obj?: object) => void;\n  error: (msg: string, obj?: object | Error) => void;\n  warn: (msg: string, obj?: object) => void;\n  debug: (msg: string, obj?: object) => void;\n  updateContext?: (context: Partial<LoggerContext>) => void;\n  child?: (options: Partial<LoggerConfig>) => LoggerClient;\n}\n\n/**\n * Logger Lattice protocol interface\n */\nexport interface LoggerLatticeProtocol\n  extends BaseLatticeProtocol<LoggerConfig, LoggerClient> {\n  // Logger operations\n  info: (msg: string, obj?: object) => void;\n  error: (msg: string, obj?: object | Error) => void;\n  warn: (msg: string, obj?: object) => void;\n  debug: (msg: string, obj?: object) => void;\n  updateContext?: (context: Partial<LoggerContext>) => void;\n  child?: (options: Partial<LoggerConfig>) => LoggerClient;\n}\n"],"mappings":";AAaO,IAAK,YAAL,kBAAKA,eAAL;AACL,EAAAA,WAAA,WAAQ;AACR,EAAAA,WAAA,gBAAa;AACb,EAAAA,WAAA,kBAAe;AACf,EAAAA,WAAA,gBAAa;AAJH,SAAAA;AAAA,GAAA;AAyFL,SAAS,SAAS,QAAqD;AAC5E,SAAO,OAAO,SAAS;AACzB;AAKO,SAAS,kBACd,QAC2B;AAC3B,SAAO,OAAO,SAAS;AACzB;AAKO,SAAS,mBAAmB,QAA+B;AAChE,MAAI,SAAS,MAAM,GAAG;AACpB,WAAO,OAAO,SAAS,CAAC;AAAA,EAC1B;AACA,SAAO,CAAC;AACV;AAKO,SAAS,uBAAuB,QAA+B;AACpE,MAAI,kBAAkB,MAAM,GAAG;AAC7B,WAAO,OAAO,aAAa,CAAC;AAAA,EAC9B;AACA,SAAO,CAAC;AACV;;;AC1HO,IAAK,aAAL,kBAAKC,gBAAL;AACL,EAAAA,YAAA,gBAAa;AACb,EAAAA,YAAA,eAAY;AACZ,EAAAA,YAAA,cAAW;AACX,EAAAA,YAAA,cAAW;AACX,EAAAA,YAAA,aAAU;AALA,SAAAA;AAAA,GAAA;;;ACAL,IAAK,kBAAL,kBAAKC,qBAAL;AACL,EAAAA,iBAAA,eAAY;AACZ,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,YAAS;AACT,EAAAA,iBAAA,UAAO;AACP,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,UAAO;AACP,EAAAA,iBAAA,UAAO;AACP,EAAAA,iBAAA,WAAQ;AACR,EAAAA,iBAAA,YAAS;AAVC,SAAAA;AAAA,GAAA;;;ACAL,IAAK,YAAL,kBAAKC,eAAL;AACL,EAAAA,WAAA,YAAS;AACT,EAAAA,WAAA,WAAQ;AAFE,SAAAA;AAAA,GAAA;;;ACEL,IAAK,eAAL,kBAAKC,kBAAL;AACL,EAAAA,cAAA,YAAS;AACT,EAAAA,cAAA,cAAW;AACX,EAAAA,cAAA,WAAQ;AAHE,SAAAA;AAAA,GAAA;AASL,IAAK,wBAAL,kBAAKC,2BAAL;AACL,EAAAA,uBAAA,UAAO;AACP,EAAAA,uBAAA,UAAO;AAFG,SAAAA;AAAA,GAAA;AAQL,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,qBAAA,aAAU;AACV,EAAAA,qBAAA,aAAU;AACV,EAAAA,qBAAA,eAAY;AACZ,EAAAA,qBAAA,YAAS;AACT,EAAAA,qBAAA,eAAY;AACZ,EAAAA,qBAAA,YAAS;AANC,SAAAA;AAAA,GAAA;;;ACnBL,IAAK,aAAL,kBAAKC,gBAAL;AACL,EAAAA,YAAA,UAAO;AACP,EAAAA,YAAA,aAAU;AACV,EAAAA,YAAA,YAAS;AAHC,SAAAA;AAAA,GAAA;","names":["AgentType","MemoryType","UIComponentType","QueueType","ScheduleType","ScheduleExecutionType","ScheduledTaskStatus","LoggerType"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "2.1.7",
+  "version": "2.1.9",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

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/LoggerLatticeProtocol.ts

@@ -0,0 +1,81 @@
+/**
+ * LoggerLatticeProtocol
+ *
+ * Logger Lattice protocol for logging management
+ */
+
+import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
+/**
+ * Logger service type enumeration
+ */
+export enum LoggerType {
+  PINO = "pino",
+  CONSOLE = "console",
+  CUSTOM = "custom",
+}
+
+/**
+ * Logger context interface
+ */
+export interface LoggerContext {
+  "x-user-id"?: string;
+  "x-tenant-id"?: string;
+  "x-request-id"?: string;
+  "x-task-id"?: string;
+  "x-thread-id"?: string;
+  [key: string]: any;
+}
+
+/**
+ * Pino logger file transport options
+ */
+export interface PinoFileOptions {
+  file?: string; // Log file path (e.g., "./logs/app.log" or "./logs/app")
+  frequency?: "daily" | "hourly" | "minutely" | string; // Log rotation frequency
+  mkdir?: boolean; // Create directory if not exists
+  size?: string; // Max file size (e.g., "10M", "100K")
+  maxFiles?: number; // Maximum number of log files to keep
+}
+
+/**
+ * Logger configuration interface
+ */
+export interface LoggerConfig {
+  name: string; // Logger name
+  description?: string; // Logger description
+  type: LoggerType; // Logger service type
+  serviceName?: string; // Service name (e.g., "lattice-gateway")
+  loggerName?: string; // Logger instance name (e.g., "fastify-server")
+  context?: LoggerContext; // Initial context
+  // File logging options (for PINO type)
+  file?: string | PinoFileOptions; // Log file path or detailed file options
+  // Additional options (e.g., pino config, custom logger settings)
+  options?: Record<string, any>;
+}
+
+/**
+ * Logger client interface
+ */
+export interface LoggerClient {
+  info: (msg: string, obj?: object) => void;
+  error: (msg: string, obj?: object | Error) => void;
+  warn: (msg: string, obj?: object) => void;
+  debug: (msg: string, obj?: object) => void;
+  updateContext?: (context: Partial<LoggerContext>) => void;
+  child?: (options: Partial<LoggerConfig>) => LoggerClient;
+}
+
+/**
+ * Logger Lattice protocol interface
+ */
+export interface LoggerLatticeProtocol
+  extends BaseLatticeProtocol<LoggerConfig, LoggerClient> {
+  // Logger operations
+  info: (msg: string, obj?: object) => void;
+  error: (msg: string, obj?: object | Error) => void;
+  warn: (msg: string, obj?: object) => void;
+  debug: (msg: string, obj?: object) => void;
+  updateContext?: (context: Partial<LoggerContext>) => void;
+  child?: (options: Partial<LoggerConfig>) => LoggerClient;
+}

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>;
 }

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./QueueLatticeProtocol";
 export * from "./ScheduleLatticeProtocol";
 export * from "./EmbeddingsLatticeProtocol";
 export * from "./VectorStoreLatticeProtocol";
+export * from "./LoggerLatticeProtocol";
 export * from "./MessageProtocol";
 export * from "./ThreadStoreProtocol";
 export * from "./AssistantStoreProtocol";