Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

12.4 KB
Raw Blame
import cron from 'node-cron';
import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
import { randomUUID } from 'node:crypto';
import { join } from 'node:path';
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
import type { MercuryConfig } from '../utils/config.js';
import { getMercuryHome } from '../utils/config.js';
import { logger } from '../utils/logger.js';

export interface ScheduledTask {
  id: string;
  cron: string;
  handler: () => Promise<void>;
  description: string;
  timezone?: string;
}

export type ScheduledRunStatus = 'running' | 'completed' | 'failed' | 'interrupted' | 'skipped' | 'dispatched';
export interface ScheduledRun {
  id: string;
  status: ScheduledRunStatus;
  startedAt: string;
  finishedAt?: string;
  error?: string;
}

/** Queued main-agent work completes via finishRun; bots own a separate work ledger. */
export type ScheduledDispatch = void | 'queued' | 'dispatched' | 'skipped';

export interface ScheduledTaskManifest {
  id: string;
  cron?: string;
  description: string;
  skillName?: string;
  prompt?: string;
  delaySeconds?: number;
  executeAt?: string;
  createdAt: string;
  /** IANA timezone for cron; omitted means the host timezone for legacy schedules. */
  timezone?: string;
  /** Overdue one-shots default to skip, preserving the legacy no-replay behavior. */
  missedRunPolicy?: 'skip' | 'run_once';
  paused?: boolean;
  lastRun?: ScheduledRun;
  sourceChannelId?: string;
  sourceChannelType?: string;
  /** Set for Mercury Bot routines — the run routes to the bot, not the main agent. */
  botId?: string;
  /**
   * Plugin tools this task may run without asking when it fires (e.g.
   * "whatsapp__call_owner" for "call me in 10 minutes"). Approved by the owner
   * once, when the task was created; nothing else is pre-approved.
   */
  allowTools?: string[];
}

const SCHEDULES_FILE = 'schedules.yaml';

function getSchedulesPath(): string {
  return join(getMercuryHome(), SCHEDULES_FILE);
}

export function loadSchedules(): ScheduledTaskManifest[] {
  const path = getSchedulesPath();
  if (!existsSync(path)) return [];
  try {
    const raw = readFileSync(path, 'utf-8');
    const data = parseYaml(raw) as { tasks?: ScheduledTaskManifest[] };
    return Array.isArray(data?.tasks) ? data.tasks : [];
  } catch (err) {
    logger.warn({ err }, 'Failed to load schedules.yaml');
    return [];
  }
}

export function saveSchedules(tasks: ScheduledTaskManifest[]): void {
  const path = getSchedulesPath();
  mkdirSync(getMercuryHome(), { recursive: true, mode: 0o700 });
  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
  let fd: number | undefined;
  try {
    fd = openSync(temp, 'wx', 0o600);
    writeFileSync(fd, stringifyYaml({ tasks }), 'utf-8');
    fsyncSync(fd);
    closeSync(fd);
    fd = undefined;
    renameSync(temp, path);
    // Directory fsync is unavailable on some platforms (notably Windows).
    try {
      fd = openSync(getMercuryHome(), 'r');
      fsyncSync(fd);
    } catch { /* the file itself has already been synced */ }
  } finally {
    if (fd !== undefined) closeSync(fd);
    if (existsSync(temp)) unlinkSync(temp);
  }
}

export function isValidScheduleTimezone(timezone: string): boolean {
  try {
    new Intl.DateTimeFormat('en', { timeZone: timezone }).format();
    return true;
  } catch { return false; }
}

const MAX_TIMER_MS = 2 ** 31 - 1;
const MAX_FINISHED_ONESHOTS = 100;

export class Scheduler {
  private tasks: Map<string, cron.ScheduledTask> = new Map();
  private delayedTasks: Map<string, NodeJS.Timeout> = new Map();
  private taskManifests: Map<string, ScheduledTaskManifest> = new Map();
  private heartbeatIntervalMinutes: number;
  private heartbeatHandler?: () => Promise<void>;
  private heartbeatTimer: NodeJS.Timeout | null = null;

  constructor(
    config: MercuryConfig,
    private onScheduledTask?: (manifest: ScheduledTaskManifest, runId: string) => Promise<ScheduledDispatch>,
  ) {
    this.heartbeatIntervalMinutes = config.heartbeat.intervalMinutes;
  }

  setOnScheduledTask(handler: (manifest: ScheduledTaskManifest, runId: string) => Promise<ScheduledDispatch>): void {
    this.onScheduledTask = handler;
  }

