@sentry/junior-scheduler 0.89.0 → 0.90.0

package/src/tool-support.ts

@@ -0,0 +1,471 @@
+import { randomUUID } from "node:crypto";
+import {
+  PluginToolInputError,
+  pluginToolResultSchema,
+  pluginCredentialSubjectSchema,
+  sourceSchema,
+  type PluginCredentialSubject,
+  type SlackDestination,
+  type SlackRequester,
+  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 {
+  credentialSubject?: PluginCredentialSubject;
+  requester?: SlackRequester;
+  source?: SlackSource;
+  store: SchedulerStore;
+  userText?: string;
+}
+
+const TASK_ID_PREFIX = "sched";
+export const MAX_LISTED_TASKS = 50;
+const DEFAULT_SCHEDULE_TIMEZONE = "America/Los_Angeles";
+
+const compactTaskResultSchema = z
+  .object({
+    id: z.string(),
+    status: z.enum(["active", "paused", "blocked", "deleted"]),
+    task: z.string(),
+    schedule: z.string(),
+    timezone: z.string(),
+    recurrence: z.unknown().nullable(),
+    next_run_at: z.string().nullable(),
+    conversation_access: z.unknown().nullable(),
+    credential_subject: z.unknown().nullable(),
+    last_run_at: z.string().nullable(),
+    run_now_at: z.string().nullable(),
+  })
+  .strict();
+
+const scheduleTaskResultDataSchema = z
+  .object({
+    ok: z.literal(true),
+    task: compactTaskResultSchema,
+  })
+  .strict();
+
+export const scheduleTaskToolResultSchema = pluginToolResultSchema.extend({
+  ok: z.literal(true),
+  status: z.literal("success"),
+  target: z.string(),
+  data: scheduleTaskResultDataSchema,
+  task: compactTaskResultSchema,
+});
+
+const scheduleListResultDataSchema = z
+  .object({
+    ok: z.literal(true),
+    tasks: z.array(compactTaskResultSchema),
+    truncated: z.boolean(),
+  })
+  .strict();
+
+export const scheduleListToolResultSchema = pluginToolResultSchema.extend({
+  ok: z.literal(true),
+  status: z.literal("success"),
+  target: z.string(),
+  data: scheduleListResultDataSchema,
+  tasks: z.array(compactTaskResultSchema),
+  truncated: z.boolean(),
+});
+export type CompactTaskResult = z.output<typeof compactTaskResultSchema>;
+
+type SchemaIssue = {
+  code: string;
+  path: readonly PropertyKey[];
+};
+
+/** Normalize scheduler validation failures into the plugin tool error contract. */
+export function throwToolInputError(error: string): never {
+  throw new PluginToolInputError(error);
+}
+
+/** Require scheduler mutations to stay scoped to the active Slack conversation. */
+export function requireActiveConversation(
+  context: SchedulerToolContext,
+): SlackDestination {
+  const parsed = sourceSchema.safeParse(context.source);
+  if (!parsed.success) {
+    const source = context.source as Partial<SlackSource> | undefined;
+    const issues = parsed.error.issues as readonly SchemaIssue[];
+    if (!source || source.platform !== "slack") {
+      throwToolInputError("No active Slack conversation is available.");
+    }
+    if (issues.some((issue) => issue.code === "unrecognized_keys")) {
+      throwToolInputError(
+        "Active Slack conversation must not include unknown fields.",
+      );
+    }
+    if (issues.some((issue) => issue.path[0] === "channelId")) {
+      throwToolInputError("Active Slack conversation channel is invalid.");
+    }
+    if (issues.some((issue) => issue.path[0] === "teamId")) {
+      throwToolInputError("Active Slack conversation workspace is invalid.");
+    }
+    throwToolInputError("No active Slack conversation is available.");
+  }
+
+  if (parsed.data.platform !== "slack") {
+    throwToolInputError("No active Slack conversation is available.");
+  }
+
+  return {
+    platform: "slack",
+    teamId: parsed.data.teamId,
+    channelId: parsed.data.channelId,
+  };
+}
+
+/** Require a concrete Slack requester before creating scheduler ownership state. */
+export function requireRequester(
+  context: SchedulerToolContext,
+): ScheduledTaskPrincipal {
+  if (context.requester?.platform !== "slack") {
+    throwToolInputError("No active Slack requester context is available.");
+  }
+  const userId = context.requester?.userId?.trim();
+  if (!userId || userId.toLowerCase() === "unknown") {
+    throwToolInputError("No active Slack requester context is available.");
+  }
+
+  return sanitizeScheduledTaskPrincipal({
+    slackUserId: userId,
+    ...(context.requester?.userName
+      ? { userName: context.requester.userName }
+      : {}),
+    ...(context.requester?.fullName
+      ? { fullName: context.requester.fullName }
+      : {}),
+  });
+}
+
+function isDmChannel(channelId: string): boolean {
+  return channelId.startsWith("D");
+}
+
+/** Preserve destination visibility so scheduled work can replay with matching access. */
+export function getConversationAccess(
+  destination: SlackDestination,
+): ScheduledTaskConversationAccess {
+  if (isDmChannel(destination.channelId)) {
+    return { audience: "direct", visibility: "private" };
+  }
+  if (destination.channelId.startsWith("G")) {
+    return { audience: "group", visibility: "private" };
+  }
+  if (destination.channelId.startsWith("C")) {
+    return { audience: "channel", visibility: "unknown" };
+  }
+  return { audience: "channel", visibility: "unknown" };
+}
+
+/** Carry private-DM credential authority only when scheduled work is allowed to reuse it. */
+export function getCredentialSubject(args: {
+  access: ScheduledTaskConversationAccess;
+  subject: PluginCredentialSubject | undefined;
+}): PluginCredentialSubject | undefined {
+  if (
+    args.access.audience !== "direct" ||
+    args.access.visibility !== "private"
+  ) {
+    return undefined;
+  }
+  if (!args.subject) {
+    return undefined;
+  }
+  const subject = pluginCredentialSubjectSchema.safeParse(args.subject);
+  if (!subject.success) {
+    throwToolInputError("Active Slack credential subject is invalid.");
+  }
+  return {
+    type: subject.data.type,
+    userId: subject.data.userId,
+    allowedWhen: subject.data.allowedWhen,
+  };
+}
+
+/** Keep scheduler management operations bound to the task's original Slack destination. */
+export function sameDestination(
+  task: ScheduledTask,
+  destination: SlackDestination,
+): boolean {
+  const taskDestination = task.destination;
+  return (
+    taskDestination.platform === "slack" &&
+    taskDestination.teamId === destination.teamId &&
+    taskDestination.channelId === destination.channelId
+  );
+}
+
+/** Look up a mutable task only after enforcing active-conversation ownership. */
+export async function getWritableTask(args: {
+  context: SchedulerToolContext;
+  taskId: string;
+}): Promise<ScheduledTask> {
+  const destination = requireActiveConversation(args.context);
+
+  const task = await schedulerStore(args.context).getTask(args.taskId);
+  if (!task || task.status === "deleted") {
+    throwToolInputError(
+      "Scheduled task was not found in the active Slack conversation.",
+    );
+  }
+
+  if (!sameDestination(task, destination)) {
+    throwToolInputError(
+      "Scheduled task can only be managed from the Slack destination where it was created.",
+    );
+  }
+  return task;
+}
+
+/** Project scheduled task state into the stable model-facing result shape. */
+export function compactTask(task: ScheduledTask): CompactTaskResult {
+  return compactTaskResultSchema.parse({
+    id: task.id,
+    status: task.status,
+    task: task.task.text,
+    schedule: task.schedule.description,
+    timezone: task.schedule.timezone,
+    recurrence: task.schedule.recurrence
+      ? {
+          frequency: task.schedule.recurrence.frequency,
+          interval: task.schedule.recurrence.interval,
+          start_date: task.schedule.recurrence.startDate,
+          time: task.schedule.recurrence.time,
+          weekdays: task.schedule.recurrence.weekdays,
+          month: task.schedule.recurrence.month,
+          day_of_month: task.schedule.recurrence.dayOfMonth,
+        }
+      : null,
+    next_run_at: task.nextRunAtMs
+      ? new Date(task.nextRunAtMs).toISOString()
+      : null,
+    conversation_access: task.conversationAccess ?? null,
+    credential_subject: task.credentialSubject
+      ? {
+          type: task.credentialSubject.type,
+          allowed_when: task.credentialSubject.allowedWhen,
+        }
+      : null,
+    last_run_at: task.lastRunAtMs
+      ? new Date(task.lastRunAtMs).toISOString()
+      : null,
+    run_now_at: task.runNowAtMs
+      ? new Date(task.runNowAtMs).toISOString()
+      : null,
+  });
+}
+
+/** Build the structured result shared by single-task scheduler tools. */
+export function scheduleTaskToolResult(
+  target: string,
+  task: CompactTaskResult,
+) {
+  const data = {
+    ok: true,
+    task,
+  } as const;
+  return {
+    ok: true,
+    status: "success",
+    target,
+    data,
+    task,
+  } as const;
+}
+
+/** Build the structured result for listing scheduler tools. */
+export function scheduleListToolResult(args: {
+  target: string;
+  tasks: CompactTaskResult[];
+  truncated: boolean;
+}) {
+  const data = {
+    ok: true,
+    tasks: args.tasks,
+    truncated: args.truncated,
+  } as const;
+  return {
+    ok: true,
+    status: "success",
+    target: args.target,
+    data,
+    tasks: args.tasks,
+    truncated: args.truncated,
+  } as const;
+}
+
+/** Prefix generated scheduler ids so tool results are distinguishable from provider ids. */
+export function buildTaskId(): string {
+  return `${TASK_ID_PREFIX}_${randomUUID()}`;
+}
+
+/** Keep concrete scheduler tools coupled to the injected store, not global state. */
+export function schedulerStore(context: SchedulerToolContext): SchedulerStore {
+  return context.store;
+}
+
+/** Accept only persisted scheduler statuses from model-facing update input. */
+export function normalizeStatus(
+  value: string | undefined,
+): ScheduledTaskStatus | undefined {
+  if (value === "active" || value === "paused" || value === "blocked") {
+    return value;
+  }
+  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

@@ -0,0 +1,121 @@
+import { definePluginTool } from "@sentry/junior-plugin-api";
+import { z } from "zod";
+import { SCHEDULED_TASK_SYSTEM_ACTOR } from "../types";
+import type { ScheduledTask } from "../types";
+import {
+  buildRecurrence,
+  buildTaskId,
+  compactTask,
+  getConversationAccess,
+  getCredentialSubject,
+  getDefaultScheduleTimezone,
+  isValidTimeZone,
+  parseNextRunAtMs,
+  requireActiveConversation,
+  requireRequester,
+  scheduleTaskToolResult,
+  scheduleTaskToolResultSchema,
+  schedulerStore,
+  throwToolInputError,
+  validateCreateScheduleKind,
+  validateRecurringFrequencyLimit,
+  type SchedulerToolContext,
+} from "../tool-support";
+
+/** Create a tool that stores a scheduled task for the active Slack context. */
+export function createSlackScheduleCreateTaskTool(
+  context: SchedulerToolContext,
+) {
+  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. Only manage tasks for the active Slack DM or channel; never target threads, other channels, or another user's DM. When the task, schedule, and destination are clear, create it without asking for confirmation; ask only when one of those is ambiguous.",
+    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.",
+        ),
+      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(),
+    }),
+    outputSchema: scheduleTaskToolResultSchema,
+    execute: async (input) => {
+      const destination = requireActiveConversation(context);
+      const requester = requireRequester(context);
+
+      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 nextRunAtMs = parseNextRunAtMs(input.next_run_at);
+      if (!nextRunAtMs) {
+        throwToolInputError("Provide next_run_at as a valid ISO timestamp.");
+      }
+      const recurrence = buildRecurrence({
+        input,
+        nextRunAtMs,
+        timezone,
+      });
+      const conversationAccess = getConversationAccess(destination);
+      const credentialSubject = getCredentialSubject({
+        access: conversationAccess,
+        subject: context.credentialSubject,
+      });
+
+      const task: ScheduledTask = {
+        id: buildTaskId(),
+        createdAtMs: nowMs,
+        updatedAtMs: nowMs,
+        createdBy: requester,
+        conversationAccess,
+        ...(credentialSubject ? { credentialSubject } : {}),
+        destination,
+        executionActor: SCHEDULED_TASK_SYSTEM_ACTOR,
+        nextRunAtMs,
+        originalRequest: context.userText,
+        schedule: {
+          description: input.schedule,
+          timezone,
+          kind: recurrence ? "recurring" : "one_off",
+          recurrence,
+        },
+        status: "active",
+        task: {
+          text: input.task,
+        },
+      };
+
+      await schedulerStore(context).saveTask(task);
+      return scheduleTaskToolResult(
+        "slackScheduleCreateTask",
+        compactTask(task),
+      );
+    },
+  });
+}

