@dexto/tools-scheduler 1.6.0

package/dist/manager.js

@@ -0,0 +1,430 @@
+import cron from "node-cron";
+import * as cronParser from "cron-parser";
+import { randomUUID } from "crypto";
+import { DextoRuntimeError } from "@dexto/core";
+import {
+  CreateScheduleInputSchema,
+  UpdateScheduleFieldsOnlySchema
+} from "./schemas.js";
+import { ScheduleStorage } from "./storage.js";
+import { ScheduleExecutor } from "./executor.js";
+import { SchedulerError } from "./errors.js";
+class SchedulerManager {
+  constructor(storageManager, config, logger) {
+    this.config = config;
+    this.logger = logger;
+    this.storage = new ScheduleStorage(storageManager, config.maxExecutionHistory, logger);
+    this.executor = new 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 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 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 = CreateScheduleInputSchema.parse(input);
+    const existingSchedules = await this.storage.listSchedules();
+    if (existingSchedules.length >= this.config.maxSchedules) {
+      throw SchedulerError.limitReached(existingSchedules.length, this.config.maxSchedules);
+    }
+    if (!cron.validate(validated.cronExpression)) {
+      throw SchedulerError.invalidCron(validated.cronExpression, "Invalid cron format");
+    }
+    let resolvedSessionId;
+    const sessionMode = validated.sessionMode ?? "ephemeral";
+    if (sessionMode === "inherit") {
+      if (!currentSessionId) {
+        throw 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: 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 = UpdateScheduleFieldsOnlySchema.parse(updates);
+    const existing = await this.storage.loadSchedule(scheduleId);
+    if (!existing) {
+      throw SchedulerError.notFound(scheduleId);
+    }
+    if (validated.cronExpression && !cron.validate(validated.cronExpression)) {
+      throw 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 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 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 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 = cron.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 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 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 DextoRuntimeError) {
+        throw error;
+      }
+      throw 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;
+    }
+  }
+}
+export {
+  SchedulerManager
+};

package/dist/schemas.cjs

@@ -0,0 +1,138 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var schemas_exports = {};
+__export(schemas_exports, {
+  CreateScheduleInputSchema: () => CreateScheduleInputSchema,
+  DeleteScheduleInputSchema: () => DeleteScheduleInputSchema,
+  GetScheduleHistoryInputSchema: () => GetScheduleHistoryInputSchema,
+  GetScheduleInputSchema: () => GetScheduleInputSchema,
+  ListSchedulesInputSchema: () => ListSchedulesInputSchema,
+  ScheduleSessionModeSchema: () => ScheduleSessionModeSchema,
+  SchedulerToolsConfigSchema: () => SchedulerToolsConfigSchema,
+  TriggerScheduleInputSchema: () => TriggerScheduleInputSchema,
+  UpdateScheduleFieldsOnlySchema: () => UpdateScheduleFieldsOnlySchema,
+  UpdateScheduleInputSchema: () => UpdateScheduleInputSchema
+});
+module.exports = __toCommonJS(schemas_exports);
+var import_zod = require("zod");
+const ScheduleSessionModeSchema = import_zod.z.enum(["ephemeral", "dedicated", "inherit", "fixed"]).describe(
+  `How to manage conversation context for scheduled executions:
+\u2022 ephemeral - New isolated session each time (default). Use for standalone tasks like reports.
+\u2022 dedicated - Persistent session for this schedule. Builds context over multiple runs.
+\u2022 inherit - Continue in the current conversation. Use for "remind me later" scenarios.
+\u2022 fixed - Use a specific sessionId. Advanced: for cross-session orchestration.`
+);
+const SchedulerToolsConfigSchema = import_zod.z.object({
+  type: import_zod.z.literal("scheduler-tools"),
+  timezone: import_zod.z.string().default("UTC").describe("Default timezone for schedules"),
+  maxSchedules: import_zod.z.number().default(100).describe("Maximum number of schedules"),
+  executionTimeout: import_zod.z.number().default(3e5).describe("Maximum execution time in milliseconds (default 5 minutes)"),
+  maxExecutionHistory: import_zod.z.number().default(100).describe("Maximum execution history entries to keep")
+}).strict();
+const CreateScheduleInputSchema = import_zod.z.object({
+  name: import_zod.z.string().min(1).max(100).describe(
+    'Human-readable name for the schedule (e.g., "Coffee Reminder", "Daily Standup")'
+  ),
+  cronExpression: import_zod.z.string().describe('Cron expression (e.g., "0 9 * * 1-5" for weekdays at 9am)'),
+  instruction: import_zod.z.string().min(1).describe(
+    "What should happen when this schedule triggers. Be natural and clear about the intent."
+  ),
+  timezone: import_zod.z.string().optional().describe("Optional timezone (defaults to config timezone)"),
+  enabled: import_zod.z.boolean().default(true).describe("Whether schedule is enabled"),
+  metadata: import_zod.z.record(import_zod.z.unknown()).optional().describe("Optional metadata for the task"),
+  workspacePath: import_zod.z.string().optional().nullable().describe("Optional workspace path for scheduled runs"),
+  sessionMode: ScheduleSessionModeSchema.default("ephemeral").describe(
+    `Session context mode:
+\u2022 ephemeral (default) - Fresh session each run. Example: "Send daily report"
+\u2022 dedicated - Same session across runs. Example: "Track project progress daily"
+\u2022 inherit - Continue current conversation. Example: "Remind me about this in 2 hours"
+\u2022 fixed - Specific session. Example: "Post update to session abc-123"`
+  ),
+  sessionId: import_zod.z.string().optional().describe(
+    'Target session ID. Required for "fixed" mode. For "inherit", this is auto-captured.'
+  ),
+  targetAgentId: import_zod.z.string().optional().describe(
+    'Target agent ID to execute this schedule (e.g., "notes", "filesystem", "coding"). If not specified, executes in the creator agent context. Use this to delegate scheduled tasks to specialized agents.'
+  )
+}).strict().superRefine((data, ctx) => {
+  if (data.sessionMode === "fixed" && !data.sessionId) {
+    ctx.addIssue({
+      code: import_zod.z.ZodIssueCode.custom,
+      message: 'sessionId is required when sessionMode is "fixed"',
+      path: ["sessionId"]
+    });
+  }
+});
+const UpdateScheduleFieldsSchema = import_zod.z.object({
+  name: import_zod.z.string().min(1).max(100).optional().describe("Updated name"),
+  cronExpression: import_zod.z.string().optional().describe("Updated cron expression"),
+  instruction: import_zod.z.string().min(1).optional().describe("Updated instruction - what should happen when this schedule triggers"),
+  timezone: import_zod.z.string().optional().describe("Updated timezone"),
+  enabled: import_zod.z.boolean().optional().describe("Updated enabled state"),
+  metadata: import_zod.z.record(import_zod.z.unknown()).optional().describe("Updated metadata"),
+  workspacePath: import_zod.z.string().optional().nullable().describe("Updated workspace path for scheduled runs"),
+  sessionMode: ScheduleSessionModeSchema.optional().describe(
+    "Updated session mode (ephemeral, dedicated, inherit, fixed)"
+  ),
+  sessionId: import_zod.z.string().optional().describe('Updated session ID (required if changing to "fixed" mode)'),
+  targetAgentId: import_zod.z.string().optional().describe(
+    "Updated target agent ID. Set to reassign schedule execution to a different agent."
+  )
+}).strict();
+const UpdateScheduleInputSchema = UpdateScheduleFieldsSchema.extend({
+  scheduleId: import_zod.z.string().describe("The schedule ID to update")
+}).superRefine((data, ctx) => {
+  if (data.sessionMode === "fixed" && !data.sessionId) {
+    ctx.addIssue({
+      code: import_zod.z.ZodIssueCode.custom,
+      message: 'sessionId is required when sessionMode is "fixed"',
+      path: ["sessionId"]
+    });
+  }
+});
+const UpdateScheduleFieldsOnlySchema = UpdateScheduleFieldsSchema;
+const GetScheduleInputSchema = import_zod.z.object({
+  scheduleId: import_zod.z.string().describe("The schedule ID")
+}).strict();
+const DeleteScheduleInputSchema = import_zod.z.object({
+  scheduleId: import_zod.z.string().describe("The schedule ID to delete")
+}).strict();
+const TriggerScheduleInputSchema = import_zod.z.object({
+  scheduleId: import_zod.z.string().describe("The schedule ID to trigger")
+}).strict();
+const GetScheduleHistoryInputSchema = import_zod.z.object({
+  scheduleId: import_zod.z.string().describe("The schedule ID"),
+  limit: import_zod.z.number().optional().describe("Maximum number of history entries to return (default: 10)")
+}).strict();
+const ListSchedulesInputSchema = import_zod.z.object({
+  enabled: import_zod.z.boolean().optional().describe("Filter by enabled status (true/false)")
+}).strict();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CreateScheduleInputSchema,
+  DeleteScheduleInputSchema,
+  GetScheduleHistoryInputSchema,
+  GetScheduleInputSchema,
+  ListSchedulesInputSchema,
+  ScheduleSessionModeSchema,
+  SchedulerToolsConfigSchema,
+  TriggerScheduleInputSchema,
+  UpdateScheduleFieldsOnlySchema,
+  UpdateScheduleInputSchema
+});