Implement Triggers System

[djthorpe]

Summary

Implement a trigger system that allows LLMs to schedule and manage long-running background processes. Triggers expose tools that LLMs can call to schedule future actions, enabling event-driven workflows and autonomous agent behavior.

Motivation

Currently, go-llm supports stateless completions and conversational sessions, but has no mechanism for:

• Scheduling future actions (reminders, recurring tasks)
• Responding to external events (webhooks, file changes, API notifications)
• Creating autonomous workflows that react to time or conditions

Triggers solve this by:

1. Making sessions truly long-running - sessions can have actions scheduled for the future
2. Enabling event-driven agents - respond to external stimuli without user intervention
3. Composing with agents - triggers can fire agents as child sessions, maintaining full audit trail
4. Extensibility - users define their own trigger types for their specific infrastructure

Requirements

Core Trigger Interface

• Define Trigger interface that any trigger type must implement
• Provide Name(), Description(), Schema() methods for self-description
• Implement Run(ctx context.Context) for background process lifecycle
• Implement Fire(ctx context.Context, instance *TriggerInstance) for injecting into sessions

Automatic Tool Generation

• When a trigger is registered, automatically generate four standard tools:
  • schedule_{type} - Create a new trigger instance
  • update_{type} - Modify an existing trigger instance
  • list_{type} - List all triggers for the current session
  • delete_{type} - Remove a trigger instance
• Tools appear in the LLM's toolkit and can be called naturally in conversation
• Tool schemas are generated from the trigger's Schema() definition

Trigger Instance Management

• Store trigger instances in PostgreSQL (complementing session storage)
• Track: type, session_id, configuration, state, enabled status
• Support partial updates to trigger configuration
• Support enabling/disabling without deletion

Session Integration

• Triggers inject messages into their parent session when fired
• Use existing Session.Append() and Session.Continue() mechanics
• Respect session's delivery backend (Telegram, Slack, webhook, etc.)
• Support firing agents as child sessions from triggers

Parent/Child Session Tracking

• Trigger executions create child sessions (if firing an agent)
• Maintain full audit trail via session hierarchy
• Enable cost attribution and debugging

Built-in Triggers

Provide minimal built-in triggers to demonstrate the pattern:

• Scheduler Trigger - One-time and recurring scheduled actions
  • Support duration-based delays ("4h", "2d", "1w")
  • Support cron-like recurring schedules
  • Store fire_at timestamp and check periodically

Extension Framework

• Clear documentation on implementing custom triggers
• Example implementations in examples/triggers/:
  • Webhook listener
  • File system watcher (fsnotify)
  • API polling (price alerts, status checks)
  • Email monitoring (IMAP IDLE)
• Users implement trigger interface and register with manager
• No built-in dependencies on external services

API Endpoints

• Tools are automatically exposed when triggers are registered
• No additional API endpoints needed (tools handle CRUD)
• Trigger instances are queryable via session endpoints

CLI Commands

• Triggers are managed through LLM conversations
• No dedicated CLI needed beyond existing session commands
• llm session show displays associated triggers

Example Usage Scenarios

Simple Reminder

User: Remind me in 4 hours to call the dentist
Assistant: [calls schedule_scheduler tool]
Assistant: I'll remind you at 2:30 PM
[4 hours pass]
[Trigger fires, injects message into session]
Assistant: ⏰ Reminder: call the dentist

Recurring Task

User: Every morning at 9am, summarize my unread emails
Assistant: [calls schedule_scheduler with recurring configuration]
Assistant: [calls fire_agent to execute email-summarizer agent]
[Next morning at 9am]
[Trigger fires, executes email-summarizer agent as child session]
Assistant: Good morning! Here's your email summary...

Webhook Integration (User-Implemented)

User: Create a webhook for GitHub PR notifications
Assistant: [calls schedule_webhook tool from user's custom trigger]
Assistant: Webhook created at: https://example.com/webhooks/abc123
[Later, when PR is opened]
[Webhook receives payload, trigger fires]
[Executes code-reviewer agent on the PR]
Assistant: New PR detected, here's my review...

File Monitoring (User-Implemented)

User: Watch /uploads for new PDFs and analyze them
Assistant: [calls schedule_file_watch tool]
[When new PDF appears]
[Trigger fires, executes pdf-analyzer agent]
Assistant: New PDF uploaded: quarterly-report.pdf. Summary: ...

Dependencies

• Requires Agents implementation (issue #XX)
• Builds on existing session management and PostgreSQL storage
• Uses existing ToolKit infrastructure

Success Criteria

• LLMs can schedule reminders and recurring tasks naturally
• Users can implement custom trigger types with clear examples
• Full session hierarchy tracking for trigger executions
• Minimal core (just scheduler trigger), extensible framework
• Works seamlessly with existing Telegram bot and session delivery

Future Enhancements (Out of Scope)

• Trigger chains (one trigger fires another)
• Conditional trigger execution (rules engine)
• Trigger priority and rate limiting
• Dead letter queue for failed triggers
• UI for visualizing trigger executions