@inceptionstack/roundhouse 0.2.2 → 0.3.1

package/src/cron/schedule.ts

@@ -0,0 +1,101 @@
+/**
+ * cron/schedule.ts — Schedule evaluation using croner
+ */
+
+import { Cron } from "croner";
+import { parseDuration, isDuration } from "./durations";
+import type { CronSchedule, CronJobConfig, CronJobState } from "./types";
+
+/** Validate a schedule config. Throws on invalid. */
+export function validateSchedule(schedule: CronSchedule): void {
+  switch (schedule.type) {
+    case "cron": {
+      try {
+        const c = new Cron(schedule.cron, { timezone: schedule.tz, paused: true });
+        c.stop();
+      } catch (err) {
+        throw new Error(`Invalid cron expression "${schedule.cron}": ${(err as Error).message}`);
+      }
+      // Validate timezone
+      try {
+        Intl.DateTimeFormat(undefined, { timeZone: schedule.tz });
+      } catch {
+        throw new Error(`Invalid timezone "${schedule.tz}"`);
+      }
+      break;
+    }
+    case "interval": {
+      parseDuration(schedule.every); // throws if invalid
+      break;
+    }
+    case "once": {
+      if (isDuration(schedule.at)) {
+        // relative — ok
+      } else {
+        const d = new Date(schedule.at);
+        if (isNaN(d.getTime())) throw new Error(`Invalid date: "${schedule.at}"`);
+      }
+      if (schedule.tz) {
+        try { Intl.DateTimeFormat(undefined, { timeZone: schedule.tz }); }
+        catch { throw new Error(`Invalid timezone "${schedule.tz}"`); }
+      }
+      break;
+    }
+    default:
+      throw new Error(`Unknown schedule type: ${(schedule as any).type}`);
+  }
+}
+
+/** Compute the next run time after `after` for a given schedule */
+export function computeNextRun(schedule: CronSchedule, after: Date): Date | null {
+  switch (schedule.type) {
+    case "cron": {
+      const c = new Cron(schedule.cron, { timezone: schedule.tz, paused: true });
+      const next = c.nextRun(after);
+      c.stop();
+      return next ?? null;
+    }
+    case "interval":
+      return null; // interval uses lastScheduledAt + every
+    case "once":
+      return null; // once uses absolute time
+    default:
+      return null;
+  }
+}
+
+/** Check if a job is due to run now */
+export function isDue(job: CronJobConfig, state: CronJobState, now: Date): Date | null {
+  if (!job.enabled) return null;
+
+  switch (job.schedule.type) {
+    case "cron": {
+      const lastRun = state.lastScheduledAt ? new Date(state.lastScheduledAt) : new Date(job.createdAt);
+      const c = new Cron(job.schedule.cron, { timezone: job.schedule.tz, paused: true });
+      const next = c.nextRun(lastRun);
+      c.stop();
+      if (next && next <= now) return next;
+      return null;
+    }
+    case "interval": {
+      const everyMs = parseDuration(job.schedule.every);
+      const lastRun = state.lastScheduledAt ? new Date(state.lastScheduledAt) : new Date(job.createdAt);
+      const nextTime = new Date(lastRun.getTime() + everyMs);
+      if (nextTime <= now) return nextTime;
+      return null;
+    }
+    case "once": {
+      if (state.totalRuns > 0) return null; // already ran
+      let targetTime: Date;
+      if (isDuration(job.schedule.at)) {
+        targetTime = new Date(new Date(job.createdAt).getTime() + parseDuration(job.schedule.at));
+      } else {
+        targetTime = new Date(job.schedule.at);
+      }
+      if (targetTime <= now) return targetTime;
+      return null;
+    }
+    default:
+      return null;
+  }
+}

package/src/cron/scheduler.ts

