volute 0.4.0 → 0.6.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,7 +114,7 @@ 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.
@@ -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-X7GJLBLW.js

@@ -0,0 +1,79 @@
+#!/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-G525LWEA.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "start":
+      await import("./start-VHQ7LNWM.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "stop":
+      await import("./stop-CAGCT5NI.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "restart":
+      await import("./restart-O4ETYLJF.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "delete":
+      await import("./delete-2PH2CGDY.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "list":
+      await import("./status-QAJWXKMZ.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-QAJWXKMZ.js").then((m) => m.run(rest));
+      break;
+    }
+    case "logs": {
+      const rest = args.slice(1);
+      const logsArgs = transformAgentFlag(rest);
+      await import("./logs-EDGK26AK.js").then((m) => m.run(logsArgs));
+      break;
+    }
+    case "upgrade":
+      await import("./upgrade-YXKPWDRU.js").then((m) => m.run(args.slice(1)));
+      break;
+    case "import":
+      await import("./import-AVKQJDYC.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 restart [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-JDVXU3ON.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-G6ZNGLUX.js";
+import "./chunk-H7AMDUIA.js";
+import "./chunk-W76KWE23.js";
+import "./chunk-UWHWAPGO.js";
 import "./chunk-K3NQKI34.js";
 export {
   AgentManager,

package/dist/channel-SMCNOIVQ.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+import {
+  readStdin
+} from "./chunk-ZYGKG6VC.js";
+import {
+  resolveAgentName
+} from "./chunk-AZEL2IEK.js";
+import {
+  CHANNELS,
+  getChannelDriver
+} from "./chunk-ZZOOTYXK.js";
+import {
+  loadMergedEnv
+} from "./chunk-H7AMDUIA.js";
+import {
+  writeChannelEntry
+} from "./chunk-BX7KI4S3.js";
+import {
+  parseArgs
+} from "./chunk-D424ZQGI.js";
+import {
+  daemonFetch
+} from "./chunk-JR4UXCTO.js";
+import {
+  resolveAgent
+} from "./chunk-UWHWAPGO.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 "list":
+      await listChannels(args.slice(1));
+      break;
+    case "users":
+      await listUsers(args.slice(1));
+      break;
+    case "create":
+      await createChannel(args.slice(1));
+      break;
+    case "typing":
+      await typingChannel(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>]
+  volute channel list [<platform>] [--agent <name>]
+  volute channel users <platform> [--agent <name>]
+  volute channel create <platform> --participants user1,user2 [--name "..."] [--agent <name>]
+  volute channel typing <channel-uri> [--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 } = parseUri(uri);
+  const driver = requireDriver(platform);
+  const { dir } = resolveAgent(agentName);
+  const env = { ...loadMergedEnv(dir), VOLUTE_AGENT: agentName, VOLUTE_AGENT_DIR: dir };
+  try {
+    const limit = flags.limit ?? 20;
+    const output = await driver.read(env, uri, 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 } = parseUri(uri);
+  const driver = requireDriver(platform);
+  const { dir } = resolveAgent(agentName);
+  const env = { ...loadMergedEnv(dir), VOLUTE_AGENT: agentName, VOLUTE_AGENT_DIR: dir };
+  try {
+    await driver.send(env, uri, message);
+    try {
+      await daemonFetch(`/api/agents/${encodeURIComponent(agentName)}/history`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ channel: uri, content: message })
+      });
+    } catch (err) {
+      console.error(`Failed to persist to history: ${err instanceof Error ? err.message : err}`);
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function listChannels(args) {
+  const { positional, flags } = parseArgs(args, {
+    agent: { type: "string" }
+  });
+  const platform = positional[0];
+  const agentName = resolveAgentName(flags);
+  const { dir } = resolveAgent(agentName);
+  const env = { ...loadMergedEnv(dir), VOLUTE_AGENT: agentName, VOLUTE_AGENT_DIR: dir };
+  const platforms = platform ? [platform] : Object.keys(CHANNELS);
+  for (const p of platforms) {
+    const driver = getChannelDriver(p);
+    if (!driver?.listConversations) continue;
+    try {
+      const convs = await driver.listConversations(env);
+      for (const conv of convs) {
+        writeChannelEntry(dir, conv.id, {
+          platformId: conv.platformId,
+          platform: p,
+          name: conv.name,
+          type: conv.type
+        });
+        const parts = [conv.id.padEnd(24), conv.name.padEnd(28), conv.type];
+        if (conv.participantCount != null) {
+          parts.push(String(conv.participantCount));
+        }
+        console.log(parts.join("  "));
+      }
+    } catch (err) {
+      console.error(`${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}
+async function listUsers(args) {
+  const { positional, flags } = parseArgs(args, {
+    agent: { type: "string" }
+  });
+  const platform = positional[0];
+  if (!platform) {
+    console.error("Usage: volute channel users <platform> [--agent <name>]");
+    process.exit(1);
+  }
+  const driver = requireDriver(platform);
+  if (!driver.listUsers) {
+    console.error(`Platform ${platform} does not support listing users`);
+    process.exit(1);
+  }
+  const agentName = resolveAgentName(flags);
+  const { dir } = resolveAgent(agentName);
+  const env = { ...loadMergedEnv(dir), VOLUTE_AGENT: agentName, VOLUTE_AGENT_DIR: dir };
+  try {
+    const users = await driver.listUsers(env);
+    for (const user of users) {
+      console.log(`${user.username.padEnd(20)}  ${user.id.padEnd(20)}  ${user.type ?? ""}`);
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function createChannel(args) {
+  const { positional, flags } = parseArgs(args, {
+    agent: { type: "string" },
+    participants: { type: "string" },
+    name: { type: "string" }
+  });
+  const platform = positional[0];
+  if (!platform || !flags.participants) {
+    console.error(
+      'Usage: volute channel create <platform> --participants user1,user2 [--name "..."] [--agent <name>]'
+    );
+    process.exit(1);
+  }
+  const driver = requireDriver(platform);
+  if (!driver.createConversation) {
+    console.error(`Platform ${platform} does not support creating conversations`);
+    process.exit(1);
+  }
+  const agentName = resolveAgentName(flags);
+  const { dir } = resolveAgent(agentName);
+  const env = { ...loadMergedEnv(dir), VOLUTE_AGENT: agentName, VOLUTE_AGENT_DIR: dir };
+  const participants = flags.participants.split(",").map((s) => s.trim());
+  try {
+    const slug = await driver.createConversation(env, participants, flags.name);
+    console.log(slug);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function typingChannel(args) {
+  const { positional, flags } = parseArgs(args, {
+    agent: { type: "string" }
+  });
+  const uri = positional[0];
+  if (!uri) {
+    console.error("Usage: volute channel typing <channel-uri> [--agent <name>]");
+    process.exit(1);
+  }
+  const agentName = resolveAgentName(flags);
+  try {
+    const res = await daemonFetch(
+      `/api/agents/${encodeURIComponent(agentName)}/typing?channel=${encodeURIComponent(uri)}`
+    );
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      console.error(body.error ?? `Server responded with ${res.status}`);
+      process.exit(1);
+    }
+    const data = await res.json();
+    if (data.typing.length > 0) {
+      console.log(data.typing.join(", "));
+    }
+  } 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-AOKAQGO4.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import {
+  voluteHome
+} from "./chunk-UWHWAPGO.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-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-MXUCNIBG.js → chunk-BX7KI4S3.js}

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 
+// src/lib/slugify.ts
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+
 // src/connectors/sdk.ts
-import { existsSync, readFileSync } from "fs";
-import { resolve } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
 function loadEnv() {
   const agentPort = process.env.VOLUTE_AGENT_PORT;
   const agentName = process.env.VOLUTE_AGENT_NAME;
@@ -92,6 +97,15 @@ function onShutdown(cleanup) {
   process.on("SIGINT", handler);
   process.on("SIGTERM", handler);
 }
+function reportTyping(env, channel, sender, active) {
+  fetch(`${env.baseUrl}/typing`, {
+    method: "POST",
+    headers: getHeaders(env),
+    body: JSON.stringify({ channel, sender, active })
+  }).catch((err) => {
+    console.warn(`[typing] failed to report for ${sender} on ${channel}: ${err}`);
+  });
+}
 async function fireAndForget(env, payload) {
   try {
     const res = await fetch(`${env.baseUrl}/message`, {
@@ -157,12 +171,63 @@ async function handleAgentMessage(env, payload, handlers) {
     await handlers.onError(errMsg);
   }
 }
+function buildChannelSlug(platform, meta) {
+  if (meta.isDM) {
+    if (meta.recipients && meta.recipients.length > 0) {
+      const sorted = meta.recipients.map(slugify).sort();
+      return `${platform}:@${sorted.join(",")}`;
+    }
+    if (meta.senderName) {
+      return `${platform}:@${slugify(meta.senderName)}`;
+    }
+  }
+  if (meta.channelName && meta.serverName) {
+    return `${platform}:${slugify(meta.serverName)}/${slugify(meta.channelName)}`;
+  }
+  if (meta.channelName) {
+    return `${platform}:${slugify(meta.channelName)}`;
+  }
+  if (meta.platformId) {
+    return `${platform}:${meta.platformId}`;
+  }
+  return `${platform}:unknown`;
+}
+function readChannelMap(agentDir) {
+  const filePath = join(agentDir, ".volute", "channels.json");
+  if (!existsSync(filePath)) return {};
+  try {
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function writeChannelEntry(agentDir, slug, entry) {
+  const voluteDir = join(agentDir, ".volute");
+  mkdirSync(voluteDir, { recursive: true });
+  const filePath = join(voluteDir, "channels.json");
+  const map = readChannelMap(agentDir);
+  map[slug] = entry;
+  writeFileSync(filePath, JSON.stringify(map, null, 2) + "\n");
+}
+function resolveChannelId(agentDir, slug) {
+  const map = readChannelMap(agentDir);
+  if (map[slug]) {
+    return map[slug].platformId;
+  }
+  const colonIndex = slug.indexOf(":");
+  return colonIndex >= 0 ? slug.slice(colonIndex + 1) : slug;
+}
 
 export {
+  slugify,
   loadEnv,
   loadFollowedChannels,
   splitMessage,
   onShutdown,
+  reportTyping,
   fireAndForget,
-  handleAgentMessage
+  handleAgentMessage,
+  buildChannelSlug,
+  writeChannelEntry,
+  resolveChannelId
 };