mercury-agent 0.4.5

package/docs/scheduler.md

@@ -0,0 +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

package/docs/setup-discord.md

@@ -0,0 +1,100 @@
+# Discord Setup Guide
+
+Connect Mercury to Discord using a bot application with gateway (WebSocket) connection.
+
+## Prerequisites
+
+- A Discord account
+- A Discord server where you have **Manage Server** permission
+- Mercury initialized (`mercury init`)
+
+## Step 1: Create a Discord Application
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Click **New Application** → name it (e.g., "Mercury")
+3. Go to the **Bot** tab
+4. Click **Reset Token** → copy the bot token
+
+## Step 2: Configure Bot Settings
+
+In the **Bot** tab:
+
+- **Privileged Gateway Intents** — enable all three:
+  - ✅ Presence Intent
+  - ✅ Server Members Intent
+  - ✅ Message Content Intent
+
+These are required for Mercury to read message content and user information.
+
+## Step 3: Invite the Bot to Your Server
+
+1. Go to the **OAuth2 → URL Generator** tab
+2. Select scopes: `bot`
+3. Select bot permissions:
+   - Send Messages
+   - Read Message History
+   - Attach Files
+   - Use Slash Commands
+   - Add Reactions
+4. Copy the generated URL and open it in your browser
+5. Select your server and authorize
+
+## Step 4: Configure Mercury
+
+In your `.env` file:
+
+```bash
+MERCURY_ENABLE_DISCORD=true
+MERCURY_DISCORD_BOT_TOKEN=your-bot-token-here
+```
+
+## Step 5: Find Your Discord User ID
+
+To add yourself as admin, you need your Discord user ID:
+
+1. Enable **Developer Mode** in Discord (Settings → Advanced → Developer Mode)
+2. Right-click your username → **Copy User ID**
+3. Add to `.env`:
+
+```bash
+MERCURY_ADMINS=discord:YOUR_USER_ID
+```
+
+## Step 6: Start Mercury
+
+```bash
+mercury service install
+mercury service status
+mercury service logs -f
+```
+
+## Step 7: Link conversations
+
+Send a message to the bot (DM or mention in a channel), then:
+
+```bash
+mercury conversations --unlinked
+mercury link <id> <space-name>
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MERCURY_ENABLE_DISCORD` | `false` | Enable Discord adapter |
+| `MERCURY_DISCORD_BOT_TOKEN` | — | Bot token from Developer Portal |
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Bot is online but doesn't respond | Check Message Content Intent is enabled |
+| "Missing Permissions" errors | Re-invite with correct permissions (step 3) |
+| Bot doesn't appear online | Verify `MERCURY_DISCORD_BOT_TOKEN` is correct |
+| Messages not arriving in logs | Ensure bot is in the channel and has Read Message History |
+
+## Security
+
+- Never commit your bot token to version control
+- Regenerate the token immediately if it's ever exposed
+- Use minimal permissions — only grant what Mercury needs

package/docs/setup-slack.md

