@sentry/junior-scheduler 0.107.1 → 0.108.0

package/src/schedule-intent.ts

@@ -0,0 +1,372 @@
+/**
+ * Owns model-facing schedule intent and materializes it against the trusted
+ * server clock into the canonical schedule persisted by the scheduler.
+ */
+import { z } from "zod";
+import {
+  getFirstRunAtMs,
+  getZonedDateTimeParts,
+  resolveLocalScheduleAtMs,
+} from "./cadence";
+import type {
+  ScheduledLocalTime,
+  ScheduledTaskRecurrence,
+  ScheduledTaskSchedule,
+} from "./types";
+
+const localDateSchema = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/, "Use a local date in YYYY-MM-DD format.");
+const localTimeSchema = z
+  .string()
+  .regex(/^([01]\d|2[0-3]):[0-5]\d$/, "Use local time in HH:MM format.");
+const timezoneSchema = z
+  .string()
+  .min(1)
+  .max(80)
+  .describe(
+    "IANA timezone, for example America/Los_Angeles. Omit or use null for the scheduler default.",
+  )
+  .nullable()
+  .optional();
+const weekdaySchema = z.enum([
+  "sunday",
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday",
+]);
+
+const oneOffScheduleIntentSchema = z
+  .object({
+    kind: z.literal("one_off").describe("A schedule that runs once."),
+    timezone: timezoneSchema,
+    timing: z
+      .discriminatedUnion("type", [
+        z
+          .object({
+            type: z
+              .literal("after")
+              .describe("Run after a relative delay from the server clock."),
+            value: z.number().int().positive().max(100_000),
+            unit: z.enum(["second", "minute", "hour", "day", "week"]),
+          })
+          .strict(),
+        z
+          .object({
+            type: z
+              .literal("at")
+              .describe("Run at an explicit local calendar date and time."),
+            date: localDateSchema.describe(
+              "Requested local calendar date in YYYY-MM-DD format.",
+            ),
+            time: localTimeSchema.describe(
+              "Requested local wall-clock time in HH:MM format.",
+            ),
+          })
+          .strict(),
+      ])
+      .describe("Relative delay or explicit local time for the one-off run."),
+  })
+  .strict();
+
+const recurringScheduleIntentSchema = z
+  .object({
+    kind: z.literal("recurring").describe("A repeating calendar schedule."),
+    frequency: z
+      .enum(["daily", "weekly", "monthly", "yearly"])
+      .describe("Recurring tasks can run at most once per day."),
+    interval: z
+      .number()
+      .int()
+      .positive()
+      .max(365)
+      .describe("Repeat every N frequency units. Defaults to 1.")
+      .nullable()
+      .optional(),
+    time: localTimeSchema.describe(
+      "Local wall-clock time for each occurrence in HH:MM format.",
+    ),
+    weekdays: z
+      .array(weekdaySchema)
+      .min(1)
+      .max(7)
+      .describe("Required for weekly schedules.")
+      .nullable()
+      .optional(),
+    day_of_month: z
+      .number()
+      .int()
+      .min(1)
+      .max(31)
+      .describe("Required for monthly and yearly schedules.")
+      .nullable()
+      .optional(),
+    month: z
+      .number()
+      .int()
+      .min(1)
+      .max(12)
+      .describe("Required for yearly schedules, where January is 1.")
+      .nullable()
+      .optional(),
+    start_date: localDateSchema
+      .describe(
+        "Optional local calendar date that anchors the recurrence. Omit to start with the next matching occurrence.",
+      )
+      .nullable()
+      .optional(),
+    timezone: timezoneSchema,
+  })
+  .strict()
+  .superRefine((schedule, context) => {
+    if (schedule.frequency === "weekly" && schedule.weekdays == null) {
+      context.addIssue({
+        code: "custom",
+        message: "Weekly schedules require weekdays.",
+        path: ["weekdays"],
+      });
+    }
+    if (
+      (schedule.frequency === "monthly" || schedule.frequency === "yearly") &&
+      schedule.day_of_month == null
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: `${schedule.frequency} schedules require day_of_month.`,
+        path: ["day_of_month"],
+      });
+    }
+    if (schedule.frequency === "yearly" && schedule.month == null) {
+      context.addIssue({
+        code: "custom",
+        message: "Yearly schedules require month.",
+        path: ["month"],
+      });
+    }
+    if (schedule.frequency !== "weekly" && schedule.weekdays != null) {
+      context.addIssue({
+        code: "custom",
+        message: "weekdays applies only to weekly schedules.",
+        path: ["weekdays"],
+      });
+    }
+    if (
+      schedule.frequency !== "monthly" &&
+      schedule.frequency !== "yearly" &&
+      schedule.day_of_month != null
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "day_of_month applies only to monthly or yearly schedules.",
+        path: ["day_of_month"],
+      });
+    }
+    if (schedule.frequency !== "yearly" && schedule.month != null) {
+      context.addIssue({
+        code: "custom",
+        message: "month applies only to yearly schedules.",
+        path: ["month"],
+      });
+    }
+  });
+
+export const scheduleIntentSchema = z.union([
+  oneOffScheduleIntentSchema,
+  recurringScheduleIntentSchema,
+]);
+export type ScheduleIntent = z.infer<typeof scheduleIntentSchema>;
+
+const WEEKDAY_INDEX = {
+  sunday: 0,
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6,
+} as const;
+
+const DURATION_MS = {
+  second: 1000,
+  minute: 60 * 1000,
+  hour: 60 * 60 * 1000,
+  day: 24 * 60 * 60 * 1000,
+  week: 7 * 24 * 60 * 60 * 1000,
+} as const;
+
+function parseLocalTime(value: string): ScheduledLocalTime {
+  const [hour, minute] = value.split(":").map(Number);
+  return { hour: hour!, minute: minute! };
+}
+
+function localDateAt(timestampMs: number, timezone: string): string {
+  const parts = getZonedDateTimeParts(timestampMs, timezone);
+  return [parts.year, parts.month, parts.day]
+    .map((value, index) =>
+      index === 0
+        ? String(value).padStart(4, "0")
+        : String(value).padStart(2, "0"),
+    )
+    .join("-");
+}
+
+function isValidTimeZone(timezone: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function plural(value: number, unit: string): string {
+  return value === 1 ? unit : `${unit}s`;
+}
+
+function formatWeekdays(weekdays: readonly string[]): string {
+  const labels = weekdays.map(
+    (weekday) => `${weekday[0]!.toUpperCase()}${weekday.slice(1)}`,
+  );
+  if (labels.length < 2) {
+    return labels[0] ?? "";
+  }
+  return `${labels.slice(0, -1).join(", ")} and ${labels.at(-1)}`;
+}
+
+function recurringDescription(
+  schedule: z.infer<typeof recurringScheduleIntentSchema>,
+  timezone: string,
+): string {
+  const interval = schedule.interval ?? 1;
+  const cadenceUnit = {
+    daily: "day",
+    weekly: "week",
+    monthly: "month",
+    yearly: "year",
+  }[schedule.frequency];
+  const cadence = interval === 1 ? cadenceUnit : `${interval} ${cadenceUnit}s`;
+  let detail = "";
+  if (schedule.frequency === "weekly") {
+    detail = ` on ${formatWeekdays(schedule.weekdays!)}`;
+  } else if (schedule.frequency === "monthly") {
+    detail = ` on day ${schedule.day_of_month}`;
+  } else if (schedule.frequency === "yearly") {
+    detail = ` on ${String(schedule.month).padStart(2, "0")}-${String(
+      schedule.day_of_month,
+    ).padStart(2, "0")}`;
+  }
+  return `Every ${cadence}${detail} at ${schedule.time} (${timezone})`;
+}
+
+export interface CompiledScheduleIntent {
+  nextRunAtMs: number;
+  schedule: ScheduledTaskSchedule;
+}
+
+export class ScheduleIntentError extends Error {}
+
+/** Materialize model-interpreted schedule intent against the trusted server clock. */
+export function compileScheduleIntent(args: {
+  defaultTimezone: string;
+  intent: ScheduleIntent;
+  nowMs: number;
+}): CompiledScheduleIntent {
+  const timezone = args.intent.timezone ?? args.defaultTimezone;
+  if (!isValidTimeZone(timezone)) {
+    throw new ScheduleIntentError("timezone must be a valid IANA time zone.");
+  }
+
+  if (args.intent.kind === "one_off") {
+    if (args.intent.timing.type === "after") {
+      const nextRunAtMs =
+        args.nowMs +
+        args.intent.timing.value * DURATION_MS[args.intent.timing.unit];
+      return {
+        nextRunAtMs,
+        schedule: {
+          description: `In ${args.intent.timing.value} ${plural(
+            args.intent.timing.value,
+            args.intent.timing.unit,
+          )}`,
+          kind: "one_off",
+          timezone,
+        },
+      };
+    }
+
+    const nextRunAtMs = resolveLocalScheduleAtMs({
+      date: args.intent.timing.date,
+      time: parseLocalTime(args.intent.timing.time),
+      timezone,
+    });
+    if (nextRunAtMs === undefined) {
+      throw new ScheduleIntentError(
+        "The requested local date or time does not exist in that timezone.",
+      );
+    }
+    if (nextRunAtMs <= args.nowMs) {
+      throw new ScheduleIntentError(
+        "The requested one-off schedule must be in the future.",
+      );
+    }
+    return {
+      nextRunAtMs,
+      schedule: {
+        description: `Once on ${args.intent.timing.date} at ${args.intent.timing.time} (${timezone})`,
+        kind: "one_off",
+        timezone,
+      },
+    };
+  }
+
+  const recurrence: ScheduledTaskRecurrence = {
+    frequency: args.intent.frequency,
+    interval: args.intent.interval ?? 1,
+    startDate: args.intent.start_date ?? localDateAt(args.nowMs, timezone),
+    time: parseLocalTime(args.intent.time),
+    ...(args.intent.frequency === "weekly"
+      ? {
+          weekdays: [
+            ...new Set(
+              args.intent.weekdays!.map((weekday) => WEEKDAY_INDEX[weekday]),
+            ),
+          ].sort((left, right) => left - right),
+        }
+      : {}),
+    ...(args.intent.frequency === "monthly" ||
+    args.intent.frequency === "yearly"
+      ? { dayOfMonth: args.intent.day_of_month ?? undefined }
+      : {}),
+    ...(args.intent.frequency === "yearly"
+      ? { month: args.intent.month ?? undefined }
+      : {}),
+  };
+  const searchRecurrence = args.intent.start_date
+    ? recurrence
+    : { ...recurrence, interval: 1 };
+  const nextRunAtMs = getFirstRunAtMs({
+    afterMs: args.nowMs,
+    recurrence: searchRecurrence,
+    timezone,
+  });
+  if (nextRunAtMs === undefined) {
+    throw new ScheduleIntentError(
+      "The recurring schedule has no valid future occurrence.",
+    );
+  }
+  const materializedRecurrence = args.intent.start_date
+    ? recurrence
+    : { ...recurrence, startDate: localDateAt(nextRunAtMs, timezone) };
+  return {
+    nextRunAtMs,
+    schedule: {
+      description: recurringDescription(args.intent, timezone),
+      kind: "recurring",
+      recurrence: materializedRecurrence,
+      timezone,
+    },
+  };
+}

package/src/store.ts

@@ -148,6 +148,7 @@ const runRecordSchema = z
 
 export interface SchedulerStore {
   claimDueRun(args: { nowMs: number }): Promise<ScheduledRun | undefined>;
+  createTask(task: ScheduledTask): Promise<ScheduledTask>;
   getRun(runId: string): Promise<ScheduledRun | undefined>;
   getTask(taskId: string): Promise<ScheduledTask | undefined>;
   listIncompleteRuns(): Promise<ScheduledRun[]>;
@@ -236,6 +237,13 @@ function unique(values: string[]): string[] {
   return [...new Set(values.filter(Boolean))];
 }
 
+const schedulerTaskIndexSchema = z.array(z.string().min(1));
+
+/** Parse the persisted scheduler task index without repairing malformed state. */
+function parseStringIndex(value: unknown): string[] {
+  return value === undefined ? [] : schedulerTaskIndexSchema.parse(value);
+}
+
 async function withLock<T>(
   state: PluginState,
   key: string,
@@ -250,9 +258,7 @@ async function addToIndex(
   taskId: string,
 ): Promise<void> {
   await withLock(state, indexLockKey(key), async () => {
-    const current = ((await state.get<string[]>(key)) ?? []).filter(
-      (value): value is string => typeof value === "string",
-    );
+    const current = unique(parseStringIndex(await state.get(key)));
     await state.set(key, unique([...current, taskId]), SCHEDULER_RECORD_TTL_MS);
   });
 }
@@ -263,11 +269,7 @@ async function removeFromIndex(
   taskId: string,
 ): Promise<void> {
   await withLock(state, indexLockKey(key), async () => {
-    const current = unique(
-      ((await state.get<string[]>(key)) ?? []).filter(
-        (value): value is string => typeof value === "string",
-      ),
-    );
+    const current = unique(parseStringIndex(await state.get(key)));
     const next = current.filter((value) => value !== taskId);
     if (next.length === current.length) {
       return;
@@ -284,10 +286,7 @@ async function getIndex(
   state: PluginReadState,
   key: string,
 ): Promise<string[]> {
-  const values = (await state.get<string[]>(key)) ?? [];
-  return unique(
-    values.filter((value): value is string => typeof value === "string"),
-  );
+  return unique(parseStringIndex(await state.get(key)));
 }
 
 async function clearActiveRun(
@@ -634,6 +633,18 @@ class PluginStateSchedulerStore implements SchedulerStore {
     this.state = state;
   }
 
+  async createTask(task: ScheduledTask): Promise<ScheduledTask> {
+    const next = requireStoredTask(task);
+    return await withLock(this.state, taskLockKey(task.id), async () => {
+      const current = await getTaskFromState(this.state, task.id);
+      if (current) {
+        return current;
+      }
+      await this.saveTaskRecord(next, undefined);
+      return next;
+    });
+  }
+
   async saveTask(task: ScheduledTask): Promise<void> {
     const next = requireStoredTask(task);
     await withLock(this.state, taskLockKey(task.id), async () => {
@@ -1255,6 +1266,18 @@ async function listIncompleteRunsForTasksFromSql(
 class SqlSchedulerStore implements SchedulerStore, SchedulerOperationalStore {
   constructor(private readonly db: SchedulerDb) {}
 
+  async createTask(task: ScheduledTask): Promise<ScheduledTask> {
+    const next = requireStoredTask(task);
+    return await withSqlLock(this.db, taskLockKey(task.id), async (db) => {
+      const current = await getTaskFromSql(db, task.id);
+      if (current) {
+        return current;
+      }
+      await this.saveTaskRecord(db, next, undefined);
+      return next;
+    });
+  }
+
   async saveTask(task: ScheduledTask): Promise<void> {
     const next = requireStoredTask(task);
     await withSqlLock(this.db, taskLockKey(task.id), async (db) => {

package/src/tool-support.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import {
   PluginToolInputError,
   pluginToolResultSchema,
@@ -8,20 +8,18 @@ import {
   type SlackSource,
 } from "@sentry/junior-plugin-api";
 import { z } from "zod";
-import { buildCalendarRecurrence, parseScheduleTimestamp } from "./cadence";
 import { sanitizeScheduledTaskPrincipal } from "./identity";
 import { type SchedulerStore } from "./store";
 import type {
-  ScheduledCalendarFrequency,
   ScheduledTask,
   ScheduledTaskConversationAccess,
   ScheduledTaskPrincipal,
-  ScheduledTaskRecurrence,
   ScheduledTaskStatus,
 } from "./types";
 
 export interface SchedulerToolContext {
   actor?: SlackActor;
+  now?: () => number;
   source?: SlackSource;
   store: SchedulerStore;
   userText?: string;
@@ -277,9 +275,29 @@ export function scheduleListToolResult(args: {
   } as const;
 }
 
-/** Prefix generated scheduler ids so tool results are distinguishable from provider ids. */
-export function buildTaskId(): string {
-  return `${TASK_ID_PREFIX}_${randomUUID()}`;
+/** Build a retry-stable scheduler id scoped to the creating actor and destination. */
+export function buildTaskId(args: {
+  actor: ScheduledTaskPrincipal;
+  destination: SlackDestination;
+  toolCallId: string | undefined;
+}): string {
+  const toolCallId = args.toolCallId?.trim();
+  if (!toolCallId) {
+    throw new Error("Scheduler task creation requires a tool-call identity.");
+  }
+  const digest = createHash("sha256")
+    .update(
+      JSON.stringify({
+        actor: args.actor.slackUserId,
+        channel: args.destination.channelId,
+        operation: toolCallId,
+        platform: args.destination.platform,
+        team: args.destination.teamId,
+      }),
+    )
+    .digest("hex")
+    .slice(0, 32);
+  return `${TASK_ID_PREFIX}_${digest}`;
 }
 
 /** Keep concrete scheduler tools coupled to the injected store, not global state. */
@@ -297,143 +315,7 @@ export function normalizeStatus(
   return undefined;
 }
 
-function normalizeFrequency(
-  value: unknown,
-): ScheduledCalendarFrequency | undefined {
-  if (
-    value === "daily" ||
-    value === "weekly" ||
-    value === "monthly" ||
-    value === "yearly"
-  ) {
-    return value;
-  }
-  return undefined;
-}
-
-/** Rebuild recurrence only from validated daily-or-slower schedule requests. */
-export function buildRecurrence(args: {
-  existing?: ScheduledTaskRecurrence;
-  input: {
-    recurrence?: unknown;
-  };
-  nextRunAtMs: number | undefined;
-  timezone: string;
-}): ScheduledTaskRecurrence | undefined {
-  if (args.input.recurrence === null) {
-    return undefined;
-  }
-
-  const frequency =
-    normalizeFrequency(args.input.recurrence) ?? args.existing?.frequency;
-  if (!frequency) {
-    return undefined;
-  }
-  if (!args.nextRunAtMs) {
-    throwToolInputError("Recurring scheduled tasks require next_run_at.");
-  }
-
-  try {
-    return buildCalendarRecurrence({
-      frequency,
-      interval: args.existing?.interval,
-      nextRunAtMs: args.nextRunAtMs,
-      timezone: args.timezone,
-      weekdays: frequency === "weekly" ? args.existing?.weekdays : undefined,
-    });
-  } catch (error) {
-    throwToolInputError(
-      error instanceof RangeError
-        ? "timezone must be a valid IANA time zone."
-        : error instanceof Error
-          ? error.message
-          : String(error),
-    );
-  }
-}
-
-/** Reject recurrence values that would exceed the scheduler cadence policy. */
-export function validateRecurringFrequencyLimit(input: {
-  recurrence?: unknown;
-}) {
-  if (
-    input.recurrence !== undefined &&
-    input.recurrence !== null &&
-    !normalizeFrequency(input.recurrence)
-  ) {
-    throwToolInputError(
-      "Recurring scheduled tasks can run at most once per day.",
-    );
-  }
-}
-
-/** Force create-tool callers to explicitly choose one-off versus recurring semantics. */
-export function validateCreateScheduleKind(input: {
-  recurrence?: unknown;
-  schedule_kind?: unknown;
-}) {
-  if (input.schedule_kind === undefined) {
-    throwToolInputError("Provide schedule_kind as one_off or recurring.");
-  }
-  if (
-    input.schedule_kind !== "one_off" &&
-    input.schedule_kind !== "recurring"
-  ) {
-    throwToolInputError("schedule_kind must be one_off or recurring.");
-  }
-  if (
-    input.schedule_kind === "one_off" &&
-    input.recurrence !== undefined &&
-    input.recurrence !== null
-  ) {
-    throwToolInputError("Omit recurrence when schedule_kind is one_off.");
-  }
-  if (
-    input.schedule_kind === "recurring" &&
-    (input.recurrence === undefined || input.recurrence === null)
-  ) {
-    throwToolInputError("Provide recurrence when schedule_kind is recurring.");
-  }
-}
-
-/** Detect update inputs that affect calendar recurrence materialization. */
-export function shouldRebuildRecurrence(input: {
-  next_run_at?: string;
-  recurrence?: unknown;
-  timezone?: string;
-}): boolean {
-  return (
-    input.next_run_at !== undefined ||
-    input.recurrence !== undefined ||
-    input.timezone !== undefined
-  );
-}
-
 /** Centralize scheduler timezone defaulting for all concrete tool entry points. */
 export function getDefaultScheduleTimezone(): string {
   return process.env.JUNIOR_TIMEZONE?.trim() || DEFAULT_SCHEDULE_TIMEZONE;
 }
-
-/** Validate IANA timezone names before persisting scheduler cadence state. */
-export function isValidTimeZone(timezone: string): boolean {
-  try {
-    new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format();
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** Parse model-supplied timestamps without leaking date parser details to tools. */
-export function parseNextRunAtMs(
-  nextRunAtIso: string | undefined,
-): number | undefined {
-  try {
-    if (nextRunAtIso) {
-      return parseScheduleTimestamp(nextRunAtIso);
-    }
-  } catch {
-    return undefined;
-  }
-  return undefined;
-}