package/src/tools/delete-task.ts

@@ -0,0 +1,48 @@
+import { definePluginTool } from "@sentry/junior-plugin-api";
+import { z } from "zod";
+import type { ScheduledTask } from "../types";
+import {
+  compactTask,
+  getWritableTask,
+  scheduleTaskToolResult,
+  scheduleTaskToolResultSchema,
+  schedulerStore,
+  type SchedulerToolContext,
+} from "../tool-support";
+
+/** Create a tool that removes a scheduled task from the active Slack conversation. */
+export function createSlackScheduleDeleteTaskTool(
+  context: SchedulerToolContext,
+) {
+  return definePluginTool({
+    description:
+      "Delete one scheduled Junior task from the active Slack conversation. Use only task IDs returned for this conversation. Do not delete schedules from threads, other channels, or another user's DM.",
+    executionMode: "sequential",
+    inputSchema: z.object({
+      task_id: z
+        .string()
+        .min(1)
+        .describe(
+          "ID of the task to delete. Must be from this active Slack conversation.",
+        ),
+    }),
+    outputSchema: scheduleTaskToolResultSchema,
+    execute: async ({ task_id }) => {
+      const lookup = await getWritableTask({ context, taskId: task_id });
+
+      const next: ScheduledTask = {
+        ...lookup,
+        updatedAtMs: Date.now(),
+        status: "deleted",
+        nextRunAtMs: undefined,
+        runNowAtMs: undefined,
+      };
+
+      await schedulerStore(context).saveTask(next);
+      return scheduleTaskToolResult(
+        "slackScheduleDeleteTask",
+        compactTask(next),
+      );
+    },
+  });
+}

