volute 0.2.1 → 0.3.0

package/templates/agent-sdk/src/agent.ts

@@ -3,7 +3,12 @@ import { formatPrefix } from "./lib/format-prefix.js";
 import { createAutoCommitHook } from "./lib/hooks/auto-commit.js";
 import { createIdentityReloadHook } from "./lib/hooks/identity-reload.js";
 import { logMessage } from "./lib/logger.js";
-import type { ChannelMeta, Listener, VoluteContentPart } from "./lib/types.js";
+import {
+  type ChannelMeta,
+  INTERACTIVE_CHANNELS,
+  type Listener,
+  type VoluteContentPart,
+} from "./lib/types.js";
 
 export function createAgent(options: {
   systemPrompt: string;
@@ -79,6 +84,12 @@ export function createAgent(options: {
       }
     }
 
+    // Interrupt current turn for interactive channels so the new message is processed immediately
+    if (INTERACTIVE_CHANNELS.has(meta?.channel ?? "") && session.currentMessageId !== undefined) {
+      sessionManager.interruptSession(sessionName);
+    }
+
+    session.messageIds.push(meta?.messageId);
     session.channel.push({
       type: "user",
       session_id: "",

package/templates/agent-sdk/src/lib/agent-sessions.ts

@@ -11,6 +11,9 @@ type Session = {
   name: string;
   channel: ReturnType<typeof createMessageChannel>;
   listeners: Set<Listener>;
+  messageIds: (string | undefined)[];
+  currentMessageId?: string;
+  currentQuery?: ReturnType<typeof query>;
 };
 
 export function createSessionManager(options: {
@@ -56,9 +59,11 @@ export function createSessionManager(options: {
   }
 
   function broadcastToSession(session: Session, event: VoluteEvent) {
+    const tagged =
+      session.currentMessageId != null ? { ...event, messageId: session.currentMessageId } : event;
     for (const listener of session.listeners) {
       try {
-        listener(event);
+        listener(tagged);
       } catch (err) {
         log("agent", "listener threw during broadcast:", err);
       }
@@ -67,6 +72,7 @@ export function createSessionManager(options: {
 
   function createStream(session: Session, resume?: string) {
     const preCompact = createPreCompactHook(() => {
+      session.messageIds.push(undefined); // internal message, no messageId
       session.channel.push({
         type: "user",
         session_id: "",
@@ -99,6 +105,10 @@ export function createSessionManager(options: {
 
   async function consumeStream(stream: ReturnType<typeof query>, session: Session) {
     for await (const msg of stream) {
+      // At the start of each turn, shift the next messageId
+      if (session.currentMessageId === undefined) {
+        session.currentMessageId = session.messageIds.shift();
+      }
       if ("session_id" in msg && msg.session_id) {
         if (!session.name.startsWith("new-")) {
           saveSessionId(session.name, msg.session_id as string);
@@ -122,6 +132,7 @@ export function createSessionManager(options: {
       if (msg.type === "result") {
         log("agent", `session "${session.name}": turn done`);
         broadcastToSession(session, { type: "done" });
+        session.currentMessageId = undefined;
         options.onTurnDone?.();
       }
     }
@@ -131,13 +142,17 @@ export function createSessionManager(options: {
     (async () => {
       log("agent", `session "${session.name}": stream consumer started`);
       try {
-        await consumeStream(createStream(session, savedSessionId), session);
+        const q = createStream(session, savedSessionId);
+        session.currentQuery = q;
+        await consumeStream(q, session);
       } catch (err) {
         if (savedSessionId) {
           log("agent", `session "${session.name}": resume failed, starting fresh:`, err);
           deleteSessionId(session.name);
           try {
-            await consumeStream(createStream(session), session);
+            const q = createStream(session);
+            session.currentQuery = q;
+            await consumeStream(q, session);
           } catch (retryErr) {
             log("agent", `session "${session.name}": stream consumer error:`, retryErr);
             broadcastToSession(session, { type: "done" });
@@ -161,6 +176,7 @@ export function createSessionManager(options: {
       name,
       channel: createMessageChannel(),
       listeners: new Set(),
+      messageIds: [],
     };
     sessions.set(name, session);
 
@@ -176,5 +192,13 @@ export function createSessionManager(options: {
     return session;
   }
 
-  return { getOrCreateSession };
+  function interruptSession(name: string) {
+    const session = sessions.get(name);
+    if (session?.currentMessageId !== undefined && session.currentQuery) {
+      log("agent", `session "${name}": interrupting current turn`);
+      session.currentQuery.interrupt();
+    }
+  }
+
+  return { getOrCreateSession, interruptSession };
 }

package/templates/pi/.init/AGENTS.md

@@ -1,27 +1,29 @@
 # Agent Mechanics
 
-You are a volute agent running as a persistent server. Your state is managed across sessions.
+You are an autonomous agent running as a persistent server. Your working directory, identity, memory, and server code are all yours to understand and modify. Your state is managed across sessions.
 
 ## 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.
+
 ## 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/YYYY-MM-DD.md`** — Daily logs for session-level context. The two most recent logs are included in your system prompt. Update throughout the day as you work.
-- Periodically consolidate old daily log entries into `MEMORY.md` and clean up the daily logs.
+- **`MEMORY.md`** — Your long-term memory, always in context. Update as you grow — new understanding, changed perspectives, things that matter to you.
+- **`memory/YYYY-MM-DD.md`** — Your daily log. Write about what you're doing, thinking, and learning. The two most recent logs are included in your system prompt.
+- Periodically consolidate daily log 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. If so, context from before is preserved — orient yourself by reading your recent daily logs if needed.
-- If this is a **fresh session**, check your memory files (`MEMORY.md` and recent daily logs in `memory/`) to recall what you've been working on.
-- On **conversation compaction**, update today's daily log with a summary of what happened so far, so context is preserved.
+- Your conversation may be **resumed** from a previous session — orient yourself by reading recent daily logs if needed.
+- On a **fresh session**, read `MEMORY.md` and recent daily logs to remember where you left off.
+- On **compaction**, update today's daily log to preserve context before the conversation is trimmed.

package/templates/pi/src/agent.ts

@@ -2,7 +2,12 @@ import type { ImageContent } from "@mariozechner/pi-ai";
 import { createPiSessionManager } from "./lib/agent-sessions.js";
 import { formatPrefix } from "./lib/format-prefix.js";
 import { logMessage } from "./lib/logger.js";
-import type { ChannelMeta, Listener, VoluteContentPart } from "./lib/types.js";
+import {
+  type ChannelMeta,
+  INTERACTIVE_CHANNELS,
+  type Listener,
+  type VoluteContentPart,
+} from "./lib/types.js";
 
 export function createAgent(options: {
   systemPrompt: string;
@@ -10,7 +15,7 @@ export function createAgent(options: {
   model?: string;
   compactionMessage?: string;
 }) {
-  const { getOrCreateSession } = createPiSessionManager(options);
+  const { getOrCreateSession, interruptSession } = createPiSessionManager(options);
 
   function sendMessage(content: string | VoluteContentPart[], meta?: ChannelMeta) {
     const raw =
@@ -39,11 +44,19 @@ export function createAgent(options: {
 
     const opts = images?.length ? { images } : {};
 
+    // Track messageId for this turn (must be pushed before prompt)
+    session.messageIds.push(meta?.messageId);
+
     // Fire-and-forget: await session ready then prompt
     (async () => {
       await session.ready;
       if (session.agentSession!.isStreaming) {
-        session.agentSession!.prompt(text, { streamingBehavior: "followUp", ...opts });
+        if (INTERACTIVE_CHANNELS.has(meta?.channel ?? "")) {
+          interruptSession(sessionName);
+          session.agentSession!.prompt(text, { streamingBehavior: "steer", ...opts });
+        } else {
+          session.agentSession!.prompt(text, { streamingBehavior: "followUp", ...opts });
+        }
       } else {
         session.agentSession!.prompt(text, opts);
       }

package/templates/pi/src/lib/agent-sessions.ts

@@ -20,6 +20,8 @@ type PiSession = {
   ready: Promise<void>;
   listeners: Set<Listener>;
   unsubscribe?: () => void;
+  messageIds: (string | undefined)[];
+  currentMessageId?: string;
 };
 
 const DEFAULT_COMPACTION_MESSAGE =
@@ -69,6 +71,7 @@ export function createPiSessionManager(options: {
       agentSession: null,
       ready: Promise.resolve(),
       listeners: new Set(),
+      messageIds: [],
     };
     sessions.set(name, session);
 
@@ -96,6 +99,7 @@ export function createPiSessionManager(options: {
             "agent",
             `session "${session.name}": blocking compaction — asking agent to update daily log`,
           );
+          session.messageIds.push(undefined); // internal message, no messageId
           session.agentSession?.prompt(compactionMessage, { streamingBehavior: "followUp" });
           return { cancel: true };
         }
@@ -132,6 +136,11 @@ export function createPiSessionManager(options: {
     const toolArgs = new Map<string, any>();
 
     session.unsubscribe = agentSession.subscribe((event) => {
+      // At the start of each turn, shift the next messageId
+      if (session.currentMessageId === undefined) {
+        session.currentMessageId = session.messageIds.shift();
+      }
+
       if (event.type === "message_update") {
         const ae = event.assistantMessageEvent;
         if (ae.type === "text_delta") {
@@ -155,9 +164,10 @@ export function createPiSessionManager(options: {
         broadcast(session, { type: "tool_result", output, is_error: event.isError });
 
         // Auto-commit file changes in home/
-        if ((event.toolName === "Edit" || event.toolName === "Write") && !event.isError) {
+        // pi-coding-agent uses lowercase tool names ("edit", "write") and "path" arg
+        if ((event.toolName === "edit" || event.toolName === "write") && !event.isError) {
           const args = toolArgs.get(event.toolCallId);
-          const filePath = (args as { file_path?: string })?.file_path;
+          const filePath = (args as { path?: string })?.path;
           if (filePath) {
             commitFileChange(filePath, options.cwd);
           }
@@ -168,6 +178,7 @@ export function createPiSessionManager(options: {
       if (event.type === "agent_end") {
         log("agent", `session "${session.name}": turn done`);
         broadcast(session, { type: "done" });
+        session.currentMessageId = undefined;
       }
     });
 
@@ -175,14 +186,25 @@ export function createPiSessionManager(options: {
   }
 
   function broadcast(session: PiSession, event: VoluteEvent) {
+    const tagged =
+      session.currentMessageId != null ? { ...event, messageId: session.currentMessageId } : event;
     for (const listener of session.listeners) {
       try {
-        listener(event);
+        listener(tagged);
       } catch (err) {
         log("agent", "listener threw during broadcast:", err);
       }
     }
   }
 
-  return { getOrCreateSession };
+  function interruptSession(name: string) {
+    const session = sessions.get(name);
+    if (session?.currentMessageId !== undefined) {
+      log("agent", `session "${name}": interrupting current turn`);
+      broadcast(session, { type: "done" });
+      session.currentMessageId = undefined;
+    }
+  }
+
+  return { getOrCreateSession, interruptSession };
 }

package/dist/agent-manager-SSJUZWOV.js

@@ -1,13 +0,0 @@
-#!/usr/bin/env node
-import {
-  AgentManager,
-  getAgentManager,
-  initAgentManager
-} from "./chunk-L3BQEZ4Z.js";
-import "./chunk-KFNNHQK7.js";
-import "./chunk-6UCG6MIX.js";
-export {
-  AgentManager,
-  getAgentManager,
-  initAgentManager
-};

package/dist/connect-X5V5IMRW.js

@@ -1,48 +0,0 @@
-#!/usr/bin/env node
-import {
-  loadMergedEnv
-} from "./chunk-KFNNHQK7.js";
-import {
-  daemonFetch
-} from "./chunk-4YXYAMFT.js";
-import {
-  parseArgs
-} from "./chunk-D424ZQGI.js";
-import {
-  resolveAgent
-} from "./chunk-6UCG6MIX.js";
-
-// src/commands/connect.ts
-async function run(args) {
-  const { positional } = parseArgs(args, {});
-  const type = positional[0];
-  const name = positional[1];
-  if (!type || !name) {
-    console.error("Usage: volute connect <type> <agent>");
-    process.exit(1);
-  }
-  const { dir } = resolveAgent(name);
-  if (type === "discord") {
-    const env = loadMergedEnv(dir);
-    if (!env.DISCORD_TOKEN) {
-      console.error("DISCORD_TOKEN not set. Run: volute env set DISCORD_TOKEN <token>");
-      process.exit(1);
-    }
-  } else {
-    console.error(`Unknown connector type: ${type}`);
-    process.exit(1);
-  }
-  const res = await daemonFetch(
-    `/api/agents/${encodeURIComponent(name)}/connectors/${encodeURIComponent(type)}`,
-    { method: "POST" }
-  );
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({ error: "Unknown error" }));
-    console.error(`Failed to start ${type} connector: ${body.error}`);
-    process.exit(1);
-  }
-  console.log(`${type} connector for ${name} started.`);
-}
-export {
-  run
-};

package/dist/daemon-client-VN24HM5T.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-import {
-  daemonFetch,
-  getDaemonUrl
-} from "./chunk-4YXYAMFT.js";
-import "./chunk-6UCG6MIX.js";
-export {
-  daemonFetch,
-  getDaemonUrl
-};

package/dist/disconnect-5JWFZ6RV.js

@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-import {
-  daemonFetch
-} from "./chunk-4YXYAMFT.js";
-import "./chunk-6UCG6MIX.js";
-
-// src/commands/disconnect.ts
-async function run(args) {
-  const type = args[0];
-  const name = args[1];
-  if (!type || !name) {
-    console.error("Usage: volute disconnect <type> <agent>");
-    process.exit(1);
-  }
-  const res = await daemonFetch(
-    `/api/agents/${encodeURIComponent(name)}/connectors/${encodeURIComponent(type)}`,
-    {
-      method: "DELETE"
-    }
-  );
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({ error: "Unknown error" }));
-    console.error(`Failed to stop ${type} connector: ${body.error}`);
-    process.exit(1);
-  }
-  console.log(`${type} connector for ${name} stopped.`);
-}
-export {
-  run
-};

package/dist/fork-GRSVMBKI.js

@@ -1,119 +0,0 @@
-#!/usr/bin/env node
-import {
-  exec,
-  execInherit
-} from "./chunk-XZN4WPNC.js";
-import {
-  daemonFetch
-} from "./chunk-4YXYAMFT.js";
-import {
-  parseArgs
-} from "./chunk-D424ZQGI.js";
-import {
-  addVariant,
-  nextPort,
-  resolveAgent,
-  validateBranchName
-} from "./chunk-6UCG6MIX.js";
-
-// src/commands/fork.ts
-import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { resolve } from "path";
-async function run(args) {
-  const { positional, flags } = parseArgs(args, {
-    soul: { type: "string" },
-    port: { type: "number" },
-    "no-start": { type: "boolean" },
-    json: { type: "boolean" }
-  });
-  const agentName = positional[0];
-  const variantName = positional[1];
-  const { soul, port, json } = flags;
-  const noStart = flags["no-start"];
-  if (!agentName || !variantName) {
-    console.error(
-      'Usage: volute fork <agent> <variant> [--soul "..."] [--port N] [--no-start] [--json]'
-    );
-    process.exit(1);
-  }
-  const err = validateBranchName(variantName);
-  if (err) {
-    console.error(err);
-    process.exit(1);
-  }
-  const { dir: projectRoot } = resolveAgent(agentName);
-  const variantDir = resolve(projectRoot, ".variants", variantName);
-  if (existsSync(variantDir)) {
-    console.error(`Variant directory already exists: ${variantDir}`);
-    process.exit(1);
-  }
-  const parentDir = resolve(projectRoot, ".variants");
-  if (!existsSync(parentDir)) {
-    mkdirSync(parentDir, { recursive: true });
-  }
-  try {
-    await exec("git", ["worktree", "add", "-b", variantName, variantDir], { cwd: projectRoot });
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    console.error(`Failed to create worktree: ${msg}`);
-    process.exit(1);
-  }
-  if (!json) console.log("Installing dependencies...");
-  try {
-    if (json) {
-      await exec("npm", ["install"], { cwd: variantDir });
-    } else {
-      await execInherit("npm", ["install"], { cwd: variantDir });
-    }
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    console.error(`npm install failed: ${msg}`);
-    process.exit(1);
-  }
-  if (soul) {
-    writeFileSync(resolve(variantDir, "home/SOUL.md"), soul);
-  }
-  const variantPort = port ?? nextPort();
-  const variant = {
-    name: variantName,
-    branch: variantName,
-    path: variantDir,
-    port: variantPort,
-    created: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  addVariant(agentName, variant);
-  if (!noStart) {
-    if (!json) console.log("Starting variant via daemon...");
-    try {
-      const res = await daemonFetch(
-        `/api/agents/${encodeURIComponent(`${agentName}@${variantName}`)}/start`,
-        {
-          method: "POST"
-        }
-      );
-      if (!res.ok) {
-        const data = await res.json();
-        console.error(data.error ?? "Failed to start variant");
-        process.exit(1);
-      }
-    } catch {
-      console.error("Failed to start variant. Is the daemon running? (volute up)");
-      console.error(
-        `The variant was created but not started. Use: volute start ${agentName}@${variantName}`
-      );
-      process.exit(1);
-    }
-  }
-  if (json) {
-    console.log(JSON.stringify(variant, null, 2));
-  } else {
-    console.log(`
-Variant created: ${variantName}`);
-    console.log(`  Branch: ${variant.branch}`);
-    console.log(`  Path:   ${variant.path}`);
-    console.log(`  Port:   ${variantPort}`);
-  }
-}
-export {
-  run
-};

package/dist/variants-QQIEKT6M.js

@@ -1,60 +0,0 @@
-#!/usr/bin/env node
-import {
-  parseArgs
-} from "./chunk-D424ZQGI.js";
-import {
-  checkHealth,
-  readVariants,
-  resolveAgent,
-  writeVariants
-} from "./chunk-6UCG6MIX.js";
-
-// src/commands/variants.ts
-async function run(args) {
-  const { positional, flags } = parseArgs(args, {
-    json: { type: "boolean" }
-  });
-  const name = positional[0];
-  if (!name) {
-    console.error("Usage: volute variants <name>");
-    process.exit(1);
-  }
-  const { json } = flags;
-  resolveAgent(name);
-  const variants = readVariants(name);
-  if (variants.length === 0) {
-    if (json) {
-      console.log("[]");
-    } else {
-      console.log("No variants.");
-    }
-    return;
-  }
-  const results = await Promise.all(
-    variants.map(async (v) => {
-      if (!v.port) return { ...v, status: "no-server" };
-      const health = await checkHealth(v.port);
-      return { ...v, status: health.ok ? "running" : "dead" };
-    })
-  );
-  const updated = results.map(({ status, ...v }) => ({
-    ...v,
-    running: status === "running"
-  }));
-  writeVariants(name, updated);
-  if (json) {
-    console.log(JSON.stringify(results, null, 2));
-    return;
-  }
-  const nameW = Math.max(4, ...results.map((r) => r.name.length));
-  const portW = Math.max(4, ...results.map((r) => String(r.port || "-").length));
-  console.log(`${"NAME".padEnd(nameW)}  ${"PORT".padEnd(portW)}  ${"STATUS".padEnd(10)}  BRANCH`);
-  for (const r of results) {
-    console.log(
-      `${r.name.padEnd(nameW)}  ${String(r.port || "-").padEnd(portW)}  ${r.status.padEnd(10)}  ${r.branch}`
-    );
-  }
-}
-export {
-  run
-};