clawmon 0.1.2 → 0.2.0

package/bin/clawmon.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+const BASE = process.env.CLAWMON_URL || "http://127.0.0.1:7070";
+
+const [,, cmd, ...args] = process.argv;
+
+async function api(path, opts) {
+  const res = await fetch(`${BASE}${path}`, opts);
+  const body = await res.json();
+  if (!res.ok) {
+    console.error(`Error ${res.status}: ${body.error || JSON.stringify(body)}`);
+    process.exit(1);
+  }
+  return body;
+}
+
+function flag(name) {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+
+function printTable(tasks) {
+  if (!tasks.length) { console.log("No tasks found."); return; }
+  const cols = [
+    { key: "id", label: "ID", w: 14 },
+    { key: "name", label: "Name", w: 30 },
+    { key: "kind", label: "Kind", w: 14 },
+    { key: "status", label: "Status", w: 10 },
+  ];
+  const header = cols.map(c => c.label.padEnd(c.w)).join("  ");
+  console.log(header);
+  console.log("-".repeat(header.length));
+  for (const t of tasks) {
+    const row = cols.map(c => String(t[c.key] ?? "").padEnd(c.w)).join("  ");
+    console.log(row);
+  }
+}
+
+async function main() {
+  switch (cmd) {
+    case "status": {
+      const data = await api("/api/overview");
+      console.log(`Total: ${data.total}  Running: ${data.running}  Failed: ${data.failed}`);
+      if (data.last_updated) {
+        console.log(`Last update: ${new Date(data.last_updated * 1000).toLocaleString()}`);
+      }
+      break;
+    }
+
+    case "tasks": {
+      const status = flag("--status");
+      let tasks;
+      if (status === "running") tasks = await api("/api/tasks/running");
+      else if (status === "failed") tasks = await api("/api/tasks/failed");
+      else tasks = await api("/api/tasks");
+      printTable(tasks);
+      break;
+    }
+
+    case "add": {
+      const name = args.filter(a => !a.startsWith("--"))[0];
+      if (!name) { console.error("Usage: clawmon add <name> [--kind <k>]"); process.exit(1); }
+      const kind = flag("--kind");
+      const body = { name };
+      if (kind) body.kind = kind;
+      const task = await api("/api/tasks", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      console.log(`Created task ${task.id}: ${task.name}`);
+      break;
+    }
+
+    case "update": {
+      const id = args.filter(a => !a.startsWith("--"))[0];
+      if (!id) { console.error("Usage: clawmon update <id> --status <s>"); process.exit(1); }
+      const updates = {};
+      const status = flag("--status");
+      const error = flag("--error");
+      const exitCode = flag("--exit-code");
+      if (status) updates.status = status;
+      if (error) updates.error = error;
+      if (exitCode) updates.exit_code = Number(exitCode);
+      const task = await api(`/api/tasks/${id}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(updates),
+      });
+      console.log(`Updated task ${task.id}: status=${task.status}`);
+      break;
+    }
+
+    case "delete": {
+      const id = args[0];
+      if (!id) { console.error("Usage: clawmon delete <id>"); process.exit(1); }
+      await api(`/api/tasks/${id}`, { method: "DELETE" });
+      console.log(`Deleted task ${id}`);
+      break;
+    }
+
+    case "load": {
+      const file = args[0];
+      if (!file) { console.error("Usage: clawmon load <file.json>"); process.exit(1); }
+      const { readFileSync } = await import("node:fs");
+      const data = JSON.parse(readFileSync(file, "utf-8"));
+      const tasks = Array.isArray(data) ? data : data.tasks;
+      if (!Array.isArray(tasks)) { console.error("JSON must be an array or {tasks: [...]}"); process.exit(1); }
+      const result = await api("/api/tasks/bulk", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tasks }),
+      });
+      console.log(`Bulk load: ${result.created} created, ${result.updated} updated`);
+      break;
+    }
+
+    case "open": {
+      const { exec } = await import("node:child_process");
+      const url = BASE;
+      const platform = process.platform;
+      const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+      exec(`${cmd} ${url}`);
+      console.log(`Opening ${url}`);
+      break;
+    }
+
+    case "help":
+    case undefined:
+    case "--help":
+    case "-h": {
+      console.log(`clawmon — task monitor CLI
+
+Usage:
+  clawmon status                       Overview counts
+  clawmon tasks [--status <s>]         List tasks
+  clawmon add <name> [--kind <k>]      Create task
+  clawmon update <id> --status <s>     Update task
+  clawmon delete <id>                  Delete task
+  clawmon load <file.json>             Bulk load from JSON
+  clawmon open                         Open web UI in browser
+  clawmon help                         Show this help
+
+Environment:
+  CLAWMON_URL   Server URL (default: http://127.0.0.1:7070)`);
+      break;
+    }
+
+    default:
+      console.error(`Unknown command: ${cmd}\nRun "clawmon help" for usage.`);
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/openclaw.plugin.json

@@ -1,11 +1,12 @@
 {
+  "id": "clawmon",
   "name": "clawmon",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local task monitor with web UI — tracks running, stale, and failed tasks",
   "entry": "src/index.ts",
-  "config": {
-    "port": 7070,
-    "db_dir": "~/.openclaw/monitor",
-    "retention_days": 7
+  "configSchema": {
+    "port": { "type": "number", "default": 7070 },
+    "db_dir": { "type": "string", "default": "~/.openclaw/monitor" },
+    "retention_days": { "type": "number", "default": 7 }
   }
 }

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "clawmon",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Local task monitor plugin for OpenClaw",
   "type": "module",
   "main": "src/index.ts",
+  "bin": {
+    "clawmon": "bin/clawmon.js"
+  },
   "files": [
     "src",
     "ui",
+    "bin",
     "openclaw.plugin.json"
   ],
   "scripts": {

package/src/db.ts

@@ -1,9 +1,29 @@
 import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import type { MonitorConfig } from "./config.js";
 
 let db: Database.Database | null = null;
 
+export interface TaskInput {
+  name: string;
+  kind?: string;
+  status?: string;
+  pid?: number;
+  id?: string;
+}
+
+export interface TaskUpdate {
+  name?: string;
+  kind?: string;
+  status?: string;
+  pid?: number;
+  exit_code?: number;
+  error?: string;
+  started_at?: number;
+  finished_at?: number;
+}
+
 export function initDb(config: MonitorConfig): Database.Database {
   mkdirSync(config.dbDir, { recursive: true });
   db = new Database(config.dbPath);
@@ -22,6 +42,13 @@ export function initDb(config: MonitorConfig): Database.Database {
       error TEXT
     )
   `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS webhooks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      url TEXT NOT NULL,
+      enabled INTEGER NOT NULL DEFAULT 1
+    )
+  `);
   return db;
 }
 
@@ -44,3 +71,112 @@ export function query(sql: string, ...params: unknown[]): Record<string, unknown
 export function queryOne(sql: string, ...params: unknown[]): Record<string, unknown> | undefined {
   return (getDb().prepare(sql).get(...params) as Record<string, unknown>) ?? undefined;
 }
+
+export function generateId(): string {
+  return randomBytes(6).toString("hex");
+}
+
+export function insertTask(input: TaskInput): Record<string, unknown> {
+  const id = input.id ?? generateId();
+  const now = Math.floor(Date.now() / 1000);
+  const status = input.status ?? "pending";
+  const startedAt = status === "running" ? now : null;
+
+  getDb().prepare(`
+    INSERT INTO tasks (id, name, kind, status, pid, started_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(id, input.name, input.kind ?? null, status, input.pid ?? null, startedAt, now);
+
+  return queryOne("SELECT * FROM tasks WHERE id = ?", id)!;
+}
+
+export function updateTask(id: string, updates: TaskUpdate): Record<string, unknown> | undefined {
+  const fields: string[] = [];
+  const values: unknown[] = [];
+
+  if (updates.name !== undefined) { fields.push("name = ?"); values.push(updates.name); }
+  if (updates.kind !== undefined) { fields.push("kind = ?"); values.push(updates.kind); }
+  if (updates.status !== undefined) {
+    fields.push("status = ?"); values.push(updates.status);
+    if (updates.status === "running" && updates.started_at === undefined) {
+      fields.push("started_at = ?"); values.push(Math.floor(Date.now() / 1000));
+    }
+    if (updates.status === "done" || updates.status === "failed") {
+      fields.push("finished_at = ?"); values.push(Math.floor(Date.now() / 1000));
+    }
+  }
+  if (updates.pid !== undefined) { fields.push("pid = ?"); values.push(updates.pid); }
+  if (updates.exit_code !== undefined) { fields.push("exit_code = ?"); values.push(updates.exit_code); }
+  if (updates.error !== undefined) { fields.push("error = ?"); values.push(updates.error); }
+  if (updates.started_at !== undefined) { fields.push("started_at = ?"); values.push(updates.started_at); }
+  if (updates.finished_at !== undefined) { fields.push("finished_at = ?"); values.push(updates.finished_at); }
+
+  if (fields.length === 0) return queryOne("SELECT * FROM tasks WHERE id = ?", id);
+
+  fields.push("updated_at = ?");
+  values.push(Math.floor(Date.now() / 1000));
+  values.push(id);
+
+  const result = getDb().prepare(`UPDATE tasks SET ${fields.join(", ")} WHERE id = ?`).run(...values);
+  if (result.changes === 0) return undefined;
+  return queryOne("SELECT * FROM tasks WHERE id = ?", id);
+}
+
+export function deleteTask(id: string): boolean {
+  const result = getDb().prepare("DELETE FROM tasks WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+export function bulkUpsert(tasks: TaskInput[]): { created: number; updated: number } {
+  const d = getDb();
+  const now = Math.floor(Date.now() / 1000);
+  let created = 0;
+  let updated = 0;
+
+  const upsert = d.prepare(`
+    INSERT INTO tasks (id, name, kind, status, pid, started_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      name = excluded.name,
+      kind = excluded.kind,
+      status = excluded.status,
+      pid = excluded.pid,
+      updated_at = excluded.updated_at
+  `);
+
+  const tx = d.transaction(() => {
+    for (const t of tasks) {
+      const id = t.id ?? generateId();
+      const status = t.status ?? "pending";
+      const startedAt = status === "running" ? now : null;
+      const existing = queryOne("SELECT id FROM tasks WHERE id = ?", id);
+      upsert.run(id, t.name, t.kind ?? null, status, t.pid ?? null, startedAt, now);
+      if (existing) updated++; else created++;
+    }
+  });
+
+  tx();
+  return { created, updated };
+}
+
+// --- Webhook CRUD ---
+
+export function getWebhooks(): Record<string, unknown>[] {
+  return query("SELECT * FROM webhooks ORDER BY id");
+}
+
+export function insertWebhook(url: string): Record<string, unknown> {
+  const result = getDb().prepare("INSERT INTO webhooks (url) VALUES (?)").run(url);
+  return queryOne("SELECT * FROM webhooks WHERE id = ?", result.lastInsertRowid)!;
+}
+
+export function deleteWebhook(id: number): boolean {
+  const result = getDb().prepare("DELETE FROM webhooks WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+export function toggleWebhook(id: number, enabled: boolean): Record<string, unknown> | undefined {
+  const result = getDb().prepare("UPDATE webhooks SET enabled = ? WHERE id = ?").run(enabled ? 1 : 0, id);
+  if (result.changes === 0) return undefined;
+  return queryOne("SELECT * FROM webhooks WHERE id = ?", id);
+}

package/src/hooks.ts

@@ -0,0 +1,58 @@
+import { insertTask, updateTask } from "./db.js";
+
+interface PluginApi {
+  on(event: string, handler: (...args: unknown[]) => void): void;
+}
+
+export function registerHooks(api: PluginApi): void {
+  api.on("session_start", (ctx: unknown) => {
+    try {
+      const context = ctx as Record<string, unknown>;
+      const sessionId = (context.sessionId as string) ?? "unknown";
+      const taskId = `agent-${sessionId}`;
+      insertTask({
+        id: taskId,
+        name: `Agent session ${sessionId}`,
+        kind: "agent-session",
+        status: "running",
+      });
+      console.log(`[clawmon] tracking agent session: ${taskId}`);
+    } catch (err) {
+      console.error("[clawmon] session_start hook error:", (err as Error).message);
+    }
+  });
+
+  api.on("session_end", (ctx: unknown) => {
+    try {
+      const context = ctx as Record<string, unknown>;
+      const sessionId = (context.sessionId as string) ?? "unknown";
+      const taskId = `agent-${sessionId}`;
+      const failed = context.error || context.exitCode;
+      updateTask(taskId, {
+        status: failed ? "failed" : "done",
+        error: context.error ? String(context.error) : undefined,
+        exit_code: context.exitCode as number | undefined,
+      });
+      console.log(`[clawmon] session ended: ${taskId} (${failed ? "failed" : "done"})`);
+    } catch (err) {
+      console.error("[clawmon] session_end hook error:", (err as Error).message);
+    }
+  });
+
+  api.on("before_agent_start", (ctx: unknown) => {
+    try {
+      const context = ctx as Record<string, unknown>;
+      if (typeof context.addSystemPrompt === "function") {
+        (context.addSystemPrompt as (hint: string) => void)(
+          "You have access to clawmon task monitoring tools: " +
+          "clawmon_create_task, clawmon_update_task, clawmon_list_tasks, clawmon_bulk_load. " +
+          "Use them to track task progress and view status."
+        );
+      }
+    } catch (err) {
+      console.error("[clawmon] before_agent_start hook error:", (err as Error).message);
+    }
+  });
+
+  console.log("[clawmon] registered lifecycle hooks");
+}

package/src/index.ts

@@ -2,6 +2,8 @@ import { resolveConfig } from "./config.js";
 import { initDb, closeDb } from "./db.js";
 import { startWatcher } from "./watcher.js";
 import { createHttpServer, listenServer } from "./server.js";
+import { registerTools } from "./tools.js";
+import { registerHooks } from "./hooks.js";
 import type { Server } from "node:http";
 
 interface PluginApi {
@@ -10,6 +12,13 @@ interface PluginApi {
     start: () => Promise<void>;
     stop: () => Promise<void>;
   }): void;
+  registerTool?(tool: {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (input: Record<string, unknown>) => unknown;
+  }): void;
+  on?(event: string, handler: (...args: unknown[]) => void): void;
   config?: Record<string, unknown>;
 }
 
@@ -17,6 +26,16 @@ export function register(api: PluginApi): void {
   let stopWatcher: (() => void) | null = null;
   let server: Server | null = null;
 
+  // Register agent tools if the host supports it
+  if (api.registerTool) {
+    registerTools(api as { registerTool: NonNullable<PluginApi["registerTool"]> });
+  }
+
+  // Register lifecycle hooks if the host supports it
+  if (api.on) {
+    registerHooks(api as { on: NonNullable<PluginApi["on"]> });
+  }
+
   api.registerService({
     id: "clawmon",
 

package/src/server.ts

@@ -2,10 +2,15 @@ import { createServer, type Server, type IncomingMessage, type ServerResponse }
 import { readFile } from "node:fs/promises";
 import { join, extname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { query, queryOne } from "./db.js";
+import {
+  query, queryOne,
+  insertTask, updateTask, deleteTask, bulkUpsert,
+  getWebhooks, insertWebhook, deleteWebhook, toggleWebhook,
+} from "./db.js";
+import { fireWebhooks, fireTestWebhook } from "./webhooks.js";
 import type { MonitorConfig } from "./config.js";
 
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 
 const MIME: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
@@ -25,9 +30,9 @@ let startTime = 0;
 export function createHttpServer(config: MonitorConfig): Server {
   startTime = Date.now();
 
-  const server = createServer((req, res) => {
+  const server = createServer(async (req, res) => {
     try {
-      route(req, res, config);
+      await route(req, res, config);
     } catch (err) {
       res.writeHead(500, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ error: "Internal server error" }));
@@ -44,30 +49,136 @@ export function listenServer(server: Server, config: MonitorConfig): Promise<voi
   });
 }
 
-function route(req: IncomingMessage, res: ServerResponse, config: MonitorConfig): void {
+// --- Body parser ---
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    const MAX = 1024 * 1024; // 1MB
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX) { req.destroy(); reject(new Error("Body too large")); return; }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+// --- CORS headers ---
+
+function setCors(res: ServerResponse): void {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+}
+
+// --- Router ---
+
+async function route(req: IncomingMessage, res: ServerResponse, config: MonitorConfig): Promise<void> {
   const url = req.url ?? "/";
   const method = req.method ?? "GET";
 
-  if (method !== "GET") {
-    res.writeHead(405, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Method not allowed" }));
+  setCors(res);
+
+  // Preflight
+  if (method === "OPTIONS") {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  // --- GET routes ---
+  if (method === "GET") {
+    if (url === "/health") return json(res, { status: "ok" });
+    if (url === "/api/overview") return apiOverview(res);
+    if (url === "/api/tasks") return apiAllTasks(res);
+    if (url === "/api/tasks/running") return apiRunningTasks(res);
+    if (url === "/api/tasks/recent") return apiRecentTasks(res);
+    if (url === "/api/tasks/failed") return apiFailedTasks(res);
+    if (url === "/api/system") return apiSystem(res, config);
+    if (url === "/api/webhooks") return json(res, getWebhooks());
+
+    // Static files
+    if (url.startsWith("/static/")) { serveStatic(res, url.slice("/static/".length)); return; }
+
+    // Root → index.html
+    if (url === "/" || url === "/index.html") { serveStatic(res, "index.html"); return; }
+
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
     return;
   }
 
-  // API routes
-  if (url === "/health") return json(res, { status: "ok" });
-  if (url === "/api/overview") return apiOverview(res);
-  if (url === "/api/tasks") return apiAllTasks(res);
-  if (url === "/api/tasks/running") return apiRunningTasks(res);
-  if (url === "/api/tasks/recent") return apiRecentTasks(res);
-  if (url === "/api/tasks/failed") return apiFailedTasks(res);
-  if (url === "/api/system") return apiSystem(res, config);
+  // --- POST routes ---
+  if (method === "POST") {
+    if (url === "/api/tasks") {
+      const body = JSON.parse(await readBody(req));
+      if (!body.name) return jsonError(res, 400, "name is required");
+      const task = insertTask(body);
+      fireWebhooks("task.created", task);
+      return json(res, task, 201);
+    }
+
+    if (url === "/api/tasks/bulk") {
+      const body = JSON.parse(await readBody(req));
+      if (!Array.isArray(body.tasks)) return jsonError(res, 400, "tasks array is required");
+      const result = bulkUpsert(body.tasks);
+      return json(res, result);
+    }
+
+    if (url === "/api/webhooks") {
+      const body = JSON.parse(await readBody(req));
+      if (!body.url) return jsonError(res, 400, "url is required");
+      const hook = insertWebhook(body.url);
+      return json(res, hook, 201);
+    }
 
-  // Static files
-  if (url.startsWith("/static/")) { serveStatic(res, url.slice("/static/".length)); return; }
+    if (url === "/api/webhooks/test") {
+      const result = fireTestWebhook();
+      return json(res, result);
+    }
+  }
 
-  // Root → index.html
-  if (url === "/" || url === "/index.html") { serveStatic(res, "index.html"); return; }
+  // --- PATCH routes ---
+  if (method === "PATCH") {
+    const taskMatch = url.match(/^\/api\/tasks\/([a-zA-Z0-9_-]+)$/);
+    if (taskMatch) {
+      const body = JSON.parse(await readBody(req));
+      const task = updateTask(taskMatch[1], body);
+      if (!task) return jsonError(res, 404, "Task not found");
+      fireWebhooks("task.updated", task);
+      return json(res, task);
+    }
+
+    const webhookMatch = url.match(/^\/api\/webhooks\/(\d+)$/);
+    if (webhookMatch) {
+      const body = JSON.parse(await readBody(req));
+      const hook = toggleWebhook(Number(webhookMatch[1]), body.enabled);
+      if (!hook) return jsonError(res, 404, "Webhook not found");
+      return json(res, hook);
+    }
+  }
+
+  // --- DELETE routes ---
+  if (method === "DELETE") {
+    const taskMatch = url.match(/^\/api\/tasks\/([a-zA-Z0-9_-]+)$/);
+    if (taskMatch) {
+      const existing = queryOne("SELECT * FROM tasks WHERE id = ?", taskMatch[1]);
+      const ok = deleteTask(taskMatch[1]);
+      if (!ok) return jsonError(res, 404, "Task not found");
+      if (existing) fireWebhooks("task.deleted", existing);
+      return json(res, { ok: true });
+    }
+
+    const webhookMatch = url.match(/^\/api\/webhooks\/(\d+)$/);
+    if (webhookMatch) {
+      const ok = deleteWebhook(Number(webhookMatch[1]));
+      if (!ok) return jsonError(res, 404, "Webhook not found");
+      return json(res, { ok: true });
+    }
+  }
 
   res.writeHead(404, { "Content-Type": "application/json" });
   res.end(JSON.stringify({ error: "Not found" }));
@@ -115,15 +226,19 @@ function apiSystem(res: ServerResponse, config: MonitorConfig): void {
 
 // --- Helpers ---
 
-function json(res: ServerResponse, data: unknown): void {
+function json(res: ServerResponse, data: unknown, status = 200): void {
   const body = JSON.stringify(data);
-  res.writeHead(200, {
+  res.writeHead(status, {
     "Content-Type": "application/json; charset=utf-8",
     "Content-Length": Buffer.byteLength(body),
   });
   res.end(body);
 }
 
+function jsonError(res: ServerResponse, status: number, message: string): void {
+  json(res, { error: message }, status);
+}
+
 async function serveStatic(res: ServerResponse, filePath: string): Promise<void> {
   // Prevent directory traversal
   if (filePath.includes("..")) {

package/src/tools.ts

@@ -0,0 +1,128 @@
+import { insertTask, updateTask, query, bulkUpsert } from "./db.js";
+import type { TaskInput } from "./db.js";
+
+interface ToolDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (input: Record<string, unknown>) => unknown;
+}
+
+interface PluginApi {
+  registerTool(tool: ToolDef): void;
+}
+
+export function registerTools(api: PluginApi): void {
+  api.registerTool({
+    name: "clawmon_create_task",
+    description: "Create a new task in the clawmon monitor. Returns the created task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Task name (required)" },
+        kind: { type: "string", description: "Task kind/category" },
+        status: { type: "string", description: "Initial status (default: pending)" },
+        pid: { type: "number", description: "Process ID if applicable" },
+      },
+      required: ["name"],
+    },
+    handler(input) {
+      try {
+        const task = insertTask(input as TaskInput);
+        return { ok: true, task };
+      } catch (err: unknown) {
+        return { ok: false, error: (err as Error).message };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "clawmon_update_task",
+    description: "Update an existing task in the clawmon monitor. Returns the updated task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Task ID (required)" },
+        status: { type: "string", description: "New status" },
+        exit_code: { type: "number", description: "Exit code" },
+        error: { type: "string", description: "Error message" },
+        name: { type: "string", description: "Updated name" },
+        kind: { type: "string", description: "Updated kind" },
+      },
+      required: ["id"],
+    },
+    handler(input) {
+      try {
+        const { id, ...updates } = input as { id: string; [key: string]: unknown };
+        const task = updateTask(id, updates);
+        if (!task) return { ok: false, error: "Task not found" };
+        return { ok: true, task };
+      } catch (err: unknown) {
+        return { ok: false, error: (err as Error).message };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "clawmon_list_tasks",
+    description: "List tasks from the clawmon monitor, optionally filtered by status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", description: "Filter by status (running, pending, done, failed)" },
+        limit: { type: "number", description: "Max results (default: 50)" },
+      },
+    },
+    handler(input) {
+      try {
+        const status = input.status as string | undefined;
+        const limit = (input.limit as number) || 50;
+        let tasks;
+        if (status) {
+          tasks = query("SELECT * FROM tasks WHERE status = ? ORDER BY updated_at DESC LIMIT ?", status, limit);
+        } else {
+          tasks = query("SELECT * FROM tasks ORDER BY updated_at DESC LIMIT ?", limit);
+        }
+        return { ok: true, tasks, count: tasks.length };
+      } catch (err: unknown) {
+        return { ok: false, error: (err as Error).message };
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "clawmon_bulk_load",
+    description: "Bulk upsert tasks into the clawmon monitor. Creates new tasks or updates existing ones by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tasks: {
+          type: "array",
+          description: "Array of task objects with at least a name field",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              name: { type: "string" },
+              kind: { type: "string" },
+              status: { type: "string" },
+              pid: { type: "number" },
+            },
+            required: ["name"],
+          },
+        },
+      },
+      required: ["tasks"],
+    },
+    handler(input) {
+      try {
+        const result = bulkUpsert(input.tasks as TaskInput[]);
+        return { ok: true, ...result };
+      } catch (err: unknown) {
+        return { ok: false, error: (err as Error).message };
+      }
+    },
+  });
+
+  console.log("[clawmon] registered 4 agent tools");
+}

package/src/webhooks.ts

@@ -0,0 +1,56 @@
+import { getWebhooks } from "./db.js";
+
+type WebhookEvent = "task.created" | "task.updated" | "task.deleted";
+
+export function fireWebhooks(event: WebhookEvent, task: Record<string, unknown>): void {
+  const payload = JSON.stringify({
+    event,
+    task,
+    timestamp: Math.floor(Date.now() / 1000),
+  });
+
+  const hooks = getWebhooks().filter((h) => h.enabled === 1);
+  for (const hook of hooks) {
+    fetch(hook.url as string, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: payload,
+    }).catch((err) => {
+      console.error(`[clawmon] webhook error (${hook.url}):`, err.message);
+    });
+  }
+}
+
+export function fireTestWebhook(): { sent_to: number } {
+  const sampleTask = {
+    id: "test-000000000000",
+    name: "Test Task",
+    kind: "test",
+    status: "running",
+    pid: null,
+    started_at: Math.floor(Date.now() / 1000),
+    updated_at: Math.floor(Date.now() / 1000),
+    finished_at: null,
+    exit_code: null,
+    error: null,
+  };
+
+  const hooks = getWebhooks().filter((h) => h.enabled === 1);
+  const payload = JSON.stringify({
+    event: "task.updated" as WebhookEvent,
+    task: sampleTask,
+    timestamp: Math.floor(Date.now() / 1000),
+  });
+
+  for (const hook of hooks) {
+    fetch(hook.url as string, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: payload,
+    }).catch((err) => {
+      console.error(`[clawmon] test webhook error (${hook.url}):`, err.message);
+    });
+  }
+
+  return { sent_to: hooks.length };
+}

package/ui/app.js

@@ -17,6 +17,9 @@
   });
 
   function fetchAndRender() {
+    // Static views (no fetch needed)
+    if (currentView === "docs") { renderDocs(); return; }
+
     var url = endpoints[currentView];
     if (!url) return;
     fetch(url)
@@ -33,7 +36,8 @@
     running: "/api/tasks/running",
     recent: "/api/tasks/recent",
     failed: "/api/tasks/failed",
-    system: "/api/system"
+    system: "/api/system",
+    webhooks: "/api/webhooks"
   };
 
   var renderers = {
@@ -41,7 +45,8 @@
     running: renderRunning,
     recent: renderRecent,
     failed: renderFailed,
-    system: renderSystem
+    system: renderSystem,
+    webhooks: renderWebhooks
   };
 
   function esc(s) {
@@ -133,6 +138,209 @@
       "</ul>";
   }
 
+  // --- Webhooks View ---
+
+  function renderWebhooks(hooks) {
+    var html = "<h2>Webhooks</h2>";
+
+    // Add form
+    html += '<div class="webhook-form">' +
+      '<input type="text" id="webhook-url" class="input" placeholder="https://example.com/webhook" />' +
+      '<button class="btn" onclick="window.__clawmon.addWebhook()">Add Webhook</button>' +
+      '<button class="btn btn-secondary" onclick="window.__clawmon.testWebhooks()">Send Test</button>' +
+      '<span id="webhook-feedback" class="feedback"></span>' +
+    '</div>';
+
+    // List
+    if (hooks.length) {
+      html += "<table><thead><tr>" +
+        "<th>ID</th><th>URL</th><th>Enabled</th><th>Actions</th>" +
+        "</tr></thead><tbody>";
+      hooks.forEach(function (h) {
+        html += "<tr>" +
+          "<td>" + esc(h.id) + "</td>" +
+          "<td>" + esc(h.url) + "</td>" +
+          "<td>" +
+            '<label class="toggle">' +
+              '<input type="checkbox" ' + (h.enabled ? "checked" : "") +
+              ' onchange="window.__clawmon.toggleWebhook(' + h.id + ', this.checked)" />' +
+              '<span class="toggle-slider"></span>' +
+            '</label>' +
+          "</td>" +
+          "<td>" +
+            '<button class="btn btn-small btn-danger" onclick="window.__clawmon.deleteWebhook(' + h.id + ')">Delete</button>' +
+          "</td>" +
+        "</tr>";
+      });
+      html += "</tbody></table>";
+    } else {
+      html += '<div class="empty">No webhooks configured.</div>';
+    }
+
+    // Payload example
+    html += '<div class="docs-section">' +
+      "<h3>Webhook Payload</h3>" +
+      '<pre class="code-block">' + esc(JSON.stringify({
+        event: "task.created | task.updated | task.deleted",
+        task: { id: "abc123", name: "My Task", kind: "build", status: "running" },
+        timestamp: 1234567890
+      }, null, 2)) + "</pre>" +
+    "</div>";
+
+    document.getElementById("content").innerHTML = html;
+  }
+
+  // Expose webhook actions globally
+  window.__clawmon = {
+    addWebhook: function () {
+      var url = document.getElementById("webhook-url").value.trim();
+      if (!url) return;
+      fetch("/api/webhooks", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ url: url })
+      })
+        .then(function (r) { return r.json(); })
+        .then(function () {
+          showFeedback("Webhook added", false);
+          fetchAndRender();
+        })
+        .catch(function () { showFeedback("Failed to add webhook", true); });
+    },
+
+    deleteWebhook: function (id) {
+      fetch("/api/webhooks/" + id, { method: "DELETE" })
+        .then(function () { fetchAndRender(); })
+        .catch(function () { showFeedback("Failed to delete", true); });
+    },
+
+    toggleWebhook: function (id, enabled) {
+      fetch("/api/webhooks/" + id, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ enabled: enabled })
+      })
+        .then(function () { fetchAndRender(); })
+        .catch(function () { showFeedback("Failed to update", true); });
+    },
+
+    testWebhooks: function () {
+      fetch("/api/webhooks/test", { method: "POST" })
+        .then(function (r) { return r.json(); })
+        .then(function (data) {
+          showFeedback("Test sent to " + data.sent_to + " webhook(s)", false);
+        })
+        .catch(function () { showFeedback("Failed to send test", true); });
+    }
+  };
+
+  function showFeedback(msg, isError) {
+    var el = document.getElementById("webhook-feedback");
+    if (!el) return;
+    el.textContent = msg;
+    el.className = "feedback " + (isError ? "feedback-error" : "feedback-ok");
+    setTimeout(function () { if (el) el.textContent = ""; }, 3000);
+  }
+
+  // --- Docs View ---
+
+  function renderDocs() {
+    document.getElementById("content").innerHTML =
+      "<h2>How to Use</h2>" +
+
+      '<div class="docs-section">' +
+        "<h3>CLI Commands</h3>" +
+        '<pre class="code-block">' +
+          "clawmon status                       # Overview counts\n" +
+          "clawmon tasks [--status &lt;s&gt;]         # List tasks\n" +
+          "clawmon add &lt;name&gt; [--kind &lt;k&gt;]      # Create task\n" +
+          "clawmon update &lt;id&gt; --status &lt;s&gt;     # Update task\n" +
+          "clawmon delete &lt;id&gt;                  # Delete task\n" +
+          "clawmon load &lt;file.json&gt;             # Bulk load from JSON\n" +
+          "clawmon open                         # Open web UI in browser\n" +
+          "clawmon help                         # Show help\n\n" +
+          "# Environment: CLAWMON_URL (default http://127.0.0.1:7070)" +
+        "</pre>" +
+      "</div>" +
+
+      '<div class="docs-section">' +
+        "<h3>REST API</h3>" +
+        "<table><thead><tr><th>Method</th><th>Endpoint</th><th>Description</th></tr></thead><tbody>" +
+          "<tr><td>GET</td><td>/api/overview</td><td>Task counts</td></tr>" +
+          "<tr><td>GET</td><td>/api/tasks</td><td>All tasks</td></tr>" +
+          "<tr><td>GET</td><td>/api/tasks/running</td><td>Running tasks</td></tr>" +
+          "<tr><td>GET</td><td>/api/tasks/recent</td><td>Last 50 tasks</td></tr>" +
+          "<tr><td>GET</td><td>/api/tasks/failed</td><td>Failed tasks</td></tr>" +
+          "<tr><td>POST</td><td>/api/tasks</td><td>Create task</td></tr>" +
+          "<tr><td>POST</td><td>/api/tasks/bulk</td><td>Bulk upsert</td></tr>" +
+          "<tr><td>PATCH</td><td>/api/tasks/:id</td><td>Update task</td></tr>" +
+          "<tr><td>DELETE</td><td>/api/tasks/:id</td><td>Delete task</td></tr>" +
+          "<tr><td>GET</td><td>/api/webhooks</td><td>List webhooks</td></tr>" +
+          "<tr><td>POST</td><td>/api/webhooks</td><td>Add webhook</td></tr>" +
+          "<tr><td>PATCH</td><td>/api/webhooks/:id</td><td>Toggle webhook</td></tr>" +
+          "<tr><td>DELETE</td><td>/api/webhooks/:id</td><td>Remove webhook</td></tr>" +
+          "<tr><td>POST</td><td>/api/webhooks/test</td><td>Fire test payload</td></tr>" +
+          "<tr><td>GET</td><td>/api/system</td><td>Version &amp; uptime</td></tr>" +
+          "<tr><td>GET</td><td>/health</td><td>Health check</td></tr>" +
+        "</tbody></table>" +
+      "</div>" +
+
+      '<div class="docs-section">' +
+        "<h3>curl Examples</h3>" +
+        '<pre class="code-block">' +
+          "# Create a task\n" +
+          "curl -X POST http://127.0.0.1:7070/api/tasks \\\n" +
+          '  -H "Content-Type: application/json" \\\n' +
+          "  -d '{\"name\": \"build-app\", \"kind\": \"build\"}'\n\n" +
+          "# Update task status\n" +
+          "curl -X PATCH http://127.0.0.1:7070/api/tasks/TASK_ID \\\n" +
+          '  -H "Content-Type: application/json" \\\n' +
+          "  -d '{\"status\": \"done\", \"exit_code\": 0}'\n\n" +
+          "# Delete a task\n" +
+          "curl -X DELETE http://127.0.0.1:7070/api/tasks/TASK_ID\n\n" +
+          "# Bulk load\n" +
+          "curl -X POST http://127.0.0.1:7070/api/tasks/bulk \\\n" +
+          '  -H "Content-Type: application/json" \\\n' +
+          "  -d '{\"tasks\": [{\"name\": \"t1\"}, {\"name\": \"t2\"}]}'" +
+        "</pre>" +
+      "</div>" +
+
+      '<div class="docs-section">' +
+        "<h3>Agent Tools</h3>" +
+        "<table><thead><tr><th>Tool</th><th>Description</th></tr></thead><tbody>" +
+          "<tr><td>clawmon_create_task</td><td>Create a task. Input: {name, kind?, status?, pid?}</td></tr>" +
+          "<tr><td>clawmon_update_task</td><td>Update a task. Input: {id, status?, exit_code?, error?}</td></tr>" +
+          "<tr><td>clawmon_list_tasks</td><td>List tasks. Input: {status?, limit?}</td></tr>" +
+          "<tr><td>clawmon_bulk_load</td><td>Bulk upsert. Input: {tasks: [...]}</td></tr>" +
+        "</tbody></table>" +
+      "</div>" +
+
+      '<div class="docs-section">' +
+        "<h3>Task JSON Schema</h3>" +
+        '<pre class="code-block">' + esc(JSON.stringify({
+          id: "string (auto-generated 12-char hex)",
+          name: "string (required)",
+          kind: "string | null",
+          status: "pending | running | done | failed | unknown",
+          pid: "number | null",
+          started_at: "unix epoch seconds | null",
+          updated_at: "unix epoch seconds | null",
+          finished_at: "unix epoch seconds | null",
+          exit_code: "number | null",
+          error: "string | null"
+        }, null, 2)) + "</pre>" +
+      "</div>" +
+
+      '<div class="docs-section">' +
+        "<h3>Webhook Payload</h3>" +
+        '<pre class="code-block">' + esc(JSON.stringify({
+          event: "task.created | task.updated | task.deleted",
+          task: { "...": "full task object" },
+          timestamp: 1234567890
+        }, null, 2)) + "</pre>" +
+      "</div>";
+  }
+
   // Initial fetch + polling
   fetchAndRender();
   pollTimer = setInterval(fetchAndRender, 2000);

package/ui/index.html

@@ -15,6 +15,8 @@
         <li class="menu-item" data-view="running">Running Tasks</li>
         <li class="menu-item" data-view="recent">Recent Tasks</li>
         <li class="menu-item" data-view="failed">Failed Tasks</li>
+        <li class="menu-item" data-view="webhooks">Webhooks</li>
+        <li class="menu-item" data-view="docs">How to Use</li>
         <li class="menu-item" data-view="system">System Info</li>
       </ul>
     </nav>

package/ui/styles.css

@@ -197,3 +197,151 @@ tr:last-child td {
   color: #666;
   text-align: center;
 }
+
+/* Docs */
+.docs-section {
+  margin-top: 24px;
+}
+
+.docs-section h3 {
+  font-size: 15px;
+  color: #e94560;
+  margin-bottom: 8px;
+}
+
+.code-block {
+  background: #0d1117;
+  border: 1px solid #0f3460;
+  border-radius: 6px;
+  padding: 16px;
+  font-family: "SF Mono", "Fira Code", "Fira Mono", Menlo, Consolas, monospace;
+  font-size: 13px;
+  color: #c9d1d9;
+  overflow-x: auto;
+  white-space: pre;
+  line-height: 1.5;
+}
+
+/* Webhook form */
+.webhook-form {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  margin-bottom: 16px;
+  flex-wrap: wrap;
+}
+
+.input {
+  background: #0d1117;
+  border: 1px solid #0f3460;
+  border-radius: 4px;
+  color: #e0e0e0;
+  padding: 8px 12px;
+  font-size: 14px;
+  flex: 1;
+  min-width: 250px;
+}
+
+.input:focus {
+  outline: none;
+  border-color: #e94560;
+}
+
+.btn {
+  background: #e94560;
+  color: #fff;
+  border: none;
+  border-radius: 4px;
+  padding: 8px 16px;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.15s;
+  white-space: nowrap;
+}
+
+.btn:hover {
+  background: #d63851;
+}
+
+.btn-secondary {
+  background: #0f3460;
+}
+
+.btn-secondary:hover {
+  background: #1a4a7a;
+}
+
+.btn-small {
+  padding: 4px 10px;
+  font-size: 12px;
+}
+
+.btn-danger {
+  background: #4d1e1e;
+  color: #fc5c65;
+}
+
+.btn-danger:hover {
+  background: #6b2a2a;
+}
+
+/* Toggle switch */
+.toggle {
+  position: relative;
+  display: inline-block;
+  width: 36px;
+  height: 20px;
+}
+
+.toggle input {
+  opacity: 0;
+  width: 0;
+  height: 0;
+}
+
+.toggle-slider {
+  position: absolute;
+  cursor: pointer;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: #2d2d2d;
+  border-radius: 20px;
+  transition: background 0.2s;
+}
+
+.toggle-slider::before {
+  content: "";
+  position: absolute;
+  height: 14px;
+  width: 14px;
+  left: 3px;
+  bottom: 3px;
+  background: #e0e0e0;
+  border-radius: 50%;
+  transition: transform 0.2s;
+}
+
+.toggle input:checked + .toggle-slider {
+  background: #26de81;
+}
+
+.toggle input:checked + .toggle-slider::before {
+  transform: translateX(16px);
+}
+
+/* Feedback */
+.feedback {
+  font-size: 13px;
+  margin-left: 4px;
+}
+
+.feedback-ok {
+  color: #26de81;
+}
+
+.feedback-error {
+  color: #fc5c65;
+}