package/src/tools/list-tasks.ts

@@ -0,0 +1,42 @@
+import { definePluginTool } from "@sentry/junior-plugin-api";
+import { z } from "zod";
+import {
+  compactTask,
+  MAX_LISTED_TASKS,
+  requireActiveConversation,
+  sameDestination,
+  scheduleListToolResult,
+  scheduleListToolResultSchema,
+  schedulerStore,
+  type SchedulerToolContext,
+} from "../tool-support";
+
+/** Create a tool that lists scheduled tasks for the active Slack conversation. */
+export function createSlackScheduleListTasksTool(
+  context: SchedulerToolContext,
+) {
+  return definePluginTool({
+    description:
+      "List scheduled Junior tasks for the active Slack conversation. Use when the user asks what is scheduled here, or when task IDs are needed before editing, deleting, or running schedules. Only manages tasks for the active Slack DM or channel.",
+    annotations: { readOnlyHint: true, destructiveHint: false },
+    inputSchema: z.object({}),
+    outputSchema: scheduleListToolResultSchema,
+    execute: async () => {
+      const destination = requireActiveConversation(context);
+
+      const tasks = await schedulerStore(context).listTasksForTeam(
+        destination.teamId,
+      );
+      const matching = tasks.filter((task) =>
+        sameDestination(task, destination),
+      );
+      const visible = matching.slice(0, MAX_LISTED_TASKS).map(compactTask);
+
+      return scheduleListToolResult({
+        target: "slackScheduleListTasks",
+        tasks: visible,
+        truncated: matching.length > visible.length,
+      });
+    },
+  });
+}