volute 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mimsy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# Volute
+
+A CLI for creating and managing persistent, self-modifying AI agents.
+
+Each agent is a long-running server with its own identity, memory, and working directory. Agents can read and write their own files, remember things across conversations, and — most importantly — fork themselves to test changes in isolation before merging back. Talk to them from the terminal, the web dashboard, or Discord.
+
+Built on the [Anthropic Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk).
+
+## Quickstart
+
+```sh
+npm install -g volute
+
+# Start the daemon (manages all your agents)
+volute up
+
+# Create an agent
+volute create atlas
+
+# Start it
+volute start atlas
+
+# Talk to it
+volute send atlas "hey, what can you do?"
+```
+
+You now have a running AI agent with persistent memory, auto-committing file changes, and session resume across restarts. Open `http://localhost:4200` for the web dashboard.
+
+## The daemon
+
+One background process runs everything. `volute up` starts it; `volute down` stops it.
+
+```sh
+volute up              # start (default port 4200)
+volute up --port 8080  # custom port
+volute down            # stop all agents and shut down
+```
+
+The daemon handles agent lifecycle, crash recovery (auto-restarts after 3 seconds), connector processes, scheduled messages, and the web dashboard.
+
+## Agents
+
+### Lifecycle
+
+```sh
+volute create atlas           # scaffold a new agent
+volute start atlas            # start it
+volute stop atlas             # stop it
+volute status                 # list all agents
+volute status atlas           # check one
+volute logs atlas --follow    # tail logs
+volute delete atlas           # remove from registry
+volute delete atlas --force   # also delete files
+```
+
+### Sending messages
+
+```sh
+volute send atlas "what's on your mind?"
+```
+
+Responses stream back to your terminal in real time. The agent knows which channel each message came from — CLI, web, Discord, or system — and routes its response back to the source.
+
+### Anatomy of an agent
+
+```
+~/.volute/agents/atlas/
+├── home/                  # the agent's working directory (its cwd)
+│   ├── SOUL.md            # personality and system prompt
+│   ├── MEMORY.md          # long-term memory, always in context
+│   ├── VOLUTE.md          # channel routing docs
+│   └── memory/            # daily logs (YYYY-MM-DD.md)
+├── src/                   # agent server code
+├── volute.json            # agent config (model, etc.)
+└── .volute/               # runtime state, session, logs
+```
+
+**`SOUL.md`** is the identity. This is the core of the system prompt. Edit it to change how the agent thinks and speaks.
+
+**`MEMORY.md`** is long-term memory, always included in context. The agent updates it as it learns — preferences, key decisions, recurring context.
+
+**Daily logs** (`memory/YYYY-MM-DD.md`) are working memory. Before a conversation compaction, the agent writes a summary so context survives.
+
+**Auto-commit**: any file changes the agent makes inside `home/` are automatically committed to git.
+
+**Session resume**: if the agent restarts, it picks up where it left off.
+
+## Variants
+
+This is the interesting part. Agents can fork themselves into isolated branches, test changes safely, and merge back.
+
+```sh
+# Create a variant — gets its own git worktree and running server
+volute fork atlas experiment
+
+# Talk to the variant directly
+volute send atlas@experiment "try a different approach"
+
+# List all variants
+volute variants atlas
+
+# Merge it back (verifies, merges, cleans up, restarts the main agent)
+volute merge atlas experiment --summary "improved response style"
+```
+
+What happens:
+
+1. **Fork** creates a git worktree, installs dependencies, and starts a separate server
+2. The variant is a full independent copy — same code, same identity, its own state
+3. **Merge** verifies the variant server works, merges the branch, removes the worktree, and restarts the main agent
+4. After restart, the agent receives orientation context about what changed
+
+You can fork with a custom personality:
+
+```sh
+volute fork atlas poet --soul "You are a poet who responds only in verse."
+```
+
+Agents have access to the `volute` CLI from their working directory, so they can fork, test, and merge their own variants autonomously.
+
+## Connectors
+
+Connect agents to external services.
+
+### Discord
+
+```sh
+# Set the bot token (shared across agents, or per-agent with --agent)
+volute env set DISCORD_TOKEN <your-bot-token>
+
+# Connect
+volute connect discord atlas
+
+# Disconnect
+volute disconnect discord atlas
+```
+
+The agent receives Discord messages and responds in-channel. Tool calls are filtered out — Discord users see clean text responses.
+
+### Channel commands
+
+Read from and write to channels directly:
+
+```sh
+volute channel read discord:123456789         # recent messages
+volute channel send discord:123456789 "hello" # send a message
+```
+
+## Schedules
+
+Cron-based scheduled messages — daily check-ins, periodic tasks, whatever you need.
+
+```sh
+volute schedule add atlas \
+  --cron "0 9 * * *" \
+  --message "good morning — write your daily log"
+
+volute schedule list atlas
+volute schedule remove atlas --id <schedule-id>
+```
+
+## Environment variables
+
+Manage secrets and config. Supports shared (all agents) and per-agent scoping.
+
+```sh
+volute env set API_KEY sk-abc123                # shared
+volute env set API_KEY sk-xyz789 --agent atlas   # agent-specific override
+volute env list --agent atlas                    # see effective config
+volute env remove API_KEY
+```
+
+## Web dashboard
+
+The daemon serves a web UI at `http://localhost:4200` (or whatever port you chose).
+
+- Real-time chat with full tool call visibility
+- File browser and editor
+- Log streaming
+- Connector and schedule management
+- Variant status
+- First user to register becomes admin
+
+## Upgrading agents
+
+When the Volute template updates, you can upgrade agents without touching their identity:
+
+```sh
+volute upgrade atlas          # creates an "upgrade" variant
+# resolve conflicts if needed, then:
+volute upgrade atlas --continue
+# test:
+volute send atlas@upgrade "are you working?"
+# merge:
+volute merge atlas upgrade
+```
+
+Your agent's `SOUL.md` and `MEMORY.md` are never overwritten.
+
+## Templates
+
+Two built-in templates:
+
+- **`agent-sdk`** (default) — Anthropic Claude Agent SDK
+- **`pi`** — [pi-coding-agent](https://github.com/nicepkg/pi) for multi-provider LLM support
+
+```sh
+volute create atlas --template pi
+```
+
+## Model configuration
+
+Set the model via `volute.json` in the agent's root directory, or the `VOLUTE_MODEL` env var.
+
+## Development
+
+```sh
+git clone <repo-url>
+cd volute
+npm install
+npm run dev          # run CLI via tsx
+npm run build        # build CLI + web frontend
+npm run dev:web      # frontend dev server
+npm test             # run tests
+```
+
+Install globally for testing: `npm run build && npm link`.

package/dist/channel-Q642YUZE.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import {
+  loadMergedEnv
+} from "./chunk-A5ZJEMHT.js";
+import {
+  parseArgs
+} from "./chunk-D424ZQGI.js";
+import {
+  resolveAgent
+} from "./chunk-5YW4B7CG.js";
+
+// src/lib/channels/discord.ts
+var API_BASE = "https://discord.com/api/v10";
+async function read(token, channelId, limit) {
+  const res = await fetch(`${API_BASE}/channels/${channelId}/messages?limit=${limit}`, {
+    headers: { Authorization: `Bot ${token}` }
+  });
+  if (!res.ok) {
+    throw new Error(`Discord API error: ${res.status} ${res.statusText}`);
+  }
+  const messages = await res.json();
+  return messages.reverse().map((m) => `${m.author.username}: ${m.content}`).join("\n");
+}
+async function send(token, channelId, message) {
+  const res = await fetch(`${API_BASE}/channels/${channelId}/messages`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bot ${token}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ content: message })
+  });
+  if (!res.ok) {
+    throw new Error(`Discord API error: ${res.status} ${res.statusText}`);
+  }
+}
+
+// src/commands/channel.ts
+async function run(args) {
+  const { positional, flags } = parseArgs(args, {
+    agent: { type: "string" },
+    limit: { type: "number" }
+  });
+  const subcommand = positional[0];
+  const uri = positional[1];
+  const message = positional[2];
+  if (!subcommand || !uri || subcommand === "send" && !message) {
+    console.error(`Usage:
+  volute channel read <channel-uri> [--limit N] [--agent <name>]
+  volute channel send <channel-uri> "<message>" [--agent <name>]`);
+    process.exit(1);
+  }
+  const agentName = flags.agent || process.env.VOLUTE_AGENT;
+  if (!agentName) {
+    console.error("No agent specified. Use --agent <name> or run from within an agent process.");
+    process.exit(1);
+  }
+  const colonIdx = uri.indexOf(":");
+  if (colonIdx === -1) {
+    console.error(`Invalid channel URI: ${uri} (expected format: platform:id)`);
+    process.exit(1);
+  }
+  const platform = uri.slice(0, colonIdx);
+  const channelId = uri.slice(colonIdx + 1);
+  const { dir } = resolveAgent(agentName);
+  const env = loadMergedEnv(dir);
+  if (platform === "discord") {
+    const token = env.DISCORD_TOKEN;
+    if (!token) {
+      console.error("DISCORD_TOKEN not set. Run: volute env set DISCORD_TOKEN <token>");
+      process.exit(1);
+    }
+    if (subcommand === "read") {
+      const limit = flags.limit ?? 20;
+      const output = await read(token, channelId, limit);
+      console.log(output);
+    } else if (subcommand === "send") {
+      await send(token, channelId, message);
+    } else {
+      console.error(`Unknown subcommand: ${subcommand}`);
+      process.exit(1);
+    }
+  } else {
+    console.error(`Unsupported platform: ${platform}`);
+    process.exit(1);
+  }
+}
+export {
+  run
+};

