Schedule Integration Package

A self-contained Laravel package that enables time-based agent execution for PromptlyAgent using Laravel's scheduling system.

Features

• ⏰ Multiple Schedule Types: One-time, recurring (hourly/daily/weekly/monthly), custom intervals, and cron expressions
• 🔄 Automatic Execution: Integrated with Laravel scheduler for reliable execution
• 📝 Placeholder Support: Dynamic placeholders for dates, times, and custom variables
• 🌐 Timezone-Aware: Full timezone support for accurate scheduling across regions
• 🎯 Manual Execution: UI button for immediate trigger testing
• 📊 Execution Tracking: Built-in statistics and logging
• 🚀 Queue Integration: Async execution via Laravel Horizon/Queue

Screenshots

Schedule Configuration Interface

Configure time-based triggers through the PromptlyAgent admin interface:

Schedule type selection, timezone settings, and recurrence configuration

Placeholder support, execution history, and manual trigger controls

Installation

The package is auto-discovered by Laravel and requires no manual setup beyond:

1. Ensure Laravel Scheduler is Running:

   # The scheduler is configured in docker/supervisor/supervisord.conf
   # Runs: php artisan schedule:work

2. Verify Package is Loaded:

   php artisan schedule:list
   # Should show registered scheduled triggers

Architecture

Package Structure

packages/schedule-trigger/
├── src/
│   ├── Commands/
│   │   └── ExecuteScheduledTriggerCommand.php    # CLI execution
│   ├── Http/Controllers/
│   │   └── ScheduledTriggerController.php        # Manual execution endpoint
│   ├── Jobs/
│   │   └── ExecuteScheduledTriggerJob.php        # Async queue job
│   ├── Providers/
│   │   └── ScheduledInputTriggerProvider.php     # Main trigger provider
│   ├── Services/
│   │   ├── ScheduleManager.php                   # Laravel scheduler integration
│   │   ├── ScheduleCalculator.php                # Next run calculations
│   │   ├── PlaceholderResolver.php               # Dynamic placeholder engine
│   │   └── HttpDataFetcher.php                   # External data fetching
│   ├── Support/
│   │   └── ScheduleConfig.php                    # Config value object
│   └── ScheduleIntegrationServiceProvider.php    # Package bootstrap
├── resources/views/
│   └── trigger-config.blade.php                  # UI configuration form
└── composer.json

tests/Feature/
└── ScheduledTriggerIntegrationTest.php           # Integration tests

How It Works

1. Service Provider Registration:

   • Registers all services as singletons
   • Registers routes for manual execution
   • Registers commands
   • Hooks into Laravel's Schedule resolver using callAfterResolving()
   • Registers provider with InputTriggerRegistry and ProviderRegistry

2. Schedule Registration:

   • ScheduleManager loads active scheduled triggers from database
   • Converts trigger config to Laravel schedule definitions
   • Caches for 5 minutes for performance
   • Cache invalidates on trigger save/delete

3. Execution Flow:

   • Laravel scheduler runs schedule:work (via supervisor)
   • At scheduled time, executes scheduled-trigger:execute {trigger_id}
   • Command resolves placeholders and invokes TriggerExecutor
   • TriggerExecutor creates chat session and executes agent
   • Results appear in user's chat interface

4. Manual Execution:

   • UI button dispatches ExecuteScheduledTriggerJob to queue
   • Job resolves placeholders and executes trigger asynchronously
   • User gets immediate feedback without waiting for agent completion

Configuration Schema

Triggers store configuration in input_triggers.config JSON column:

{
  "schedule_type": "recurring",
  "timezone": "UTC",

  "recurring": {
    "type": "daily",
    "time": "09:00",
    "days_of_week": [1, 2, 3, 4, 5]
  },

  "input_text": "Analyze today's metrics for {{date}}",

  "placeholders": {
    "static": {
      "company": "Acme Corp"
    }
  },

  "execution_limits": {
    "max_executions": 100,
    "expires_at": "2025-12-31T23:59:59"
  },

  "error_handling": {
    "on_failure": "continue",
    "max_consecutive_failures": 3
  }
}

