memex/notes/org-skill-cron.org

SKILL: Cron Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Heartbeat Trigger Verification
    • Timestamp Parsing Accuracy
    • Overdue Task Detection
• Phase B: Blueprint (PROTOCOL)
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces (Lisp Signatures)
    • `cron/register-task`
    • `cron/remove-task`
    • `cron/check-schedule`
    • `cron/notify`

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.