mercury-agent 0.5.0 → 0.5.2

package/docs/scheduler.md

@@ -1,288 +1,288 @@
-# Scheduler
-
-Mercury includes a task scheduler for automated prompts. Tasks can run on **cron schedules** (recurring) or **at schedules** (one-shot).
-
-## Task Types
-
-### Cron Tasks (Recurring)
-
-Run on a cron schedule, repeating indefinitely:
-
-```bash
-# Daily standup at 9am
-mrctl tasks create --cron "0 9 * * *" --prompt "Good morning! What's on the agenda today?"
-```
-
-### At Tasks (One-Shot)
-
-Run once at a specific time, then auto-delete:
-
-```bash
-# Reminder in 2 hours
-mrctl tasks create --at "2026-03-02T16:00:00Z" --prompt "Time for the team meeting!"
-
-# Schedule a future check
-mrctl tasks create --at "2026-03-15T09:00:00Z" --prompt "Follow up on the Q1 report"
-```
-
-At-tasks are useful for:
-- **Reminders** — one-time notifications
-- **Delayed actions** — schedule something for later
-- **Follow-ups** — check back on something at a specific time
-
-The `at` timestamp must be:
-- ISO 8601 format (e.g., `2026-03-02T14:00:00Z`)
-- In the future
-
-## Silent Tasks
-
-Tasks can be marked as **silent** to execute without posting results to the chat. This is useful for:
-
-- **Maintenance tasks** — cleanup, archiving, or housekeeping
-- **Health checks** — periodic monitoring without noise
-- **Background updates** — knowledge base updates, data syncing
-
-The task executes normally but no message is sent to the space.
-
-```bash
-# Create a silent cron task
-mrctl tasks create --cron "0 3 * * *" --prompt "Run nightly maintenance" --silent
-
-# Create a silent at-task
-mrctl tasks create --at "2026-03-02T03:00:00Z" --prompt "One-time cleanup" --silent
-```
-
-## How It Works
-
-```
-TaskScheduler.start()
-  │
-  └─► Poll loop (every 5 seconds)
-        │
-        ├─► Query DB for due tasks (active=1, next_run_at <= now)
-        │
-        ├─► For each due task:
-        │     │
-        │     ├─► [Cron task]
-        │     │     ├─► Compute next run time from cron expression
-        │     │     ├─► Update next_run_at in DB
-        │     │     └─► Execute handler
-        │     │
-        │     └─► [At task]
-        │           ├─► Execute handler
-        │           └─► Delete task from DB
-        │
-        └─► Schedule next poll
-```
-
-Tasks are processed sequentially within a poll cycle. Each task runs as if the `createdBy` user sent the prompt.
-
-**At-task lifecycle:**
-1. Created with a future timestamp
-2. Waits until scheduled time
-3. Executes once
-4. Auto-deletes (regardless of success/failure)
-
-## Creating Tasks
-
-The agent creates tasks via `mrctl`:
-
-```bash
-# === Cron tasks (recurring) ===
-
-# Daily standup at 9am
-mrctl tasks create --cron "0 9 * * *" --prompt "Good morning! What's on the agenda today?"
-
-# Weekly summary on Fridays at 5pm
-mrctl tasks create --cron "0 17 * * 5" --prompt "Generate a summary of this week's discussions."
-
-# Every 6 hours
-mrctl tasks create --cron "0 */6 * * *" --prompt "Check for any pending items."
-
-# Silent nightly cleanup (no chat output)
-mrctl tasks create --cron "0 3 * * *" --prompt "Clean up old temp files" --silent
-
-# === At tasks (one-shot) ===
-
-# Reminder at a specific time
-mrctl tasks create --at "2026-03-02T14:00:00Z" --prompt "Meeting starts in 15 minutes!"
-
-# Delayed follow-up
-mrctl tasks create --at "2026-03-10T09:00:00Z" --prompt "Check if the deployment completed successfully"
-```
-
-**Note:** You must specify either `--cron` or `--at`, not both.
-
-## Managing Tasks
-
-```bash
-# List all tasks in the current space
-mrctl tasks list
-
-# Pause a task (stops execution, keeps definition)
-mrctl tasks pause <id>
-
-# Resume a paused task
-mrctl tasks resume <id>
-
-# Manually trigger a task now
-mrctl tasks run <id>
-
-# Delete a task permanently
-mrctl tasks delete <id>
-```
-
-## Cron Format
-
-Standard 5-field cron expressions:
-
-```
-┌───────────── minute (0-59)
-│ ┌───────────── hour (0-23)
-│ │ ┌───────────── day of month (1-31)
-│ │ │ ┌───────────── month (1-12)
-│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 are Sunday)
-│ │ │ │ │
-* * * * *
-```
-
-Examples:
-
-| Expression | Description |
-|------------|-------------|
-| `0 9 * * *` | Every day at 9:00 AM |
-| `0 9 * * 1-5` | Weekdays at 9:00 AM |
-| `*/15 * * * *` | Every 15 minutes |
-| `0 */6 * * *` | Every 6 hours |
-| `0 17 * * 5` | Fridays at 5:00 PM |
-| `0 0 1 * *` | First day of each month at midnight |
-
-Mercury uses [cron-parser](https://www.npmjs.com/package/cron-parser) for parsing.
-
-## Task Execution
-
-When a task fires:
-
-1. The prompt is sent to the space as if from the task creator
-2. Runs through the normal routing (trigger check bypassed for scheduled tasks)
-3. Caller ID is the `createdBy` user
-4. Permissions are checked against the creator's role at execution time
-
-Tasks run with `system` caller privileges for the routing layer, but the prompt is attributed to the original creator.
-
-## Storage
-
-Tasks are stored in SQLite:
-
-```sql
-CREATE TABLE tasks (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  space_id TEXT NOT NULL,
-  cron TEXT,                          -- Cron expression (null for at-tasks)
-  at TEXT,                            -- ISO 8601 timestamp (null for cron-tasks)
-  prompt TEXT NOT NULL,
-  active INTEGER NOT NULL DEFAULT 1,
-  silent INTEGER NOT NULL DEFAULT 0,
-  next_run_at INTEGER NOT NULL,
-  created_by TEXT NOT NULL,
-  created_at INTEGER NOT NULL,
-  updated_at INTEGER NOT NULL
-);
-
-CREATE INDEX idx_tasks_next ON tasks(active, next_run_at);
-```
-
-| Column | Description |
-|--------|-------------|
-| `cron` | Cron expression for recurring tasks (null for at-tasks) |
-| `at` | ISO 8601 timestamp for one-shot tasks (null for cron-tasks) |
-| `silent` | If 1, task runs but doesn't post results to chat |
-
-## Permissions
-
-Task management requires specific permissions:
-
-| Permission | Action |
-|------------|--------|
-| `tasks.list` | View scheduled tasks |
-| `tasks.create` | Create new tasks |
-| `tasks.pause` | Pause a task |
-| `tasks.resume` | Resume a paused task |
-| `tasks.delete` | Delete a task |
-
-By default, only `admin` has these permissions. Grant to other roles:
-
-```bash
-mrctl permissions set member prompt,tasks.list
-mrctl permissions set moderator prompt,tasks.list,tasks.pause,tasks.resume
-```
-
-## Lifecycle
-
-```
-mercury run
-  │
-  ├─► runtime.initialize()
-  │
-  ├─► scheduler.start(handler)
-  │     └─► Poll loop begins
-  │
-  ├─► ... running ...
-  │
-  └─► SIGTERM/SIGINT
-        └─► scheduler.stop()
-              └─► Poll loop ends (graceful)
-```
-
-The scheduler stops cleanly on shutdown — no orphaned timers.
-
-## API
-
-### `TaskScheduler`
-
-```typescript
-const scheduler = new TaskScheduler(db, pollIntervalMs);
-
-scheduler.start(handler);    // Begin polling
-scheduler.stop();            // Stop polling
-scheduler.computeNextRun(cron, from);  // Get next run time for cron tasks
-```
-
-### Handler Signature
-
-```typescript
-type TaskHandler = (task: {
-  id: number;
-  spaceId: string;
-  prompt: string;
-  createdBy: string;
-  silent: boolean;
-}) => Promise<void>;
-```
-
-### Database Methods
-
-```typescript
-// Create a cron task
-db.createTask(spaceId, { cron: "0 9 * * *" }, prompt, nextRunAt, createdBy, silent);
-
-// Create an at-task
-db.createTask(spaceId, { at: "2026-03-02T14:00:00Z" }, prompt, nextRunAt, createdBy, silent);
-
-db.listTasks(spaceId?);       // List tasks (optionally filter by space)
-db.getDueTasks(now);          // Get tasks ready to run
-db.getTask(id);               // Get single task
-db.setTaskActive(id, active); // Pause/resume
-db.deleteTask(id, spaceId);   // Delete task (with space check)
-db.deleteTaskById(id);        // Delete task (no space check, for scheduler)
-db.updateTaskNextRun(id, nextRunAt);  // Update next execution time
-```
-
-## Error Handling
-
-If a task handler fails:
-- Error is logged
-- Task is not retried in the same cycle
-- **Cron tasks:** `next_run_at` is already updated, so it will run again at the next scheduled time
-- **At tasks:** Still deleted after execution (one-shot behavior preserved)
-- Other tasks in the cycle continue to execute
+# Scheduler
+
+Mercury includes a task scheduler for automated prompts. Tasks can run on **cron schedules** (recurring) or **at schedules** (one-shot).
+
+## Task Types
+
+### Cron Tasks (Recurring)
+
+Run on a cron schedule, repeating indefinitely:
+
+```bash
+# Daily standup at 9am
+mrctl tasks create --cron "0 9 * * *" --prompt "Good morning! What's on the agenda today?"
+```
+
+### At Tasks (One-Shot)
+
+Run once at a specific time, then auto-delete:
+
+```bash
+# Reminder in 2 hours
+mrctl tasks create --at "2026-03-02T16:00:00Z" --prompt "Time for the team meeting!"
+
+# Schedule a future check
+mrctl tasks create --at "2026-03-15T09:00:00Z" --prompt "Follow up on the Q1 report"
+```
+
+At-tasks are useful for:
+- **Reminders** — one-time notifications
+- **Delayed actions** — schedule something for later
+- **Follow-ups** — check back on something at a specific time
+
+The `at` timestamp must be:
+- ISO 8601 format (e.g., `2026-03-02T14:00:00Z`)
+- In the future
+
+## Silent Tasks
+
+Tasks can be marked as **silent** to execute without posting results to the chat. This is useful for:
+
+- **Maintenance tasks** — cleanup, archiving, or housekeeping
+- **Health checks** — periodic monitoring without noise
+- **Background updates** — knowledge base updates, data syncing
+
+The task executes normally but no message is sent to the space.
+
+```bash
+# Create a silent cron task
+mrctl tasks create --cron "0 3 * * *" --prompt "Run nightly maintenance" --silent
+
+# Create a silent at-task
+mrctl tasks create --at "2026-03-02T03:00:00Z" --prompt "One-time cleanup" --silent
+```
+
+## How It Works
+
+```
+TaskScheduler.start()
+  │
+  └─► Poll loop (every 5 seconds)
+        │
+        ├─► Query DB for due tasks (active=1, next_run_at <= now)
+        │
+        ├─► For each due task:
+        │     │
+        │     ├─► [Cron task]
+        │     │     ├─► Compute next run time from cron expression
+        │     │     ├─► Update next_run_at in DB
+        │     │     └─► Execute handler
+        │     │
+        │     └─► [At task]
+        │           ├─► Execute handler
+        │           └─► Delete task from DB
+        │
+        └─► Schedule next poll
+```
+
+Tasks are processed sequentially within a poll cycle. Each task runs as if the `createdBy` user sent the prompt.
+
+**At-task lifecycle:**
+1. Created with a future timestamp
+2. Waits until scheduled time
+3. Executes once
+4. Auto-deletes (regardless of success/failure)
+
+## Creating Tasks
+
+The agent creates tasks via `mrctl`:
+
+```bash
+# === Cron tasks (recurring) ===
+
+# Daily standup at 9am
+mrctl tasks create --cron "0 9 * * *" --prompt "Good morning! What's on the agenda today?"
+
+# Weekly summary on Fridays at 5pm
+mrctl tasks create --cron "0 17 * * 5" --prompt "Generate a summary of this week's discussions."
+
+# Every 6 hours
+mrctl tasks create --cron "0 */6 * * *" --prompt "Check for any pending items."
+
+# Silent nightly cleanup (no chat output)
+mrctl tasks create --cron "0 3 * * *" --prompt "Clean up old temp files" --silent
+
+# === At tasks (one-shot) ===
+
+# Reminder at a specific time
+mrctl tasks create --at "2026-03-02T14:00:00Z" --prompt "Meeting starts in 15 minutes!"
+
+# Delayed follow-up
+mrctl tasks create --at "2026-03-10T09:00:00Z" --prompt "Check if the deployment completed successfully"
+```
+
+**Note:** You must specify either `--cron` or `--at`, not both.
+
+## Managing Tasks
+
+```bash
+# List all tasks in the current space
+mrctl tasks list
+
+# Pause a task (stops execution, keeps definition)
+mrctl tasks pause <id>
+
+# Resume a paused task
+mrctl tasks resume <id>
+
+# Manually trigger a task now
+mrctl tasks run <id>
+
+# Delete a task permanently
+mrctl tasks delete <id>
+```
+
+## Cron Format
+
+Standard 5-field cron expressions:
+
+```
+┌───────────── minute (0-59)
+│ ┌───────────── hour (0-23)
+│ │ ┌───────────── day of month (1-31)
+│ │ │ ┌───────────── month (1-12)
+│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 are Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+Examples:
+
+| Expression | Description |
+|------------|-------------|
+| `0 9 * * *` | Every day at 9:00 AM |
+| `0 9 * * 1-5` | Weekdays at 9:00 AM |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 */6 * * *` | Every 6 hours |
+| `0 17 * * 5` | Fridays at 5:00 PM |
+| `0 0 1 * *` | First day of each month at midnight |
+
+Mercury uses [cron-parser](https://www.npmjs.com/package/cron-parser) for parsing.
+
+## Task Execution
+
+When a task fires:
+
+1. The prompt is sent to the space as if from the task creator
+2. Runs through the normal routing (trigger check bypassed for scheduled tasks)
+3. Caller ID is the `createdBy` user
+4. Permissions are checked against the creator's role at execution time
+
+Tasks run with `system` caller privileges for the routing layer, but the prompt is attributed to the original creator.
+
+## Storage
+
+Tasks are stored in SQLite:
+
+```sql
+CREATE TABLE tasks (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  space_id TEXT NOT NULL,
+  cron TEXT,                          -- Cron expression (null for at-tasks)
+  at TEXT,                            -- ISO 8601 timestamp (null for cron-tasks)
+  prompt TEXT NOT NULL,
+  active INTEGER NOT NULL DEFAULT 1,
+  silent INTEGER NOT NULL DEFAULT 0,
+  next_run_at INTEGER NOT NULL,
+  created_by TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_tasks_next ON tasks(active, next_run_at);
+```
+
+| Column | Description |
+|--------|-------------|
+| `cron` | Cron expression for recurring tasks (null for at-tasks) |
+| `at` | ISO 8601 timestamp for one-shot tasks (null for cron-tasks) |
+| `silent` | If 1, task runs but doesn't post results to chat |
+
+## Permissions
+
+Task management requires specific permissions:
+
+| Permission | Action |
+|------------|--------|
+| `tasks.list` | View scheduled tasks |
+| `tasks.create` | Create new tasks |
+| `tasks.pause` | Pause a task |
+| `tasks.resume` | Resume a paused task |
+| `tasks.delete` | Delete a task |
+
+By default, only `admin` has these permissions. Grant to other roles:
+
+```bash
+mrctl permissions set member prompt,tasks.list
+mrctl permissions set moderator prompt,tasks.list,tasks.pause,tasks.resume
+```
+
+## Lifecycle
+
+```
+mercury run
+  │
+  ├─► runtime.initialize()
+  │
+  ├─► scheduler.start(handler)
+  │     └─► Poll loop begins
+  │
+  ├─► ... running ...
+  │
+  └─► SIGTERM/SIGINT
+        └─► scheduler.stop()
+              └─► Poll loop ends (graceful)
+```
+
+The scheduler stops cleanly on shutdown — no orphaned timers.
+
+## API
+
+### `TaskScheduler`
+
+```typescript
+const scheduler = new TaskScheduler(db, pollIntervalMs);
+
+scheduler.start(handler);    // Begin polling
+scheduler.stop();            // Stop polling
+scheduler.computeNextRun(cron, from);  // Get next run time for cron tasks
+```
+
+### Handler Signature
+
+```typescript
+type TaskHandler = (task: {
+  id: number;
+  spaceId: string;
+  prompt: string;
+  createdBy: string;
+  silent: boolean;
+}) => Promise<void>;
+```
+
+### Database Methods
+
+```typescript
+// Create a cron task
+db.createTask(spaceId, { cron: "0 9 * * *" }, prompt, nextRunAt, createdBy, silent);
+
+// Create an at-task
+db.createTask(spaceId, { at: "2026-03-02T14:00:00Z" }, prompt, nextRunAt, createdBy, silent);
+
+db.listTasks(spaceId?);       // List tasks (optionally filter by space)
+db.getDueTasks(now);          // Get tasks ready to run
+db.getTask(id);               // Get single task
+db.setTaskActive(id, active); // Pause/resume
+db.deleteTask(id, spaceId);   // Delete task (with space check)
+db.deleteTaskById(id);        // Delete task (no space check, for scheduler)
+db.updateTaskNextRun(id, nextRunAt);  // Update next execution time
+```
+
+## Error Handling
+
+If a task handler fails:
+- Error is logged
+- Task is not retried in the same cycle
+- **Cron tasks:** `next_run_at` is already updated, so it will run again at the next scheduled time
+- **At tasks:** Still deleted after execution (one-shot behavior preserved)
+- Other tasks in the cycle continue to execute