openvole 0.2.0 → 0.3.0

package/README.md

@@ -1,9 +1,17 @@
-# OpenVole
+<p align="center">
+  <img src="assets/vole.png" alt="OpenVole" width="200">
+</p>
 
-**Micro-agent core. The smallest possible thing that other useful things can be built on top of.**
+<h1 align="center">OpenVole</h1>
 
-[![npm](https://img.shields.io/npm/v/openvole)](https://www.npmjs.com/package/openvole)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+<p align="center">
+  <strong>Micro-agent core. The smallest possible thing that other useful things can be built on top of.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/openvole"><img src="https://img.shields.io/npm/v/openvole" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+</p>
 
 ---
 
@@ -45,7 +53,7 @@ Edit `vole.config.json`:
     }
   ],
   "skills": [],
-  "loop": { "maxIterations": 10, "logLevel": "info" }
+  "loop": { "maxIterations": 25, "compactThreshold": 50 }
 }
 ```
 
@@ -104,11 +112,12 @@ curl -fsSL https://raw.githubusercontent.com/openvole/openvole/main/presets/full
   [Brain Paw] [Channel]  [Tools]   [In-Process]
    Ollama     Telegram   Browser    Compact
    Claude     Slack      Shell      Memory
-   OpenAI     Discord    MCP
-   Gemini     WhatsApp   Email/GitHub/Calendar
+   OpenAI     Discord    MCP        Session
+   Gemini     WhatsApp   Email/Resend/GitHub/Calendar
+   xAI
 ```
 
-19 official Paws: 4 Brain, 4 Channel, 7 Tool, 4 Infrastructure.
+22 official Paws: 5 Brain, 4 Channel, 8 Tool, 4 Infrastructure.
 
 ## Core Concepts
 
@@ -162,6 +171,7 @@ The Brain is a Paw — the core is LLM-ignorant. Swap models by swapping Brain P
 - `@openvole/paw-claude` — Anthropic Claude models
 - `@openvole/paw-openai` — OpenAI models
 - `@openvole/paw-gemini` — Google Gemini models
+- `@openvole/paw-xai` — xAI Grok models
 
 ## Features
 
@@ -182,22 +192,28 @@ The Brain is a Paw — the core is LLM-ignorant. Swap models by swapping Brain P
 
 ### Heartbeat
 
-Periodic wake-up — the Brain checks `HEARTBEAT.md` and decides what to do. No user input needed.
+Periodic wake-up — the Brain checks `HEARTBEAT.md` and decides what to do. No user input needed. Uses cron expressions:
 
 ```json
-{ "heartbeat": { "enabled": true, "intervalMinutes": 30 } }
+{ "heartbeat": { "enabled": true, "cron": "*/30 * * * *" } }
 ```
 
 ### Persistent Scheduling
 
