@johpaz/hive 1.1.0

package/packages/core/src/tools/cron.ts

@@ -0,0 +1,611 @@
+import type { Tool } from "../agent/native-tools.ts";
+import { Cron } from "croner";
+import type { Config } from "../config/loader.ts";
+import { logger } from "../utils/logger.ts";
+import { getDb } from "../storage/sqlite";
+import { getUserDate, getUserTime } from "../utils/date";
+
+export interface CronJob {
+  id: string;
+  userId: string;
+  name: string;
+  cronExpression: string;
+  taskType: string;
+  taskConfig: any;
+  notifyChannelId: string | null;
+  enabled: boolean;
+  maxRuns: number | null;
+  runCount: number;
+  expiresAt: number | null;
+  lastRun: number | null;
+  nextRun: number | null;
+  createdAt: number;
+}
+
+type TriggerFn = (
+  sessionId: string,
+  task: string,
+  jobId: string,
+  context: { fecha_usuario: string; hora_usuario: string }
+) => void;
+
+// ── Scheduler in-memory state ────────────────────────────────────────────────
+// One Croner instance per active job, keyed by jobId
+const activeJobs = new Map<string, Cron>();
+let globalOnTrigger: TriggerFn | undefined;
+let schedulerInitialized = false;
+
+const log = logger.child("cron");
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Computes the next UTC timestamp for a cron expression interpreted in the
+ * user's timezone.  All timestamps stored in DB are UTC (Unix seconds).
+ */
+function calculateNextRun(expression: string, timezone = "UTC"): number {
+  try {
+    const cron = new Cron(expression, { timezone });
+    const next = cron.nextRun();
+    if (next) return Math.floor(next.getTime() / 1000);
+  } catch (e) {
+    log.error(`calculateNextRun error: ${(e as Error).message}`);
+  }
+  // Fallback: 1 hour from now
+  return Math.floor(Date.now() / 1000) + 3600;
+}
+
+/**
+ * Formats a UTC timestamp as a human-readable local date-time string.
+ */
+function formatLocal(utcSeconds: number | null, timezone: string): string | null {
+  if (!utcSeconds) return null;
+  try {
+    return new Date(utcSeconds * 1000).toLocaleString("es", {
+      timeZone: timezone,
+      dateStyle: "full",
+      timeStyle: "short",
+    });
+  } catch {
+    return new Date(utcSeconds * 1000).toISOString();
+  }
+}
+
+/**
+ * Resolves the best notification channel for a user, applying the priority chain:
+ *  1. Explicit job-level notify_channel_id
+ *  2. User's preferred_cron_channel (if not 'auto')
+ *  3. AUTO: telegram (active) > discord (active) > webchat
+ */
+export function resolveBestChannel(userId: string, explicitChannelId?: string | null): string {
+  if (explicitChannelId) return explicitChannelId;
+
+  const db = getDb();
+
+  // Check user preference
+  const userRow = db.query<{ preferred_cron_channel: string }, [string]>(
+    "SELECT preferred_cron_channel FROM users WHERE id = ?"
+  ).get(userId);
+  const preference = userRow?.preferred_cron_channel ?? "auto";
+
+  if (preference !== "auto") {
+    // Verify the preferred channel is actually active before using it
+    const ch = db.query<{ id: string }, [string]>(
+      "SELECT id FROM channels WHERE id = ? AND active = 1"
+    ).get(preference);
+    if (ch) return preference;
+  }
+
+  // AUTO: pick best active channel by priority
+  const priority = ["telegram", "discord", "webchat"];
+  for (const channelId of priority) {
+    const ch = db.query<{ id: string }, [string]>(
+      "SELECT id FROM channels WHERE id = ? AND active = 1"
+    ).get(channelId);
+    if (ch) return channelId;
+  }
+
+  return "webchat";
+}
+
+/** Stops and removes a job from the active map. */
+function stopJob(jobId: string): void {
+  const existing = activeJobs.get(jobId);
+  if (existing) {
+    existing.stop();
+    activeJobs.delete(jobId);
+    log.debug(`Stopped cron job: ${jobId}`);
+  }
+}
+
+/**
+ * Schedules (or re-schedules) a job using a native Croner instance.
+ * The expression is interpreted in `userTimezone`; Croner fires at the
+ * exact wall-clock time in that timezone and converts to the correct UTC
+ * moment internally.
+ */
+function scheduleJob(
+  jobId: string,
+  name: string,
+  expression: string,
+  taskConfig: any,
+  userTimezone: string,
+  notifyChannelId: string | null
+): void {
+  // Replace any existing instance for this job
+  stopJob(jobId);
+
+  try {
+    const cron = new Cron(expression, { timezone: userTimezone }, () => {
+      const db = getDb();
+      const now = Math.floor(Date.now() / 1000);
+
+      // Reload job state to get fresh run_count / max_runs / expires_at
+      const job = db.query<any, [string]>(
+        "SELECT run_count, max_runs, expires_at FROM cron_jobs WHERE id = ?"
+      ).get(jobId);
+
+      if (!job) {
+        log.warn(`Cron job ${jobId} no longer exists, stopping`);
+        stopJob(jobId);
+        return;
+      }
+
+      // Check expiry
+      if (job.expires_at && now >= job.expires_at) {
+        log.info(`Cron job ${jobId} (${name}) expired — auto-disabling`);
+        db.query("UPDATE cron_jobs SET enabled = 0 WHERE id = ?").run(jobId);
+        stopJob(jobId);
+        return;
+      }
+
+      const newRunCount = (job.run_count ?? 0) + 1;
+      const nextRun = calculateNextRun(expression, userTimezone);
+
+      // Check max_runs BEFORE firing — auto-disable when limit reached
+      if (job.max_runs !== null && newRunCount > job.max_runs) {
+        log.info(`Cron job ${jobId} (${name}) reached max_runs=${job.max_runs} — auto-disabling`);
+        db.query("UPDATE cron_jobs SET enabled = 0 WHERE id = ?").run(jobId);
+        stopJob(jobId);
+        return;
+      }
+
+      // Update DB: last_run, next_run, run_count; auto-disable if this was the last run
+      const isLastRun = job.max_runs !== null && newRunCount >= job.max_runs;
+      db.query(
+        "UPDATE cron_jobs SET last_run = ?, next_run = ?, run_count = ?, enabled = ? WHERE id = ?"
+      ).run(now, nextRun, newRunCount, isLastRun ? 0 : 1, jobId);
+
+      if (isLastRun) {
+        log.info(`Cron job ${jobId} (${name}) completed all ${job.max_runs} run(s) — auto-disabling`);
+        stopJob(jobId);
+      }
+
+      log.info(`Cron triggered: ${jobId} — ${name} (run ${newRunCount}${job.max_runs ? `/${job.max_runs}` : ""})`, {
+        userTimezone,
+        localTime: getUserTime(userTimezone),
+        nextRun: new Date(nextRun * 1000).toISOString(),
+      });
+
+      const sessionId = taskConfig?.sessionId || jobId;
+
+      if (globalOnTrigger) {
+        globalOnTrigger(sessionId, name, jobId, {
+          fecha_usuario: getUserDate(userTimezone),
+          hora_usuario: getUserTime(userTimezone),
+        });
+      }
+    });
+
+    activeJobs.set(jobId, cron);
+
+    // Keep next_run in DB in sync with what Croner computed
+    const next = cron.nextRun();
+    if (next) {
+      getDb()
+        .query("UPDATE cron_jobs SET next_run = ? WHERE id = ?")
+        .run(Math.floor(next.getTime() / 1000), jobId);
+    }
+
+    log.debug(`Scheduled job "${name}" (${expression}) in ${userTimezone}`);
+  } catch (e) {
+    log.error(`Failed to schedule job ${jobId}: ${(e as Error).message}`);
+  }
+}
+
+// ── Public initializer ────────────────────────────────────────────────────────
+
+/**
+ * Called once at gateway startup.  Loads all enabled jobs from DB and creates
+ * a Croner instance for each one so they fire at the right moment.
+ */
+export function initCronScheduler(onTrigger: TriggerFn): void {
+  globalOnTrigger = onTrigger;
+  schedulerInitialized = true;
+
+  // Stop any leftover instances (hot-reload safety)
+  for (const cron of activeJobs.values()) cron.stop();
+  activeJobs.clear();
+
+  try {
+    const db = getDb();
+    const now = Math.floor(Date.now() / 1000);
+    const jobs = db.query<any, [number]>(`
+      SELECT c.*, u.timezone
+      FROM cron_jobs c
+      LEFT JOIN users u ON c.user_id = u.id
+      WHERE c.enabled = 1
+        AND (c.expires_at IS NULL OR c.expires_at > ?)
+        AND (c.max_runs IS NULL OR c.run_count < c.max_runs)
+    `).all(now);
+
+    for (const job of jobs) {
+      const tz = job.timezone || "UTC";
+      const taskConfig = job.task_config ? JSON.parse(job.task_config) : {};
+      scheduleJob(job.id, job.name, job.cron_expression, taskConfig, tz, job.notify_channel_id);
+    }
+
+    log.info(`Cron scheduler initialized — ${jobs.length} job(s) active`);
+  } catch (e) {
+    log.error(`initCronScheduler error: ${(e as Error).message}`);
+  }
+}
+
+// ── Tool factory ──────────────────────────────────────────────────────────────
+
+export function createCronTools(
+  _config: Config,
+  onTrigger?: TriggerFn
+): Tool[] {
+  if (onTrigger) globalOnTrigger = onTrigger;
+
+  // Boot scheduler only once — subsequent calls from tool resolution skip this
+  if (!schedulerInitialized) {
+    initCronScheduler(globalOnTrigger ?? (() => { }));
+  }
+
+  // ── cron_add ────────────────────────────────────────────────────────────────
+  const cronAdd: Tool = {
+    name: "cron_add",
+    description:
+      "Add a scheduled task. The cron expression is interpreted in the user's timezone; " +
+      "storage in DB is always UTC. Never ask the user for cron syntax — convert natural " +
+      "language to a 5-field expression yourself. " +
+      "The notification channel is auto-selected (prefers Telegram if active); " +
+      "pass notifyChannelId only if the user explicitly requests a specific channel.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Short name / description of the task" },
+        expression: {
+          type: "string",
+          description:
+            "5-field cron expression in user's LOCAL timezone. " +
+            "E.g. '0 9 * * *' = every day at 9 AM local time.",
+        },
+        taskType: {
+          type: "string",
+          enum: ["message", "agent", "custom"],
+          description: "Type of task",
+        },
+        taskMessage: {
+          type: "string",
+          description: "Message or instruction the agent should execute when the task fires",
+        },
+        notifyChannelId: {
+          type: "string",
+          description:
+            "Channel to notify (optional). Leave unset to auto-select best available channel " +
+            "(telegram > discord > webchat based on user preference).",
+        },
+        maxRuns: {
+          type: "number",
+          description:
+            "Maximum number of times this job should run. " +
+            "After reaching this count the job auto-disables. Omit for unlimited.",
+        },
+        expiresAt: {
+          type: "string",
+          description:
+            "ISO-8601 date/time after which the job auto-disables (e.g. '2024-12-31T23:59:00'). " +
+            "Interpreted in the user's timezone. Omit for no expiry.",
+        },
+      },
+      required: ["name", "expression"],
+    },
+    execute: async (params, config) => {
+      const name = params.name as string;
+      const expression = params.expression as string;
+      const taskType = (params.taskType as string) || "message";
+      const taskMessage = (params.taskMessage as string) || name;
+      const explicitChannelId = params.notifyChannelId as string | undefined;
+      const maxRuns = params.maxRuns != null ? Number(params.maxRuns) : null;
+
+      const db = getDb();
+      const userId = (config?.configurable?.user_id as string) || process.env.HIVE_USER_ID;
+      if (!userId) throw new Error("userId not found — complete onboarding first.");
+
+      const sessionId = (config?.configurable?.thread_id as string) || userId;
+
+      const userRow = db.query<any, [string]>("SELECT timezone FROM users WHERE id = ?").get(userId);
+      if (!userRow) throw new Error(`User ${userId} not found.`);
+      const userTimezone = userRow.timezone || "UTC";
+
+      // Parse expiresAt in user's timezone → UTC unix timestamp
+      let expiresAt: number | null = null;
+      if (params.expiresAt) {
+        try {
+          const d = new Date(params.expiresAt as string);
+          if (!isNaN(d.getTime())) expiresAt = Math.floor(d.getTime() / 1000);
+        } catch {
+          log.warn(`Invalid expiresAt value: ${params.expiresAt}`);
+        }
+      }
+
+      // Auto-resolve best notification channel
+      const notifyChannelId = resolveBestChannel(userId, explicitChannelId);
+
+      const now = Math.floor(Date.now() / 1000);
+      const taskConfig = { message: taskMessage, sessionId };
+      const nextRun = calculateNextRun(expression, userTimezone);
+
+      const row = db.query(`
+        INSERT INTO cron_jobs
+        (user_id, name, cron_expression, task_type, task_config,
+         notify_channel_id, enabled, max_runs, run_count, expires_at, last_run, next_run, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, 1, ?, 0, ?, NULL, ?, ?)
+        RETURNING id
+      `).get(
+        userId, name, expression, taskType, JSON.stringify(taskConfig),
+        notifyChannelId, maxRuns, expiresAt, nextRun, now
+      ) as { id: string };
+
+      const id = row.id;
+
+      scheduleJob(id, name, expression, taskConfig, userTimezone, notifyChannelId);
+
+      log.info(`Added cron job: ${id}`, { name, expression, userTimezone, sessionId, notifyChannelId });
+
+      return {
+        success: true,
+        jobId: id,
+        name,
+        expression,
+        notifyChannelId,
+        maxRuns: maxRuns ?? "unlimited",
+        expiresAt: expiresAt ? new Date(expiresAt * 1000).toISOString() : null,
+        nextRunUtc: new Date(nextRun * 1000).toISOString(),
+        nextRunLocal: formatLocal(nextRun, userTimezone),
+        timezone: userTimezone,
+      };
+    },
+  };
+
+  // ── cron_list ───────────────────────────────────────────────────────────────
+  const cronList: Tool = {
+    name: "cron_list",
+    description:
+      "List all scheduled tasks. Returns both UTC timestamps and local-time strings " +
+      "so you can display dates in the user's timezone without manual conversion.",
+    parameters: { type: "object", properties: {} },
+    execute: async (_params, config) => {
+      const db = getDb();
+      const userId = (config?.configurable?.user_id as string) || process.env.HIVE_USER_ID;
+      const userRow = userId
+        ? db.query<any, [string]>("SELECT timezone FROM users WHERE id = ?").get(userId)
+        : null;
+      const userTimezone = userRow?.timezone || "UTC";
+
+      const rows = db.query<any, []>(
+        "SELECT * FROM cron_jobs ORDER BY created_at DESC"
+      ).all();
+
+      const jobs = rows.map((row: any) => ({
+        id: row.id,
+        name: row.name,
+        expression: row.cron_expression,
+        taskType: row.task_type,
+        enabled: row.enabled === 1,
+        // UTC ISO — for programmatic use
+        nextRunUtc: row.next_run ? new Date(row.next_run * 1000).toISOString() : null,
+        lastRunUtc: row.last_run ? new Date(row.last_run * 1000).toISOString() : null,
+        // Local strings — display these to the user
+        nextRunLocal: formatLocal(row.next_run, userTimezone),
+        lastRunLocal: formatLocal(row.last_run, userTimezone),
+        timezone: userTimezone,
+        notifyChannelId: row.notify_channel_id,
+      }));
+
+      return { jobs, count: jobs.length, timezone: userTimezone };
+    },
+  };
+
+  // ── cron_remove ─────────────────────────────────────────────────────────────
+  const cronRemove: Tool = {
+    name: "cron_remove",
+    description: "Remove a scheduled task",
+    parameters: {
+      type: "object",
+      properties: {
+        jobId: { type: "string", description: "ID of the job to remove" },
+      },
+      required: ["jobId"],
+    },
+    execute: async (params) => {
+      const jobId = params.jobId as string;
+      const db = getDb();
+
+      const existing = db.query<any, [string]>(
+        "SELECT id FROM cron_jobs WHERE id = ?"
+      ).get(jobId);
+      if (!existing) throw new Error(`Job not found: ${jobId}`);
+
+      // Stop Croner instance first, then remove from DB
+      stopJob(jobId);
+      db.query("DELETE FROM cron_jobs WHERE id = ?").run(jobId);
+
+      log.info(`Removed cron job: ${jobId}`);
+      return { success: true, removedJob: jobId };
+    },
+  };
+
+  // ── cron_edit ───────────────────────────────────────────────────────────────
+  const cronEdit: Tool = {
+    name: "cron_edit",
+    description: "Edit a scheduled task (name, expression, enable/disable, channel, limits)",
+    parameters: {
+      type: "object",
+      properties: {
+        jobId: { type: "string", description: "ID of the job to edit" },
+        name: { type: "string", description: "New name" },
+        expression: {
+          type: "string",
+          description: "New cron expression (5-field, in user's local timezone)",
+        },
+        enabled: { type: "boolean", description: "Enable or disable the job" },
+        notifyChannelId: {
+          type: "string",
+          description: "New notification channel. Use 'auto' to re-apply auto-selection.",
+        },
+        maxRuns: {
+          type: "number",
+          description: "New max runs limit. Set to 0 to remove the limit.",
+        },
+        expiresAt: {
+          type: "string",
+          description: "New expiry date (ISO-8601). Set to '' to remove expiry.",
+        },
+      },
+      required: ["jobId"],
+    },
+    execute: async (params) => {
+      const jobId = params.jobId as string;
+      const db = getDb();
+
+      const existing = db.query<any, [string]>(
+        "SELECT * FROM cron_jobs WHERE id = ?"
+      ).get(jobId);
+      if (!existing) throw new Error(`Job not found: ${jobId}`);
+
+      const userRow = db.query<any, [string]>(
+        "SELECT timezone FROM users WHERE id = ?"
+      ).get(existing.user_id);
+      const userTimezone = userRow?.timezone || "UTC";
+
+      const sets: string[] = [];
+      const vals: any[] = [];
+
+      if (params.name) {
+        sets.push("name = ?");
+        vals.push(params.name);
+      }
+      if (params.expression) {
+        sets.push("cron_expression = ?");
+        vals.push(params.expression);
+        sets.push("next_run = ?");
+        vals.push(calculateNextRun(params.expression as string, userTimezone));
+      }
+      if (params.enabled !== undefined) {
+        sets.push("enabled = ?");
+        vals.push(params.enabled ? 1 : 0);
+      }
+      if (params.notifyChannelId !== undefined) {
+        const ch = params.notifyChannelId === "auto"
+          ? resolveBestChannel(existing.user_id)
+          : params.notifyChannelId as string;
+        sets.push("notify_channel_id = ?");
+        vals.push(ch);
+      }
+      if (params.maxRuns !== undefined) {
+        sets.push("max_runs = ?");
+        vals.push((params.maxRuns as number) === 0 ? null : Number(params.maxRuns));
+      }
+      if (params.expiresAt !== undefined) {
+        if (params.expiresAt === "") {
+          sets.push("expires_at = ?");
+          vals.push(null);
+        } else {
+          const d = new Date(params.expiresAt as string);
+          if (!isNaN(d.getTime())) {
+            sets.push("expires_at = ?");
+            vals.push(Math.floor(d.getTime() / 1000));
+          }
+        }
+      }
+
+      if (sets.length > 0) {
+        vals.push(jobId);
+        db.query(`UPDATE cron_jobs SET ${sets.join(", ")} WHERE id = ?`).run(...vals);
+      }
+
+      const updated = db.query<any, [string]>(
+        "SELECT * FROM cron_jobs WHERE id = ?"
+      ).get(jobId);
+
+      if (updated.enabled) {
+        const taskConfig = updated.task_config ? JSON.parse(updated.task_config) : {};
+        scheduleJob(
+          jobId, updated.name, updated.cron_expression,
+          taskConfig, userTimezone, updated.notify_channel_id
+        );
+      } else {
+        stopJob(jobId);
+      }
+
+      log.info(`Edited cron job: ${jobId}`);
+
+      return {
+        success: true,
+        job: {
+          id: updated.id,
+          name: updated.name,
+          expression: updated.cron_expression,
+          enabled: updated.enabled === 1,
+          notifyChannelId: updated.notify_channel_id,
+          maxRuns: updated.max_runs ?? "unlimited",
+          runCount: updated.run_count ?? 0,
+          expiresAt: updated.expires_at ? new Date(updated.expires_at * 1000).toISOString() : null,
+          nextRunUtc: updated.next_run ? new Date(updated.next_run * 1000).toISOString() : null,
+          nextRunLocal: formatLocal(updated.next_run, userTimezone),
+          timezone: userTimezone,
+        },
+      };
+    },
+  };
+
+  return [cronAdd, cronList, cronRemove, cronEdit];
+}
+
+// ── Query helpers (used externally) ──────────────────────────────────────────
+
+function rowToCronJob(row: any): CronJob {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    name: row.name,
+    cronExpression: row.cron_expression,
+    taskType: row.task_type,
+    taskConfig: row.task_config ? JSON.parse(row.task_config) : null,
+    notifyChannelId: row.notify_channel_id,
+    enabled: row.enabled === 1,
+    maxRuns: row.max_runs ?? null,
+    runCount: row.run_count ?? 0,
+    expiresAt: row.expires_at ?? null,
+    lastRun: row.last_run,
+    nextRun: row.next_run,
+    createdAt: row.created_at,
+  };
+}
+
+export function getCronJobById(jobId: string): CronJob | null {
+  const db = getDb();
+  const row = db.query<any, [string]>("SELECT * FROM cron_jobs WHERE id = ?").get(jobId);
+  if (!row) return null;
+  return rowToCronJob(row);
+}
+
+export function getCronJobsByUser(userId: string): CronJob[] {
+  const db = getDb();
+  const rows = db.query<any, [string]>("SELECT * FROM cron_jobs WHERE user_id = ?").all(userId);
+  return rows.map(rowToCronJob);
+}