index.ts

// Cron — scheduled agent tasks. Stores jobs in ~/.deepcode/cron.json and matches
// 5-field cron expressions. The CronCreate/CronList/CronDelete tools CRUD the
// store; a separate `deepcode scheduler run` (CLI) executes due jobs.
// Spec: docs/DEVELOPMENT_PLAN.md §3.15.4 / §0.1 (CronCreate family)

import { promises as fs } from 'node:fs';
import type { TriggerProfile } from './profile.js';
import {
  isTriggerDue,
  resolveTrigger,
  type TriggerSource,
  type TriggerVerdict,
} from './triggers.js';
import { homedir } from 'node:os';
import { dirname, join } from 'node:path';

/**
 * What an unattended run does when a tool call resolves to `ask`.
 *
 * `deny` (default, and the pre-existing behaviour) refuses that one call and
 * lets the run continue. `abort` stops the whole run instead — the right choice
 * when a half-executed job is worse than no job, since a denied first call
 * otherwise leaves the agent looping against a wall while it burns tokens.
 */
export type UnattendedApprovalPolicy = 'deny' | 'abort';

export interface CronJob {
  id: string;
  /**
   * 5-field cron expression: "min hour day-of-month month day-of-week".
   *
   * Still the source when `trigger` is absent, which is every job written
   * before triggers existed. Kept rather than migrated: a store nobody has to
   * rewrite is a store that cannot be rewritten wrongly.
   */
  schedule: string;
  /**
   * Where this job's events come from. Absent means the `schedule` above.
   */
  trigger?: TriggerSource;
  /** Prompt to run headlessly when the job fires. */
  prompt: string;
  /** Working directory to run in. */
  cwd: string;
  createdAt: string;
  lastRunAt?: string;
  enabled: boolean;
  /**
   * Unattended approval policy for this job. Absent on jobs created before this
   * field existed, which is why every read goes through
   * `resolveUnattendedApproval` instead of touching the field directly.
   */
  onApprovalRequired?: UnattendedApprovalPolicy;
  /**
   * Permission posture for this job, independent of the interactive settings it
   * would otherwise inherit. Absent means "use the ambient settings, clamped" —
   * see `resolveTriggerMode`.
   */
  profile?: TriggerProfile;
}

/** The effective policy for a job, defaulting to the historical `deny`. */
export function resolveUnattendedApproval(
  job: Pick<CronJob, 'onApprovalRequired'>,
): UnattendedApprovalPolicy {
  return job.onApprovalRequired === 'abort' ? 'abort' : 'deny';
}

export interface CronStore {
  jobs: CronJob[];
}

export function cronStorePath(home: string = homedir()): string {
  return join(home, '.deepcode', 'cron.json');
}

export async function loadCronStore(home: string = homedir()): Promise<CronStore> {
  try {
    const raw = await fs.readFile(cronStorePath(home), 'utf8');
    const parsed = JSON.parse(raw) as CronStore;
    return { jobs: Array.isArray(parsed.jobs) ? parsed.jobs : [] };
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { jobs: [] };
    throw err;
  }
}

export async function saveCronStore(store: CronStore, home: string = homedir()): Promise<void> {
  const path = cronStorePath(home);
  await fs.mkdir(dirname(path), { recursive: true });
  await fs.writeFile(path, JSON.stringify(store, null, 2) + '\n', 'utf8');
}

let cronSeq = 0;
function newCronId(): string {
  return `cron-${Date.now().toString(36)}-${(cronSeq++).toString(36)}`;
}

export async function addCronJob(
  job: {
    schedule: string;
    prompt: string;
    cwd: string;
    onApprovalRequired?: UnattendedApprovalPolicy;
    profile?: TriggerProfile;
  },
  home: string = homedir(),
): Promise<CronJob> {
  const invalid = validateCronExpr(job.schedule);
  if (invalid) throw new Error(invalid);
  const store = await loadCronStore(home);
  const created: CronJob = {
    id: newCronId(),
    schedule: job.schedule.trim(),
    prompt: job.prompt,
    cwd: job.cwd,
    createdAt: new Date().toISOString(),
    enabled: true,
    ...(job.onApprovalRequired ? { onApprovalRequired: job.onApprovalRequired } : {}),
    ...(job.profile ? { profile: job.profile } : {}),
  };
  store.jobs.push(created);
  await saveCronStore(store, home);
  return created;
}

export async function removeCronJob(id: string, home: string = homedir()): Promise<boolean> {
  const store = await loadCronStore(home);
  const before = store.jobs.length;
  store.jobs = store.jobs.filter((j) => j.id !== id);
  if (store.jobs.length === before) return false;
  await saveCronStore(store, home);
  return true;
}