Built-in Placeholders

All placeholders are timezone-aware and resolved at execution time:

• {{date}} - Current date (Y-m-d)
• {{time}} - Current time (H:i:s)
• {{datetime}} - Current date and time
• {{timestamp}} - Unix timestamp
• {{day}} - Day of week (Monday-Sunday)
• {{week}} - Week number
• {{month}} - Month name
• {{year}} - Four-digit year
• {{trigger_id}} - Trigger UUID
• {{trigger_name}} - Trigger name
• {{user_id}} - Trigger owner's user ID
• {{execution_count}} - Total executions so far

API

Creating a Scheduled Trigger

Via UI: Navigate to Integrations → Create Trigger → Select "Scheduled Trigger"

Via Code:

use App\Models\InputTrigger;

$trigger = InputTrigger::create([
    'user_id' => auth()->id(),
    'provider_id' => 'schedule',
    'name' => 'Daily Report',
    'agent_id' => $agent->id,
    'session_strategy' => 'new_each',
    'status' => 'active',
    'config' => [
        'schedule_type' => 'recurring',
        'timezone' => 'UTC',
        'input_text' => 'Generate daily report for {{date}}',
        'recurring' => [
            'type' => 'daily',
            'time' => '09:00',
        ],
        'error_handling' => [
            'on_failure' => 'continue',
            'max_consecutive_failures' => 3,
        ],
    ],
]);

Manual Execution

# Via CLI
php artisan scheduled-trigger:execute {trigger-id}

# Via HTTP (authenticated)
POST /integrations/triggers/{trigger-id}/execute

Testing

Run the integration test suite:

php artisan test --filter=ScheduledTriggerIntegrationTest

Tests cover:

• Provider registration
• Creating all schedule types
• Updating triggers
• Validation rules
• Static placeholders
• Execution limits
• HTTP security bypass

Core App Integration Points

The package requires minimal core app integration:

1. Composer Registration (composer.json):

   {
     "require": {
       "promptlyagentai/schedule-trigger": "@dev"
     },
     "repositories": [
       {
         "type": "vcs",
         "url": "https://github.com/promptlyagentai/schedule-trigger.git"
       }
     ]
   }

2. Scheduler Running (docker/supervisor/supervisord.conf):

   [program:scheduler]
   command=/usr/bin/php /var/www/html/artisan schedule:work
   autostart=true
   autorestart=true

3. UI Integration (resources/views/settings/integrations/trigger-details.blade.php):

   • Execute Now button for scheduled triggers

4. Integration Test (tests/Feature/ScheduledTriggerIntegrationTest.php):

   • Comprehensive test coverage

Dependencies

• Laravel 12+
• PHP 8.2+
• Laravel Queue/Horizon (for async execution)
• Cron Expression Parser (dragonmantank/cron-expression)

Security

• No HTTP endpoints exposed (internal scheduler only)
• No rate limits or IP whitelisting required
• User authentication enforced on manual execution endpoint
• All execution logged with user context

Performance

• Schedule cache: 5 minutes TTL
• Singleton services for minimal overhead
• Lazy loading of triggers
• Async execution via queue prevents blocking

Troubleshooting

Triggers not executing automatically

• Check scheduler is running: supervisorctl status scheduler
• Verify trigger is active: Check input_triggers.status = 'active'
• Check logs: storage/logs/laravel.log for schedule registration
• View schedule: php artisan schedule:list

Manual execution not working

• Verify queue worker is running (Horizon)
• Check job failed logs: Horizon dashboard
• Review storage/logs/laravel.log for job errors

Placeholder not resolving

• Check placeholder syntax: Must use {{placeholder}}
• Verify timezone configuration
• Review placeholder resolver logs

License

MIT License. See LICENSE for details.

Support

For issues and questions, please use this repository: https://github.com/promptlyagentai/schedule-trigger