openvole 0.3.1 → 0.3.2

package/README.md

@@ -26,8 +26,11 @@ A fresh OpenVole installation has zero tools, zero skills, zero opinions. This i
 ```bash
 mkdir my-agent && cd my-agent
 npm init -y
-npm install openvole @openvole/paw-ollama @openvole/paw-memory @openvole/paw-dashboard
+npm install openvole
 npx vole init
+npx vole paw add @openvole/paw-ollama
+npx vole paw add @openvole/paw-memory
+npx vole paw add @openvole/paw-dashboard
 ```
 
 Edit `vole.config.json`:
@@ -91,23 +94,23 @@ curl -fsSL https://raw.githubusercontent.com/openvole/openvole/main/presets/full
                               |
                               v
 ┌─────────────────────────────────────────────────────────────┐
-│                       VoleEngine                             │
-│                                                              │
-│   Tool Registry ──── Skill Registry ──── Paw Registry        │
-│        |                   |                  |              │
+│                       VoleEngine                            │
+│                                                             │
+│   Tool Registry ──── Skill Registry ──── Paw Registry       │
+│        |                   |                  |             │
 │   ┌────────────────────────────────────────────────┐        │
-│   │              Agent Loop (per task)              │        │
-│   │                                                 │        │
+│   │              Agent Loop (per task)             │        │
+│   │                                                │        │
 │   │   PERCEIVE ─── THINK ─── ACT ─── OBSERVE       │        │
-│   │       |           |        |         |          │        │
-│   │   Enrich      Brain    Execute   Process        │        │
-│   │   context     plans    tools     results        │        │
-│   │                                                 │        │
-│   └─────────────────────────────────────────────────┘        │
-│                                                              │
-│   Task Queue ──── Scheduler ──── Message Bus                 │
-│                                                              │
-└──────┬──────────┬──────────┬──────────┬──────────────────────┘
+│   │       |           |        |         |         │        │
+│   │   Enrich      Brain    Execute   Process       │        │
+│   │   context     plans    tools     results       │        │
+│   │                                                │        │
+│   └────────────────────────────────────────────────┘        │
+│                                                             │
+│   Task Queue ──── Scheduler ──── Message Bus                │
+│                                                             │
+└──────┬──────────┬──────────┬──────────┬─────────────────────┘
        |          |          |          |
   [Brain Paw] [Channel]  [Tools]   [In-Process]
    Ollama     Telegram   Browser    Compact
@@ -141,7 +144,7 @@ Perceive → Think → Act → Observe → loop
 **Paws are tool providers.** They connect OpenVole to the outside world — APIs, databases, browsers, messaging platforms. Each Paw runs in an isolated subprocess with capability-based permissions.
 
 ```bash
-npm install @openvole/paw-telegram
+npx vole paw add @openvole/paw-telegram
 ```
 
 ### Skills
@@ -312,7 +315,15 @@ When context grows too large, `paw-compact` summarizes old messages while preser
 
 ### Dashboard
 
-Real-time web UI at `localhost:3001` — paws, tools, skills, tasks, schedules, live events.
+Real-time web UI — powered by `paw-dashboard`, another Paw you install like any other. Shows paws, tools, skills, tasks, schedules, and live events.
+
+```bash
+npx vole paw add @openvole/paw-dashboard
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/openvole/openvole/main/assets/example/paw-dashboard/paw-dashboard.png" alt="OpenVole Dashboard" width="800">
+</p>
 
 ## Official Paws (22)
 
@@ -362,7 +373,8 @@ All paws live in [PawHub](https://github.com/openvole/pawhub) and are installed
 Install from npm:
 
 ```bash
-npm install @openvole/paw-telegram @openvole/paw-browser
+npx vole paw add @openvole/paw-telegram
+npx vole paw add @openvole/paw-browser
 ```
 
 ## CLI
@@ -444,6 +456,37 @@ npx vole clawhub install summarize
 └── HEARTBEAT.md             ← recurring job definitions
 ```
 