  onHeartbeat(handler: () => Promise<void>): void {
    this.heartbeatHandler = handler;
  }

  startHeartbeat(): void {
    if (this.heartbeatTimer) return;
    const ms = this.heartbeatIntervalMinutes * 60 * 1000;
    logger.info({ intervalMin: this.heartbeatIntervalMinutes }, 'Heartbeat started');

    this.heartbeatTimer = setInterval(async () => {
      try {
        await this.heartbeatHandler?.();
      } catch (err) {
        logger.error({ err }, 'Heartbeat error');
      }
    }, ms);
  }

  stopHeartbeat(): void {
    if (this.heartbeatTimer) {
      clearInterval(this.heartbeatTimer);
      this.heartbeatTimer = null;
      logger.info('Heartbeat stopped');
    }
  }

  addTask(task: ScheduledTask): void {
    this.tasks.get(task.id)?.stop();
    let running = false;
    const scheduled = cron.schedule(task.cron, async () => {
      if (running) return; // Cron ticks never build an overlapping backlog.
      running = true;
      try {
        await task.handler();
      } catch (err) {
        logger.error({ task: task.id, err }, 'Scheduled task error');
      } finally { running = false; }
    }, { timezone: task.timezone });
    this.tasks.set(task.id, scheduled);
  }

  private validate(manifest: ScheduledTaskManifest): void {
    if (manifest.timezone !== undefined && !isValidScheduleTimezone(manifest.timezone)) {
      throw new Error('Invalid schedule timezone');
    }
    if (manifest.missedRunPolicy !== undefined && !['skip', 'run_once'].includes(manifest.missedRunPolicy)) {
      throw new Error('Invalid missed-run policy');
    }
    if (manifest.cron && cron.validate(manifest.cron) && manifest.delaySeconds === undefined) return;
    if (!manifest.cron && Number.isFinite(manifest.delaySeconds) && manifest.delaySeconds! > 0
      && (!manifest.executeAt || Number.isFinite(Date.parse(manifest.executeAt)))) return;
    throw new Error('Manifest requires a valid cron or positive finite delaySeconds');
  }

  addPersistedTask(manifest: ScheduledTaskManifest): void {
    this.validate(manifest);
    // Registering a bot's declared routine again must not erase interrupted state.
    const previous = this.taskManifests.get(manifest.id);
    const next = { ...manifest, lastRun: manifest.lastRun ?? previous?.lastRun, paused: manifest.paused ?? previous?.paused };
    this.removeTask(manifest.id);
    this.taskManifests.set(manifest.id, next);
    if (next.paused) return;
    this.addTask({
      id: next.id, cron: next.cron!, description: next.description, timezone: next.timezone,
      handler: () => this.runTask(next.id),
    });
  }

  addDelayedTask(manifest: ScheduledTaskManifest): void {
    this.validate(manifest);
    const next = { ...manifest, executeAt: manifest.executeAt ?? new Date(Date.now() + manifest.delaySeconds! * 1000).toISOString() };
    this.removeTask(next.id);
    this.taskManifests.set(next.id, next);
    if (!next.paused && !next.lastRun) this.armDelayedTask(next);
  }

  private armDelayedTask(manifest: ScheduledTaskManifest): void {
    const remaining = Date.parse(manifest.executeAt!) - Date.now();
    const timer = setTimeout(() => {
      this.delayedTasks.delete(manifest.id);
      if (this.taskManifests.get(manifest.id) !== manifest) return;
      if (Date.parse(manifest.executeAt!) > Date.now()) {
        this.armDelayedTask(manifest); // Node timers longer than ~24 days otherwise fire immediately.
      } else {
        void this.runTask(manifest.id).catch((err) => logger.error({ err, task: manifest.id }, 'Could not persist scheduled run'));
      }
    }, Math.min(MAX_TIMER_MS, Math.max(0, remaining)));
    this.delayedTasks.set(manifest.id, timer);
  }

  private async runTask(id: string): Promise<void> {
    const manifest = this.taskManifests.get(id);
    if (!manifest || manifest.paused || manifest.lastRun?.status === 'running') return;
    const runId = randomUUID();
    manifest.lastRun = { id: runId, status: 'running', startedAt: new Date().toISOString() };
    // Fail closed: no handler runs unless the intent is durable first.
    this.persistSchedules();
    try {
      if (!this.onScheduledTask) throw new Error('Scheduled task handler unavailable');
      const outcome = await this.onScheduledTask(manifest, runId);
      if (outcome !== 'queued') this.finishRun(id, runId, outcome ?? 'completed');
    } catch (err) {
      this.finishRun(id, runId, 'failed', err instanceof Error ? err.message : String(err));
      logger.error({ err, task: id }, 'Scheduled task failed; review before resuming');
    }
  }