@@ -0,0 +1,119 @@
+# Slack Setup Guide
+
+Connect Mercury to Slack using the Events API with a bot token.
+
+## Prerequisites
+
+- A Slack workspace where you have admin access
+- A publicly accessible URL for webhooks (or use a tunnel like ngrok)
+- Mercury initialized (`mercury init`)
+
+## Step 1: Create a Slack App
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App → From scratch**
+3. Name it (e.g., "Mercury") and select your workspace
+
+## Step 2: Configure Bot Scopes
+
+Go to **OAuth & Permissions** → **Bot Token Scopes** and add:
+
+- `chat:write` — Send messages
+- `channels:history` — Read channel messages
+- `groups:history` — Read private channel messages
+- `im:history` — Read DMs
+- `mpim:history` — Read group DMs
+- `channels:read` — List channels
+- `groups:read` — List private channels
+- `im:read` — List DMs
+- `users:read` — Read user info
+- `files:read` — Access shared files
+- `files:write` — Upload files
+
+## Step 3: Install to Workspace
+
+1. Go to **OAuth & Permissions**
+2. Click **Install to Workspace** → authorize
+3. Copy the **Bot User OAuth Token** (`xoxb-...`)
+
+## Step 4: Get the Signing Secret
+
+1. Go to **Basic Information**
+2. Under **App Credentials**, copy the **Signing Secret**
+
+## Step 5: Configure Mercury
+
+In your `.env` file:
+
+```bash
+MERCURY_ENABLE_SLACK=true
+MERCURY_SLACK_BOT_TOKEN=xoxb-your-bot-token
+MERCURY_SLACK_SIGNING_SECRET=your-signing-secret
+```
+
+## Step 6: Set Up Event Subscriptions
+
+Mercury needs to receive events from Slack via webhooks.
+
+1. Start Mercury first (it needs to respond to Slack's verification challenge):
+   ```bash
+   mercury service install
+   ```
+
+2. In the Slack app settings, go to **Event Subscriptions**
+3. Toggle **Enable Events** to on
+4. Set the **Request URL** to: `https://your-domain.com/webhooks/slack/events`
+5. Wait for Slack to verify the URL (Mercury handles this automatically)
+
+6. Under **Subscribe to Bot Events**, add:
+   - `message.channels`
+   - `message.groups`
+   - `message.im`
+   - `message.mpim`
+
+7. Click **Save Changes**
+
+## Step 7: Find Your Slack User ID
+
+To add yourself as admin:
+
+1. In Slack, click your profile picture → **Profile**
+2. Click **⋯** (more) → **Copy member ID**
+3. Add to `.env`:
+
+```bash
+MERCURY_ADMINS=slack:U0123456789
+```
+
+## Step 8: Link conversations
+
+Send a message to the bot (DM or mention in a channel), then:
+
+```bash
+mercury conversations --unlinked
+mercury link <id> <space-name>
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MERCURY_ENABLE_SLACK` | `false` | Enable Slack adapter |
+| `MERCURY_SLACK_BOT_TOKEN` | — | Bot User OAuth Token (`xoxb-...`) |
+| `MERCURY_SLACK_SIGNING_SECRET` | — | Signing secret for request verification |
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Event URL verification fails | Ensure Mercury is running and reachable at the URL |
+| Bot doesn't respond in channels | Invite the bot to the channel (`/invite @Mercury`) |
+| "not_authed" errors | Check `MERCURY_SLACK_BOT_TOKEN` is correct |
+| Missing messages | Verify all `message.*` events are subscribed |
+| Can't receive events locally | Use ngrok: `ngrok http 8787` and use the HTTPS URL |
+
+## Security
+
+- Never commit tokens or signing secrets to version control
+- The signing secret verifies that events come from Slack — keep it secret
+- Rotate tokens if exposed: **OAuth & Permissions → Revoke Token**

package/docs/setup-whatsapp.md

@@ -0,0 +1,94 @@
+# WhatsApp Setup Guide
+
+Connect Mercury to WhatsApp using the Baileys library (WhatsApp Web protocol).
+
+## Prerequisites
+
+- A phone number with WhatsApp installed
+- Mercury initialized (`mercury init`)
+
+## Step 1: Enable WhatsApp
+
+In your `.env` file:
+
+```bash
+MERCURY_ENABLE_WHATSAPP=true
+```
+
+## Step 2: Authenticate
+
+You **must** authenticate before starting Mercury.
+
+### QR Code (recommended)
+
+```bash
+mercury auth whatsapp
+```
+
+1. Open WhatsApp on your phone
+2. Go to **Settings → Linked Devices → Link a Device**
+3. Scan the QR code displayed in your terminal
+
+### Pairing Code (headless/remote servers)
+
+```bash
+mercury auth whatsapp --pairing-code --phone 14155551234
+```
+
+1. Open WhatsApp → **Settings → Linked Devices → Link a Device**
+2. Tap **"Link with phone number instead"**
+3. Enter the 8-character code shown in your terminal
+
+After successful auth, your WhatsApp ID is printed — copy it into `MERCURY_ADMINS` in `.env`.
+
+## Step 3: Start Mercury
+
+```bash
+mercury service install
+mercury service status
+mercury service logs -f
+```
+
+## Step 4: Link conversations
+
+Send a message to the bot's WhatsApp number, then:
+
+```bash
+mercury conversations --unlinked
+mercury link <id> <space-name>
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MERCURY_ENABLE_WHATSAPP` | `false` | Enable WhatsApp adapter |
+| `MERCURY_WHATSAPP_AUTH_DIR` | `.mercury/whatsapp-auth` | Credentials directory |
+
+## Session Lifecycle
+
+WhatsApp linked device sessions last **~14–20 days** before requiring re-authentication. When expired:
+
+```bash
+mercury service uninstall
+rm -rf .mercury/whatsapp-auth/
+mercury auth whatsapp
+mercury service install
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| QR code not showing | Run `mercury auth whatsapp` separately, not `mercury run` |
+| "Already authenticated" but not working | Delete `.mercury/whatsapp-auth/` and re-auth |
+| QR code expires too fast | Use `--pairing-code` mode instead |
+| Messages not arriving | Check `MERCURY_ENABLE_WHATSAPP=true` and re-auth |
+| Old messages appear on startup | Normal — Mercury ignores pre-connection messages |
+
+## Security
+
+- Credentials in `.mercury/whatsapp-auth/` are sensitive — treat like passwords
+- Consider using a dedicated phone number for the bot
+
+See also: [auth/whatsapp.md](auth/whatsapp.md) for detailed auth internals.