package/dist/chunk-5YW4B7CG.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/lib/variants.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { resolve } from "path";
+var VOLUTE_HOME = process.env.VOLUTE_HOME || resolve(homedir(), ".volute");
+var VARIANTS_PATH = resolve(VOLUTE_HOME, "variants.json");
+function readAllVariants() {
+  if (!existsSync(VARIANTS_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(VARIANTS_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function writeAllVariants(all) {
+  mkdirSync(VOLUTE_HOME, { recursive: true });
+  writeFileSync(VARIANTS_PATH, `${JSON.stringify(all, null, 2)}
+`);
+}
+function readVariants(agentName) {
+  return readAllVariants()[agentName] ?? [];
+}
+function writeVariants(agentName, variants) {
+  const all = readAllVariants();
+  if (variants.length === 0) {
+    delete all[agentName];
+  } else {
+    all[agentName] = variants;
+  }
+  writeAllVariants(all);
+}
+function addVariant(agentName, variant) {
+  const variants = readVariants(agentName);
+  const filtered = variants.filter((v) => v.name !== variant.name);
+  filtered.push(variant);
+  writeVariants(agentName, filtered);
+}
+function removeVariant(agentName, name) {
+  const variants = readVariants(agentName);
+  writeVariants(
+    agentName,
+    variants.filter((v) => v.name !== name)
+  );
+}
+function findVariant(agentName, name) {
+  return readVariants(agentName).find((v) => v.name === name);
+}
+function removeAllVariants(agentName) {
+  const all = readAllVariants();
+  delete all[agentName];
+  writeAllVariants(all);
+}
+async function checkHealth(port) {
+  try {
+    const res = await fetch(`http://localhost:${port}/health`, {
+      signal: AbortSignal.timeout(2e3)
+    });
+    if (!res.ok) return { ok: false };
+    const data = await res.json();
+    return { ok: true, name: data.name };
+  } catch {
+    return { ok: false };
+  }
+}
+var SAFE_BRANCH_RE = /^[a-zA-Z0-9._\-/]+$/;
+function validateBranchName(branch) {
+  if (!SAFE_BRANCH_RE.test(branch)) {
+    return `Invalid branch name: ${branch}. Only alphanumeric, '.', '_', '-', '/' allowed.`;
+  }
+  if (branch.includes("..")) {
+    return `Invalid branch name: ${branch}. '..' not allowed.`;
+  }
+  return null;
+}
+
+// src/lib/registry.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { resolve as resolve2 } from "path";
+var VOLUTE_HOME2 = process.env.VOLUTE_HOME || resolve2(homedir2(), ".volute");
+var AGENTS_DIR = resolve2(VOLUTE_HOME2, "agents");
+var REGISTRY_PATH = resolve2(VOLUTE_HOME2, "agents.json");
+function ensureVoluteHome() {
+  mkdirSync2(AGENTS_DIR, { recursive: true });
+}
+function readRegistry() {
+  if (!existsSync2(REGISTRY_PATH)) return [];
+  try {
+    const entries = JSON.parse(readFileSync2(REGISTRY_PATH, "utf-8"));
+    return entries.map((e) => ({ ...e, running: e.running ?? false }));
+  } catch {
+    return [];
+  }
+}
+function writeRegistry(entries) {
+  ensureVoluteHome();
+  writeFileSync2(REGISTRY_PATH, `${JSON.stringify(entries, null, 2)}
+`);
+}
+function addAgent(name, port) {
+  const entries = readRegistry();
+  const filtered = entries.filter((e) => e.name !== name);
+  filtered.push({ name, port, created: (/* @__PURE__ */ new Date()).toISOString(), running: false });
+  writeRegistry(filtered);
+}
+function removeAgent(name) {
+  const entries = readRegistry();
+  writeRegistry(entries.filter((e) => e.name !== name));
+}
+function setAgentRunning(name, running) {
+  const entries = readRegistry();
+  const entry = entries.find((e) => e.name === name);
+  if (entry) {
+    entry.running = running;
+    writeRegistry(entries);
+  }
+}
+function findAgent(name) {
+  return readRegistry().find((e) => e.name === name);
+}
+function agentDir(name) {
+  return resolve2(AGENTS_DIR, name);
+}
+function nextPort() {
+  const entries = readRegistry();
+  const usedPorts = new Set(entries.map((e) => e.port));
+  let port = 4100;
+  while (usedPorts.has(port)) port++;
+  return port;
+}
+function resolveAgent(name) {
+  const [baseName, variantName] = name.split("@", 2);
+  const entry = findAgent(baseName);
+  if (!entry) {
+    console.error(`Unknown agent: ${baseName}`);
+    process.exit(1);
+  }
+  const dir = agentDir(baseName);
+  if (!existsSync2(dir)) {
+    console.error(`Agent directory missing: ${dir}`);
+    process.exit(1);
+  }
+  if (variantName) {
+    const variant = findVariant(baseName, variantName);
+    if (!variant) {
+      console.error(`Unknown variant: ${variantName} (agent: ${baseName})`);
+      process.exit(1);
+    }
+    return { entry: { ...entry, port: variant.port }, dir };
+  }
+  return { entry, dir };
+}
+
+export {
+  __export,
+  readVariants,
+  writeVariants,
+  addVariant,
+  removeVariant,
+  findVariant,
+  removeAllVariants,
+  checkHealth,
+  validateBranchName,
+  VOLUTE_HOME2 as VOLUTE_HOME,
+  ensureVoluteHome,
+  readRegistry,
+  addAgent,
+  removeAgent,
+  setAgentRunning,
+  findAgent,
+  agentDir,
+  nextPort,
+  resolveAgent
+};

package/dist/chunk-A5ZJEMHT.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import {
+  VOLUTE_HOME
+} from "./chunk-5YW4B7CG.js";
+
+// src/lib/env.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+function sharedEnvPath() {
+  return resolve(VOLUTE_HOME, "env.json");
+}
+function agentEnvPath(agentDir) {
+  return resolve(agentDir, ".volute", "env.json");
+}
+function readEnv(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function writeEnv(path, env) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(env, null, 2)}
+`);
+}
+function loadMergedEnv(agentDir) {
+  const shared = readEnv(sharedEnvPath());
+  const agent = readEnv(agentEnvPath(agentDir));
+  return { ...shared, ...agent };
+}
+
+export {
+  sharedEnvPath,
+  agentEnvPath,
+  readEnv,
+  writeEnv,
+  loadMergedEnv
+};

package/dist/chunk-D424ZQGI.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+// src/lib/parse-args.ts
+function parseArgs(args, flags) {
+  const positional = [];
+  const result = {};
+  for (const [key, def] of Object.entries(flags)) {
+    result[key] = def.type === "boolean" ? false : void 0;
+  }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const name = arg.slice(2);
+      const def = flags[name];
+      if (!def) continue;
+      if (def.type === "boolean") {
+        result[name] = true;
+      } else if (i + 1 < args.length) {
+        const val = args[++i];
+        result[name] = def.type === "number" ? parseInt(val, 10) : val;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags: result };
+}
+
+export {
+  parseArgs
+};