  /** A run identity prevents a late completion from changing an edited/deleted task. */
  finishRun(id: string, runId: string, status: Exclude<ScheduledRunStatus, 'running'>, error?: string): void {
    const manifest = this.taskManifests.get(id);
    if (!manifest || manifest.lastRun?.id !== runId || manifest.lastRun.status !== 'running') return;
    manifest.lastRun = { ...manifest.lastRun, status, finishedAt: new Date().toISOString(), ...(error ? { error: error.slice(0, 1000) } : {}) };
    if (status === 'failed' || status === 'interrupted') manifest.paused = true;
    this.persistSchedules();
  }

  removeTask(id: string): void {
    const task = this.tasks.get(id);
    if (task) {
      task.stop();
      this.tasks.delete(id);
    }
    const timer = this.delayedTasks.get(id);
    if (timer) {
      clearTimeout(timer);
      this.delayedTasks.delete(id);
    }
    this.taskManifests.delete(id);
  }

  getManifests(): ScheduledTaskManifest[] {
    return [...this.taskManifests.values()];
  }

  getManifest(id: string): ScheduledTaskManifest | null {
    return this.taskManifests.get(id) || null;
  }

  replaceManifest(manifest: ScheduledTaskManifest, resume = false): void {
    this.validate(manifest);
    if (this.getManifest(manifest.id)?.lastRun?.status === 'running') throw new Error('Cannot edit a running schedule');
    const next = { ...manifest };
    if (resume) {
      next.paused = false;
      next.lastRun = undefined;
      if (next.delaySeconds) next.executeAt = new Date(Date.now() + next.delaySeconds * 1000).toISOString();
    }
    this.removeTask(next.id);
    if (next.cron) this.addPersistedTask(next);
    else this.addDelayedTask(next);
  }

  restorePersistedTasks(): void {
    const persisted = loadSchedules();
    for (const stored of persisted) {
      const manifest = { ...stored };
      try {
        this.validate(manifest);
        if (manifest.lastRun?.status === 'running') {
          manifest.lastRun = { ...manifest.lastRun, status: 'interrupted', finishedAt: new Date().toISOString(), error: 'Mercury stopped before this run was confirmed. Check its effects before resuming.' };
          manifest.paused = true;
        }
        if (manifest.cron) {
          this.addPersistedTask(manifest);
        } else {
          // Old schedules without executeAt cannot safely be inferred as pending.
          const overdue = !manifest.executeAt || Date.parse(manifest.executeAt) <= Date.now();
          if (!manifest.lastRun && overdue && (manifest.missedRunPolicy ?? 'skip') === 'skip') {
            manifest.lastRun = { id: randomUUID(), status: 'skipped', startedAt: new Date().toISOString(), finishedAt: new Date().toISOString(), error: 'Missed while Mercury was offline (policy: skip).' };
          }
          if (overdue && !manifest.lastRun) manifest.executeAt = new Date().toISOString();
          this.addDelayedTask(manifest);
        }
      } catch (err) {
        logger.warn({ err, id: manifest.id }, 'Skipping invalid task');
      }
    }
    if (persisted.length > 0) this.persistSchedules();
  }

  persistSchedules(): void {
    // Keep active work and all unresolved failures. Bound successful/skipped one-shot history.
    const finished = this.getManifests().filter((m) => !m.cron && m.lastRun && ['completed', 'skipped', 'dispatched'].includes(m.lastRun.status))
      .sort((a, b) => (b.lastRun!.finishedAt ?? '').localeCompare(a.lastRun!.finishedAt ?? ''));
    for (const manifest of finished.slice(MAX_FINISHED_ONESHOTS)) this.removeTask(manifest.id);
    saveSchedules(this.getManifests());
  }

  stopAll(): void {
    this.stopHeartbeat();
    for (const [, task] of this.tasks) {
      task.stop();
    }
    for (const [, timer] of this.delayedTasks) {
      clearTimeout(timer);
    }
    this.tasks.clear();
    this.delayedTasks.clear();
    this.taskManifests.clear();
  }
}