PrimeTime

Scheduler

How @primetime/scheduler computes the next primer run time.

@primetime/scheduler computes when a primer should run from a user's work schedule:

import { computeNextPrimerRun, parseScheduleConfig } from "@primetime/scheduler";

const config = parseScheduleConfig({
  timeZone: "America/New_York",
  workStartTime: "09:00",
  // A small safety-margin buffer, independent of the provider's usage-window
  // length -- see usageWindowMinutes below.
  leadTimeMinutes: 30,
  activeWeekdays: ["monday", "tuesday", "wednesday", "thursday", "friday"],
});

// How long the provider's usage window stays warm after a primer -- see
// ProviderAdapter.usageWindowMinutes (@primetime/providers).
const usageWindowMinutes = 300;

computeNextPrimerRun(config, new Date(), usageWindowMinutes);

computeNextPrimerRun returns the next absolute instant, strictly after now, at which the provider's usage window needs re-warming: leadTimeMinutes before workStartTime local to timeZone for the day's first active stretch, plus additional rolling-refresh instants spaced usageWindowMinutes - leadTimeMinutes apart for a stretch longer than the usage window itself (and, if deadTimeWindows are configured, one instant per stretch that follows a gap like lunch or a meeting) -- on the next date whose local weekday is in activeWeekdays. It uses the JavaScript Intl API (no date library dependency) to convert local wall-clock time to UTC, so it accounts for daylight-saving transitions correctly on either side of the change. parseScheduleConfig validates an untrusted input object and throws a descriptive InvalidScheduleConfigError for anything malformed, rather than silently falling back to a default.

The CLI exposes this through primetime schedule next <config-path> <provider>, which reads a JSON file in the shape above, looks up that provider's usageWindowMinutes, and prints the next primer run as an ISO instant:

node apps/cli/dist/src/bin.js schedule next ./schedule.json claude-code
# Next primer run: 2024-01-16T13:30:00.000Z

It does not yet trigger prime itself on a schedule -- that still requires the GitHub Actions integration described in GitHub Actions setup.