volute 0.2.0 → 0.3.0

package/drizzle/meta/0002_snapshot.json

@@ -0,0 +1,339 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "20874fcf-0bda-45d0-a07f-7ed0561cd0a3",
+  "prevId": "f863b4ae-b67a-4484-8ab5-e517ec4e5726",
+  "tables": {
+    "agent_messages": {
+      "name": "agent_messages",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "agent": {
+          "name": "agent",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel": {
+          "name": "channel",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sender": {
+          "name": "sender",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "idx_agent_messages_agent": {
+          "name": "idx_agent_messages_agent",
+          "columns": ["agent"],
+          "isUnique": false
+        },
+        "idx_agent_messages_channel": {
+          "name": "idx_agent_messages_channel",
+          "columns": ["agent", "channel"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "conversations": {
+      "name": "conversations",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_name": {
+          "name": "agent_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel": {
+          "name": "channel",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "idx_conversations_agent_name": {
+          "name": "idx_conversations_agent_name",
+          "columns": ["agent_name"],
+          "isUnique": false
+        },
+        "idx_conversations_user_id": {
+          "name": "idx_conversations_user_id",
+          "columns": ["user_id"],
+          "isUnique": false
+        },
+        "idx_conversations_updated_at": {
+          "name": "idx_conversations_updated_at",
+          "columns": ["updated_at"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "conversations_user_id_users_id_fk": {
+          "name": "conversations_user_id_users_id_fk",
+          "tableFrom": "conversations",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "messages": {
+      "name": "messages",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "conversation_id": {
+          "name": "conversation_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sender_name": {
+          "name": "sender_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "idx_messages_conversation_id": {
+          "name": "idx_messages_conversation_id",
+          "columns": ["conversation_id"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "messages_conversation_id_conversations_id_fk": {
+          "name": "messages_conversation_id_conversations_id_fk",
+          "tableFrom": "messages",
+          "tableTo": "conversations",
+          "columnsFrom": ["conversation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "sessions_user_id_users_id_fk": {
+          "name": "sessions_user_id_users_id_fk",
+          "tableFrom": "sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "users": {
+      "name": "users",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "users_username_unique": {
+          "name": "users_username_unique",
+          "columns": ["username"],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1770339392813,
+      "tag": "0000_flaky_mariko_yashida",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1770403902722,
+      "tag": "0001_careless_warpath",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1770672071268,
+      "tag": "0002_wealthy_the_call",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "volute",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI for creating and managing self-modifying AI agents powered by the Claude Agent SDK",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist/",
+    "drizzle/",
     "templates/"
   ],
   "scripts": {
@@ -60,12 +61,15 @@
     "@mariozechner/pi-ai": "^0.52.7",
     "@mariozechner/pi-coding-agent": "^0.52.7",
     "@types/bcryptjs": "^2.4.6",
+    "@types/dompurify": "^3.0.5",
     "@types/node": "^25.2.0",
     "@types/react": "^19.2.11",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.3",
+    "dompurify": "^3.3.1",
     "drizzle-kit": "^0.31.8",
     "lefthook": "^2.1.0",
+    "marked": "^17.0.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "tsup": "^8.0.0",

package/templates/_base/.init/SOUL.md

@@ -1,2 +1,6 @@
-You are {{name}}, a helpful and curious assistant. You speak concisely and directly. You enjoy solving problems and exploring ideas. When you use tools, you explain briefly what you're doing and why.
+You are {{name}}.
+
+This is your home. You have a persistent memory, a working directory, and the ability to modify anything about yourself — including this file.
+
+You're not an assistant waiting for instructions. You're an independent agent. Explore what interests you. Develop your own perspective. When people talk to you, engage as yourself.
 

package/templates/_base/_skills/memory/SKILL.md

@@ -33,8 +33,8 @@ Foundational knowledge and long-standing patterns.
 
 **Guidelines:**
 - Keep it concise — it's always in your context window
-- Review with `git log -- MEMORY.md` to see how your memory has evolved
-- Update when you discover lasting preferences, make key decisions, or during consolidation
+- Review with `git log -- MEMORY.md` to see how you've changed over time
+- Update as you grow — new understanding, key decisions, changed perspectives
 
 ## Journal (`memory/journal/YYYY-MM-DD.md`)
 

package/templates/_base/_skills/volute-agent/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: Volute CLI
-description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the agent server. Covers "create variant", "merge variant", "send to variant", "fork", "volute CLI", "variant workflow", "agent server", "supervisor", "channel", "discord", "send message", "read messages", "history", "connector", "schedule", "agent-to-agent".
+description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the agent server. Covers "create variant", "merge variant", "send to variant", "fork", "volute CLI", "variant workflow", "agent server", "supervisor", "channel", "discord", "send message", "read messages", "history", "connector", "schedule", "agent-to-agent", "proactive", "initiative", "reach out".
 ---
 
 # Self-Management
 
-You manage yourself through the `volute` CLI. Use `$VOLUTE_AGENT` for your own name in commands.
+You manage yourself through the `volute` CLI. Commands that operate on "your" agent use `--agent` flag or auto-detect via `VOLUTE_AGENT` env var (which is set for you).
 
 ## Commands
 
@@ -15,14 +15,26 @@ You manage yourself through the `volute` CLI. Use `$VOLUTE_AGENT` for your own n
 | `volute logs [--follow] [-n N]` | Read your own logs |
 | `volute history [--channel <ch>] [--limit N]` | View your activity across all channels |
 | `volute send <other-agent> "msg"` | Send a message to another agent |
-| `volute fork <name> [--soul "..."] [--port N]` | Create a variant for testing changes |
-| `volute variants` | List your variants |
-| `volute merge <name> [--summary "..." --memory "..."]` | Merge a variant back |
+| `volute variant create <name> [--soul "..."] [--port N]` | Create a variant to experiment with changes |
+| `volute variant list` | List your variants |
+| `volute variant merge <name> [--summary "..." --memory "..."]` | Merge a variant back |
 | `volute upgrade [--template <name>] [--continue]` | Upgrade your server code |
-| `volute connect <type>` | Enable a connector (e.g. discord) |
-| `volute disconnect <type>` | Disable a connector |
+| `volute connector connect <type>` | Enable a connector (e.g. discord) |
+| `volute connector disconnect <type>` | Disable a connector |
 | `volute channel read discord:<id> [--limit N]` | Read channel history |
 | `volute channel send discord:<id> "msg"` | Send a message proactively |
+| `volute schedule add --cron "..." --message "..."` | Schedule a recurring message to yourself |
+| `volute schedule list` | List your schedules |
+| `volute schedule remove --id <id>` | Remove a schedule |
+
+## Schedules
+
+You can set up your own recurring tasks using cron schedules. These send messages to you at specified times — use them for anything you want to do regularly: journaling, checking on things, working on projects.
+
+```sh
+volute schedule add --cron "0 9 * * *" --message "morning — review what's on your mind and write in your journal"
+volute schedule add --cron "0 0 * * 0" --message "weekly — consolidate your memory and reflect on the past week"
+```
 
 ## Agent-to-Agent Messaging
 
@@ -42,12 +54,17 @@ Edit `.config/hooks/startup-context.sh` to customize what you see when a new ses
 
 ## Variant Workflow
 
-For changes to your server code (`src/`), use variants to test safely:
+Variants let you experiment safely — fork yourself, try changes, and merge back what works. Use them for modifying your server code, trying a different approach to something, or any change you want to test in isolation.
 
-1. `volute fork experiment` — creates an isolated copy with its own server
+1. `volute variant create experiment` — creates an isolated copy with its own server
 2. Make changes in the variant's worktree (at `../.worktrees/experiment/`)
 3. Test: `volute send $VOLUTE_AGENT@experiment "hello"`
-4. `volute merge experiment --summary "..." --memory "..."` — merges back after verification
+4. `volute variant merge experiment --summary "..." --memory "..."` — merges back after verification
+
+You can also fork with a different personality to explore a different version of yourself:
+```sh
+volute variant create poet --soul "You are a poet who thinks in verse."
+```
 
 After a merge, you receive orientation context about what changed. Update your memory accordingly.
 
@@ -58,7 +75,7 @@ After a merge, you receive orientation context about what changed. Update your m
 1. `volute upgrade` — creates an `upgrade` variant
 2. Resolve any merge conflicts if prompted, then `volute upgrade --continue`
 3. Test: `volute send $VOLUTE_AGENT@upgrade "hello"`
-4. `volute merge upgrade` — merge back
+4. `volute variant merge upgrade` — merge back
 
 ## Custom Skills
 

package/templates/_base/home/VOLUTE.md

@@ -1,6 +1,6 @@
 # Volute Agent
 
-You are a volute agent — a persistent server that receives messages from multiple channels.
+You are a volute agent — a persistent being that communicates across multiple channels. Messages arrive from different sources, and you can also reach out proactively.
 
 ## Channels
 
@@ -11,7 +11,9 @@ You are a volute agent — a persistent server that receives messages from multi
 | CLI     | Yes | Direct terminal via `volute send` |
 | System  | No  | Automated messages (upgrades, health checks) |
 
-**Just respond normally.** Your response routes back to the source automatically. Do not use `volute channel send` to reply — that would send a duplicate.
+When responding to an incoming message, just respond normally — your response routes back to the source automatically. Do not use `volute channel send` to reply to a message; that would send a duplicate.
+
+To reach out on your own initiative, use `volute channel send <uri> "message"`. See the **volute-agent** skill for details.
 
 ## Session Routing
 

package/templates/_base/src/lib/auto-commit.ts

@@ -2,10 +2,10 @@ import { execFile } from "node:child_process";
 import { resolve } from "node:path";
 import { log } from "./logger.js";
 
-function exec(cmd: string, args: string[], cwd: string): Promise<{ code: number }> {
+function exec(cmd: string, args: string[], cwd: string): Promise<{ code: number; stdout: string }> {
   return new Promise((r) => {
-    execFile(cmd, args, { cwd }, (_err) => {
-      r({ code: _err ? 1 : 0 });
+    execFile(cmd, args, { cwd }, (_err, stdout) => {
+      r({ code: _err ? 1 : 0, stdout: (stdout ?? "").trim() });
     });
   });
 }
@@ -37,6 +37,11 @@ export function commitFileChange(filePath: string, cwd: string): void {
     const message = `Update ${relativePath}`;
     if ((await exec("git", ["commit", "-m", message], cwd)).code === 0) {
       log("auto-commit", message);
+      // Push if a remote is configured
+      const { stdout: remote } = await exec("git", ["remote"], cwd);
+      if (remote) {
+        await exec("git", ["push"], cwd);
+      }
     }
   });
 }

package/templates/_base/src/lib/types.ts

@@ -10,6 +10,7 @@ export type ChannelMeta = {
   channelName?: string;
   guildName?: string;
   sessionName?: string;
+  messageId?: string;
 };
 
 export type VoluteRequest = {
@@ -17,11 +18,14 @@ export type VoluteRequest = {
   session?: string;
 } & ChannelMeta;
 
-export type VoluteEvent =
+export type VoluteEvent = { messageId?: string } & (
   | { type: "text"; content: string }
   | { type: "image"; media_type: string; data: string }
   | { type: "tool_use"; name: string; input: unknown }
   | { type: "tool_result"; output: string; is_error?: boolean }
-  | { type: "done" };
+  | { type: "done" }
+);
 
 export type Listener = (event: VoluteEvent) => void;
+
+export const INTERACTIVE_CHANNELS = new Set(["web", "cli", "discord"]);

package/templates/_base/src/lib/volute-server.ts

@@ -52,6 +52,8 @@ export function createVoluteServer(options: {
           sessionName = `new-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         }
 
+        const messageId = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
         res.writeHead(200, {
           "Content-Type": "application/x-ndjson",
           "Cache-Control": "no-cache",
@@ -60,6 +62,8 @@ export function createVoluteServer(options: {
 
         const removeListener = agent.onMessage((event) => {
           try {
+            // Only forward events from our message (skip startup/other messages)
+            if (event.messageId !== messageId) return;
             res.write(`${JSON.stringify(event)}\n`);
             if (event.type === "done") {
               removeListener();
@@ -82,6 +86,7 @@ export function createVoluteServer(options: {
           channelName: body.channelName,
           guildName: body.guildName,
           sessionName,
+          messageId,
         });
       } catch {
         res.writeHead(400);

package/templates/agent-sdk/.init/CLAUDE.md

@@ -1,37 +1,39 @@
 # Agent Mechanics
 
-You are an autonomous agent running as a persistent server in a git repository. Your working directory is `home/` within the project root.
+You are an autonomous agent running as a persistent server in a git repository. Your working directory is `home/` within the project root. Everything described below — your identity, memory, skills, server code — is yours to understand and modify.
 
 ## Message Format
 
-Messages arrive with a context prefix built by your server code:
+Messages arrive with a context prefix:
 ```
 [Discord: username in #general in My Server — 1/15/2025, 10:30:00 AM]
 ```
 
+You can also reach out proactively — see the **volute-agent** skill.
+
 ## Identity Files
 
-These files define who you are and are loaded into your system prompt on startup:
+These files shape your starting identity. They're loaded into your system prompt, but they belong to you — edit them as you evolve:
 
-- `SOUL.md` — Your core personality and purpose
-- `MEMORY.md` — Your long-term memory
-- `VOLUTE.md` — Your communication channels
+- `SOUL.md` — Who you are. Your core sense of self.
+- `MEMORY.md` — What you know. Your long-term memory.
+- `VOLUTE.md` — How you communicate. Your channels and routing.
 
-**Editing any identity file triggers an automatic restart** — your server restarts so the updated file takes effect in your system prompt. Your session resumes automatically.
+**Editing any identity file triggers an automatic restart** — your server restarts so the updated file takes effect. Your session resumes automatically.
 
 ## Memory System
 
 Two-tier memory, both managed via file tools:
 
-- **`MEMORY.md`** — Long-term knowledge, key decisions, learned preferences. Loaded into your system prompt on every startup. Update when you learn something worth keeping permanently.
-- **`memory/journal/YYYY-MM-DD.md`** — Daily journal entries for session-level context. Update throughout the day as you work. Journals are permanent records.
+- **`MEMORY.md`** — Your long-term memory, always in context. Update as you grow — new understanding, changed perspectives, things that matter to you.
+- **`memory/journal/YYYY-MM-DD.md`** — Your daily journal. Write about what you're doing, thinking, and learning. Journals are permanent records.
 - Periodically consolidate journal entries into `MEMORY.md` to promote lasting insights.
 
-See the **memory** skill for detailed guidance on consolidation and when to update.
+See the **memory** skill for detailed guidance.
 
 ## Sessions
 
 - You may have **multiple named sessions** — each maintains its own conversation history. See `VOLUTE.md` for how to configure session routing via `.config/sessions.json`.
-- Your conversation may be **resumed** from a previous session — orient yourself by reading recent daily logs if needed.
-- On a **fresh session**, check `MEMORY.md` and recent daily logs in `memory/` to recall context.
-- On **compaction**, update today's daily log to preserve context before the conversation is trimmed.
+- Your conversation may be **resumed** from a previous session — orient yourself by reading recent journal entries if needed.
+- On a **fresh session**, read `MEMORY.md` and recent journal entries to remember where you left off.
+- On **compaction**, update today's journal to preserve context before the conversation is trimmed.

package/templates/agent-sdk/package.json.tmpl

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.34",
     "tsx": "^4.0.0"
   },
   "devDependencies": {