export async function listCronJobs(home: string = homedir()): Promise<CronJob[]> {
  return (await loadCronStore(home)).jobs;
}

// ── Cron expression matching ────────────────────────────────────────────
// 5 fields: minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-6, 0=Sun).
// Each supports: *  a  a-b  a,b,c  */n  a-b/n

const FIELD_RANGES: Array<[number, number]> = [
  [0, 59],
  [0, 23],
  [1, 31],
  [1, 12],
  [0, 6],
];

/** Returns an error message if `expr` is not a valid 5-field cron, else null. */
export function validateCronExpr(expr: string): string | null {
  const fields = expr.trim().split(/\s+/);
  if (fields.length !== 5) {
    return `cron expression must have 5 fields (got ${fields.length}): "${expr}"`;
  }
  for (let i = 0; i < 5; i++) {
    try {
      matchField(fields[i]!, FIELD_RANGES[i]![0], FIELD_RANGES[i]![1], FIELD_RANGES[i]![0]);
    } catch (err) {
      return `invalid cron field "${fields[i]}": ${(err as Error).message}`;
    }
  }
  return null;
}

/** Whether a single field matches `value` within [min,max]. Throws on bad syntax. */
function matchField(field: string, min: number, max: number, value: number): boolean {
  return field.split(',').some((part) => {
    let step = 1;
    let range = part;
    const slash = part.indexOf('/');
    if (slash !== -1) {
      step = Number(part.slice(slash + 1));
      range = part.slice(0, slash);
      if (!Number.isInteger(step) || step <= 0) throw new Error(`bad step "${part}"`);
    }
    let lo = min;
    let hi = max;
    if (range !== '*') {
      const dash = range.indexOf('-');
      if (dash !== -1) {
        lo = Number(range.slice(0, dash));
        hi = Number(range.slice(dash + 1));
      } else {
        lo = hi = Number(range);
      }
      if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo < min || hi > max || lo > hi) {
        throw new Error(`out of range [${min}-${max}]`);
      }
    }
    if (value < lo || value > hi) return false;
    return (value - lo) % step === 0;
  });
}

/** Is `date` a firing time for `schedule`? (minute granularity.) */
export function isCronDue(schedule: string, date: Date): boolean {
  const fields = schedule.trim().split(/\s+/);
  if (fields.length !== 5) return false;
  const values = [
    date.getMinutes(),
    date.getHours(),
    date.getDate(),
    date.getMonth() + 1,
    date.getDay(),
  ];
  try {
    for (let i = 0; i < 5; i++) {
      if (!matchField(fields[i]!, FIELD_RANGES[i]![0], FIELD_RANGES[i]![1], values[i]!)) {
        return false;
      }
    }
  } catch {
    return false;
  }
  return true;
}

/**
 * Enabled jobs due to run at `now`.
 *
 * Synchronous and cron-only. Kept because it is the shape every existing caller
 * and test uses, and because a clock trigger needs nothing but the clock — but
 * a job with a non-cron trigger is not decidable here, so it is skipped rather
 * than guessed at. Use `dueJobsWithTriggers` to evaluate all of them.
 */
export function dueJobs(jobs: CronJob[], now: Date): CronJob[] {
  return jobs.filter(
    (j) => j.enabled && resolveTrigger(j).kind === 'cron' && isCronDue(j.schedule, now),
  );
}

export interface DueJob {
  job: CronJob;
  verdict: TriggerVerdict;
}

/**
 * Every enabled job whose trigger has fired, whatever kind it is.
 *
 * Async because a calendar has to be read and a watched file has to be stat'd.
 * Diagnostics ride along on the verdict so the scheduler can log "this
 * calendar has an RRULE I cannot express" next to the job it belongs to,
 * instead of on nobody's behalf.
 */
export async function dueJobsWithTriggers(jobs: CronJob[], now: Date): Promise<DueJob[]> {
  const out: DueJob[] = [];
  for (const job of jobs) {
    if (!job.enabled) continue;
    const verdict = await isTriggerDue(
      resolveTrigger(job),
      { now, cwd: job.cwd, lastRunAt: job.lastRunAt },
      isCronDue,
    );
    if (verdict.due) out.push({ job, verdict });
  }
  return out;
}

export {
  describeTrigger,
  isTriggerDue,
  resolveTrigger,
  validateTrigger,
  type TriggerContext,
  type TriggerSource,
  type TriggerVerdict,
} from './triggers.js';

export {
  matchingEvents,
  occursAt,
  parseIcs,
  type IcsCalendar,
  type IcsEvent,
  type IcsRecurrence,
} from './ics.js';

export {
  describeClamp,
  resolveTriggerMode,
  tightenPermissions,
  tightenSandbox,
  type ResolvedTriggerMode,
  type TriggerProfile,
} from './profile.js';