+## OpenVole vs OpenClaw
+
+Both are open-source AI agent frameworks. Different philosophies, many shared concepts.
+
+| | OpenVole | OpenClaw |
+|---|---|---|
+| **Philosophy** | Microkernel — empty core, everything is a plugin | Batteries-included — 25 built-in tools |
+| **Core size** | ~60KB | ~8MB |
+| **Skills** | SKILL.md (same format, compatible) | SKILL.md |
+| **Skill marketplace** | ClawHub-compatible (`vole clawhub install`) | ClawHub (13K+ skills) |
+| **Skill loading** | Progressive on-demand | Progressive on-demand |
+| **Brain/LLM** | External Paw — core is LLM-ignorant | Configurable provider in core |
+| **Brain options** | 5 (Ollama, Claude, OpenAI, Gemini, xAI) | Multi-provider with fallback chains |
+| **Heartbeat** | HEARTBEAT.md + cron | HEARTBEAT.md + cron |
+| **Memory** | Source-isolated (user/paw/heartbeat scoped) | Shared (no source isolation) |
+| **Identity files** | BRAIN.md, SOUL.md, USER.md, AGENT.md | SOUL.md, USER.md, AGENTS.md |
+| **MCP support** | Via Paw with auto-discovery + late registration | Native in core |
+| **Channels** | 4 (Telegram, Slack, Discord, WhatsApp) | 20+ (WhatsApp, iMessage, Signal, etc.) |
+| **Plugin isolation** | Subprocess sandbox + capability permissions | Optional Docker sandbox |
+| **Tool profiles** | Per-source deny/allow lists | Channel sandboxing |
+| **Scheduling** | Cron-based, persistent, Brain-initiated | Cron + heartbeat |
+| **Sessions** | Per-session transcripts with auto-expiry | Built-in session keys |
+| **Vault** | AES-256 encrypted, write-once, metadata | N/A (env vars) |
+| **Dashboard** | Real-time web UI | Gateway web UI |
+| **CLI** | `vole` (start/run/tool call/clawhub/skill) | `openclaw` |
+| **Config** | Single JSON file | Single JSON file |
+
+OpenVole is a newborn — a tiny vole just getting started. We share the same skill format, the same heartbeat pattern, and the same MCP ecosystem as OpenClaw. Skills written for one work on the other.
+
+We're building something small, modular, and community-driven. If you like the microkernel approach — where every piece is a Paw you can swap, extend, or build yourself — come join us. Try it out, build a Paw, write a Skill, break things, and help this little vole grow.
+
 ## Philosophy
 
 > **If it connects to something, it's a Paw.**

package/dist/cli.js

@@ -485,6 +485,19 @@ var init_task = __esm({
         }
         return false;
       }
+      /** Cancel all queued tasks (for shutdown) */
+      cancelAll() {
+        while (this.queue.length > 0) {
+          const task = this.queue.shift();
+          task.status = "cancelled";
+          task.completedAt = Date.now();
+          this.completed.push(task);
+          this.bus.emit("task:cancelled", { taskId: task.id });
+        }
+        for (const task of this.running.values()) {
+          task.status = "cancelled";
+        }
+      }
       /** Get all tasks (queued + running + completed) */
       list() {
         return [
@@ -612,7 +625,8 @@ var init_scheduler = __esm({
           if (persisted.length > 0) {
             logger4.info(`Restored ${persisted.length} schedule(s) from disk`);
           }
-        } catch {
+        } catch (err) {
+          logger4.warn(`Could not restore schedules: ${err}`);
         }
       }
       /** Create or replace a recurring schedule */
@@ -655,8 +669,9 @@ var init_scheduler = __esm({
           createdAt
         }));
       }
