reeboot 1.0.0 → 1.3.0

package/README.md

@@ -7,16 +7,22 @@
 ## Quick Start
 
 ```bash
-# Install and launch the setup wizard
-npx reeboot
-
-# Or install globally
 npm install -g reeboot
-reeboot setup
-reeboot start
+reeboot
 ```
 
-The wizard will ask for your LLM provider, API key, model, and which channels to enable. After that, `reeboot start` runs the agent — open the WebChat URL it prints, or scan the WhatsApp QR code.
+That's it. On first run, `reeboot` detects that no config exists and launches the guided setup wizard automatically. The wizard walks you through:
+
+1. **AI Provider** — choose from 8 providers (Anthropic, OpenAI, Google, Groq, Mistral, xAI, OpenRouter, Ollama)
+2. **Agent Name** — give your agent a name (default: Reeboot)
+3. **Channels** — optionally link WhatsApp or Signal inline (QR code shown in terminal)
+4. **Web Search** — choose DuckDuckGo (default), Brave, Tavily, Serper, Exa, SearXNG, or None
+
+After setup, the wizard offers to start your agent immediately. On subsequent runs, `reeboot` detects the existing config and starts the agent directly — no flags needed.
+
+To re-run setup: `reeboot setup` (asks before overwriting your existing config).
+
+Open the WebChat URL printed on startup, or send a message to your linked WhatsApp/Signal number.
 
 ---
 
