volute 0.3.1 → 0.5.0

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

@@ -1,15 +1,58 @@
-import { createSessionManager } from "./lib/agent-sessions.js";
-import { formatPrefix } from "./lib/format-prefix.js";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { query } from "@anthropic-ai/claude-agent-sdk";
 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,
-  INTERACTIVE_CHANNELS,
-  type Listener,
-  type VoluteContentPart,
+import { createPreCompactHook } from "./lib/hooks/pre-compact.js";
+import { log, logText, logThinking, logToolUse } from "./lib/logger.js";
+import { createMessageChannel } from "./lib/message-channel.js";
+import type {
+  HandlerMeta,
+  HandlerResolver,
+  Listener,
+  MessageHandler,
+  VoluteContentPart,
+  VoluteEvent,
 } from "./lib/types.js";
 
+type SDKContent = (
+  | { type: "text"; text: string }
+  | {
+      type: "image";
+      source: {
+        type: "base64";
+        media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+        data: string;
+      };
+    }
+)[];
+
+type Session = {
+  name: string;
+  channel: ReturnType<typeof createMessageChannel>;
+  listeners: Set<Listener>;
+  messageIds: (string | undefined)[];
+  currentMessageId?: string;
+  currentQuery?: ReturnType<typeof query>;
+};
+
+function toSDKContent(content: VoluteContentPart[]): SDKContent {
+  return content.map((part) => {
+    if (part.type === "text") {
+      return { type: "text" as const, text: part.text };
+    }
+    return {
+      type: "image" as const,
+      source: {
+        type: "base64" as const,
+        media_type: part.media_type as "image/jpeg" | "image/png" | "image/gif" | "image/webp",
+        data: part.data,
+      },
+    };
+  });
+}
+
 export function createAgent(options: {
   systemPrompt: string;
   cwd: string;
@@ -18,95 +61,239 @@ export function createAgent(options: {
   sessionsDir: string;
   compactionMessage?: string;
   onIdentityReload?: () => Promise<void>;
-}) {
+}): { resolve: HandlerResolver; waitForCommits: () => Promise<void> } {
   const autoCommit = createAutoCommitHook(options.cwd);
   const identityReload = createIdentityReloadHook(options.cwd);
+  const postToolUseHooks: { matcher: string; hooks: HookCallback[] }[] = [
+    { matcher: "Edit|Write", hooks: [autoCommit.hook, identityReload.hook] },
+  ];
 
-  const sessionManager = createSessionManager({
-    systemPrompt: options.systemPrompt,
-    cwd: options.cwd,
-    abortController: options.abortController,
-    model: options.model,
-    sessionsDir: options.sessionsDir,
-    compactionMessage: options.compactionMessage,
-    postToolUseHooks: [{ matcher: "Edit|Write", hooks: [autoCommit.hook, identityReload.hook] }],
-    onTurnDone: () => {
-      if (identityReload.needsReload()) {
-        options.onIdentityReload?.();
+  const sessions = new Map<string, Session>();
+  const today = new Date().toISOString().slice(0, 10);
+  const compactionMessage =
+    options.compactionMessage ??
+    `Context is getting long — compaction is about to summarize this conversation. Before that happens, save anything important to files (MEMORY.md, memory/journal/${today}.md, etc.) since those survive compaction. Focus on: decisions made, open tasks, and anything you'd need to pick up where you left off.`;
+
+  // --- Session persistence ---
+
+  function sessionFilePath(sessionName: string): string {
+    return resolvePath(options.sessionsDir, `${sessionName}.json`);
+  }
+
+  function loadSessionId(sessionName: string): string | undefined {
+    try {
+      const data = JSON.parse(readFileSync(sessionFilePath(sessionName), "utf-8"));
+      return data.sessionId;
+    } catch (err: any) {
+      if (err?.code !== "ENOENT") {
+        log("agent", `failed to load session file for "${sessionName}":`, err);
       }
-    },
-  });
+      return undefined;
+    }
+  }
 
-  function sendMessage(content: string | VoluteContentPart[], meta?: ChannelMeta) {
-    const sessionName = meta?.sessionName ?? "main";
-    const session = sessionManager.getOrCreateSession(sessionName);
-
-    const text =
-      typeof content === "string"
-        ? content
-        : content.map((p) => (p.type === "text" ? p.text : `[${p.type}]`)).join(" ");
-    logMessage("in", text, meta?.channel);
-
-    const time = new Date().toLocaleString();
-    const prefix = formatPrefix(meta, time);
-
-    let sdkContent: (
-      | { type: "text"; text: string }
-      | {
-          type: "image";
-          source: {
-            type: "base64";
-            media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
-            data: string;
-          };
-        }
-    )[];
+  function saveSessionId(sessionName: string, sessionId: string) {
+    mkdirSync(options.sessionsDir, { recursive: true });
+    writeFileSync(sessionFilePath(sessionName), JSON.stringify({ sessionId }));
+  }
 
-    if (typeof content === "string") {
-      sdkContent = [{ type: "text" as const, text: prefix + content }];
-    } else {
-      const hasText = content.some((p) => p.type === "text");
-      sdkContent = content.map((part, i) => {
-        if (part.type === "text") {
-          return { type: "text" as const, text: (i === 0 ? prefix : "") + part.text };
-        }
-        return {
-          type: "image" as const,
-          source: {
-            type: "base64" as const,
-            media_type: part.media_type as "image/jpeg" | "image/png" | "image/gif" | "image/webp",
-            data: part.data,
-          },
-        };
+  function deleteSessionId(sessionName: string) {
+    try {
+      const path = sessionFilePath(sessionName);
+      if (existsSync(path)) unlinkSync(path);
+    } catch (err) {
+      log("agent", `failed to delete session file for "${sessionName}":`, err);
+    }
+  }
+
+  // --- Event broadcasting ---
+
+  function broadcastToSession(session: Session, event: VoluteEvent) {
+    const tagged =
+      session.currentMessageId != null ? { ...event, messageId: session.currentMessageId } : event;
+    for (const listener of session.listeners) {
+      try {
+        listener(tagged);
+      } catch (err) {
+        log("agent", "listener threw during broadcast:", err);
+      }
+    }
+  }
+
+  // --- SDK stream management ---
+
+  function createStream(session: Session, resume?: string) {
+    const preCompact = createPreCompactHook(() => {
+      session.messageIds.push(undefined);
+      session.channel.push({
+        type: "user",
+        session_id: "",
+        message: {
+          role: "user",
+          content: [{ type: "text", text: compactionMessage }],
+        },
+        parent_tool_use_id: null,
       });
-      if (prefix && !hasText) {
-        sdkContent.unshift({ type: "text" as const, text: prefix.trimEnd() });
+    });
+
+    return query({
+      prompt: session.channel.iterable,
+      options: {
+        systemPrompt: options.systemPrompt,
+        permissionMode: "bypassPermissions",
+        allowDangerouslySkipPermissions: true,
+        settingSources: ["project"],
+        cwd: options.cwd,
+        abortController: options.abortController,
+        model: options.model,
+        resume,
+        hooks: {
+          PostToolUse: postToolUseHooks,
+          PreCompact: [{ hooks: [preCompact.hook] }],
+        },
+      },
+    });
+  }
+
+  async function consumeStream(stream: ReturnType<typeof query>, session: Session) {
+    for await (const msg of stream) {
+      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);
+        }
+      }
+      if (msg.type === "assistant") {
+        for (const b of msg.message.content) {
+          if (b.type === "thinking" && "thinking" in b && b.thinking) {
+            logThinking(b.thinking as string);
+          } else if (b.type === "text") {
+            const text = (b as { text: string }).text;
+            logText(text);
+            broadcastToSession(session, { type: "text", content: text });
+          } else if (b.type === "tool_use") {
+            const tb = b as { name: string; input: unknown };
+            logToolUse(tb.name, tb.input);
+            broadcastToSession(session, { type: "tool_use", name: tb.name, input: tb.input });
+          }
+        }
+      }
+      if (msg.type === "result") {
+        log("agent", `session "${session.name}": turn done`);
+        broadcastToSession(session, { type: "done" });
+        session.currentMessageId = undefined;
+        if (identityReload.needsReload()) {
+          options.onIdentityReload?.();
+        }
       }
     }
+  }
+
+  function startSession(session: Session, savedSessionId?: string) {
+    (async () => {
+      log("agent", `session "${session.name}": stream consumer started`);
+      try {
+        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 {
+            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" });
+            sessions.delete(session.name);
+          }
+        } else {
+          log("agent", `session "${session.name}": stream consumer error:`, err);
+          broadcastToSession(session, { type: "done" });
+          sessions.delete(session.name);
+        }
+      }
+      log("agent", `session "${session.name}": stream consumer ended`);
+    })();
+  }
+
+  function getOrCreateSession(name: string): Session {
+    const existing = sessions.get(name);
+    if (existing) return existing;
+
+    const session: Session = {
+      name,
+      channel: createMessageChannel(),
+      listeners: new Set(),
+      messageIds: [],
+    };
+    sessions.set(name, session);
 
-    // 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);
+    const isEphemeral = name.startsWith("new-");
+    const savedSessionId = isEphemeral ? undefined : loadSessionId(name);
+    if (savedSessionId) {
+      log("agent", `session "${name}": resuming ${savedSessionId}`);
+    } else {
+      log("agent", `session "${name}": starting fresh`);
     }
 
-    session.messageIds.push(meta?.messageId);
-    session.channel.push({
-      type: "user",
-      session_id: "",
-      message: {
-        role: "user",
-        content: sdkContent,
+    startSession(session, savedSessionId);
+    return session;
+  }
+
+  // --- MessageHandler implementation ---
+
+  function createSessionHandler(sessionName: string): MessageHandler {
+    return {
+      handle(content: VoluteContentPart[], meta: HandlerMeta, listener: Listener): () => void {
+        const session = getOrCreateSession(sessionName);
+
+        // Filter listener to only receive events for this messageId
+        const filteredListener: Listener = (event) => {
+          if (event.messageId === meta.messageId) listener(event);
+        };
+        session.listeners.add(filteredListener);
+
+        // Interrupt if requested and session is mid-turn
+        if (meta.interrupt && session.currentMessageId !== undefined && session.currentQuery) {
+          log("agent", `session "${sessionName}": interrupting current turn`);
+          session.currentQuery.interrupt();
+        }
+
+        // Push message into SDK
+        session.messageIds.push(meta.messageId);
+        session.channel.push({
+          type: "user",
+          session_id: "",
+          message: { role: "user", content: toSDKContent(content) },
+          parent_tool_use_id: null,
+        });
+
+        return () => session.listeners.delete(filteredListener);
       },
-      parent_tool_use_id: null,
-    });
+    };
   }
 
-  function onMessage(listener: Listener, sessionName?: string): () => void {
-    const name = sessionName ?? "main";
-    const session = sessionManager.getOrCreateSession(name);
-    session.listeners.add(listener);
-    return () => session.listeners.delete(listener);
+  // --- HandlerResolver ---
+
+  const handlers = new Map<string, MessageHandler>();
+
+  function resolve(sessionName: string): MessageHandler {
+    // Ephemeral sessions get unique names — don't cache their handlers
+    if (sessionName.startsWith("new-")) {
+      return createSessionHandler(sessionName);
+    }
+    let handler = handlers.get(sessionName);
+    if (!handler) {
+      handler = createSessionHandler(sessionName);
+      handlers.set(sessionName, handler);
+    }
+    return handler;
   }
 
-  return { sendMessage, onMessage, waitForCommits: autoCommit.waitForCommits };
+  return { resolve, waitForCommits: autoCommit.waitForCommits };
 }

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

@@ -1,7 +1,9 @@
-import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createAgent } from "./agent.js";
+import { createFileHandlerResolver } from "./lib/file-handler.js";
 import { log } from "./lib/logger.js";
+import { createRouter } from "./lib/router.js";
 import {
   handleMergeContext,
   loadConfig,
@@ -39,24 +41,37 @@ const agent = createAgent({
   onIdentityReload: async () => {
     log("server", "identity file changed — restarting to reload");
     await agent.waitForCommits();
+    // Signal daemon to restart immediately (bypasses crash backoff)
+    try {
+      writeFileSync(resolve(".volute/restart.json"), JSON.stringify({ action: "reload" }));
+    } catch (err) {
+      log("server", "failed to write restart signal:", err);
+    }
     server.close();
     process.exit(0);
   },
 });
 
+const router = createRouter({
+  configPath: resolve("home/.config/routes.json"),
+  agentHandler: agent.resolve,
+  fileHandler: createFileHandlerResolver(resolve("home")),
+});
+
 const server = createVoluteServer({
-  agent,
+  router,
   port,
   name: pkg.name,
   version: pkg.version,
-  sessionsConfigPath: resolve("home/.config/sessions.json"),
 });
 
 server.listen(port, () => {
   const addr = server.address();
   const actualPort = typeof addr === "object" && addr ? addr.port : port;
   log("server", `listening on :${actualPort}`);
-  handleMergeContext((content) => agent.sendMessage(content));
+  handleMergeContext((content) =>
+    router.route([{ type: "text", text: content }], { channel: "system" }),
+  );
 });
 
 setupShutdown();

package/templates/agent-sdk/volute-template.json

@@ -4,6 +4,6 @@
     "biome.json.tmpl": "biome.json",
     "home/.config/volute.json.tmpl": "home/.config/volute.json"
   },
-  "substitute": ["package.json", ".init/SOUL.md"],
+  "substitute": ["package.json", ".init/SOUL.md", "home/.config/routes.json"],
   "skillsDir": "home/.claude/skills"
 }

package/templates/pi/.init/.config/routes.json

@@ -0,0 +1,5 @@
+{
+  "gateUnmatched": true,
+  "rules": [{ "channel": "volute:*", "isDM": true, "session": "${channel}" }],
+  "default": "main"
+}

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

@@ -23,7 +23,7 @@ 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`.
+- You may have **multiple named sessions** — each maintains its own conversation history. See `VOLUTE.md` for how to configure session routing via `.config/routes.json`.
 - 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.