@@ -0,0 +1,295 @@
+/**
+ * cron/scheduler.ts — Internal cron scheduler
+ *
+ * Runs inside the gateway process. Ticks every 60s, checks for due jobs,
+ * executes them serially via p-queue (concurrency: 1).
+ */
+
+import PQueue from "p-queue";
+import { CronStore } from "./store";
+import { CronRunner } from "./runner";
+import { isDue } from "./schedule";
+import type { CronJobConfig, CronJobState } from "./types";
+import { isBuiltinJob, BUILTIN_HEARTBEAT_JOB_ID, HEARTBEAT_FILE_NAME } from "./helpers";
+import { TICK_MS, SHUTDOWN_TIMEOUT_MS, MAX_CATCHUP_ITERATIONS, HEARTBEAT_INTERVAL_MS, HEARTBEAT_DEFAULT_CONTENT } from "./constants";
+import { emptyState } from "./format";
+import type { GatewayConfig } from "../types";
+import { readFile } from "node:fs/promises";
+
+import { join } from "node:path";
+import { ROUNDHOUSE_DIR } from "../config";
+
+export interface CronSchedulerStatus {
+  running: boolean;
+  jobCount: number;
+  enabledCount: number;
+  queueSize: number;
+  queuePending: number;
+  activeJobId: string | null;
+}
+
+export class CronSchedulerService {
+  private store: CronStore;
+  private runner: CronRunner;
+  private queue: PQueue;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private jobs: CronJobConfig[] = [];
+  private states: Map<string, CronJobState> = new Map();
+  private activeJobId: string | null = null;
+  private queuedJobIds = new Set<string>(); // prevent duplicate queueing
+  private ticking = false; // prevent concurrent tick invocations
+  private lastHeartbeatAt = 0; // 0 = fires on first tick after startup (intentional catch-up)
+  private tickMs: number;
+
+  constructor(private opts?: { tickMs?: number; agentConfig?: GatewayConfig["agent"]; notifyChatIds?: number[] }) {
+    this.store = new CronStore();
+    this.runner = new CronRunner(this.store, this.opts?.agentConfig);
+    this.queue = new PQueue({ concurrency: 1 });
+    this.tickMs = this.opts?.tickMs ?? TICK_MS;
+  }
+
+  async start(): Promise<void> {
+    await this.store.ensureDirs();
+    await this.reload();
+    await this.catchUp();
+
+    this.timer = setInterval(() => void this.tick(), this.tickMs);
+    this.timer.unref();
+
+    console.log(`[cron] scheduler started (${this.jobs.filter((j) => j.enabled).length} enabled jobs, tick every ${this.tickMs / 1000}s)`);
+  }
+
+  async stop(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.queue.clear();
+    // Wait for active job with a timeout to prevent hanging shutdown
+    const idle = this.queue.onIdle();
+    const timeoutPromise = new Promise<void>((r) => {
+      const t = setTimeout(r, SHUTDOWN_TIMEOUT_MS);
+      if (t.unref) t.unref();
+    });
+    await Promise.race([idle, timeoutPromise]);
+    console.log("[cron] scheduler stopped");
+  }
+
+  getStatus(): CronSchedulerStatus {
+    return {
+      running: this.timer !== null,
+      jobCount: this.jobs.length,
+      enabledCount: this.jobs.filter((j) => j.enabled).length,
+      queueSize: this.queue.size,
+      queuePending: this.queue.pending,
+      activeJobId: this.activeJobId,
+    };
+  }
+
+  async listJobs(): Promise<Array<{ job: CronJobConfig; state: CronJobState }>> {
+    await this.reload();
+    return this.jobs.map((job) => ({
+      job,
+      state: this.states.get(job.id) ?? emptyState(job.id),
+    }));
+  }
+
+  async trigger(jobId: string): Promise<void> {
+    const job = this.jobs.find((j) => j.id === jobId) ?? await this.store.getJob(jobId);
+    if (!job) throw new Error(`Job not found: ${jobId}`);
+    this.enqueueJob(job, new Date(), "manual");
+  }
+
+  async pauseJob(jobId: string): Promise<void> {
+    const job = await this.store.getJob(jobId);
+    if (!job) throw new Error(`Job not found: ${jobId}`);
+    job.enabled = false;
+    job.updatedAt = new Date().toISOString();
+    await this.store.writeJob(job);
+    await this.reload();
+  }
+
+  async resumeJob(jobId: string): Promise<void> {
+    const job = await this.store.getJob(jobId);
+    if (!job) throw new Error(`Job not found: ${jobId}`);
+    job.enabled = true;
+    job.updatedAt = new Date().toISOString();
+    await this.store.writeJob(job);
+    await this.reload();
+  }
+
+  // ── Internal ─────────────────────────────────────
+
+  private enqueueJob(job: CronJobConfig, dueAt: Date, kind: "scheduled" | "manual"): void {
+    // Skip if already queued or running (prevent backlog for long-running jobs)
+    if (kind === "scheduled" && this.queuedJobIds.has(job.id)) {
+      console.log(`[cron] skipping ${job.id} — already queued or running`);
+      return;
+    }
+
+    this.queuedJobIds.add(job.id);
+
+    this.queue.add(async () => {
+      this.activeJobId = job.id;
+      try {
+        await this.runner.runJob(job, dueAt, kind);
+      } catch (err) {
+        console.error(`[cron] ${job.id} run failed:`, (err as Error).message);
+      } finally {
+        this.activeJobId = null;
+        if (isBuiltinJob(job.id)) this.lastHeartbeatAt = Date.now();
+        this.queuedJobIds.delete(job.id);
+      }
+    }).catch((err) => {
+      console.error(`[cron] ${job.id} queue error:`, (err as Error).message);
+      this.queuedJobIds.delete(job.id);
+    });
+  }
+
+  private async reload(): Promise<void> {
+    this.jobs = await this.store.listJobs();
+    // Always refresh state from disk (runner writes updated state after each run)
+    for (const job of this.jobs) {
+      this.states.set(job.id, await this.store.getState(job.id));
+    }
+  }
+
+  private async catchUp(): Promise<void> {
+    const now = new Date();
+    for (const job of this.jobs) {
+      if (!job.enabled) continue;
+      const catchUpMode = job.catchUp?.mode ?? "latest";
+      if (catchUpMode === "none") continue;
+
+      try {
+        const state = this.states.get(job.id)!;
+
+        // Fast-forward to latest due time (not first missed)
+        // Cap iterations to prevent blocking on high-frequency schedules after long downtime
+        let latestDue: Date | null = null;
+        let current = isDue(job, state, now);
+        let iterations = 0;
+        let prevIso = "";
+        while (current && iterations < MAX_CATCHUP_ITERATIONS) {
+          latestDue = current;
+          const currentIso = current.toISOString();
+          // Break if no forward progress (e.g. once jobs always return same time)
+          if (currentIso === prevIso) break;
+          prevIso = currentIso;
+          const tempState = { ...state, lastScheduledAt: currentIso };
+          current = isDue(job, tempState, now);
+          iterations++;
+        }
+
+        if (latestDue) {
+          console.log(`[cron] catch-up: ${job.id} fast-forwarded to ${latestDue.toISOString()}`);
+          state.lastScheduledAt = latestDue.toISOString();
+          await this.store.writeState(state);
+          this.enqueueJob(job, latestDue, "scheduled");
+        }
+      } catch (err) {
+        console.error(`[cron] catch-up failed for ${job.id}:`, (err as Error).message);
+      }
+    }
+  }
+
+  /** Read HEARTBEAT.md and check if it has real content */
+  private async readHeartbeat(): Promise<string | null> {
+    try {
+      const path = join(ROUNDHOUSE_DIR, HEARTBEAT_FILE_NAME);
+      const content = await readFile(path, "utf8");
+      const trimmed = content.trim();
+
+      // Skip if empty
+      if (!trimmed) return null;
+
+      // Skip if content matches the default template exactly
+      // Normalize line endings for cross-platform compatibility
+      if (trimmed.replace(/\r\n/g, "\n") === HEARTBEAT_DEFAULT_CONTENT) return null;
+
+      return trimmed;
+    } catch (err: any) {
+      if (err?.code !== "ENOENT") {
+        console.warn("[cron] failed to read HEARTBEAT.md:", err?.message);
+      }
+      return null;
+    }
+  }
+
+  /** Run heartbeat if due and HEARTBEAT.md has content */
+  private async checkHeartbeat(): Promise<void> {
+    const now = Date.now();
+    if (now - this.lastHeartbeatAt < HEARTBEAT_INTERVAL_MS) return;
+
+    const heartbeatContent = await this.readHeartbeat();
+    if (!heartbeatContent) return;
+
+    // Only advance timer when we actually have content to run.
+    // Also updated in enqueueJob's finally block after completion.
+    this.lastHeartbeatAt = now;
+
+    // Create a synthetic job config for the heartbeat
+    const heartbeatJob: CronJobConfig = {
+      id: BUILTIN_HEARTBEAT_JOB_ID,
+      enabled: true,
+      description: "Built-in heartbeat",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      schedule: { type: "interval", every: "30m" },
+      prompt: heartbeatContent,
+      notify: this.getHeartbeatNotifyConfig(),
+    };
+
+    this.enqueueJob(heartbeatJob, new Date(), "scheduled");
+  }
+
+  /** Get notify config for heartbeat from gateway config's notifyChatIds */
+  private getHeartbeatNotifyConfig(): CronJobConfig["notify"] {
+    const chatIds = this.opts?.notifyChatIds;
+    if (chatIds?.length) {
+      return { telegram: { chatIds, onlyOn: "always" } };
+    }
+    return undefined;
+  }
+
+  private async tick(): Promise<void> {
+    if (this.ticking) return; // prevent concurrent ticks
+    this.ticking = true;
+    try {
+      try {
+        await this.reload();
+      } catch (err) {
+        console.error("[cron] reload failed:", (err as Error).message);
+        return;
+      }
+
+      const now = new Date();
+
+      for (const job of this.jobs) {
+        if (!job.enabled) continue;
+
+        try {
+          const state = this.states.get(job.id)!;
+          const dueAt = isDue(job, state, now);
+          if (!dueAt) continue;
+
+          // Skip if already queued — don't write state that could race with the runner
+          if (this.queuedJobIds.has(job.id)) continue;
+
+          // Update lastScheduledAt to prevent re-queueing next tick
+          state.lastScheduledAt = dueAt.toISOString();
+          await this.store.writeState(state);
+
+          this.enqueueJob(job, dueAt, "scheduled");
+        } catch (err) {
+          console.error(`[cron] tick error for ${job.id}:`, (err as Error).message);
+        }
+      }
+
+      // Check heartbeat
+      await this.checkHeartbeat();
+    } finally {
+      this.ticking = false;
+    }
+  }
+}