-      /** Clear all schedules (for shutdown) */
+      /** Clear all schedules (for shutdown). Disables persistence so the file is never overwritten. */
       clearAll() {
+        this.savePath = void 0;
         for (const entry of this.schedules.values()) {
           entry.job.stop();
         }
@@ -665,16 +680,29 @@ var init_scheduler = __esm({
       }
       /** Save schedules to disk */
       async persist() {
-        if (!this.savePath) return;
+        const targetPath = this.savePath;
+        if (!targetPath) return;
         const toSave = Array.from(this.schedules.values()).filter((s) => s.id !== "__heartbeat__").map(({ id, input, cron, createdAt }) => ({
           id,
           input,
           cron,
           createdAt
         }));
+        if (toSave.length === 0) {
+          try {
+            const existing = await fs3.readFile(targetPath, "utf-8");
+            const parsed = JSON.parse(existing);
+            if (parsed.length > 0) {
+              logger4.warn(`Refusing to overwrite ${parsed.length} persisted schedule(s) with empty list`);
+              return;
+            }
+          } catch {
+          }
+        }
         try {
-          await fs3.mkdir(path3.dirname(this.savePath), { recursive: true });
-          await fs3.writeFile(this.savePath, JSON.stringify(toSave, null, 2) + "\n", "utf-8");
+          await fs3.mkdir(path3.dirname(targetPath), { recursive: true });
+          await fs3.writeFile(targetPath, JSON.stringify(toSave, null, 2) + "\n", "utf-8");
+          logger4.debug(`Persisted ${toSave.length} schedule(s) to disk`);
         } catch (err) {
           logger4.error(`Failed to persist schedules: ${err}`);
         }
@@ -2042,8 +2070,14 @@ var IpcTransport = class {
     this.handlers.clear();
   }
   send(message) {
+    if (this.disposed) return;
     if (this.type === "ipc") {
-      this.childProcess.send?.(message);
+      try {
+        if (this.childProcess.connected) {
+          this.childProcess.send?.(message);
+        }
+      } catch {
+      }
     } else {
       const json = JSON.stringify(message);
       const header = `Content-Length: ${Buffer.byteLength(json)}\r
@@ -2876,6 +2910,7 @@ async function createEngine(projectRoot, options) {
       rateLimiter
     });
   });
+  let shuttingDown = false;
   const engine = {
     bus,
     toolRegistry,
@@ -2886,10 +2921,12 @@ async function createEngine(projectRoot, options) {
     config,
     async start() {
       engineLogger.info("Starting OpenVole...");
+      const headless = options?.headless ?? false;
       if (config.brain) {
       } else {
         engineLogger.info("No Brain Paw configured \u2014 Think step will be a no-op");
       }
+      const headlessSkipPatterns = ["paw-dashboard", "paw-telegram", "paw-slack", "paw-discord", "paw-whatsapp"];
       const pawConfigs = config.paws.map(normalizePawConfig);
       const brainConfig = pawConfigs.find((p) => p.name === config.brain);
       const subprocessPaws = pawConfigs.filter(
@@ -2907,15 +2944,18 @@ async function createEngine(projectRoot, options) {
           pawRegistry.setBrain("");
         }
       }
-      for (const pawConfig of subprocessPaws) {
-        await pawRegistry.load(pawConfig);
-      }
+      const pawsToLoad = headless ? subprocessPaws.filter((p) => !headlessSkipPatterns.some((pat) => p.name.includes(pat))) : subprocessPaws;
+      await Promise.all(pawsToLoad.map((pawConfig) => pawRegistry.load(pawConfig)));
       for (const skillName of config.skills) {
         await skillRegistry.load(skillName);
       }
       skillRegistry.resolve();
-      await scheduler.restore();
-      if (config.heartbeat.enabled) {
+      if (!headless) {
+        await scheduler.restore();
+      } else {
+        await scheduler.loadFromDisk();
+      }
+      if (config.heartbeat.enabled && !headless) {
         const heartbeatMdPath = path10.resolve(projectRoot, ".openvole", "HEARTBEAT.md");
         const heartbeatCron = `*/${config.heartbeat.intervalMinutes} * * * *`;
         scheduler.add(
@@ -2946,8 +2986,11 @@ ${heartbeatContent}` : "Heartbeat wake-up. Check active skills and decide if any
       taskQueue.enqueue(input, source, sessionId ? { sessionId } : void 0);
     },
     async shutdown() {
+      if (shuttingDown) return;
+      shuttingDown = true;
       engineLogger.info("Shutting down...");
       scheduler.clearAll();
+      taskQueue.cancelAll();
       for (const paw of pawRegistry.list()) {
         await pawRegistry.unload(paw.name);
       }
@@ -3097,7 +3140,7 @@ async function startInteractive(projectRoot) {
   process.on("SIGTERM", gracefulShutdown);
 }
 async function runSingle(projectRoot, input) {
-  const engine = await createEngine(projectRoot);
+  const engine = await createEngine(projectRoot, { headless: true });
   await engine.start();
   engine.run(input);
   return new Promise((resolve7) => {
@@ -3837,7 +3880,14 @@ async function handleClawHubCommand(args, projectRoot) {
           logger15.info(`  requires env: ${definition.requires.env.join(", ")}`);
         }
       } else {
-        logger15.warn(`Installed "${skillName}" but could not parse SKILL.md \u2014 add to vole.config.json manually`);
+        const fsCheck = await import("fs/promises");
+        const pluginJsonPath = path11.resolve(projectRoot, ".openvole", "skills", "clawhub", skillDir ?? skillName, "openclaw.plugin.json");
+        try {
+          await fsCheck.access(pluginJsonPath);
+          logger15.error(`"${skillName}" is an OpenClaw plugin, not a skill. OpenVole does not support OpenClaw plugins \u2014 use Paws instead.`);
+        } catch {
+          logger15.warn(`Installed "${skillName}" but could not parse SKILL.md \u2014 add to vole.config.json manually`);
+        }
       }
       break;
     }