-Brain-created schedules are stored in `.openvole/schedules.json` and survive restarts. The heartbeat is recreated from config on each startup.
+Brain-created schedules use cron expressions and are stored in `.openvole/schedules.json`, surviving restarts. The heartbeat is recreated from config on each startup (intervalMinutes is auto-converted to cron).
+
+```
+"0 13 * * *"     — daily at 1 PM UTC
+"*/30 * * * *"   — every 30 minutes
+"0 9 * * 1"      — every Monday at 9 AM
+```
 
 ### Memory (Source-Isolated)
 
 Persistent memory with daily logs scoped by task source:
 
 ```
-.openvole/memory/
+.openvole/paws/paw-memory/
 ├── MEMORY.md       # Shared long-term facts
 ├── user/           # CLI session logs
 ├── paw/            # Telegram/Slack logs
@@ -206,11 +222,47 @@ Persistent memory with daily logs scoped by task source:
 
 ### Sessions
 
-Conversation continuity across messages. Auto-expiring transcripts per session ID.
+Conversation continuity across messages. Auto-expiring transcripts per session ID. Session data lives in `.openvole/paws/paw-session/`, organized by session ID (e.g., `cli:default/`, `telegram:123/`).
 
 ### MCP Support
 
-Bridge 1000+ MCP servers into the tool registry via `paw-mcp`. MCP tools appear alongside Paw tools — the Brain doesn't know the difference.
+Bridge 1000+ community MCP servers into the tool registry via `paw-mcp`. MCP tools appear alongside Paw tools — the Brain doesn't know the difference.
+
+- MCP tools are **auto-discovered at runtime** as MCP servers connect
+- **Late tool registration** — tools appear after the engine starts, not at boot
+- MCP config lives in `.openvole/paws/paw-mcp/servers.json` (not in the installed package)
+
+Example `.openvole/paws/paw-mcp/servers.json`:
+
+```json
+{
+  "servers": [
+    {
+      "name": "resend",
+      "command": "npx",
+      "args": ["-y", "resend-mcp"],
+      "env": { "RESEND_API_KEY": "$RESEND_API_KEY" }
+    }
+  ]
+}
+```
+
+### Late Tool Registration
+
+Any Paw can discover and register tools at runtime using the `register_tools` mechanism — not just MCP. Tools registered this way appear in the tool registry like any other tool. This is a generic capability of the engine, not an MCP-specific feature.
+
+### Local Paw Config
+
+Each Paw has its own local config directory at `.openvole/paws/<name>/`. The installed npm package stays immutable — all user configuration lives in the local paw directory.
+
+```
+.openvole/paws/
+├── paw-memory/     ← memory data (MEMORY.md, daily logs)
+├── paw-session/    ← session transcripts
+└── paw-mcp/        ← MCP config (servers.json)
+```
+
+Example: `paw-mcp` reads its `servers.json` from `.openvole/paws/paw-mcp/`, not from `node_modules/`.
 
 ### Rate Limiting
 
@@ -230,12 +282,12 @@ Customize agent behavior with optional markdown files in `.openvole/`:
 
 | File | Purpose |
 |------|---------|
-| `BRAIN.md` | Custom system prompt (overrides default) |
+| `BRAIN.md` | Custom system prompt — **overrides the default system prompt entirely** |
 | `SOUL.md` | Agent personality and tone |
 | `USER.md` | User profile and preferences |
 | `AGENT.md` | Operating rules and constraints |
 
-All Brain Paws (Ollama, Claude, OpenAI, Gemini) load these on startup.
+All Brain Paws (Ollama, Claude, OpenAI, Gemini, xAI) load these on startup.
 
 ### Workspace
 
@@ -262,11 +314,11 @@ When context grows too large, `paw-compact` summarizes old messages while preser
 
 Real-time web UI at `localhost:3001` — paws, tools, skills, tasks, schedules, live events.
 
-## Official Paws (19)
+## Official Paws (22)
 
 All paws live in [PawHub](https://github.com/openvole/pawhub) and are installed via npm.
 
-### Brain (4)
+### Brain (5)
 
 | Paw | Purpose |
 |-----|---------|
@@ -274,6 +326,7 @@ All paws live in [PawHub](https://github.com/openvole/pawhub) and are installed
 | `paw-claude` | Anthropic Claude models |
 | `paw-openai` | OpenAI models |
 | `paw-gemini` | Google Gemini models |
+| `paw-xai` | xAI Grok models |
 
 ### Channel (4)
 
@@ -284,7 +337,7 @@ All paws live in [PawHub](https://github.com/openvole/pawhub) and are installed
 | `paw-discord` | Discord bot channel |
 | `paw-whatsapp` | WhatsApp bot channel |
 
-### Tool (7)
+### Tool (8)
 
 | Paw | Purpose |
 |-----|---------|
@@ -293,6 +346,7 @@ All paws live in [PawHub](https://github.com/openvole/pawhub) and are installed
 | `paw-filesystem` | File system operations |
 | `paw-mcp` | MCP server bridge |
 | `paw-email` | Email sending |
+| `paw-resend` | Email via Resend API |
 | `paw-github` | GitHub integration |
 | `paw-calendar` | Calendar integration |
 
@@ -353,8 +407,8 @@ Single `vole.config.json` — plain JSON, no imports:
   "brain": "@openvole/paw-ollama",
   "paws": ["@openvole/paw-ollama", "@openvole/paw-memory"],
   "skills": ["clawhub/summarize"],
-  "loop": { "maxIterations": 10, "logLevel": "info" },
-  "heartbeat": { "enabled": false, "intervalMinutes": 30 },
+  "loop": { "maxIterations": 25, "compactThreshold": 50 },
+  "heartbeat": { "enabled": false, "cron": "*/30 * * * *" },
   "toolProfiles": { "paw": { "deny": ["shell_exec"] } }
 }
 ```