@@ -189,6 +195,91 @@ reeboot uninstall reeboot-github-tools
 }
 ```
 
+---
+
+## Web Search
+
+Reeboot includes a built-in web search extension that registers two agent tools:
+
+- **`fetch_url`** — Always available. Fetches any URL and returns clean readable text (Readability extraction with HTML-strip fallback).
+- **`web_search`** — Available when `search.provider` is not `"none"`. Searches the web via the configured backend and returns an array of `{ title, url, snippet }` results.
+
+### Providers
+
+| Provider | Free Tier | Config |
+|----------|-----------|--------|
+| `duckduckgo` | ✅ Zero config, HTML scraping | No API key needed |
+| `brave` | ✅ 2,000 queries/month free | `BRAVE_API_KEY` or `config.search.apiKey` |
+| `tavily` | ✅ 1,000 queries/month free | `TAVILY_API_KEY` or `config.search.apiKey` |
+| `serper` | ✅ 2,500 queries free | `SERPER_API_KEY` or `config.search.apiKey` |
+| `exa` | ✅ 1,000 queries/month free | `EXA_API_KEY` or `config.search.apiKey` |
+| `searxng` | ✅ Self-hosted (Docker) | `searxngBaseUrl` in config |
+| `none` | — | Disables `web_search`; `fetch_url` still available |
+
+### Configuration
+
+Add a `search` block to `~/.reeboot/config.json`:
+
+```json
+{
+  "search": {
+    "provider": "duckduckgo"
+  }
+}
+```
+
+For API-key providers:
+
+```json
+{
+  "search": {
+    "provider": "brave",
+    "apiKey": "your-brave-api-key"
+  }
+}
+```
+
+Or set the env var instead of storing the key in config:
+
+```bash
+export BRAVE_API_KEY=your-key     # for brave
+export TAVILY_API_KEY=your-key    # for tavily
+export SERPER_API_KEY=your-key    # for serper
+export EXA_API_KEY=your-key       # for exa
+```
+
+### SearXNG (Self-Hosted)
+
+```json
+{
+  "search": {
+    "provider": "searxng",
+    "searxngBaseUrl": "http://localhost:8080"
+  }
+}
+```
+
+Start SearXNG with Docker:
+
+```bash
+docker run -d -p 8080:8080 searxng/searxng
+```
+
+If SearXNG is unreachable at agent startup, reeboot automatically falls back to DuckDuckGo for the session.
+
+### Disabling Web Search
+
+```json
+{
+  "search": {
+    "provider": "none"
+  }
+}
+```
+
+`fetch_url` remains available even when `provider = "none"`.
+
+
 ---
 
 ## WhatsApp Setup
@@ -251,6 +342,59 @@ Then: `reeboot start`
 
 ---
 
+## Bundled Skills
+
+Reeboot ships 15 skills inside the package — no extra install needed. The agent can load them on demand via `load_skill("name")` or you can make them permanently available via config.
+
+| Skill | What it does | Requires |
+|---|---|---|
+| `github` | Issues, PRs, releases, Actions, code search | `gh` CLI + `gh auth login` |
+| `gmail` | Search, read, send, draft, labels, attachments | `gmcli` npm CLI + GCP OAuth |
+| `gcal` | List, create, update, delete calendar events | `gccli` npm CLI + GCP OAuth |
+| `gdrive` | List, read, upload, search Drive files | `gdcli` npm CLI + GCP OAuth |
+| `notion` | Pages, databases, blocks, search | `NOTION_API_KEY` env var |
+| `slack` | Send messages, list channels, thread replies | `SLACK_BOT_TOKEN` env var |
+| `linear` | Issues, projects, teams, cycles | `LINEAR_API_KEY` env var |
+| `hubspot` | Contacts, deals, companies, pipelines | `HUBSPOT_ACCESS_TOKEN` env var |
+| `postgres` | Query, inspect schema, run statements | `psql` CLI + `DATABASE_URL` |
+| `sqlite` | Query, inspect tables, run statements | `sqlite3` CLI + `DATABASE_PATH` |
+| `docker` | Containers, images, compose stacks | `docker` CLI |
+| `files` | Read, write, search local filesystem | bash (built-in) |
+| `reeboot-tasks` | Schedule, list, pause, cancel own tasks | scheduler extension (built-in) |
+| `web-research` | Structured multi-query web research | web-search extension |
+| `send-message` | Send a message to the originating channel | reeboot channels (built-in) |
+
+### Skill configuration
+
+```yaml
+# ~/.reeboot/config.yaml
+skills:
+  permanent: [github, gmail]   # always in context
+  ephemeral_ttl_minutes: 60    # default lifetime for on-demand loads
+```
+
+### Managing skills
+
+```bash
+reeboot skills list             # browse all 15 bundled skills
+reeboot skills update           # pull extended catalog (coming soon)
+```
+
+The agent can also manage its own skills:
+
+```
+User: load the notion skill for 30 minutes
+Agent: → calls load_skill("notion", 30)
+
+User: what integrations do you have available?
+Agent: → calls list_available_skills()
+
+User: unload notion, I'm done
+Agent: → calls unload_skill("notion")
+```
+
+---
+
 ## CLI Reference
 
 ```
@@ -270,6 +414,9 @@ Commands:
 
   packages list         List installed packages
 
+  skills list           List all bundled skills
+  skills update         Update extended skill catalog
+
   channel list          List channels and their status
   channel login <ch>    Authenticate a channel (whatsapp, signal)
   channel logout <ch>   Disconnect a channel
