@sentry/junior-scheduler 0.107.1 → 0.109.0

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;
-}

package/src/tools/create-task.ts

@@ -1,23 +1,24 @@
 import { definePluginTool } from "@sentry/junior-plugin-api";
 import { z } from "zod";
+import {
+  compileScheduleIntent,
+  ScheduleIntentError,
+  scheduleIntentSchema,
+} from "../schedule-intent";
 import { SCHEDULED_TASK_SYSTEM_ACTOR } from "../types";
 import type { ScheduledTask } from "../types";
 import {
-  buildRecurrence,
   buildTaskId,
   compactTask,
   getConversationAccess,
   getDefaultScheduleTimezone,
-  isValidTimeZone,
-  parseNextRunAtMs,
   requireActiveConversation,
   requireActor,
+  sameDestination,
   scheduleTaskToolResult,
   scheduleTaskToolResultSchema,
   schedulerStore,
   throwToolInputError,
-  validateCreateScheduleKind,
-  validateRecurringFrequencyLimit,
   type SchedulerToolContext,
 } from "../tool-support";
 
@@ -27,74 +28,69 @@ export function createSlackScheduleCreateTaskTool(
 ) {
   return definePluginTool({
     description:
-      "Create a one-time or recurring Junior task in the active Slack conversation. For one-time reminders or one-time scheduled work, omit recurrence entirely; never choose a default recurrence. Use only when the user explicitly asks Junior to do work later or on a recurring cadence. Do not create scheduled polling tasks to watch provider resources when a subscribable tool result can deliver the requested events. Only manage tasks for the active Slack DM or channel; never target threads, other channels, or another user's DM. Set credential_mode to creator only when the current user explicitly authorizes future scheduled use of their connected credentials. If connected-credential use is needed but authorization is ambiguous, ask before creating the task. Otherwise omit credential_mode and use system credentials. When the task, schedule, destination, and credential mode are clear, create it without another confirmation.",
+      "Create a one-time or recurring Junior task in the active Slack conversation when the user asks Junior to do work later or repeatedly.",
     executionMode: "sequential",
-    inputSchema: z.object({
-      task: z.string().min(1).max(4000),
-      schedule: z.string().min(1).max(300),
-      schedule_kind: z
-        .enum(["one_off", "recurring"])
-        .describe(
-          "Required schedule classification. Use one_off for one-time reminders or one-time scheduled work. Use recurring only when the user explicitly asks for a repeating schedule.",
+    inputSchema: z
+      .object({
+        task: z.string().min(1).max(4000),
+        schedule: scheduleIntentSchema.describe(
+          "When the task runs. The scheduler computes the exact next run from this intent and the server clock.",
         ),
-      timezone: z
-        .string()
-        .min(1)
-        .max(80)
-        .describe(
-          "IANA timezone, e.g. 'America/Los_Angeles'. Defaults to the channel's configured timezone.",
-        )
-        .optional(),
-      next_run_at: z
-        .string()
-        .min(1)
-        .describe(
-          "Exact next run time as an ISO timestamp, computed from the user's requested schedule.",
-        )
-        .optional(),
-      recurrence: z
-        .enum(["daily", "weekly", "monthly", "yearly"])
-        .nullable()
-        .describe(
-          "Required when schedule_kind is recurring. Omit when schedule_kind is one_off. Recurring tasks run at most once per day: use daily, weekly, monthly, or yearly only.",
-        )
-        .optional(),
-      credential_mode: z
-        .enum(["system", "creator"])
-        .nullable()
-        .describe(
-          "Use creator only when the current user explicitly authorizes future scheduled use of their connected credentials. Omit or use system otherwise.",
-        )
-        .optional(),
-    }),
+        credential_mode: z
+          .enum(["system", "creator"])
+          .nullable()
+          .describe(
+            "Use creator only when the current user explicitly authorizes future scheduled use of their connected credentials. Omit or use system otherwise.",
+          )
+          .optional(),
+      })
+      .strict(),
     outputSchema: scheduleTaskToolResultSchema,
-    execute: async (input) => {
+    execute: async (input, options) => {
       const destination = requireActiveConversation(context);
       const actor = requireActor(context, destination);
-
-      const nowMs = Date.now();
-      const timezone = input.timezone ?? getDefaultScheduleTimezone();
-      validateCreateScheduleKind(input);
-      validateRecurringFrequencyLimit(input);
-      if (!isValidTimeZone(timezone)) {
-        throwToolInputError("timezone must be a valid IANA time zone.");
+      const store = schedulerStore(context);
+      const id = buildTaskId({
+        actor,
+        destination,
+        toolCallId: options.toolCallId,
+      });
+      // Replaying a durable tool call returns its original task instead of duplicating it.
+      const existing = await store.getTask(id);
+      if (existing) {
+        if (
+          !sameDestination(existing, destination) ||
+          existing.createdBy.slackUserId !== actor.slackUserId
+        ) {
+          throwToolInputError("Scheduled task operation identity is invalid.");
+        }
+        return scheduleTaskToolResult(
+          "slackScheduleCreateTask",
+          compactTask(existing),
+        );
       }
-      const nextRunAtMs = parseNextRunAtMs(input.next_run_at);
-      if (!nextRunAtMs) {
-        throwToolInputError("Provide next_run_at as a valid ISO timestamp.");
+
+      const nowMs = context.now?.() ?? Date.now();
+      let compiled;
+      try {
+        compiled = compileScheduleIntent({
+          defaultTimezone: getDefaultScheduleTimezone(),
+          intent: input.schedule,
+          nowMs,
+        });
+      } catch (error) {
+        if (error instanceof ScheduleIntentError) {
+          throwToolInputError(error.message);
+        }
+        throw error;
       }
-      const recurrence = buildRecurrence({
-        input,
-        nextRunAtMs,
-        timezone,
-      });
       const conversationAccess = getConversationAccess(
         destination,
         context.source,
       );
 
       const task: ScheduledTask = {
-        id: buildTaskId(),
+        id,
         createdAtMs: nowMs,
         updatedAtMs: nowMs,
         createdBy: actor,
@@ -102,24 +98,25 @@ export function createSlackScheduleCreateTaskTool(
         credentialMode: input.credential_mode ?? "system",
         destination,
         executionActor: SCHEDULED_TASK_SYSTEM_ACTOR,
-        nextRunAtMs,
+        nextRunAtMs: compiled.nextRunAtMs,
         originalRequest: context.userText,
-        schedule: {
-          description: input.schedule,
-          timezone,
-          kind: recurrence ? "recurring" : "one_off",
-          recurrence,
-        },
+        schedule: compiled.schedule,
         status: "active",
         task: {
           text: input.task,
         },
       };
 
-      await schedulerStore(context).saveTask(task);
+      const committed = await store.createTask(task);
+      if (
+        !sameDestination(committed, destination) ||
+        committed.createdBy.slackUserId !== actor.slackUserId
+      ) {
+        throwToolInputError("Scheduled task operation identity is invalid.");
+      }
       return scheduleTaskToolResult(
         "slackScheduleCreateTask",
-        compactTask(task),
+        compactTask(committed),
       );
     },
   });

package/src/tools/update-task.ts

@@ -1,20 +1,21 @@
 import { definePluginTool } from "@sentry/junior-plugin-api";
 import { z } from "zod";
+import {
+  compileScheduleIntent,
+  ScheduleIntentError,
+  scheduleIntentSchema,
+} from "../schedule-intent";
 import type { ScheduledTask } from "../types";
 import {
-  buildRecurrence,
   compactTask,
+  getDefaultScheduleTimezone,
   getWritableTask,
-  isValidTimeZone,
   normalizeStatus,
-  parseNextRunAtMs,
   requireActor,
   scheduleTaskToolResult,
   scheduleTaskToolResultSchema,
   schedulerStore,
-  shouldRebuildRecurrence,
   throwToolInputError,
-  validateRecurringFrequencyLimit,
   type SchedulerToolContext,
 } from "../tool-support";
 
@@ -24,44 +25,38 @@ export function createSlackScheduleUpdateTaskTool(
 ) {
   return definePluginTool({
     description:
-      "Edit, pause, resume, reschedule, or change credential use for an existing Junior scheduled task in the active Slack conversation. Use only task IDs returned for this conversation. Do not move scheduled tasks across conversations. Set credential_mode to creator only when the task creator explicitly authorizes future scheduled use of their connected credentials. If creator credential use is requested but authorization is ambiguous, ask before enabling it. If another user changes the executable task text, creator credential use is cleared automatically.",
+      "Edit, pause, resume, reschedule, or change credential use for an existing Junior scheduled task in the active Slack conversation.",
     executionMode: "sequential",
-    inputSchema: z.object({
-      task_id: z
-        .string()
-        .min(1)
-        .describe(
-          "ID of the task to update. Must be from this active Slack conversation.",
-        ),
-      task: z.string().min(1).max(4000).optional(),
-      schedule: z.string().min(1).max(300).optional(),
-      timezone: z.string().min(1).max(80).optional(),
-      next_run_at: z
-        .string()
-        .min(1)
-        .describe("Exact ISO timestamp when changing the next run time.")
-        .optional(),
-      recurrence: z
-        .enum(["daily", "weekly", "monthly", "yearly"])
-        .nullable()
-        .describe(
-          "Provide only for repeating schedules. Omit for one-time requests. Set to null to convert a recurring task to one-time.",
-        )
-        .optional(),
-      status: z
-        .enum(["active", "paused", "blocked"])
-        .describe(
-          "Set to active, paused, or blocked to resume, pause, or block the task.",
-        )
-        .optional(),
-      credential_mode: z
-        .enum(["system", "creator"])
-        .nullable()
-        .describe(
-          "Set creator only when the current actor is the task creator and explicitly authorizes future scheduled credential use. Set system to disable delegation.",
-        )
-        .optional(),
-    }),
+    inputSchema: z
+      .object({
+        task_id: z
+          .string()
+          .min(1)
+          .describe(
+            "ID of the task to update. Must be from this active Slack conversation.",
+          ),
+        task: z.string().min(1).max(4000).optional(),
+        schedule: scheduleIntentSchema
+          .describe(
+            "Complete replacement schedule when rescheduling. Omit for task, status, or credential-only changes; the scheduler computes the next run.",
+          )
+          .nullable()
+          .optional(),
+        status: z
+          .enum(["active", "paused", "blocked"])
+          .describe(
+            "Set to active, paused, or blocked to resume, pause, or block the task.",
+          )
+          .optional(),
+        credential_mode: z
+          .enum(["system", "creator"])
+          .nullable()
+          .describe(
+            "Set creator only when the current actor is the task creator and explicitly authorizes future scheduled credential use. Set system to disable delegation.",
+          )
+          .optional(),
+      })
+      .strict(),
     outputSchema: scheduleTaskToolResultSchema,
     execute: async (input) => {
       const lookup = await getWritableTask({
@@ -76,18 +71,24 @@ export function createSlackScheduleUpdateTaskTool(
         );
       }
 
-      const timezone = input.timezone ?? lookup.schedule.timezone;
-      validateRecurringFrequencyLimit(input);
-      if (!isValidTimeZone(timezone)) {
-        throwToolInputError("timezone must be a valid IANA time zone.");
-      }
-      const parsedNextRunAtMs = parseNextRunAtMs(input.next_run_at);
-      const nextRunAtMs = input.next_run_at
-        ? parsedNextRunAtMs
-        : lookup.nextRunAtMs;
-      if (input.next_run_at && !nextRunAtMs) {
-        throwToolInputError("Provide next_run_at as a valid ISO timestamp.");
+      const nowMs = context.now?.() ?? Date.now();
+      let compiled;
+      if (input.schedule) {
+        try {
+          compiled = compileScheduleIntent({
+            defaultTimezone:
+              lookup.schedule.timezone || getDefaultScheduleTimezone(),
+            intent: input.schedule,
+            nowMs,
+          });
+        } catch (error) {
+          if (error instanceof ScheduleIntentError) {
+            throwToolInputError(error.message);
+          }
+          throw error;
+        }
       }
+      const nextRunAtMs = compiled?.nextRunAtMs ?? lookup.nextRunAtMs;
 
       const status = normalizeStatus(input.status);
       if (input.status && !status) {
@@ -95,17 +96,9 @@ export function createSlackScheduleUpdateTaskTool(
       }
       if (status === "active" && !nextRunAtMs) {
         throwToolInputError(
-          "Active scheduled tasks require next_run_at when no next run is stored.",
+          "Active scheduled tasks require a schedule with a future occurrence.",
         );
       }
-      const recurrence = shouldRebuildRecurrence(input)
-        ? buildRecurrence({
-            existing: lookup.schedule.recurrence,
-            input,
-            nextRunAtMs,
-            timezone,
-          })
-        : lookup.schedule.recurrence;
       const nextStatus = status ?? lookup.status;
       // Another actor changing executable text revokes creator delegation.
       const credentialMode =
@@ -118,19 +111,14 @@ export function createSlackScheduleUpdateTaskTool(
       const next: ScheduledTask = {
         ...lookup,
         credentialMode,
-        updatedAtMs: Date.now(),
+        updatedAtMs: nowMs,
         nextRunAtMs,
-        runNowAtMs: nextStatus === "active" ? lookup.runNowAtMs : undefined,
+        runNowAtMs:
+          nextStatus === "active" && !compiled ? lookup.runNowAtMs : undefined,
         status: nextStatus,
         statusReason:
           nextStatus === "blocked" ? lookup.statusReason : undefined,
-        schedule: {
-          ...lookup.schedule,
-          description: input.schedule ?? lookup.schedule.description,
-          timezone,
-          kind: recurrence ? "recurring" : "one_off",
-          recurrence,
-        },
+        schedule: compiled?.schedule ?? lookup.schedule,
         task: input.task ? { text: input.task } : lookup.task,
       };