volute 0.3.1 → 0.5.0

package/README.md

@@ -17,13 +17,13 @@ npm install -g volute
 volute up
 
 # Create an agent
-volute create atlas
+volute agent create atlas
 
 # Start it
-volute start atlas
+volute agent start atlas
 
 # Talk to it
-volute send atlas "hey, what can you do?"
+volute message 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.
@@ -45,20 +45,20 @@ The daemon handles agent lifecycle, crash recovery (auto-restarts after 3 second
 ### 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
+volute agent create atlas           # scaffold a new agent
+volute agent start atlas            # start it
+volute agent stop atlas             # stop it
+volute agent list                   # list all agents
+volute agent status atlas           # check one
+volute agent logs atlas --follow    # tail logs
+volute agent delete atlas           # remove from registry
+volute agent delete atlas --force   # also delete files
 ```
 
 ### Sending messages
 
 ```sh
-volute send atlas "what's on your mind?"
+volute message 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.
@@ -92,16 +92,16 @@ This is the interesting part. Agents can fork themselves into isolated branches,
 
 ```sh
 # Create a variant — gets its own git worktree and running server
-volute fork atlas experiment
+volute variant create experiment --agent atlas
 
 # Talk to the variant directly
-volute send atlas@experiment "try a different approach"
+volute message send atlas@experiment "try a different approach"
 
 # List all variants
-volute variants atlas
+volute variant list --agent atlas
 
 # Merge it back (verifies, merges, cleans up, restarts the main agent)
-volute merge atlas experiment --summary "improved response style"
+volute variant merge experiment --agent atlas --summary "improved response style"
 ```
 
 What happens:
@@ -114,14 +114,14 @@ What happens:
 You can fork with a custom personality:
 
 ```sh
-volute fork atlas poet --soul "You are a poet who responds only in verse."
+volute variant create poet --agent atlas --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.
+Connect agents to external services. Connectors are generic — any connector type that has an implementation (built-in, shared, or agent-specific) can be enabled.
 
 ### Discord
 
@@ -130,21 +130,21 @@ Connect agents to external services.
 volute env set DISCORD_TOKEN <your-bot-token>
 
 # Connect
-volute connect discord atlas
+volute connector connect discord --agent atlas
 
 # Disconnect
-volute disconnect discord atlas
+volute connector disconnect discord --agent atlas
 ```
 
-The agent receives Discord messages and responds in-channel. Tool calls are filtered out — Discord users see clean text responses.
+The agent receives Discord messages and responds in-channel. Tool calls are filtered out — connector users see clean text responses.
 
 ### Channel commands
 
-Read from and write to channels directly:
+Read from and write to connector channels directly:
 
 ```sh
-volute channel read discord:123456789         # recent messages
-volute channel send discord:123456789 "hello" # send a message
+volute channel read discord:123456789 --agent atlas         # recent messages
+volute channel send discord:123456789 "hello" --agent atlas # send a message
 ```
 
 ## Schedules
@@ -187,13 +187,13 @@ The daemon serves a web UI at `http://localhost:4200` (or whatever port you chos
 When the Volute template updates, you can upgrade agents without touching their identity:
 
 ```sh
-volute upgrade atlas          # creates an "upgrade" variant
+volute agent upgrade atlas          # creates an "upgrade" variant
 # resolve conflicts if needed, then:
-volute upgrade atlas --continue
+volute agent upgrade atlas --continue
 # test:
-volute send atlas@upgrade "are you working?"
+volute message send atlas@upgrade "are you working?"
 # merge:
-volute merge atlas upgrade
+volute variant merge upgrade --agent atlas
 ```
 
 Your agent's `SOUL.md` and `MEMORY.md` are never overwritten.
@@ -206,7 +206,7 @@ Two built-in templates:
 - **`pi`** — [pi-coding-agent](https://github.com/nicepkg/pi) for multi-provider LLM support
 
 ```sh
-volute create atlas --template pi
+volute agent create atlas --template pi
 ```
 
 ## Model configuration

package/dist/agent-Z2B6EFEQ.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import "./chunk-K3NQKI34.js";
+
+// src/commands/agent.ts
+async function run(args) {
+  const subcommand = args[0];
+  switch (subcommand) {
+    case "create":
+      await import("./create-RVCZN6HE.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "start":
+      await import("./start-TUOXDSFL.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "stop":
+      await import("./stop-AOJZLQ5X.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "delete":
+      await import("./delete-3QH7VYIN.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "list":
+      await import("./status-A36EHRO4.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "status": {
+      const rest = args.slice(1);
+      if (!rest[0] && process.env.VOLUTE_AGENT) {
+        rest.unshift(process.env.VOLUTE_AGENT);
+      }
+      await import("./status-A36EHRO4.js").then((m) => m.run(rest));
+      break;
+    }
+    case "logs": {
+      const rest = args.slice(1);
+      const logsArgs = transformAgentFlag(rest);
+      await import("./logs-DF342W4M.js").then((m) => m.run(logsArgs));
+      break;
+    }
+    case "upgrade":
+      await import("./upgrade-FX2TKJ2S.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "import":
+      await import("./import-MXJB2EII.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "--help":
+    case "-h":
+    case void 0:
+      printUsage();
+      break;
+    default:
+      printUsage();
+      process.exit(1);
+  }
+}
+function transformAgentFlag(args) {
+  if (args.length > 0 && args[0] && !args[0].startsWith("-")) {
+    return ["--agent", args[0], ...args.slice(1)];
+  }
+  return args;
+}
+function printUsage() {
+  console.log(`Usage:
+  volute agent create <name> [--template <name>]
+  volute agent start <name>
+  volute agent stop [name]
+  volute agent delete [name] [--force]
+  volute agent list
+  volute agent status [name]
+  volute agent logs [name] [--follow] [-n N]
+  volute agent upgrade [name] [--template <name>] [--continue]
+  volute agent import <path> [--name <name>] [--session <path>] [--template <name>]
+
+Agent name can be omitted (where shown as [name]) if VOLUTE_AGENT is set.`);
+}
+export {
+  run
+};

package/dist/{agent-manager-AUCKMGPR.js → agent-manager-PXBKA2GK.js}

@@ -3,10 +3,10 @@ import {
   AgentManager,
   getAgentManager,
   initAgentManager
-} from "./chunk-I6OHXCMV.js";
-import "./chunk-DNOXHLE5.js";
-import "./chunk-SOZA2TLP.js";
-import "./chunk-3C2XR4IY.js";
+} from "./chunk-MW2KFO3B.js";
+import "./chunk-HE67X4T6.js";
+import "./chunk-UAVD2AHX.js";
+import "./chunk-UX25Z2ND.js";
 import "./chunk-K3NQKI34.js";
 export {
   AgentManager,

package/dist/channel-MK5OK2SI.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import {
+  readStdin
+} from "./chunk-ZYGKG6VC.js";
+import {
+  resolveAgentName
+} from "./chunk-AZEL2IEK.js";
+import {
+  getChannelDriver
+} from "./chunk-SMISE4SV.js";
+import {
+  loadMergedEnv
+} from "./chunk-HE67X4T6.js";
+import {
+  parseArgs
+} from "./chunk-D424ZQGI.js";
+import {
+  resolveAgent
+} from "./chunk-UX25Z2ND.js";
+import "./chunk-K3NQKI34.js";
+
+// src/commands/channel.ts
+async function run(args) {
+  const subcommand = args[0];
+  switch (subcommand) {
+    case "read":
+      await readChannel(args.slice(1));
+      break;
+    case "send":
+      await sendChannel(args.slice(1));
+      break;
+    case "--help":
+    case "-h":
+    case void 0:
+      printUsage();
+      break;
+    default:
+      printUsage();
+      process.exit(1);
+  }
+}
+function printUsage() {
+  console.log(`Usage:
+  volute channel read <channel-uri> [--limit N] [--agent <name>]
+  volute channel send <channel-uri> "<message>" [--agent <name>]
+  echo "message" | volute channel send <channel-uri> [--agent <name>]`);
+}
+async function readChannel(args) {
+  const { positional, flags } = parseArgs(args, {
+    agent: { type: "string" },
+    limit: { type: "number" }
+  });
+  const uri = positional[0];
+  if (!uri) {
+    console.error("Usage: volute channel read <channel-uri> [--limit N] [--agent <name>]");
+    process.exit(1);
+  }
+  const agentName = resolveAgentName(flags);
+  const { platform, channelId } = parseUri(uri);
+  const driver = requireDriver(platform);
+  const { dir } = resolveAgent(agentName);
+  const env = { ...loadMergedEnv(dir), VOLUTE_AGENT: agentName };
+  try {
+    const limit = flags.limit ?? 20;
+    const output = await driver.read(env, channelId, limit);
+    console.log(output);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function sendChannel(args) {
+  const { positional, flags } = parseArgs(args, {
+    agent: { type: "string" }
+  });
+  const uri = positional[0];
+  const message = positional[1] ?? await readStdin();
+  if (!uri || !message) {
+    console.error('Usage: volute channel send <channel-uri> "<message>" [--agent <name>]');
+    console.error('       echo "message" | volute channel send <channel-uri> [--agent <name>]');
+    process.exit(1);
+  }
+  const agentName = resolveAgentName(flags);
+  const { platform, channelId } = parseUri(uri);
+  const driver = requireDriver(platform);
+  const { dir } = resolveAgent(agentName);
+  const env = { ...loadMergedEnv(dir), VOLUTE_AGENT: agentName };
+  try {
+    await driver.send(env, channelId, message);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+function parseUri(uri) {
+  const colonIdx = uri.indexOf(":");
+  if (colonIdx === -1) {
+    console.error(`Invalid channel URI: ${uri} (expected format: platform:id)`);
+    process.exit(1);
+  }
+  return { platform: uri.slice(0, colonIdx), channelId: uri.slice(colonIdx + 1) };
+}
+function requireDriver(platform) {
+  const driver = getChannelDriver(platform);
+  if (!driver) {
+    console.error(`No channel driver for platform: ${platform}`);
+    process.exit(1);
+  }
+  return driver;
+}
+export {
+  run
+};

package/dist/chunk-5X7HGB6L.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import {
+  voluteHome
+} from "./chunk-UX25Z2ND.js";
+
+// src/lib/update-check.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+var CACHE_TTL = 60 * 60 * 1e3;
+function cachePath() {
+  return resolve(voluteHome(), "update-check.json");
+}
+function readCache() {
+  try {
+    const data = JSON.parse(readFileSync(cachePath(), "utf-8"));
+    if (data.latest && typeof data.checkedAt === "number") return data;
+  } catch {
+  }
+  return null;
+}
+function writeCache(latest) {
+  try {
+    writeFileSync(cachePath(), `${JSON.stringify({ latest, checkedAt: Date.now() })}
+`);
+  } catch {
+  }
+}
+function getCurrentVersion() {
+  const thisDir = new URL(".", import.meta.url).pathname;
+  const candidates = [
+    resolve(thisDir, "../../package.json"),
+    resolve(thisDir, "../../../package.json")
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try {
+        return JSON.parse(readFileSync(p, "utf-8")).version;
+      } catch {
+      }
+    }
+  }
+  return "0.0.0";
+}
+async function fetchLatestVersion() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5e3);
+  timeout.unref?.();
+  try {
+    const res = await fetch("https://registry.npmjs.org/volute/latest", {
+      signal: controller.signal
+    });
+    if (!res.ok) throw new Error(`npm registry returned ${res.status}`);
+    const data = await res.json();
+    if (typeof data.version !== "string") throw new Error("invalid npm response");
+    return data.version;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function isNewer(current, latest) {
+  const parse = (v) => v.split("-")[0].split(".").map(Number);
+  const hasPrerelease = (v) => v.includes("-");
+  const c = parse(current);
+  const l = parse(latest);
+  for (let i = 0; i < 3; i++) {
+    if ((l[i] ?? 0) > (c[i] ?? 0)) return true;
+    if ((l[i] ?? 0) < (c[i] ?? 0)) return false;
+  }
+  if (hasPrerelease(current) && !hasPrerelease(latest)) return true;
+  return false;
+}
+async function checkForUpdate() {
+  const current = getCurrentVersion();
+  const cache = readCache();
+  if (cache && Date.now() - cache.checkedAt < CACHE_TTL) {
+    return {
+      current,
+      latest: cache.latest,
+      updateAvailable: isNewer(current, cache.latest)
+    };
+  }
+  try {
+    const latest = await fetchLatestVersion();
+    writeCache(latest);
+    return { current, latest, updateAvailable: isNewer(current, latest) };
+  } catch {
+    return { current, latest: current, updateAvailable: false, checkFailed: true };
+  }
+}
+function checkForUpdateCached() {
+  const cache = readCache();
+  if (!cache) return null;
+  const current = getCurrentVersion();
+  return {
+    current,
+    latest: cache.latest,
+    updateAvailable: isNewer(current, cache.latest)
+  };
+}
+
+export {
+  getCurrentVersion,
+  fetchLatestVersion,
+  isNewer,
+  checkForUpdate,
+  checkForUpdateCached
+};

package/dist/{chunk-YGFIWIOF.js → chunk-7L4AN5D4.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   voluteHome
-} from "./chunk-3C2XR4IY.js";
+} from "./chunk-UX25Z2ND.js";
 
 // src/lib/daemon-client.ts
 import { existsSync, readFileSync } from "fs";

package/dist/{chunk-VRVVQIYY.js → chunk-AZEL2IEK.js}

@@ -4,7 +4,7 @@
 function resolveAgentName(flags) {
   const name = flags.agent || process.env.VOLUTE_AGENT;
   if (!name) {
-    console.error("No agent specified. Use --agent <name> or set VOLUTE_AGENT.");
+    console.error("No agent specified. Provide a name or set VOLUTE_AGENT.");
     process.exit(1);
   }
   return name;

package/dist/chunk-B3R6L2GW.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+// src/lib/format-tool.ts
+function summarizeTool(name, input) {
+  if (input && typeof input === "object") {
+    const args = input;
+    const val = args.path ?? args.command ?? args.query ?? args.url;
+    if (typeof val === "string") {
+      const brief = val.length > 60 ? `${val.slice(0, 57)}...` : val;
+      return `[${name} ${brief}]`;
+    }
+  }
+  return `[${name}]`;
+}
+function collectPart(event) {
+  if (event.type === "text") return event.content ?? "";
+  if (event.type === "tool_use") return summarizeTool(event.name ?? "", event.input);
+  return null;
+}
+
+export {
+  summarizeTool,
+  collectPart
+};

package/dist/{chunk-DNOXHLE5.js → chunk-HE67X4T6.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   voluteHome
-} from "./chunk-3C2XR4IY.js";
+} from "./chunk-UX25Z2ND.js";
 
 // src/lib/env.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";

package/dist/{chunk-I6OHXCMV.js → chunk-MW2KFO3B.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   loadMergedEnv
-} from "./chunk-DNOXHLE5.js";
+} from "./chunk-HE67X4T6.js";
 import {
   applyIsolation
-} from "./chunk-SOZA2TLP.js";
+} from "./chunk-UAVD2AHX.js";
 import {
   agentDir,
   findAgent,
@@ -13,11 +13,11 @@ import {
   setVariantRunning,
   validateBranchName,
   voluteHome
-} from "./chunk-3C2XR4IY.js";
+} from "./chunk-UX25Z2ND.js";
 
 // src/lib/agent-manager.ts
 import { execFile, spawn } from "child_process";
-import { createWriteStream, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, unlinkSync as unlinkSync2 } from "fs";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync2, unlinkSync as unlinkSync2 } from "fs";
 import { resolve } from "path";
 import { promisify } from "util";
 
@@ -58,6 +58,45 @@ function clearJsonMap(path, map) {
   }
 }
 
+// src/lib/rotating-log.ts
+import { createWriteStream, existsSync as existsSync2, renameSync, statSync } from "fs";
+import { Writable } from "stream";
+var MAX_SIZE = 10 * 1024 * 1024;
+var RotatingLog = class extends Writable {
+  constructor(path, maxSize = MAX_SIZE) {
+    super();
+    this.path = path;
+    this.maxSize = maxSize;
+    this.on("error", () => {
+    });
+    try {
+      this.size = existsSync2(path) ? statSync(path).size : 0;
+    } catch {
+      this.size = 0;
+    }
+    this.stream = createWriteStream(path, { flags: "a" });
+  }
+  stream;
+  size;
+  _write(chunk, _encoding, callback) {
+    this.size += chunk.length;
+    if (this.size > this.maxSize) {
+      try {
+        renameSync(this.path, `${this.path}.1`);
+        const oldStream = this.stream;
+        this.stream = createWriteStream(this.path);
+        this.size = chunk.length;
+        oldStream.end();
+      } catch {
+      }
+    }
+    this.stream.write(chunk, callback);
+  }
+  _final(callback) {
+    this.stream.end(callback);
+  }
+};
+
 // src/lib/agent-manager.ts
 var execFileAsync = promisify(execFile);
 var MAX_RESTART_ATTEMPTS = 5;
@@ -78,7 +117,7 @@ var AgentManager = class {
       return { dir: variant.path, port: variant.port, isVariant: true, baseName, variantName };
     }
     const dir = agentDir(baseName);
-    if (!existsSync2(dir)) throw new Error(`Agent directory missing: ${dir}`);
+    if (!existsSync3(dir)) throw new Error(`Agent directory missing: ${dir}`);
     return { dir, port: entry.port, isVariant: false, baseName };
   }
   async startAgent(name) {
@@ -100,9 +139,7 @@ var AgentManager = class {
     const voluteDir = resolve(dir, ".volute");
     const logsDir = resolve(voluteDir, "logs");
     mkdirSync(logsDir, { recursive: true });
-    const logStream = createWriteStream(resolve(logsDir, "agent.log"), {
-      flags: "a"
-    });
+    const logStream = new RotatingLog(resolve(logsDir, "agent.log"));
     const agentEnv = loadMergedEnv(dir);
     const { VOLUTE_DAEMON_TOKEN: _, ...parentEnv } = process.env;
     const env = { ...parentEnv, ...agentEnv, VOLUTE_AGENT: name };
@@ -198,7 +235,7 @@ var AgentManager = class {
   }
   async handleRestart(name, dir) {
     const restartPath = resolve(dir, ".volute", "restart.json");
-    if (!existsSync2(restartPath)) return false;
+    if (!existsSync3(restartPath)) return false;
     try {
       const signal = JSON.parse(readFileSync2(restartPath, "utf-8"));
       unlinkSync2(restartPath);
@@ -326,6 +363,7 @@ export {
   loadJsonMap,
   saveJsonMap,
   clearJsonMap,
+  RotatingLog,
   AgentManager,
   initAgentManager,
   getAgentManager