@@ -359,3 +506,67 @@ MIT
 - [npm package](https://www.npmjs.com/package/reeboot)
 - [Docker Hub](https://hub.docker.com/r/reeboot/reeboot)
 - [Architecture decisions](../architecture-decisions.md)
+
+---
+
+## Proactive Agent
+
+Reeboot supports a **proactive agent** mode where the agent can wake itself up, check for tasks, and act without being asked.
+
+### System Heartbeat
+
+The system heartbeat fires at a configurable interval and dispatches a prompt to the agent with the current task snapshot. If the agent has nothing to do, it responds with `IDLE` (silently suppressed). Otherwise, the response is sent to the default channel.
+
+Configure in `~/.reeboot/config.json`:
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": "every 5m",
+    "contextId": "main"
+  }
+}
+```
+
+- `enabled`: Default `false`. Set to `true` to enable.
+- `interval`: Human-friendly interval string (same parser as `schedule_task`). Examples: `"every 5m"`, `"every 1h"`, `"daily"`.
+- `contextId`: Which context the heartbeat runs in. Default `"main"`.
+
+### In-Session Timer Tool
+
+The `timer` tool lets the agent set a **non-blocking** one-shot wait. It returns immediately and fires a new agent turn after the delay:
+
+```
+timer(seconds: 10, message: "Check build status", id: "build-check")
+```
+
+- `seconds`: 1–3600
+- `message`: Included in the wake-up message
+- `id` (optional): If a timer with the same id exists, it is replaced
+
+### In-Session Heartbeat Tool
+
+The `heartbeat` tool starts a periodic non-blocking wake-up:
+
+```
+heartbeat(action: "start", interval_seconds: 60, message: "Deploy check")
+heartbeat(action: "stop")
+heartbeat(action: "status")
+```
+
+- Only one heartbeat is active per session. Starting a new one replaces the previous.
+- `interval_seconds`: 10–3600
+
+### Sleep Interceptor
+
+The extension automatically blocks `sleep` when it is the **sole or last** command in a bash chain, redirecting the agent to use `timer` instead:
+
+| Command | Outcome |
+|---------|---------|
+| `sleep 60` | ❌ Blocked — use `timer(60, msg)` |
+| `npm build && sleep 60` | ❌ Blocked — sleep is last |
+| `sleep 2 && npm start` | ✅ Allowed — sleep is not last |
+| `npm build \|\| sleep 5` | ✅ Allowed — `\|\|` is not a split point |
+
+Disable the interceptor: `REEBOOT_SLEEP_INTERCEPTOR=0 reeboot start`

package/extensions/scheduler-tool.ts

@@ -1,18 +1,134 @@
 /**
  * Scheduler Tool Extension
  *
- * Registers schedule_task, list_tasks, cancel_task tools backed by SQLite.
- * Uses getDb() for DB access and integrates with the Scheduler singleton
- * (injected via pi's extension context or resolved from the global registry).
+ * Registers schedule_task, list_tasks, cancel_task, pause_task, resume_task,
+ * update_task tools backed by SQLite, plus the /tasks slash command.
+ * Uses getDb() for DB access and integrates with the Scheduler singleton.
+ *
+ * Also registers:
+ * - timer: one-shot non-blocking wait (fires pi.sendMessage triggerTurn)
+ * - heartbeat: periodic non-blocking wake-up (start/stop/status)
+ * - bash pre-hook: sleep interceptor (blocks sleep when sole/last command)
+ * - session_shutdown: cleans up all in-session timers and heartbeat
  */
 
 import { Type } from '@sinclair/typebox';
 import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
 
+// ─── isSleepOnlyOrLast ────────────────────────────────────────────────────────
+
+/**
+ * Returns true if sleep is the sole command or the last command in a chain.
+ * Splits on && and single | (not || which is OR-fallback).
+ */
+export function isSleepOnlyOrLast(command: string): boolean {
+  // Split on && and | (pipe) — but not || (double pipe for fallback)
+  const parts = command.trim().split(/&&|(?<!\|)\|(?!\|)/).map((s) => s.trim()).filter(Boolean);
+  if (parts.length === 0) return false;
+  const last = parts[parts.length - 1];
+  return last.startsWith('sleep ') || last === 'sleep';
+}
+
+// ─── TimerManager ─────────────────────────────────────────────────────────────
+
+export class TimerManager {
+  private _timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private _heartbeat: {
+    interval: ReturnType<typeof setInterval>;
+    tickCount: number;
+    message: string;
+    intervalSeconds: number;
+    startedAt: Date;
+  } | null = null;
+
+  // ── Timer ──────────────────────────────────────────────────────────────────
+
+  setTimer(pi: ExtensionAPI, seconds: number, message: string, id: string): void {
+    if (seconds < 1 || seconds > 3600) {
+      throw new Error('seconds must be between 1 and 3600');
+    }
+
+    // Cancel existing timer with same id
+    const existing = this._timers.get(id);
+    if (existing) clearTimeout(existing);
+
+    const handle = setTimeout(() => {
+      this._timers.delete(id);
+      pi.sendMessage(
+        { content: `⏰ Timer ${id} fired: ${message}`, display: true },
+        { triggerTurn: true }
+      );
+    }, seconds * 1000);
+
+    this._timers.set(id, handle);
+  }
+
+  cancelTimer(id: string): void {
+    const handle = this._timers.get(id);
+    if (handle) {
+      clearTimeout(handle);
+      this._timers.delete(id);
+    }
+  }
+
+  // ── Heartbeat ──────────────────────────────────────────────────────────────
+
+  startHeartbeat(pi: ExtensionAPI, intervalSeconds: number, message: string): void {
+    if (intervalSeconds < 10 || intervalSeconds > 3600) {
+      throw new Error('interval_seconds must be between 10 and 3600');
+    }
+
+    // Stop any existing heartbeat
+    this.stopHeartbeat();
+
+    let tickCount = 0;
+    const startedAt = new Date();
+
+    const handle = setInterval(() => {
+      tickCount++;
+      if (this._heartbeat) this._heartbeat.tickCount = tickCount;
+      pi.sendMessage(
+        { content: `💓 Heartbeat tick ${tickCount}: ${message}`, display: true },
+        { triggerTurn: true }
+      );
+    }, intervalSeconds * 1000);
+
+    this._heartbeat = {
+      interval: handle,
+      tickCount: 0,
+      message,
+      intervalSeconds,
+      startedAt,
+    };
+  }
+
+  stopHeartbeat(): void {
+    if (this._heartbeat) {
+      clearInterval(this._heartbeat.interval);
+      this._heartbeat = null;
+    }
+  }
+
+  getHeartbeatStatus(): string {
+    if (!this._heartbeat) return 'No active heartbeat.';
+    const elapsed = Math.round((Date.now() - this._heartbeat.startedAt.getTime()) / 1000);
+    return `Active heartbeat: every ${this._heartbeat.intervalSeconds}s, message="${this._heartbeat.message}", ticks=${this._heartbeat.tickCount}, running for ${elapsed}s`;
+  }
+
+  // ── Cleanup ────────────────────────────────────────────────────────────────
+
+  clearAll(): void {
+    for (const h of this._timers.values()) clearTimeout(h);
+    this._timers.clear();
+    this.stopHeartbeat();
+  }
+}
+
+// ─── Extension default export ─────────────────────────────────────────────────
+
 export default function (pi: ExtensionAPI) {
   // Lazily resolve DB and scheduler to avoid circular imports
   function getTools() {
-    // Dynamic requires deferred to avoid startup issues
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { getDb } = require('../src/db/index.js') as typeof import('../src/db/index.js');
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -24,14 +140,149 @@ export default function (pi: ExtensionAPI) {
     return createSchedulerTools(db, globalScheduler);
   }
 
+  // ─── In-session timer manager ──────────────────────────────────────────────
+
+  const manager = new TimerManager();
+
+  // ─── session_shutdown cleanup ──────────────────────────────────────────────
+
+  pi.on('session_shutdown', () => {
+    manager.clearAll();
+  });
+
+  // ─── Sleep interceptor (bash pre-hook) ────────────────────────────────────
+
+  pi.on('user_bash', (event): any => {
+    if (process.env.REEBOOT_SLEEP_INTERCEPTOR === '0') return;
+    if (isSleepOnlyOrLast(event.command)) {
+      return {
+        result: {
+          content: [
+            {
+              type: 'text',
+              text: 'Blocking sleep command. Use timer(seconds, message) for non-blocking waits.',
+            },
+          ],
+          details: {},
+          isError: true,
+        },
+      };
+    }
+  });
+
+  // ─── timer tool ───────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: 'timer',
+    label: 'Timer',
+    description:
+      'Set a one-shot non-blocking timer. Returns immediately. After the specified delay, fires a new agent turn with the given message. Use instead of sleep.',
+    parameters: Type.Object({
+      seconds: Type.Number({ description: 'Delay in seconds (1–3600)' }),
+      message: Type.String({ description: 'Message to include when the timer fires' }),
+      id: Type.Optional(Type.String({ description: 'Timer id (optional). Same id cancels previous timer.' })),
+    }),
+    execute: async (_callId, params) => {
+      const id = params.id ?? `timer-${Date.now()}`;
+      try {
+        manager.setTimer(pi, params.seconds, params.message, id);
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Timer "${id}" set for ${params.seconds}s: "${params.message}"`,
+            },
+          ],
+          details: { id, seconds: params.seconds, message: params.message },
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: 'text' as const, text: err.message }],
+          details: {},
+          isError: true,
+        };
+      }
+    },
+  });
+
+  // ─── heartbeat tool ───────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: 'heartbeat',
+    label: 'Heartbeat',
+    description:
+      'Manage a periodic non-blocking heartbeat. Actions: start (requires interval_seconds 10–3600 and message), stop, status. Only one heartbeat active at a time.',
+    parameters: Type.Object({
+      action: Type.Union([Type.Literal('start'), Type.Literal('stop'), Type.Literal('status')], {
+        description: 'Action to perform',
+      }),
+      interval_seconds: Type.Optional(
+        Type.Number({ description: 'Interval in seconds (10–3600). Required for start.' })
+      ),
+      message: Type.Optional(
+        Type.String({ description: 'Message to include on each tick. Required for start.' })
+      ),
+    }),
+    execute: async (_callId, params) => {
+      if (params.action === 'start') {
+        const intervalSeconds = params.interval_seconds ?? 60;
+        const message = params.message ?? 'Heartbeat tick';
+        try {
+          manager.startHeartbeat(pi, intervalSeconds, message);
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `Heartbeat started: every ${intervalSeconds}s, message="${message}"`,
+              },
+            ],
+            details: { intervalSeconds, message },
+          };
+        } catch (err: any) {
+          return {
+            content: [{ type: 'text' as const, text: err.message }],
+            details: {},
+            isError: true,
+          };
+        }
+      }
+
+      if (params.action === 'stop') {
+        manager.stopHeartbeat();
+        return {
+          content: [{ type: 'text' as const, text: 'Heartbeat stopped.' }],
+          details: {},
+        };
+      }
+
+      // status
+      const status = manager.getHeartbeatStatus();
+      return {
+        content: [{ type: 'text' as const, text: status }],
+        details: {},
+      };
+    },
+  });
+
+  // ─── schedule_task ────────────────────────────────────────────────────────
+
   pi.registerTool({
     name: 'schedule_task',
     label: 'Schedule Task',
-    description: 'Schedule a recurring task. Provide a cron expression, a prompt, and optionally a contextId.',
+    description:
+      'Schedule a task. Provide a human-friendly schedule string (e.g. "every 30m", "daily", "0 9 * * *", "2026-04-01T09:00:00Z"), a prompt, and optionally contextId and context_mode.',
     parameters: Type.Object({
-      schedule: Type.String({ description: 'Cron expression (e.g. "0 9 * * 1-5" for weekdays at 9am)' }),
+      schedule: Type.String({
+        description:
+          'Schedule: cron expression, ISO datetime, or interval like "every 30m", "hourly", "daily"',
+      }),
       prompt: Type.String({ description: 'Prompt to dispatch to the agent on schedule' }),
-      contextId: Type.Optional(Type.String({ description: 'Context to run in (default: main)' })),
+      contextId: Type.Optional(
+        Type.String({ description: 'Context to run in (default: main)' })
+      ),
+      context_mode: Type.Optional(
+        Type.String({ description: 'Context mode: "shared" (default) or "isolated"' })
+      ),
     }),
     execute: async (_id, params) => {
       const tools = getTools();
@@ -39,10 +290,13 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  // ─── list_tasks ───────────────────────────────────────────────────────────
+
   pi.registerTool({
     name: 'list_tasks',
     label: 'List Tasks',
-    description: 'List all scheduled tasks with their id, schedule, prompt, contextId, enabled status and last run time.',
+    description:
+      'List all scheduled tasks with rich status: id, schedule, prompt, status, next run time (relative), last result, context mode.',
     parameters: Type.Object({}),
     execute: async () => {
       const tools = getTools();
@@ -50,6 +304,8 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  // ─── cancel_task ─────────────────────────────────────────────────────────
+
   pi.registerTool({
     name: 'cancel_task',
     label: 'Cancel Task',
@@ -62,4 +318,100 @@ export default function (pi: ExtensionAPI) {
       return tools.cancel_task(params);
     },
   });
+
+  // ─── pause_task ───────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: 'pause_task',
+    label: 'Pause Task',
+    description: 'Pause a scheduled task. The task will not run until resumed.',
+    parameters: Type.Object({
+      task_id: Type.String({ description: 'Task ID to pause (from list_tasks)' }),
+    }),
+    execute: async (_id, params) => {
+      const tools = getTools();
+      return tools.pause_task(params);
+    },
+  });
+
+  // ─── resume_task ──────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: 'resume_task',
+    label: 'Resume Task',
+    description: 'Resume a paused task. next_run is recomputed from now.',
+    parameters: Type.Object({
+      task_id: Type.String({ description: 'Task ID to resume (from list_tasks)' }),
+    }),
+    execute: async (_id, params) => {
+      const tools = getTools();
+      return tools.resume_task(params);
+    },
+  });
+
+  // ─── update_task ──────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: 'update_task',
+    label: 'Update Task',
+    description:
+      "Update a task's prompt, schedule, or context_mode. If schedule changes, next_run is recomputed.",
+    parameters: Type.Object({
+      task_id: Type.String({ description: 'Task ID to update (from list_tasks)' }),
+      schedule: Type.Optional(Type.String({ description: 'New schedule string' })),
+      prompt: Type.Optional(Type.String({ description: 'New prompt' })),
+      context_mode: Type.Optional(
+        Type.String({ description: 'New context mode: "shared" or "isolated"' })
+      ),
+    }),
+    execute: async (_id, params) => {
+      const tools = getTools();
+      return tools.update_task(params);
+    },
+  });
+
+  // ─── /tasks slash command ─────────────────────────────────────────────────
+
+  pi.registerCommand({
+    name: 'tasks',
+    description:
+      'Task management. Use "/tasks due" to list overdue tasks, or "/tasks" to list all active tasks.',
+    execute: async (args: string) => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { getDb } = require('../src/db/index.js') as typeof import('../src/db/index.js');
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { getTasksDue, formatTasksDue } = require('../src/scheduler.js') as typeof import('../src/scheduler.js');
+
+      const db = getDb();
+      const subCmd = args?.trim().toLowerCase();
+
+      if (subCmd === 'due') {
+        const due = getTasksDue(db);
+        return formatTasksDue(due as any);
+      }
+
+      // List all active tasks
+      const tasks = db
+        .prepare("SELECT * FROM tasks WHERE status='active' ORDER BY next_run ASC")
+        .all() as any[];
+
+      if (tasks.length === 0) {
+        return 'No active tasks.';
+      }
+
+      const now = Date.now();
+      const lines = tasks.map((t: any) => {
+        const nextRunMs = t.next_run ? new Date(t.next_run).getTime() : null;
+        const overdue = nextRunMs && nextRunMs <= now;
+        const rel = overdue
+          ? 'OVERDUE'
+          : nextRunMs
+          ? `in ${Math.round((nextRunMs - now) / 60_000)}m`
+          : 'unknown';
+        return `[${t.id}] ${(t.schedule_value || t.schedule).padEnd(20)} → ${t.prompt.slice(0, 40)} | next: ${rel}`;
+      });
+
+      return lines.join('\n');
+    },
+  });
 }