Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

8.5 KB
Raw Blame
/** Dependency-free task scheduling constants shared by registry and runtime modules. */

import { QUOTA_BURN_REQUEST_ORIGIN } from '../lib/quotaBurnOrigin.js';
import { isCronShaped } from '../lib/cronValidation.js';

const MINUTE_MS = 60 * 1000;
const HOUR_MS = 60 * MINUTE_MS;
const DAY_MS = 24 * HOUR_MS;

/**
 * The cadence model is exactly two variants. `perpetual` is an ORTHOGONAL
 * boolean on the same record, not a type — so a task can be on-demand+perpetual
 * (manual start when autoStart is false, otherwise drain whenever unparked) or cron+perpetual (a cron slot INITIATES a drain,
 * and the same expression gates the next attempt once it parks).
 */
export const INTERVAL_TYPES = {
  ON_DEMAND: 'on-demand',
  CRON: 'cron'
};

/**
 * Retired cadence types. Kept for the legacy decoder below (and migration 335)
 * so a schedule written by an older install — or by a peer machine still on the
 * previous release — normalizes instead of falling through as "unknown".
 */
export const LEGACY_INTERVAL_TYPES = {
  ROTATION: 'rotation',
  DAILY: 'daily',
  WEEKLY: 'weekly',
  ONCE: 'once',
  CUSTOM: 'custom',
  PERPETUAL: 'perpetual'
};

/** Conservative daily/weekly replacements for the retired named cadences. */
export const DEFAULT_DAILY_CRON = '0 7 * * *';
export const DEFAULT_WEEKLY_CRON = '0 7 * * 1';

export const WEEK = 7 * DAY_MS;
export const DEFAULT_PERPETUAL_RECHECK_MS = DAY_MS;
export const FAILURE_BACKOFF_BASE_MS = HOUR_MS;
export const FAILURE_BACKOFF_CAP_MS = DAY_MS;
export const FAILURE_PARK_THRESHOLD = 5;
/**
 * Who asked for an on-demand run.
 *
 *   USER       — a human pressed Run. The only origin that clears the drain's
 *                brakes (park, convergence signature, dispatch counter) and the
 *                only one written to the operator-action ledger.
 *   REFILL     — the perpetual drain re-issuing ITSELF through the same lane.
 *   QUOTA_BURN — a quota-burn step invoking a task the user already owns
 *                (`quotaBurnInvoke.js`). Automated, so it clears no brakes; it
 *                carries a `burn` provenance block (`lib/quotaBurnOrigin.js`)
 *                naming the family and step, and it is subject to the SAME
 *                invocation-eligibility gate a human Run faces.
 *
 * A request written before `origin` existed carries none, which reads as USER.
 */
export const ON_DEMAND_ORIGINS = { USER: 'user', REFILL: 'refill', QUOTA_BURN: QUOTA_BURN_REQUEST_ORIGIN, GITHUB_NOTIFICATION: 'github-notification' };
export const isRefillRequest = (request) => request?.origin === ON_DEMAND_ORIGINS.REFILL;
/**
 * Whether a human asked for this run. Absent origin reads as USER (see above),
 * so this is NOT `!isRefillRequest` — every automated origin added later fails
 * CLOSED into "not a human" instead of silently inheriting a human's brakes.
 */
export const isUserOriginRequest = (request) =>
  (request?.origin ?? ON_DEMAND_ORIGINS.USER) === ON_DEMAND_ORIGINS.USER;
const RECONCILE_DRAIN_TASK_TYPES = new Set(['branch-reconcile', 'issue-reconcile']);
export const isReconcileDrainTaskType = (taskType) => RECONCILE_DRAIN_TASK_TYPES.has(taskType);

/**
 * A 5-field cron expression (the only string cadence the scheduler accepts).
 * SHAPE only — it distinguishes a cron from a named cadence and says nothing
 * about validity; `isValidCronExpression` is what save boundaries gate on.
 */
export const isCronExpression = isCronShaped;

/**
 * Approximate a numeric interval as a 5-field cron expression. Used by the
 * `custom` → `cron` conversion (migration + runtime normalization) and by the
 * Layered Intelligence per-app cadence picker, which offers sub-daily slots the
 * named cadences never expressed.
 */
export function cronFromIntervalMs(intervalMs) {
  const ms = Number(intervalMs);
  if (!Number.isFinite(ms) || ms <= 0) return DEFAULT_DAILY_CRON;
  if (ms === WEEK) return DEFAULT_WEEKLY_CRON;
  if (ms >= DAY_MS) return DEFAULT_DAILY_CRON;
  if (ms >= HOUR_MS) {
    const hours = Math.round(ms / HOUR_MS);
    if (hours <= 1) return '0 * * * *';
    // Only an even divisor of 24 lays out evenly across a day; anything else
    // would fire twice around midnight, so clamp to the nearest usable step.
    const step = [2, 3, 4, 6, 8, 12].find((h) => h >= hours) || 12;
    return `0 */${step} * * *`;
  }
  const minutes = Math.min(59, Math.max(1, Math.round(ms / MINUTE_MS)));
  return `*/${minutes} * * * *`;
}

