@dexto/tools-scheduler 1.6.0

package/dist/manager.cjs

@@ -0,0 +1,461 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var manager_exports = {};
+__export(manager_exports, {
+  SchedulerManager: () => SchedulerManager
+});
+module.exports = __toCommonJS(manager_exports);
+var import_node_cron = __toESM(require("node-cron"), 1);
+var cronParser = __toESM(require("cron-parser"), 1);
+var import_crypto = require("crypto");
+var import_core = require("@dexto/core");
+var import_schemas = require("./schemas.js");
+var import_storage = require("./storage.js");
+var import_executor = require("./executor.js");
+var import_errors = require("./errors.js");
+class SchedulerManager {
+  constructor(storageManager, config, logger) {
+    this.config = config;
+    this.logger = logger;
+    this.storage = new import_storage.ScheduleStorage(storageManager, config.maxExecutionHistory, logger);
+    this.executor = new import_executor.ScheduleExecutor(config.executionTimeout, logger);
+  }
+  cronTasks = /* @__PURE__ */ new Map();
+  storage;
+  executor;
+  executionChain = Promise.resolve();
+  initialized = false;
+  started = false;
+  cachedSchedules;
+  /**
+   * Set the executor function (called to run the agent with a prompt)
+   */
+  setExecutor(fn) {
+    this.executor.setExecutor(fn);
+  }
+  /**
+   * Initialize the scheduler (load schedules from storage)
+   */
+  async init() {
+    if (this.initialized) {
+      return;
+    }
+    try {
+      const storedSchedules = await this.storage.listSchedules();
+      this.cachedSchedules = storedSchedules;
+      this.logger.info(`Loaded ${storedSchedules.length} schedules from storage`);
+      this.initialized = true;
+    } catch (error) {
+      throw import_errors.SchedulerError.invalidConfig(
+        `Failed to initialize scheduler: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Start the scheduler (begin executing schedules)
+   */
+  async start() {
+    if (!this.initialized) {
+      await this.init();
+    }
+    if (this.started) {
+      return;
+    }
+    try {
+      const schedules = this.cachedSchedules ?? await this.storage.listSchedules();
+      this.cachedSchedules = void 0;
+      for (const schedule of schedules) {
+        if (schedule.enabled) {
+          await this.scheduleTask(schedule);
+        }
+      }
+      this.started = true;
+      this.logger.info(`Scheduler started with ${this.cronTasks.size} active schedules`);
+    } catch (error) {
+      throw import_errors.SchedulerError.invalidConfig(
+        `Failed to start scheduler: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Stop the scheduler (stop all running tasks)
+   */
+  async stop() {
+    if (!this.started) {
+      return;
+    }
+    for (const task of this.cronTasks.values()) {
+      task.stop();
+    }
+    this.cronTasks.clear();
+    this.started = false;
+    this.logger.info("Scheduler stopped");
+  }
+  /**
+   * Create a new schedule
+   *
+   * @param input - Schedule creation input
+   * @param currentSessionId - The current session ID (used for 'inherit' mode)
+   */
+  async createSchedule(input, currentSessionId) {
+    const validated = import_schemas.CreateScheduleInputSchema.parse(input);
+    const existingSchedules = await this.storage.listSchedules();
+    if (existingSchedules.length >= this.config.maxSchedules) {
+      throw import_errors.SchedulerError.limitReached(existingSchedules.length, this.config.maxSchedules);
+    }
+    if (!import_node_cron.default.validate(validated.cronExpression)) {
+      throw import_errors.SchedulerError.invalidCron(validated.cronExpression, "Invalid cron format");
+    }
+    let resolvedSessionId;
+    const sessionMode = validated.sessionMode ?? "ephemeral";
+    if (sessionMode === "inherit") {
+      if (!currentSessionId) {
+        throw import_errors.SchedulerError.invalidInput(
+          'sessionMode "inherit" requires a current session context'
+        );
+      }
+      resolvedSessionId = currentSessionId;
+    } else if (sessionMode === "fixed") {
+      resolvedSessionId = validated.sessionId;
+    }
+    const now = Date.now();
+    const taskMetadata = {
+      ...validated.metadata
+    };
+    if (validated.targetAgentId) {
+      taskMetadata.__os_targetAgentId = validated.targetAgentId;
+    }
+    const workspacePath = validated.workspacePath && validated.workspacePath.trim().length > 0 ? validated.workspacePath : void 0;
+    const schedule = {
+      id: (0, import_crypto.randomUUID)(),
+      name: validated.name,
+      cronExpression: validated.cronExpression,
+      timezone: validated.timezone || this.config.timezone,
+      enabled: validated.enabled,
+      task: {
+        instruction: validated.instruction,
+        ...Object.keys(taskMetadata).length > 0 && { metadata: taskMetadata }
+      },
+      sessionMode,
+      ...resolvedSessionId && { sessionId: resolvedSessionId },
+      ...workspacePath ? { workspacePath } : {},
+      createdAt: now,
+      updatedAt: now,
+      runCount: 0,
+      successCount: 0,
+      failureCount: 0
+    };
+    const nextRun = this.calculateNextRun(schedule);
+    if (nextRun !== void 0) {
+      schedule.nextRunAt = nextRun;
+    }
+    await this.storage.saveSchedule(schedule);
+    if (schedule.enabled && this.started) {
+      await this.scheduleTask(schedule);
+    }
+    this.logger.info(`Schedule created: ${schedule.name}`, {
+      scheduleId: schedule.id,
+      sessionMode,
+      cronExpression: schedule.cronExpression
+    });
+    return schedule;
+  }
+  /**
+   * Update an existing schedule
+   *
+   * @param scheduleId - The schedule ID to update
+   * @param updates - The updates to apply
+   * @param currentSessionId - The current session ID (used if changing to 'inherit' mode)
+   */
+  async updateSchedule(scheduleId, updates, currentSessionId) {
+    const validated = import_schemas.UpdateScheduleFieldsOnlySchema.parse(updates);
+    const existing = await this.storage.loadSchedule(scheduleId);
+    if (!existing) {
+      throw import_errors.SchedulerError.notFound(scheduleId);
+    }
+    if (validated.cronExpression && !import_node_cron.default.validate(validated.cronExpression)) {
+      throw import_errors.SchedulerError.invalidCron(validated.cronExpression, "Invalid cron format");
+    }
+    let updatedSessionId = existing.sessionId;
+    const newSessionMode = validated.sessionMode ?? existing.sessionMode;
+    if (validated.sessionMode !== void 0) {
+      if (newSessionMode === "inherit") {
+        if (!currentSessionId) {
+          throw import_errors.SchedulerError.invalidInput(
+            'sessionMode "inherit" requires a current session context'
+          );
+        }
+        updatedSessionId = currentSessionId;
+      } else if (newSessionMode === "fixed") {
+        updatedSessionId = validated.sessionId;
+      } else {
+        updatedSessionId = void 0;
+      }
+    } else if (validated.sessionId !== void 0) {
+      updatedSessionId = validated.sessionId;
+    }
+    const existingTaskMetadata = existing.task.metadata ?? {};
+    const updatedTaskMetadata = validated.metadata !== void 0 ? { ...validated.metadata } : { ...existingTaskMetadata };
+    for (const [key, value] of Object.entries(existingTaskMetadata)) {
+      if (key.startsWith("__os_")) {
+        updatedTaskMetadata[key] = value;
+      }
+    }
+    if (validated.targetAgentId !== void 0) {
+      if (validated.targetAgentId) {
+        updatedTaskMetadata.__os_targetAgentId = validated.targetAgentId;
+      } else {
+        delete updatedTaskMetadata.__os_targetAgentId;
+      }
+    }
+    const resolvedWorkspacePath = validated.workspacePath === void 0 ? existing.workspacePath : validated.workspacePath && validated.workspacePath.trim().length > 0 ? validated.workspacePath : void 0;
+    const updated = {
+      ...existing,
+      ...validated.name !== void 0 && { name: validated.name },
+      ...validated.cronExpression !== void 0 && {
+        cronExpression: validated.cronExpression
+      },
+      ...validated.timezone !== void 0 && { timezone: validated.timezone },
+      ...validated.enabled !== void 0 && { enabled: validated.enabled },
+      task: {
+        ...existing.task,
+        ...validated.instruction !== void 0 && { instruction: validated.instruction },
+        ...Object.keys(updatedTaskMetadata).length > 0 ? { metadata: updatedTaskMetadata } : {}
+      },
+      sessionMode: newSessionMode,
+      ...updatedSessionId !== void 0 ? { sessionId: updatedSessionId } : {},
+      updatedAt: Date.now()
+    };
+    if (resolvedWorkspacePath) {
+      updated.workspacePath = resolvedWorkspacePath;
+    } else {
+      delete updated.workspacePath;
+    }
+    if (newSessionMode === "ephemeral" || newSessionMode === "dedicated") {
+      delete updated.sessionId;
+    }
+    const nextRunTime = this.calculateNextRun(updated);
+    if (nextRunTime !== void 0) {
+      updated.nextRunAt = nextRunTime;
+    }
+    await this.storage.saveSchedule(updated);
+    if (this.started) {
+      this.unscheduleTask(scheduleId);
+      if (updated.enabled) {
+        await this.scheduleTask(updated);
+      }
+    }
+    this.logger.info(`Schedule updated: ${updated.name}`, {
+      scheduleId,
+      sessionMode: newSessionMode
+    });
+    return updated;
+  }
+  /**
+   * Delete a schedule
+   */
+  async deleteSchedule(scheduleId) {
+    const schedule = await this.storage.loadSchedule(scheduleId);
+    if (!schedule) {
+      throw import_errors.SchedulerError.notFound(scheduleId);
+    }
+    if (this.started) {
+      this.unscheduleTask(scheduleId);
+    }
+    await this.storage.deleteSchedule(scheduleId);
+    this.logger.info(`Schedule deleted: ${schedule.name}`, { scheduleId });
+  }
+  /**
+   * Get a schedule by ID
+   */
+  async getSchedule(scheduleId) {
+    return this.storage.loadSchedule(scheduleId);
+  }
+  /**
+   * List schedules with optional filters
+   */
+  async listSchedules(filters) {
+    const schedules = await this.storage.listSchedules();
+    if (!filters) {
+      return schedules;
+    }
+    return schedules.filter((schedule) => {
+      if (filters.enabled !== void 0 && schedule.enabled !== filters.enabled) {
+        return false;
+      }
+      return true;
+    });
+  }
+  /**
+   * Trigger a schedule immediately (manual execution)
+   */
+  async triggerScheduleNow(scheduleId) {
+    const schedule = await this.storage.loadSchedule(scheduleId);
+    if (!schedule) {
+      throw import_errors.SchedulerError.notFound(scheduleId);
+    }
+    this.logger.info(`Manually triggering schedule: ${schedule.name}`, { scheduleId });
+    return this.executeSchedule(schedule);
+  }
+  /**
+   * Get execution history for a schedule
+   */
+  async getExecutionHistory(scheduleId, limit) {
+    return this.storage.getExecutionLogs(scheduleId, limit);
+  }
+  /**
+   * Get scheduler status
+   */
+  getStatus() {
+    return {
+      initialized: this.initialized,
+      started: this.started,
+      activeSchedules: this.cronTasks.size
+    };
+  }
+  /**
+   * Schedule a task using cron
+   */
+  async scheduleTask(schedule) {
+    this.unscheduleTask(schedule.id);
+    if (!schedule.enabled) {
+      return;
+    }
+    try {
+      const task = import_node_cron.default.schedule(
+        schedule.cronExpression,
+        () => {
+          this.executeSchedule(schedule).catch((error) => {
+            this.logger.error(
+              `Failed to execute schedule ${schedule.id}: ${error instanceof Error ? error.message : String(error)}`
+            );
+          });
+        },
+        {
+          timezone: schedule.timezone,
+          name: schedule.id
+        }
+      );
+      task.start();
+      this.cronTasks.set(schedule.id, task);
+      this.logger.debug(`Schedule task registered: ${schedule.name}`, {
+        scheduleId: schedule.id,
+        cronExpression: schedule.cronExpression
+      });
+    } catch (error) {
+      throw import_errors.SchedulerError.createFailed(
+        `Failed to schedule task: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Unschedule a task
+   */
+  unscheduleTask(scheduleId) {
+    const task = this.cronTasks.get(scheduleId);
+    if (task) {
+      task.stop();
+      this.cronTasks.delete(scheduleId);
+      this.logger.debug(`Schedule task unregistered: ${scheduleId}`);
+    }
+  }
+  /**
+   * Execute a schedule
+   */
+  async executeSchedule(schedule) {
+    return await this.queueExecution(() => this.executeScheduleInternal(schedule));
+  }
+  async executeScheduleInternal(schedule) {
+    try {
+      const current = await this.storage.loadSchedule(schedule.id);
+      if (!current) {
+        throw import_errors.SchedulerError.notFound(schedule.id);
+      }
+      const log = await this.executor.execute(current);
+      await this.storage.saveExecutionLog(log);
+      const updates = {
+        lastRunAt: log.triggeredAt,
+        runCount: current.runCount + 1,
+        updatedAt: Date.now()
+      };
+      if (log.status === "success") {
+        updates.successCount = current.successCount + 1;
+      } else if (log.status === "failed" || log.status === "timeout") {
+        updates.failureCount = current.failureCount + 1;
+        if (log.error) {
+          updates.lastError = log.error;
+        }
+      }
+      const nextRun = this.calculateNextRun(current);
+      if (nextRun !== void 0) {
+        updates.nextRunAt = nextRun;
+      }
+      const updated = { ...current, ...updates };
+      await this.storage.saveSchedule(updated);
+      return log;
+    } catch (error) {
+      if (error instanceof import_core.DextoRuntimeError) {
+        throw error;
+      }
+      throw import_errors.SchedulerError.executionFailed(
+        schedule.id,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  queueExecution(fn) {
+    const run = this.executionChain.then(fn);
+    this.executionChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  /**
+   * Calculate next run time for a schedule
+   */
+  calculateNextRun(schedule) {
+    try {
+      const interval = cronParser.parseExpression(schedule.cronExpression, {
+        tz: schedule.timezone
+      });
+      const next = interval.next();
+      return next.toDate().getTime();
+    } catch (error) {
+      this.logger.error(
+        `Failed to calculate next run: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return void 0;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SchedulerManager
+});

package/dist/manager.d.cts

@@ -0,0 +1,113 @@
+import { StorageManager, Logger } from '@dexto/core';
+import { SchedulerToolsConfig, CreateScheduleInput, UpdateScheduleInput } from './schemas.cjs';
+import { ScheduleExecutorFn, Schedule, ScheduleFilters, ExecutionLog } from './types.cjs';
+import 'zod';
+
+/**
+ * Scheduler Manager - Core service for internal task scheduling
+ */
+
+/**
+ * Scheduler Manager
+ *
+ * Core service for internal task scheduling. Manages cron-based schedules
+ * that execute tasks via the agent.
+ *
+ * Key features:
+ * - Cron-based scheduling with timezone support
+ * - Persistent schedules (survive agent restarts)
+ * - Direct agent execution (zero HTTP overhead)
+ * - Logging-based observability
+ * - Self-configurable via tools
+ */
+declare class SchedulerManager {
+    private config;
+    private logger;
+    private cronTasks;
+    private storage;
+    private executor;
+    private executionChain;
+    private initialized;
+    private started;
+    private cachedSchedules;
+    constructor(storageManager: StorageManager, config: SchedulerToolsConfig, logger: Logger);
+    /**
+     * Set the executor function (called to run the agent with a prompt)
+     */
+    setExecutor(fn: ScheduleExecutorFn): void;
+    /**
+     * Initialize the scheduler (load schedules from storage)
+     */
+    init(): Promise<void>;
+    /**
+     * Start the scheduler (begin executing schedules)
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the scheduler (stop all running tasks)
+     */
+    stop(): Promise<void>;
+    /**
+     * Create a new schedule
+     *
+     * @param input - Schedule creation input
+     * @param currentSessionId - The current session ID (used for 'inherit' mode)
+     */
+    createSchedule(input: CreateScheduleInput, currentSessionId?: string): Promise<Schedule>;
+    /**
+     * Update an existing schedule
+     *
+     * @param scheduleId - The schedule ID to update
+     * @param updates - The updates to apply
+     * @param currentSessionId - The current session ID (used if changing to 'inherit' mode)
+     */
+    updateSchedule(scheduleId: string, updates: Omit<UpdateScheduleInput, 'scheduleId'>, currentSessionId?: string): Promise<Schedule>;
+    /**
+     * Delete a schedule
+     */
+    deleteSchedule(scheduleId: string): Promise<void>;
+    /**
+     * Get a schedule by ID
+     */
+    getSchedule(scheduleId: string): Promise<Schedule | null>;
+    /**
+     * List schedules with optional filters
+     */
+    listSchedules(filters?: ScheduleFilters): Promise<Schedule[]>;
+    /**
+     * Trigger a schedule immediately (manual execution)
+     */
+    triggerScheduleNow(scheduleId: string): Promise<ExecutionLog>;
+    /**
+     * Get execution history for a schedule
+     */
+    getExecutionHistory(scheduleId: string, limit?: number): Promise<ExecutionLog[]>;
+    /**
+     * Get scheduler status
+     */
+    getStatus(): {
+        initialized: boolean;
+        started: boolean;
+        activeSchedules: number;
+    };
+    /**
+     * Schedule a task using cron
+     */
+    private scheduleTask;
+    /**
+     * Unschedule a task
+     */
+    private unscheduleTask;
+    /**
+     * Execute a schedule
+     */
+    private executeSchedule;
+    private executeScheduleInternal;
+    private queueExecution;
+    /**
+     * Calculate next run time for a schedule
+     */
+    private calculateNextRun;
+}
+
+export { SchedulerManager };

package/dist/manager.d.ts

@@ -0,0 +1,113 @@
+import { StorageManager, Logger } from '@dexto/core';
+import { SchedulerToolsConfig, CreateScheduleInput, UpdateScheduleInput } from './schemas.js';
+import { ScheduleExecutorFn, Schedule, ScheduleFilters, ExecutionLog } from './types.js';
+import 'zod';
+
+/**
+ * Scheduler Manager - Core service for internal task scheduling
+ */
+
+/**
+ * Scheduler Manager
+ *
+ * Core service for internal task scheduling. Manages cron-based schedules
+ * that execute tasks via the agent.
+ *
+ * Key features:
+ * - Cron-based scheduling with timezone support
+ * - Persistent schedules (survive agent restarts)
+ * - Direct agent execution (zero HTTP overhead)
+ * - Logging-based observability
+ * - Self-configurable via tools
+ */
+declare class SchedulerManager {
+    private config;
+    private logger;
+    private cronTasks;
+    private storage;
+    private executor;
+    private executionChain;
+    private initialized;
+    private started;
+    private cachedSchedules;
+    constructor(storageManager: StorageManager, config: SchedulerToolsConfig, logger: Logger);
+    /**
+     * Set the executor function (called to run the agent with a prompt)
+     */
+    setExecutor(fn: ScheduleExecutorFn): void;
+    /**
+     * Initialize the scheduler (load schedules from storage)
+     */
+    init(): Promise<void>;
+    /**
+     * Start the scheduler (begin executing schedules)
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the scheduler (stop all running tasks)
+     */
+    stop(): Promise<void>;
+    /**
+     * Create a new schedule
+     *
+     * @param input - Schedule creation input
+     * @param currentSessionId - The current session ID (used for 'inherit' mode)
+     */
+    createSchedule(input: CreateScheduleInput, currentSessionId?: string): Promise<Schedule>;
+    /**
+     * Update an existing schedule
+     *
+     * @param scheduleId - The schedule ID to update
+     * @param updates - The updates to apply
+     * @param currentSessionId - The current session ID (used if changing to 'inherit' mode)
+     */
+    updateSchedule(scheduleId: string, updates: Omit<UpdateScheduleInput, 'scheduleId'>, currentSessionId?: string): Promise<Schedule>;
+    /**
+     * Delete a schedule
+     */
+    deleteSchedule(scheduleId: string): Promise<void>;
+    /**
+     * Get a schedule by ID
+     */
+    getSchedule(scheduleId: string): Promise<Schedule | null>;
+    /**
+     * List schedules with optional filters
+     */
+    listSchedules(filters?: ScheduleFilters): Promise<Schedule[]>;
+    /**
+     * Trigger a schedule immediately (manual execution)
+     */
+    triggerScheduleNow(scheduleId: string): Promise<ExecutionLog>;
+    /**
+     * Get execution history for a schedule
+     */
+    getExecutionHistory(scheduleId: string, limit?: number): Promise<ExecutionLog[]>;
+    /**
+     * Get scheduler status
+     */
+    getStatus(): {
+        initialized: boolean;
+        started: boolean;
+        activeSchedules: number;
+    };
+    /**
+     * Schedule a task using cron
+     */
+    private scheduleTask;
+    /**
+     * Unschedule a task
+     */
+    private unscheduleTask;
+    /**
+     * Execute a schedule
+     */
+    private executeSchedule;
+    private executeScheduleInternal;
+    private queueExecution;
+    /**
+     * Calculate next run time for a schedule
+     */
+    private calculateNextRun;
+}
+
+export { SchedulerManager };