@elizaos/plugin-scheduling 2.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# @elizaos/plugin-scheduling
+
+Scheduling and calendar coordination plugin for ElizaOS agents.
+
+## Features
+
+- **Multi-party Availability Coordination**: Find meeting times that work for all participants
+- **Time Zone Aware**: Handles availability across different time zones
+- **Calendar Invites**: Generate ICS files for calendar integration
+- **Automated Reminders**: Schedule SMS/email reminders before meetings
+- **Meeting Lifecycle**: Track meetings from proposal to completion
+- **Rescheduling Support**: Handle cancellations and reschedules gracefully
+
+## Installation
+
+```bash
+npm install @elizaos/plugin-scheduling
+```
+
+## Usage
+
+```typescript
+import { schedulingPlugin } from '@elizaos/plugin-scheduling';
+import { createCharacter } from '@elizaos/core';
+
+const character = createCharacter({
+  name: 'Scheduler',
+  plugins: [schedulingPlugin],
+});
+```
+
+## API
+
+### SchedulingService
+
+The core service for managing scheduling operations.
+
+#### Save Availability
+
+```typescript
+const schedulingService = runtime.getService<SchedulingService>('SCHEDULING');
+
+await schedulingService.saveAvailability(entityId, {
+  timeZone: 'America/New_York',
+  weekly: [
+    { day: 'mon', startMinutes: 540, endMinutes: 1020 }, // 9am-5pm
+    { day: 'tue', startMinutes: 540, endMinutes: 1020 },
+    { day: 'wed', startMinutes: 540, endMinutes: 1020 },
+    { day: 'thu', startMinutes: 540, endMinutes: 1020 },
+    { day: 'fri', startMinutes: 540, endMinutes: 1020 },
+  ],
+  exceptions: [
+    { date: '2024-01-20', unavailable: true, reason: 'Holiday' },
+  ],
+});
+```
+
+#### Create Scheduling Request
+
+```typescript
+const request = await schedulingService.createSchedulingRequest(
+  roomId,
+  'Coffee Chat',
+  [
+    { entityId: user1Id, name: 'Alice', availability: aliceAvailability },
+    { entityId: user2Id, name: 'Bob', availability: bobAvailability },
+  ],
+  {
+    minDurationMinutes: 30,
+    preferredDurationMinutes: 60,
+    maxDaysOut: 7,
+    preferredTimes: ['afternoon'],
+    locationType: 'in_person',
+  }
+);
+```
+
+#### Find Available Slots
+
+```typescript
+const result = await schedulingService.findAvailableSlots(request);
+
+if (result.success) {
+  // result.proposedSlots contains ranked time slots
+  const bestSlot = result.proposedSlots[0];
+  console.log(`Best slot: ${bestSlot.slot.start} - Score: ${bestSlot.score}`);
+}
+```
+
+#### Create Meeting
+
+```typescript
+const meeting = await schedulingService.createMeeting(request, slot, {
+  type: 'in_person',
+  name: 'Blue Bottle Coffee',
+  address: '123 Main St',
+  city: 'San Francisco',
+});
+```
+
+#### Confirm Attendance
+
+```typescript
+await schedulingService.confirmParticipant(meetingId, entityId);
+```
+
+### Actions
+
+The plugin provides conversational actions:
+
+- `SCHEDULE_MEETING`: Start scheduling a meeting
+- `CONFIRM_MEETING`: Confirm or decline attendance
+- `SET_AVAILABILITY`: Update availability preferences
+
+### Provider
+
+The `SCHEDULING_CONTEXT` provider gives agents context about:
+- Upcoming meetings
+- Pending confirmations
+- User's availability settings
+
+## Types
+
+### Availability
+
+```typescript
+interface Availability {
+  timeZone: string;               // IANA time zone
+  weekly: AvailabilityWindow[];   // Recurring windows
+  exceptions: AvailabilityException[]; // One-off changes
+}
+
+interface AvailabilityWindow {
+  day: DayOfWeek;       // 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun'
+  startMinutes: number; // Minutes from midnight (0-1439)
+  endMinutes: number;   // Minutes from midnight (0-1439)
+}
+```
+
+### Meeting
+
+```typescript
+interface Meeting {
+  id: string;
+  title: string;
+  slot: TimeSlot;
+  location: MeetingLocation;
+  participants: MeetingParticipant[];
+  status: MeetingStatus;
+  rescheduleCount: number;
+}
+
+type MeetingStatus = 
+  | 'proposed'
+  | 'confirmed'
+  | 'scheduled'
+  | 'in_progress'
+  | 'completed'
+  | 'cancelled'
+  | 'rescheduling'
+  | 'no_show';
+```
+
+## Configuration
+
+```typescript
+const config: SchedulingServiceConfig = {
+  defaultReminderMinutes: [1440, 120],  // 24h and 2h before
+  maxProposals: 3,
+  defaultMaxDaysOut: 7,
+  minMeetingDuration: 30,
+  defaultMeetingDuration: 60,
+  autoSendCalendarInvites: true,
+  autoScheduleReminders: true,
+};
+```
+
+## Calendar Integration
+
+Generate ICS files for calendar apps:
+
+```typescript
+import { generateIcs } from '@elizaos/plugin-scheduling';
+
+const ics = generateIcs({
+  uid: meeting.id,
+  title: meeting.title,
+  start: meeting.slot.start,
+  end: meeting.slot.end,
+  timeZone: meeting.slot.timeZone,
+  location: meeting.location.address,
+  organizer: { name: 'Ori', email: 'ori@soulmates.app' },
+  attendees: meeting.participants.map(p => ({
+    name: p.name,
+    email: p.email,
+    role: p.role,
+  })),
+  reminderMinutes: [1440, 120],
+});
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,403 @@
+import { UUID, Service, IAgentRuntime, Plugin } from '@elizaos/core';
+
+/**
+ * @module types
+ * @description Type definitions for the scheduling plugin
+ *
+ * Key concepts:
+ * - AvailabilityWindow: A recurring time slot (e.g., "Mondays 9am-5pm")
+ * - SchedulingRequest: A request to find a meeting time for multiple participants
+ * - Meeting: A scheduled event with time, location, and participants
+ * - CalendarEvent: An ICS-compatible event for calendar invites
+ */
+
+type DayOfWeek = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+interface AvailabilityWindow {
+    day: DayOfWeek;
+    /** Minutes from midnight in local time (0-1439) */
+    startMinutes: number;
+    /** Minutes from midnight in local time (0-1439) */
+    endMinutes: number;
+}
+interface AvailabilityException {
+    /** ISO date string (YYYY-MM-DD) */
+    date: string;
+    /** If true, completely unavailable this day */
+    unavailable?: boolean;
+    /** Override start time for this day */
+    startMinutes?: number;
+    /** Override end time for this day */
+    endMinutes?: number;
+    /** Reason for the exception */
+    reason?: string;
+}
+interface Availability {
+    /** IANA time zone (e.g., "America/New_York") */
+    timeZone: string;
+    /** Weekly recurring availability */
+    weekly: AvailabilityWindow[];
+    /** One-off exceptions */
+    exceptions: AvailabilityException[];
+}
+interface TimeSlot {
+    /** ISO datetime string */
+    start: string;
+    /** ISO datetime string */
+    end: string;
+    /** IANA time zone */
+    timeZone: string;
+}
+interface Participant {
+    /** Entity ID in the system */
+    entityId: UUID;
+    /** Display name */
+    name: string;
+    /** Email for calendar invites (optional) */
+    email?: string;
+    /** Phone for SMS reminders (optional) */
+    phone?: string;
+    /** Their availability */
+    availability: Availability;
+    /** Priority weight (higher = more important to accommodate) */
+    priority?: number;
+}
+type ParticipantRole = 'organizer' | 'required' | 'optional';
+interface MeetingParticipant {
+    entityId: UUID;
+    name: string;
+    email?: string;
+    phone?: string;
+    role: ParticipantRole;
+    /** Has this participant confirmed attendance? */
+    confirmed: boolean;
+    /** When they confirmed */
+    confirmedAt?: number;
+    /** If they declined, why */
+    declineReason?: string;
+}
+type LocationType = 'in_person' | 'virtual' | 'phone';
+interface MeetingLocation {
+    type: LocationType;
+    /** Venue name for in-person meetings */
+    name?: string;
+    /** Physical address */
+    address?: string;
+    /** City */
+    city?: string;
+    /** Google Places ID or similar */
+    placeId?: string;
+    /** Video call URL for virtual meetings */
+    videoUrl?: string;
+    /** Phone number for phone meetings */
+    phoneNumber?: string;
+    /** Additional notes */
+    notes?: string;
+}
+type SchedulingUrgency = 'flexible' | 'soon' | 'urgent';
+interface SchedulingConstraints {
+    /** Minimum meeting duration in minutes */
+    minDurationMinutes: number;
+    /** Preferred meeting duration in minutes */
+    preferredDurationMinutes: number;
+    /** Maximum days in the future to search */
+    maxDaysOut: number;
+    /** Preferred times of day */
+    preferredTimes?: ('morning' | 'afternoon' | 'evening')[];
+    /** Preferred days of week */
+    preferredDays?: DayOfWeek[];
+    /** Location type preference */
+    locationType?: LocationType;
+    /** Specific location constraint (e.g., "same city") */
+    locationConstraint?: string;
+}
+interface SchedulingRequest {
+    id: string;
+    /** Room/context this scheduling is happening in */
+    roomId: UUID;
+    /** Meeting title/purpose */
+    title: string;
+    /** Meeting description */
+    description?: string;
+    /** All participants who need to attend */
+    participants: Participant[];
+    /** Scheduling constraints */
+    constraints: SchedulingConstraints;
+    /** How urgent is this meeting */
+    urgency: SchedulingUrgency;
+    /** Created timestamp */
+    createdAt: number;
+    /** Max proposals before escalating */
+    maxProposals?: number;
+}
+type MeetingStatus = 'proposed' | 'confirmed' | 'scheduled' | 'in_progress' | 'completed' | 'cancelled' | 'rescheduling' | 'no_show';
+interface Meeting {
+    id: string;
+    /** Reference to the scheduling request */
+    requestId: string;
+    /** Room/context */
+    roomId: UUID;
+    /** Meeting title */
+    title: string;
+    /** Meeting description */
+    description?: string;
+    /** Scheduled time slot */
+    slot: TimeSlot;
+    /** Meeting location */
+    location: MeetingLocation;
+    /** All participants */
+    participants: MeetingParticipant[];
+    /** Current status */
+    status: MeetingStatus;
+    /** Number of times rescheduled */
+    rescheduleCount: number;
+    /** If cancelled/rescheduled, why */
+    cancellationReason?: string;
+    /** Created timestamp */
+    createdAt: number;
+    /** Last updated timestamp */
+    updatedAt: number;
+    /** Meeting notes/agenda */
+    notes?: string;
+    /** Metadata */
+    meta?: Record<string, unknown>;
+}
+interface CalendarEvent {
+    /** Unique event ID */
+    uid: string;
+    /** Event title */
+    title: string;
+    /** Event description */
+    description?: string;
+    /** Start time (ISO string) */
+    start: string;
+    /** End time (ISO string) */
+    end: string;
+    /** IANA time zone */
+    timeZone: string;
+    /** Location */
+    location?: string;
+    /** Organizer */
+    organizer?: {
+        name: string;
+        email: string;
+    };
+    /** Attendees */
+    attendees?: Array<{
+        name: string;
+        email: string;
+        role: ParticipantRole;
+    }>;
+    /** URL to join (for virtual meetings) */
+    url?: string;
+    /** Reminder minutes before event */
+    reminderMinutes?: number[];
+}
+interface CalendarInvite {
+    /** The ICS file content */
+    ics: string;
+    /** Parsed event data */
+    event: CalendarEvent;
+    /** Recipient email */
+    recipientEmail: string;
+    /** Recipient name */
+    recipientName: string;
+}
+type ReminderType = 'sms' | 'email' | 'whatsapp' | 'push';
+type ReminderStatus = 'pending' | 'sent' | 'failed' | 'cancelled';
+interface Reminder {
+    id: string;
+    /** Meeting this reminder is for */
+    meetingId: string;
+    /** Participant to remind */
+    participantId: UUID;
+    /** When to send (ISO string) */
+    scheduledFor: string;
+    /** Reminder channel */
+    type: ReminderType;
+    /** Reminder message */
+    message: string;
+    /** Current status */
+    status: ReminderStatus;
+    /** When it was sent */
+    sentAt?: number;
+    /** Error if failed */
+    error?: string;
+    /** Created timestamp */
+    createdAt: number;
+}
+interface ProposedSlot {
+    slot: TimeSlot;
+    /** Score indicating how good this slot is (higher = better) */
+    score: number;
+    /** Why this slot was chosen */
+    reasons: string[];
+    /** Any concerns about this slot */
+    concerns: string[];
+}
+interface SchedulingResult {
+    /** Whether scheduling was successful */
+    success: boolean;
+    /** Proposed time slots, ranked by preference */
+    proposedSlots: ProposedSlot[];
+    /** If no slots found, why */
+    failureReason?: string;
+    /** Participants who have no availability overlap */
+    conflictingParticipants?: UUID[];
+}
+interface SchedulingServiceConfig {
+    /** Default reminder times (minutes before meeting) */
+    defaultReminderMinutes: number[];
+    /** Maximum proposals per scheduling request */
+    maxProposals: number;
+    /** How many days out to look for availability */
+    defaultMaxDaysOut: number;
+    /** Minimum meeting duration in minutes */
+    minMeetingDuration: number;
+    /** Default meeting duration in minutes */
+    defaultMeetingDuration: number;
+    /** Whether to auto-send calendar invites */
+    autoSendCalendarInvites: boolean;
+    /** Whether to auto-schedule reminders */
+    autoScheduleReminders: boolean;
+}
+declare const DEFAULT_CONFIG: SchedulingServiceConfig;
+
+/** Core scheduling service for multi-party coordination, availability intersection, and calendar management */
+
+declare class SchedulingService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private schedulingConfig;
+    constructor(runtime?: IAgentRuntime, schedulingConfig?: Partial<SchedulingServiceConfig>);
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    stop(): Promise<void>;
+    healthCheck(): Promise<{
+        healthy: boolean;
+        issues: string[];
+    }>;
+    getSchedulingConfig(): SchedulingServiceConfig;
+    saveAvailability(entityId: UUID, availability: Availability): Promise<void>;
+    getAvailability(entityId: UUID): Promise<Availability | null>;
+    isAvailableAt(availability: Availability, dateTime: Date): boolean;
+    createSchedulingRequest(roomId: UUID, title: string, participants: Participant[], constraints?: Partial<SchedulingConstraints>, options?: {
+        description?: string;
+        urgency?: 'flexible' | 'soon' | 'urgent';
+    }): Promise<SchedulingRequest>;
+    findAvailableSlots(request: SchedulingRequest): Promise<SchedulingResult>;
+    private findDayIntersection;
+    private findConflictingParticipants;
+    private hasAnyOverlap;
+    private scoreSlot;
+    createMeeting(request: SchedulingRequest, slot: TimeSlot, location: {
+        type: 'in_person' | 'virtual' | 'phone';
+        name?: string;
+        address?: string;
+        city?: string;
+        videoUrl?: string;
+        phoneNumber?: string;
+        notes?: string;
+    }): Promise<Meeting>;
+    getMeeting(meetingId: string): Promise<Meeting | null>;
+    getMeetingsForRoom(roomId: UUID): Promise<Meeting[]>;
+    getUpcomingMeetings(entityId: UUID): Promise<Meeting[]>;
+    confirmParticipant(meetingId: string, entityId: UUID): Promise<Meeting>;
+    declineParticipant(meetingId: string, entityId: UUID, reason?: string): Promise<Meeting>;
+    cancelMeeting(meetingId: string, reason?: string): Promise<Meeting>;
+    updateMeetingStatus(meetingId: string, status: MeetingStatus): Promise<Meeting>;
+    rescheduleMeeting(meetingId: string, newSlot: TimeSlot, reason?: string): Promise<Meeting>;
+    generateCalendarInvite(meeting: Meeting, recipientEmail: string, recipientName: string): CalendarInvite;
+    /** Sends invites via EMAIL service if available, otherwise returns ICS for manual handling */
+    sendCalendarInvites(meeting: Meeting): Promise<CalendarInvite[]>;
+    private formatInviteEmail;
+    scheduleReminders(meeting: Meeting): Promise<Reminder[]>;
+    getDueReminders(): Promise<Reminder[]>;
+    markReminderSent(reminderId: string): Promise<void>;
+    cancelReminders(meetingId: string): Promise<void>;
+    formatSlot(slot: TimeSlot, locale?: string): string;
+    getConfig(): SchedulingServiceConfig;
+}
+
+/**
+ * @module ical
+ * @description ICS (iCalendar) file generation utilities
+ *
+ * Generates RFC 5545 compliant iCalendar files for calendar invites.
+ */
+
+/**
+ * Generate ICS content for a calendar event
+ */
+declare const generateIcs: (event: CalendarEvent) => string;
+/**
+ * Parse an ICS file and extract events (basic parser)
+ */
+declare const parseIcs: (ics: string) => CalendarEvent[];
+
+/** Component-based persistence for scheduling data using ElizaOS Components */
+
+interface AvailabilityStorage {
+    get(entityId: UUID): Promise<Availability | null>;
+    save(entityId: UUID, availability: Availability): Promise<void>;
+    delete(entityId: UUID): Promise<void>;
+}
+declare const getAvailabilityStorage: (runtime: IAgentRuntime) => AvailabilityStorage;
+interface SchedulingRequestStorage {
+    get(requestId: string): Promise<SchedulingRequest | null>;
+    save(request: SchedulingRequest): Promise<void>;
+    delete(requestId: string): Promise<void>;
+    getByRoom(roomId: UUID): Promise<SchedulingRequest[]>;
+}
+declare const getSchedulingRequestStorage: (runtime: IAgentRuntime) => SchedulingRequestStorage;
+interface MeetingStorage {
+    get(meetingId: string): Promise<Meeting | null>;
+    save(meeting: Meeting): Promise<void>;
+    delete(meetingId: string): Promise<void>;
+    getByRoom(roomId: UUID): Promise<Meeting[]>;
+    getUpcomingForParticipant(entityId: UUID): Promise<Meeting[]>;
+}
+declare const getMeetingStorage: (runtime: IAgentRuntime) => MeetingStorage;
+interface ReminderStorage {
+    get(reminderId: string): Promise<Reminder | null>;
+    save(reminder: Reminder): Promise<void>;
+    delete(reminderId: string): Promise<void>;
+    getByMeeting(meetingId: string): Promise<Reminder[]>;
+    getDue(): Promise<Reminder[]>;
+}
+declare const getReminderStorage: (runtime: IAgentRuntime) => ReminderStorage;
+
+/**
+ * @module plugin-scheduling
+ * @description ElizaOS plugin for scheduling and calendar coordination
+ *
+ * This plugin provides:
+ * - Multi-party availability coordination
+ * - Meeting scheduling with time slot proposals
+ * - Calendar invite generation (ICS format)
+ * - Automated reminders
+ * - Rescheduling and cancellation handling
+ *
+ * Key features:
+ * - Time zone aware scheduling
+ * - Preference-based slot scoring
+ * - Integration with form plugin for conversational scheduling
+ */
+
+/**
+ * Scheduling plugin for ElizaOS
+ *
+ * Provides scheduling capabilities for coordinating meetings
+ * between multiple participants.
+ *
+ * Usage:
+ * ```typescript
+ * import { schedulingPlugin } from '@elizaos/plugin-scheduling';
+ *
+ * const character = createCharacter({
+ *   name: 'Scheduler',
+ *   plugins: [schedulingPlugin],
+ * });
+ * ```
+ */
+declare const schedulingPlugin: Plugin;
+
+export { type Availability, type AvailabilityException, type AvailabilityStorage, type AvailabilityWindow, type CalendarEvent, type CalendarInvite, DEFAULT_CONFIG, type DayOfWeek, type LocationType, type Meeting, type MeetingLocation, type MeetingParticipant, type MeetingStatus, type MeetingStorage, type Participant, type ParticipantRole, type ProposedSlot, type Reminder, type ReminderStatus, type ReminderStorage, type ReminderType, type SchedulingConstraints, type SchedulingRequest, type SchedulingRequestStorage, type SchedulingResult, SchedulingService, type SchedulingServiceConfig, type SchedulingUrgency, type TimeSlot, schedulingPlugin as default, generateIcs, getAvailabilityStorage, getMeetingStorage, getReminderStorage, getSchedulingRequestStorage, parseIcs, schedulingPlugin };