@@ -367,6 +421,29 @@ OpenVole loads [OpenClaw](https://openclaw.ai) skills natively — same `SKILL.m
 npx vole clawhub install summarize
 ```
 
+## .openvole Directory Structure
+
+```
+.openvole/
+├── paws/
+│   ├── paw-memory/          ← memory data
+│   │   ├── MEMORY.md
+│   │   └── user/, paw/, heartbeat/
+│   ├── paw-session/         ← session transcripts
+│   │   └── cli:default/, telegram:123/
+│   └── paw-mcp/             ← MCP config
+│       └── servers.json
+├── workspace/               ← agent scratch space
+├── skills/                  ← local and clawhub skills
+├── vault.json               ← encrypted key-value store
+├── schedules.json           ← persistent cron schedules
+├── BRAIN.md                 ← custom system prompt
+├── SOUL.md                  ← agent personality
+├── USER.md                  ← user profile
+├── AGENT.md                 ← operating rules
+└── HEARTBEAT.md             ← recurring job definitions
+```
+
 ## Philosophy
 
 > **If it connects to something, it's a Paw.**

package/dist/cli.js

@@ -575,11 +575,13 @@ var init_scheduler = __esm({
       setTickHandler(handler) {
         this.tickHandler = handler;
       }
-      /** Load schedule data from disk without starting cron jobs (for read-only access) */
+      /** Load schedule data from disk without starting cron jobs (for read-only access). Never persists. */
       async loadFromDisk() {
         if (!this.savePath) return;
+        const savedPath = this.savePath;
+        this.savePath = void 0;
         try {
-          const raw = await fs3.readFile(this.savePath, "utf-8");
+          const raw = await fs3.readFile(savedPath, "utf-8");
           const persisted = JSON.parse(raw);
           for (const s of persisted) {
             const job = new Cron(s.cron, { timezone: "UTC", paused: true }, () => {
@@ -594,6 +596,7 @@ var init_scheduler = __esm({
           }
         } catch {
         }
+        this.savePath = savedPath;
       }
       /** Load persisted schedules from disk and restart their jobs */
       async restore() {
@@ -2654,6 +2657,20 @@ var PawRegistry = class {
       const { type } = params;
       return this.handleQuery(type);
     });
+    transport.onRequest("register_tools", async (params) => {
+      const { tools } = params;
+      if (tools && tools.length > 0) {
+        const toolDefs = tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          parameters: {},
+          execute: async (toolParams) => this.executeRemoteTool(pawName, t.name, toolParams)
+        }));
+        this.toolRegistry.register(pawName, toolDefs, false);
+        logger12.info(`Paw "${pawName}" late-registered ${tools.length} tool(s)`);
+      }
+      return { ok: true };
+    });
     transport.onRequest("create_task", async (params) => {
       const { input, source, sessionId, metadata } = params;
       if (!this.taskQueue) {
@@ -2736,6 +2753,18 @@ var PawRegistry = class {
         if (registration.hooks?.bootstrap) {
           this.bootstrapPaws.push(pawName);
         }
+        if (registration.hooks?.perceive) {
+          const config = this.paws.get(pawName)?.config;
+          const hookConfig = config?.hooks?.perceive;
+          const hasTools = (registration.tools?.length ?? 0) > 0;
+          this.perceiveHooks.push({
+            pawName,
+            order: hookConfig?.order ?? 100,
+            pipeline: hookConfig?.pipeline ?? true,
+            hasTools
+          });
+          this.perceiveHooks.sort((a, b) => a.order - b.order);
+        }
         if (registration.hooks?.observe) {
           this.observeHookPaws.push(pawName);
         }
@@ -3107,11 +3136,12 @@ async function initProject(projectRoot) {
   await fs10.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
   await fs10.mkdir(path11.join(projectRoot, ".openvole", "skills"), { recursive: true });
   await fs10.mkdir(path11.join(projectRoot, ".openvole", "skills", "clawhub"), { recursive: true });
-  await fs10.mkdir(path11.join(projectRoot, ".openvole", "memory"), { recursive: true });
-  await fs10.mkdir(path11.join(projectRoot, ".openvole", "sessions"), { recursive: true });
   await fs10.mkdir(path11.join(projectRoot, ".openvole", "workspace"), { recursive: true });
+  await fs10.mkdir(path11.join(projectRoot, ".openvole", "paws", "paw-memory"), { recursive: true });
+  await fs10.mkdir(path11.join(projectRoot, ".openvole", "paws", "paw-session"), { recursive: true });
+  await fs10.mkdir(path11.join(projectRoot, ".openvole", "paws", "paw-mcp"), { recursive: true });
   await fs10.writeFile(
-    path11.join(projectRoot, ".openvole", "memory", "MEMORY.md"),
+    path11.join(projectRoot, ".openvole", "paws", "paw-memory", "MEMORY.md"),
     "# Memory\n\nLong-term memory for the agent. Store important facts, user preferences, and decisions here.\n",
     "utf-8"
   );
@@ -3156,10 +3186,12 @@ async function initProject(projectRoot) {
   }
   logger15.info("Created vole.config.json");
   logger15.info("Created .openvole/");
-  logger15.info("  skills/        \u2014 local and ClawHub skills");
-  logger15.info("  memory/        \u2014 agent memory (MEMORY.md + daily logs)");
-  logger15.info("  sessions/      \u2014 session transcripts");
-  logger15.info("Created HEARTBEAT.md");
+  logger15.info("  skills/                \u2014 local and ClawHub skills");
+  logger15.info("  workspace/             \u2014 agent scratch space");
+  logger15.info("  paws/paw-memory/       \u2014 agent memory (MEMORY.md + daily logs)");
+  logger15.info("  paws/paw-session/      \u2014 session transcripts");
+  logger15.info("  paws/paw-mcp/          \u2014 MCP server config");
+  logger15.info("Created identity files (BRAIN.md, SOUL.md, USER.md, AGENT.md, HEARTBEAT.md)");
   logger15.info("Created .env");
   logger15.info("");
   logger15.info("Next: install paws and start");