3.7 KiB
SKILL: Cron Agent (Universal Literate Note)
Overview
The Cron Agent serves as the system's temporal conscience. It provides autonomous, time-aware capabilities by hooking into the background heartbeat, enabling proactive executive assistance.
Phase A: Demand (PRD)
1. Purpose
Define automated behaviors for deadline monitoring and temporal alerting.
2. User Needs
- Punctuality: Monitor deadlines and alerts across the Memex.
- Efficiency: Symbolic filtering (System 2) to minimize LLM calls.
- Multi-Channel Awareness: Routing alerts to Emacs or external delivery.
3. Success Criteria
TODO Heartbeat Trigger Verification
TODO Timestamp Parsing Accuracy
TODO Overdue Task Detection
Phase B: Blueprint (PROTOCOL)
Phase B: Blueprint (PROTOCOL)
1. Architectural Intent
The Cron Agent operates as a reactive component driven by the Memex heartbeat. It translates temporal events (scheduled times, deadlines, overdue conditions) into actions. It prioritizes efficiency by using System 2 (symbolic) processing for initial filtering and triggering, reserving System 3 (LLM-assisted) operations for complex reasoning scenarios. This agent adopts a modular design to enable easy integration with various notification channels.
2. Semantic Interfaces (Lisp Signatures)
`cron/register-task`
Registers a new task with the Cron Agent.
`(cron/register-task task-id schedule task-function &key (notification-channel :emacs) (deadline nil))`
:ARGS:
- `task-id`: A unique symbol identifying the task.
- `schedule`: A cron-style string representing the task's schedule (e.g., "0 0 * * *" for daily at midnight).
- `task-function`: A function (lambda) to execute when the schedule is met and the conditions are satisfied. This function must take a plist containing the task-id and scheduled-time.
- `notification-channel`: Keyword specifying the destination for alerts (:emacs, :slack, :email). Defaults to `:emacs`.
- `deadline`: An optional ISO-8601 timestamp string representing the deadline. If a deadline is specified, the `task-function` will also receive information about whether the task is overdue.
:RETURNS:
The `task-id` on successful registration, or `nil` if registration fails.
:Side Effects: Adds the task to the internal cron table.
`cron/remove-task`
Removes a previously registered task.
`(cron/remove-task task-id)`
:ARGS:
- `task-id`: The unique symbol identifying the task to be removed.
:RETURNS:
`T` if the task was successfully removed, `nil` otherwise.
:Side Effects: Removes the task from the internal cron table.
`cron/check-schedule`
(Internal) Called by the heartbeat to check if any tasks are due.
`(cron/check-schedule current-time)`
:ARGS:
- `current-time`: A timestamp representing the current time.
:RETURNS:
`nil` (No return value).
:Side Effects: Executes any tasks that are due based on their schedule and deadline.
`cron/notify`
Sends a notification through the specified channel.
`(cron/notify message channel)`
:ARGS:
- `message`: The message to be sent.
- `channel`: The notification channel (:emacs, :slack, :email).
:RETURNS:
`T` if the notification was sent successfully, `nil` otherwise.
:Side Effects: Sends a notification. The implementation details of sending notifications through various channels are handled internally.