package/src/cron/store.ts

@@ -0,0 +1,125 @@
+/**
+ * cron/store.ts — Read/write cron job configs, state, and run records
+ */
+
+import { readFile, writeFile, readdir, mkdir, unlink, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { CRON_JOBS_DIR, CRON_STATE_DIR, CRON_RUNS_DIR } from "../config";
+import type { CronJobConfig, CronJobState, CronRunRecord } from "./types";
+
+/** Atomic JSON write: write to temp file then rename. Cleans up on failure. */
+async function writeJsonAtomic(path: string, value: unknown, mode = 0o600): Promise<void> {
+  const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+  try {
+    await writeFile(tmp, JSON.stringify(value, null, 2) + "\n", { mode });
+    await rename(tmp, path);
+  } catch (err) {
+    try { await unlink(tmp); } catch {}
+    throw err;
+  }
+}
+
+const JOB_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+
+export function validateJobId(id: string): void {
+  if (!JOB_ID_RE.test(id)) {
+    throw new Error(`Invalid job ID "${id}". Use alphanumeric, dots, dashes, underscores (max 64 chars).`);
+  }
+}
+
+export function generateRunId(): string {
+  return `${new Date().toISOString().replace(/[:.]/g, "-")}_${randomBytes(3).toString("hex")}`;
+}
+
+export class CronStore {
+  async ensureDirs(): Promise<void> {
+    await mkdir(CRON_JOBS_DIR, { recursive: true });
+    await mkdir(CRON_STATE_DIR, { recursive: true });
+    await mkdir(CRON_RUNS_DIR, { recursive: true });
+  }
+
+  async listJobs(): Promise<CronJobConfig[]> {
+    try {
+      const files = await readdir(CRON_JOBS_DIR);
+      const jobs: CronJobConfig[] = [];
+      for (const f of files) {
+        if (!f.endsWith(".json")) continue;
+        try {
+          const raw = await readFile(join(CRON_JOBS_DIR, f), "utf8");
+          jobs.push(JSON.parse(raw));
+        } catch (err) {
+          console.warn(`[cron/store] failed to read job ${f}:`, (err as Error).message);
+        }
+      }
+      return jobs;
+    } catch {
+      return [];
+    }
+  }
+
+  async getJob(id: string): Promise<CronJobConfig | null> {
+    validateJobId(id);
+    try {
+      const raw = await readFile(join(CRON_JOBS_DIR, `${id}.json`), "utf8");
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  async writeJob(job: CronJobConfig): Promise<void> {
+    validateJobId(job.id);
+    await writeJsonAtomic(join(CRON_JOBS_DIR, `${job.id}.json`), job);
+  }
+
+  async deleteJob(id: string): Promise<void> {
+    validateJobId(id);
+    try { await unlink(join(CRON_JOBS_DIR, `${id}.json`)); } catch {}
+    try { await unlink(join(CRON_STATE_DIR, `${id}.json`)); } catch {}
+    try {
+      const { rm } = await import("node:fs/promises");
+      await rm(join(CRON_RUNS_DIR, id), { recursive: true });
+    } catch {}
+  }
+
+  async getState(id: string): Promise<CronJobState> {
+    validateJobId(id);
+    try {
+      const raw = await readFile(join(CRON_STATE_DIR, `${id}.json`), "utf8");
+      return JSON.parse(raw);
+    } catch {
+      const { emptyState } = await import("./format");
+      return emptyState(id);
+    }
+  }
+
+  async writeState(state: CronJobState): Promise<void> {
+    validateJobId(state.id);
+    await writeJsonAtomic(join(CRON_STATE_DIR, `${state.id}.json`), state);
+  }
+
+  async appendRun(record: CronRunRecord): Promise<void> {
+    validateJobId(record.jobId);
+    const dir = join(CRON_RUNS_DIR, record.jobId);
+    await mkdir(dir, { recursive: true });
+    await writeJsonAtomic(join(dir, `${record.id}.json`), record);
+  }
+
+  async listRuns(jobId: string, limit = 10): Promise<CronRunRecord[]> {
+    validateJobId(jobId);
+    const dir = join(CRON_RUNS_DIR, jobId);
+    try {
+      const files = (await readdir(dir)).filter((f) => f.endsWith(".json")).sort().reverse().slice(0, limit);
+      const runs: CronRunRecord[] = [];
+      for (const f of files) {
+        try {
+          runs.push(JSON.parse(await readFile(join(dir, f), "utf8")));
+        } catch {}
+      }
+      return runs;
+    } catch {
+      return [];
+    }
+  }
+}

package/src/cron/template.ts

@@ -0,0 +1,89 @@
+/**
+ * cron/template.ts — Simple {{variable}} template renderer
+ *
+ * No JS eval. Unknown variables throw at validation time.
+ */
+
+import { hostname } from "node:os";
+
+export interface TemplateContext {
+  job: { id: string; description?: string };
+  run: { id: string; scheduledAt: string; startedAt: string };
+  date: { iso: string; local: string; localTime: string };
+  timezone?: string;
+  hostname: string;
+  cwd: string;
+  vars: Record<string, string>;
+}
+
+/** Extract all {{path.to.value}} references from a template */
+export function extractTemplateVars(text: string): string[] {
+  const matches = text.matchAll(/\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/g);
+  return [...matches].map((m) => m[1]);
+}
+
+/** Validate that all template variables can be resolved */
+export function validateTemplate(text: string, allowedVars?: Set<string>): string[] {
+  const vars = extractTemplateVars(text);
+  const builtins = new Set([
+    "job.id", "job.description",
+    "run.id", "run.scheduledAt", "run.startedAt",
+    "date.iso", "date.local", "date.localTime",
+    "timezone", "hostname", "cwd",
+  ]);
+  const errors: string[] = [];
+  for (const v of vars) {
+    if (builtins.has(v)) continue;
+    if (v.startsWith("vars.") && allowedVars?.has(v.slice(5))) continue;
+    if (v.startsWith("vars.")) {
+      errors.push(`Unknown variable: {{${v}}} — define it in job.vars`);
+    } else {
+      errors.push(`Unknown variable: {{${v}}}`);
+    }
+  }
+  return errors;
+}
+
+/** Render a template with the given context */
+export function renderTemplate(text: string, ctx: TemplateContext): string {
+  return text.replace(/\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/g, (_match, path: string) => {
+    const parts = path.split(".");
+    let value: unknown = ctx;
+    for (const part of parts) {
+      if (value == null || typeof value !== "object") return "";
+      value = (value as Record<string, unknown>)[part];
+    }
+    return value != null ? String(value) : "";
+  });
+}
+
+/** Build a TemplateContext for a cron run */
+export function buildTemplateContext(
+  jobId: string,
+  jobDescription: string | undefined,
+  runId: string,
+  scheduledAt: Date,
+  startedAt: Date,
+  tz: string | undefined,
+  cwd: string,
+  vars: Record<string, string>,
+): TemplateContext {
+  const now = startedAt;
+  return {
+    job: { id: jobId, description: jobDescription },
+    run: {
+      id: runId,
+      scheduledAt: scheduledAt.toISOString(),
+      startedAt: startedAt.toISOString(),
+    },
+    date: {
+      iso: now.toISOString(),
+      local: now.toLocaleDateString("en-CA", { timeZone: tz || undefined }), // YYYY-MM-DD in job timezone
+      localTime: now.toLocaleTimeString("en-GB", { hour12: false, timeZone: tz || undefined }),
+    },
+    timezone: tz,
+    hostname: hostname(),
+    cwd,
+    vars,
+  };
+}

package/src/cron/types.ts

@@ -0,0 +1,76 @@
+/**
+ * cron/types.ts — Cron job types
+ */
+
+// ── Schedule ─────────────────────────────────────────
+
+export type CronSchedule =
+  | { type: "cron"; cron: string; tz: string }
+  | { type: "interval"; every: string }
+  | { type: "once"; at: string; tz?: string };
+
+// ── Job config (persisted as JSON) ───────────────────
+
+export interface CronJobConfig {
+  id: string;
+  enabled: boolean;
+  description?: string;
+  createdAt: string;
+  updatedAt: string;
+
+  schedule: CronSchedule;
+
+  /** Prompt template with {{variable}} placeholders */
+  prompt: string;
+  /** Custom variables available in template */
+  vars?: Record<string, string>;
+
+  /** Timeout for agent run (default 30min) */
+  timeoutMs?: number;
+
+  /** Catch-up behavior after gateway restart */
+  catchUp?: { mode: "latest" | "none"; };
+
+  /** Notification targets */
+  notify?: {
+    telegram?: {
+      chatIds: (string | number)[];
+      onlyOn?: "always" | "success" | "failure";
+    };
+  };
+}
+
+// ── Job state (mutable, persisted separately) ────────
+
+export interface CronJobState {
+  id: string;
+  lastScheduledAt?: string;
+  lastStartedAt?: string;
+  lastFinishedAt?: string;
+  lastSuccessAt?: string;
+  lastFailureAt?: string;
+  lastRunId?: string;
+  lastError?: string;
+  totalRuns: number;
+  totalSuccesses: number;
+  totalFailures: number;
+}
+
+// ── Run record ───────────────────────────────────────
+
+export type CronRunStatus = "completed" | "failed" | "timeout" | "abandoned";
+
+export interface CronRunRecord {
+  id: string;
+  jobId: string;
+  kind: "scheduled" | "manual";
+  status: CronRunStatus;
+  scheduledAt: string;
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  threadId: string;
+  prompt: string;
+  responseText?: string;
+  error?: string;
+}