Agent Self-Scheduling Feature#

Overview#

Create a system that allows the Letta agent to schedule future prompts for itself by calling a Python tool that hits an HTTP endpoint on this project.

Requirements#

Core Functionality#

• Agent can set reminders by specifying:
  • Datetime (when to execute)
  • Prompt (what message to send itself)
• Scheduled prompts must respect the busy state system
• Use claimTaskThread() and releaseTaskThread() from utils/agentContext.ts
• Execute prompts via existing messageAgent() function

Implementation Decisions#

• Persistence: In-memory only (acceptable to lose on restart)
• Security: API key authentication
• Busy Handling: Queue scheduling requests (don't reject when busy)
• Task Management: Create-only (no list/cancel/update operations needed)

Technical Approach#

• HTTP Server: Use Deno's native Deno.serve() API (no external framework needed)
• Port: Configurable via environment variable (default 8000)
• Endpoint: POST /api/schedule-reminder
• Auth: Bearer token in Authorization header

Architecture#

Component 1: HTTP Server (server.ts)#

• Use native Deno.serve() API
• Single POST endpoint for scheduling
• Middleware for API key authentication
• JSON request/response format
• Bind to localhost only

Component 2: Task Scheduler (utils/taskScheduler.ts)#

• Parse ISO 8601 datetime strings
• Calculate millisecond delay from now
• Use setTimeout() for scheduling
• In-memory Map to track scheduled tasks
• Wrapper function that:
  1. Claims task thread (waits if busy)
  2. Calls messageAgent(prompt)
  3. Releases task thread
• Return task ID for tracking

Component 3: Python Tool (tools/schedule_reminder.py)#

def schedule_reminder(datetime_iso: str, reminder_prompt: str) -> str:
    """
    Schedule a future reminder for yourself.

    Args:
        datetime_iso: When to remind (ISO 8601 format)
        reminder_prompt: The message/prompt to send yourself

    Returns:
        Confirmation message with task ID
    """

Component 4: Integration (main.ts)#

• Start HTTP server alongside existing tasks
• Server runs concurrently with task loops

Files to Create#

New Files#

• server.ts - HTTP server with POST endpoint
• utils/taskScheduler.ts - Dynamic task scheduling logic
• middleware/auth.ts - API key authentication middleware (optional, can inline)
• tools/schedule_reminder.py - Python tool for Letta agent
• Documentation for uploading tool to Letta

Modified Files#

• main.ts - Start HTTP server on initialization
• .env.example - Add API_SERVER_PORT and API_AUTH_TOKEN

Environment Variables#

API_SERVER_PORT=8000
API_AUTH_TOKEN=<secure-random-token>

API Specification#

POST /api/schedule-reminder#

Request:

{
  "datetime": "2025-11-13T14:30:00",
  "prompt": "Check on the status of that conversation about TypeScript"
}

Response (Success):

{
  "success": true,
  "taskId": "reminder-1731456789012",
  "scheduledFor": "2025-11-13T14:30:00",
  "message": "Reminder scheduled successfully"
}

Response (Error):

{
  "success": false,
  "error": "Invalid datetime format"
}

Authentication:

Authorization: Bearer <API_AUTH_TOKEN>

Implementation Phases#

Phase 1: HTTP Server Infrastructure#

• Create server.ts with Deno.serve()
• Implement auth middleware
• Add POST endpoint handler
• Update main.ts to start server
• Add environment variables

Phase 2: Task Scheduler System#

• Create taskScheduler.ts
• Implement datetime parsing and delay calculation
• Create task wrapper with busy state handling
• Implement in-memory task registry
• Test scheduling and execution

Phase 3: Python Tool#

• Write schedule_reminder.py
• Test HTTP requests locally
• Document upload process for Letta

Phase 4: Testing & Documentation#

• Test scheduling from Python
• Test busy state handling
• Test authentication
• Test invalid inputs
• Document usage

Estimated Effort#

• Development Time: 2-3 hours
• Lines of Code: ~250-300 lines
• Complexity: Moderate-Low

Benefits#

• Agent gains ability to self-manage its schedule
• No modification to existing task code
• Simple, predictable architecture
• Follows existing patterns in codebase

Future Enhancements (Not in Scope)#

• Persistent storage (SQLite/JSON file)
• List/cancel/update operations (full CRUD)
• Recurring reminders
• Task history logging
• Webhook notifications on completion
• Task priorities and queue management

Notes#

• Server only needs to bind to localhost since agent runs locally
• No database needed for v1
• Scheduled tasks lost on restart (acceptable trade-off for simplicity)
• Agent must have access to API_AUTH_TOKEN environment variable