/** Every cadence value the system has ever accepted as a type name. */
export const isKnownIntervalType = (value) =>
  Object.values(INTERVAL_TYPES).includes(value) || Object.values(LEGACY_INTERVAL_TYPES).includes(value);

/**
 * Decode ANY historical cadence value into the two-variant model.
 *
 * Accepts a legacy type name, a raw cron expression, or a current type, and
 * returns `{ type, cronExpression, perpetual }` — `cronExpression` is null when
 * the decoded type is on-demand. `intervalMs` feeds the `custom` conversion.
 * Unknown/absent values decode to on-demand (never auto-running), which is the
 * safe default for a cadence we cannot read.
 */
export function decodeIntervalType(value, { intervalMs = null } = {}) {
  if (isCronExpression(value)) {
    return { type: INTERVAL_TYPES.CRON, cronExpression: value.trim(), perpetual: false };
  }
  switch (value) {
    case INTERVAL_TYPES.CRON:
      return { type: INTERVAL_TYPES.CRON, cronExpression: null, perpetual: false };
    case LEGACY_INTERVAL_TYPES.DAILY:
    case LEGACY_INTERVAL_TYPES.ROTATION:
      return { type: INTERVAL_TYPES.CRON, cronExpression: DEFAULT_DAILY_CRON, perpetual: false };
    case LEGACY_INTERVAL_TYPES.WEEKLY:
      return { type: INTERVAL_TYPES.CRON, cronExpression: DEFAULT_WEEKLY_CRON, perpetual: false };
    case LEGACY_INTERVAL_TYPES.CUSTOM:
      return { type: INTERVAL_TYPES.CRON, cronExpression: cronFromIntervalMs(intervalMs), perpetual: false };
    case LEGACY_INTERVAL_TYPES.PERPETUAL:
      return { type: INTERVAL_TYPES.ON_DEMAND, cronExpression: null, perpetual: true };
    default:
      // 'once', 'on-demand', and anything unrecognized.
      return { type: INTERVAL_TYPES.ON_DEMAND, cronExpression: null, perpetual: false };
  }
}

/**
 * Normalize a persisted task config IN PLACE onto the two-variant model.
 * Returns true when something changed, so callers (loadSchedule, the migration)
 * can decide whether the normalized shape needs persisting.
 *
 * A `perpetual: true` already on the record is preserved — the flag is
 * orthogonal, so it survives whatever the type decodes to.
 */
export function normalizeIntervalConfig(config) {
  if (!config || typeof config !== 'object') return false;
  const decoded = decodeIntervalType(config.type, { intervalMs: config.intervalMs });
  const perpetual = config.perpetual === true || decoded.perpetual;
  // Keep an already-valid cron expression; only supply one when the decode had
  // to invent the cadence (a retired named type) or the stored one is unusable.
  const cronExpression = decoded.type === INTERVAL_TYPES.CRON
    ? (isCronExpression(config.cronExpression) ? config.cronExpression.trim() : decoded.cronExpression)
    : null;

  let changed = false;
  if (config.type !== decoded.type) { config.type = decoded.type; changed = true; }
  if (config.perpetual !== perpetual) { config.perpetual = perpetual; changed = true; }
  if ((config.cronExpression ?? null) !== (cronExpression ?? null)) {
    config.cronExpression = cronExpression;
    changed = true;
  }
  return changed;
}

/**
 * Resolve the cadence ONE app actually runs a task on.
 *
 * An app's `taskTypeOverrides[taskType].interval` outranks the task's global
 * cadence — including the case that reads as a contradiction: a task left
 * `on-demand` globally while one app pins a cron expression. That app IS
 * clock-scheduled, and anything reading only the global row (the Schedule
 * card, the Schedule Timeline) would otherwise call it "manual trigger only".
 *
 * `inherited: true` means the app stated no cadence of its own and simply runs
 * the global one, so callers surfacing "schedules you cannot see from the
 * global row" skip it. Enablement is NOT checked here — a disabled app is the
 * caller's own rung (`shouldRunTask` answers 'disabled-for-app').
 */
export function resolveAppOverrideCadence(override, interval = {}) {
  const decoded = override?.interval
    ? decodeIntervalType(override.interval, { intervalMs: override.intervalMs ?? null })
    : null;
  return decoded
    ? { type: decoded.type, cronExpression: decoded.cronExpression, inherited: false }
    : { type: interval.type, cronExpression: interval.cronExpression || null, inherited: true };
}