volute 0.1.0 → 0.2.1

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

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { createPreCompactHook } from "./hooks/pre-compact.js";
+import { log, logText, logThinking, logToolUse } from "./logger.js";
+import { createMessageChannel } from "./message-channel.js";
+import type { Listener, VoluteEvent } from "./types.js";
+
+type Session = {
+  name: string;
+  channel: ReturnType<typeof createMessageChannel>;
+  listeners: Set<Listener>;
+};
+
+export function createSessionManager(options: {
+  systemPrompt: string;
+  cwd: string;
+  abortController: AbortController;
+  model?: string;
+  sessionsDir: string;
+  postToolUseHooks: { matcher: string; hooks: HookCallback[] }[];
+  onTurnDone?: () => void;
+  compactionMessage?: string;
+}) {
+  const sessions = new Map<string, Session>();
+  const compactionMessage =
+    options.compactionMessage ??
+    "Your conversation is approaching its context limit. Please update today's journal entry to preserve important context before the conversation is compacted.";
+
+  function sessionFilePath(sessionName: string): string {
+    return resolve(options.sessionsDir, `${sessionName}.json`);
+  }
+
+  function loadSessionId(sessionName: string): string | undefined {
+    try {
+      const data = JSON.parse(readFileSync(sessionFilePath(sessionName), "utf-8"));
+      return data.sessionId;
+    } catch {
+      return undefined;
+    }
+  }
+
+  function saveSessionId(sessionName: string, sessionId: string) {
+    mkdirSync(options.sessionsDir, { recursive: true });
+    writeFileSync(sessionFilePath(sessionName), JSON.stringify({ sessionId }));
+  }
+
+  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);
+    }
+  }
+
+  function broadcastToSession(session: Session, event: VoluteEvent) {
+    for (const listener of session.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        log("agent", "listener threw during broadcast:", err);
+      }
+    }
+  }
+
+  function createStream(session: Session, resume?: string) {
+    const preCompact = createPreCompactHook(() => {
+      session.channel.push({
+        type: "user",
+        session_id: "",
+        message: {
+          role: "user",
+          content: [{ type: "text", text: compactionMessage }],
+        },
+        parent_tool_use_id: null,
+      });
+    });
+
+    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: options.postToolUseHooks,
+          PreCompact: [{ hooks: [preCompact.hook] }],
+        },
+      },
+    });
+  }
+
+  async function consumeStream(stream: ReturnType<typeof query>, session: Session) {
+    for await (const msg of stream) {
+      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" });
+        options.onTurnDone?.();
+      }
+    }
+  }
+
+  function startSession(session: Session, savedSessionId?: string) {
+    (async () => {
+      log("agent", `session "${session.name}": stream consumer started`);
+      try {
+        await consumeStream(createStream(session, savedSessionId), session);
+      } catch (err) {
+        if (savedSessionId) {
+          log("agent", `session "${session.name}": resume failed, starting fresh:`, err);
+          deleteSessionId(session.name);
+          try {
+            await consumeStream(createStream(session), 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(),
+    };
+    sessions.set(name, session);
+
+    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`);
+    }
+
+    startSession(session, savedSessionId);
+    return session;
+  }
+
+  return { getOrCreateSession };
+}

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

@@ -1,117 +1,41 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { createAgent } from "./lib/agent.js";
+import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { resolve } from "node:path";
+import { createAgent } from "./agent.js";
 import { log } from "./lib/logger.js";
+import {
+  handleMergeContext,
+  loadConfig,
+  loadPackageInfo,
+  loadSystemPrompt,
+  parseArgs,
+  setupShutdown,
+} from "./lib/startup.js";
 import { createVoluteServer } from "./lib/volute-server.js";
 
-function parseArgs() {
-  const args = process.argv.slice(2);
-  let port = 4100;
-
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--port" && args[i + 1]) {
-      port = parseInt(args[++i], 10);
-    }
-  }
-
-  return { port };
-}
-
-function loadConfig(): { model?: string } {
-  try {
-    return JSON.parse(readFileSync(resolve("volute.json"), "utf-8"));
-  } catch {
-    return {};
-  }
-}
-
-function loadFile(path: string): string {
-  try {
-    return readFileSync(path, "utf-8");
-  } catch {
-    return "";
-  }
-}
-
 const { port } = parseArgs();
 const config = loadConfig();
-const model = config.model;
-if (model) {
-  log("server", `using model: ${model}`);
-}
-const soulPath = resolve("home/SOUL.md");
-const memoryPath = resolve("home/MEMORY.md");
-const volutePath = resolve("home/VOLUTE.md");
-
-const soul = loadFile(soulPath);
-if (!soul) {
-  console.error(`Could not read soul file: ${soulPath}`);
-  process.exit(1);
-}
-
-const memory = loadFile(memoryPath);
-const volute = loadFile(volutePath);
-
-const promptParts = [soul];
-if (volute) promptParts.push(volute);
-if (memory) promptParts.push(`## Memory\n\n${memory}`);
-const systemPrompt = promptParts.join("\n\n---\n\n");
+if (config.model) log("server", `using model: ${config.model}`);
 
-const sessionPath = resolve(".volute/session.json");
+const systemPrompt = loadSystemPrompt();
+const sessionsDir = resolve(".volute/sessions");
 
-function loadSessionId(): string | undefined {
-  try {
-    const data = JSON.parse(readFileSync(sessionPath, "utf-8"));
-    return data.sessionId;
-  } catch {
-    return undefined;
-  }
+// Migrate old single session.json → sessions/main.json
+const oldSessionPath = resolve(".volute/session.json");
+if (existsSync(oldSessionPath) && !existsSync(resolve(sessionsDir, "main.json"))) {
+  mkdirSync(sessionsDir, { recursive: true });
+  renameSync(oldSessionPath, resolve(sessionsDir, "main.json"));
+  log("server", "migrated session.json → sessions/main.json");
 }
 
-function saveSessionId(sessionId: string) {
-  mkdirSync(dirname(sessionPath), { recursive: true });
-  writeFileSync(sessionPath, JSON.stringify({ sessionId }));
-}
-
-let shuttingDown = false;
-
-function deleteSessionFile() {
-  if (shuttingDown) return;
-  try {
-    unlinkSync(sessionPath);
-    log("server", "deleted session file");
-  } catch {}
-}
-
-// Read name/version from package.json for health endpoint
-let pkgName = "unknown";
-let pkgVersion = "0.0.0";
-try {
-  const pkg = JSON.parse(readFileSync(resolve("package.json"), "utf-8"));
-  pkgName = pkg.name || pkgName;
-  pkgVersion = pkg.version || pkgVersion;
-} catch {}
-
+const pkg = loadPackageInfo();
 const abortController = new AbortController();
-const savedSessionId = loadSessionId();
-if (savedSessionId) {
-  log("server", `resuming session: ${savedSessionId}`);
-}
 const agent = createAgent({
   systemPrompt,
   cwd: resolve("home"),
   abortController,
-  model,
-  resume: savedSessionId,
-  onSessionId: saveSessionId,
-  onStreamError: deleteSessionFile,
-  onCompact: () => {
-    log("server", "pre-compact — asking agent to update daily log");
-    agent.sendMessage(
-      "Conversation is about to be compacted. Please update today's daily log with a summary of what we've discussed and accomplished so far, so context is preserved before compaction.",
-      "system",
-    );
-  },
+  model: config.model,
+  sessionsDir,
+  compactionMessage: config.compactionMessage,
   onIdentityReload: async () => {
     log("server", "identity file changed — restarting to reload");
     await agent.waitForCommits();
@@ -120,39 +44,19 @@ const agent = createAgent({
   },
 });
 
-const server = createVoluteServer({ agent, port, name: pkgName, version: pkgVersion });
+const server = createVoluteServer({
+  agent,
+  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}`);
-
-  // Check for post-merge context
-  const mergedPath = resolve(".volute/merged.json");
-  if (existsSync(mergedPath)) {
-    try {
-      const merged = JSON.parse(readFileSync(mergedPath, "utf-8"));
-      unlinkSync(mergedPath);
-
-      const parts = [
-        `[system] Variant "${merged.name}" has been merged and you have been restarted.`,
-      ];
-      if (merged.summary) parts.push(`Changes: ${merged.summary}`);
-      if (merged.justification) parts.push(`Why: ${merged.justification}`);
-      if (merged.memory) parts.push(`Context: ${merged.memory}`);
-
-      agent.sendMessage(parts.join("\n"));
-      log("server", `sent post-merge orientation for variant: ${merged.name}`);
-    } catch (e) {
-      log("server", "failed to process merged.json:", e);
-    }
-  }
+  handleMergeContext((content) => agent.sendMessage(content));
 });
 
-function shutdown() {
-  shuttingDown = true;
-  log("server", "shutdown signal received");
-  process.exit(0);
-}
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
+setupShutdown();

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

@@ -2,7 +2,7 @@
   "rename": {
     "package.json.tmpl": "package.json",
     "biome.json.tmpl": "biome.json",
-    "volute.json.tmpl": "volute.json"
+    "home/.config/volute.json.tmpl": "home/.config/volute.json"
   },
   "substitute": ["package.json", ".init/SOUL.md"],
   "skillsDir": "home/.claude/skills"

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

@@ -0,0 +1 @@
+{ "rules": [], "default": "main" }

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

@@ -6,7 +6,7 @@ You are a volute agent running as a persistent server. Your state is managed acr
 
 Messages arrive with a context prefix built by your server code:
 ```
-[Discord: username in #general in My Server]
+[Discord: username in #general in My Server — 1/15/2025, 10:30:00 AM]
 ```
 
 ## Memory System
@@ -21,6 +21,7 @@ See the **memory** skill for detailed guidance on consolidation and when to upda
 
 ## 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.

package/templates/pi/src/agent.ts

@@ -0,0 +1,61 @@
+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";
+
+export function createAgent(options: {
+  systemPrompt: string;
+  cwd: string;
+  model?: string;
+  compactionMessage?: string;
+}) {
+  const { getOrCreateSession } = createPiSessionManager(options);
+
+  function sendMessage(content: string | VoluteContentPart[], meta?: ChannelMeta) {
+    const raw =
+      typeof content === "string"
+        ? content
+        : content
+            .filter((p) => p.type === "text")
+            .map((p) => (p as { text: string }).text)
+            .join("\n");
+    logMessage("in", raw, meta?.channel);
+
+    const sessionName = meta?.sessionName ?? "main";
+    const session = getOrCreateSession(sessionName);
+
+    // Build context prefix from channel metadata
+    const prefix = formatPrefix(meta, new Date().toLocaleString());
+    const text = prefix + raw;
+
+    // Convert image parts to pi-ai ImageContent format
+    const images: ImageContent[] | undefined =
+      typeof content === "string"
+        ? undefined
+        : content
+            .filter((p) => p.type === "image")
+            .map((p) => ({ type: "image" as const, mimeType: p.media_type, data: p.data }));
+
+    const opts = images?.length ? { images } : {};
+
+    // Fire-and-forget: await session ready then prompt
+    (async () => {
+      await session.ready;
+      if (session.agentSession!.isStreaming) {
+        session.agentSession!.prompt(text, { streamingBehavior: "followUp", ...opts });
+      } else {
+        session.agentSession!.prompt(text, opts);
+      }
+    })();
+  }
+
+  function onMessage(listener: Listener, sessionName?: string): () => void {
+    const name = sessionName ?? "main";
+    const session = getOrCreateSession(name);
+    session.listeners.add(listener);
+    return () => session.listeners.delete(listener);
+  }
+
+  return { sendMessage, onMessage };
+}

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

@@ -0,0 +1,188 @@
+import { getModel, getModels } from "@mariozechner/pi-ai";
+import {
+  AuthStorage,
+  createAgentSession,
+  DefaultResourceLoader,
+  type ExtensionFactory,
+  ModelRegistry,
+  SessionManager,
+  SettingsManager,
+} from "@mariozechner/pi-coding-agent";
+import { commitFileChange } from "./auto-commit.js";
+import { log, logText, logThinking, logToolResult, logToolUse } from "./logger.js";
+import type { Listener, VoluteEvent } from "./types.js";
+
+type AgentSession = Awaited<ReturnType<typeof createAgentSession>>["session"];
+
+type PiSession = {
+  name: string;
+  agentSession: AgentSession | null;
+  ready: Promise<void>;
+  listeners: Set<Listener>;
+  unsubscribe?: () => void;
+};
+
+const DEFAULT_COMPACTION_MESSAGE =
+  "Your conversation is approaching its context limit. Please update today's journal entry to preserve important context before the conversation is compacted.";
+
+function resolveModel(modelStr: string) {
+  const [provider, ...rest] = modelStr.split(":");
+  const modelId = rest.join(":");
+
+  // Try exact match first, then prefix match against available models
+  let model = getModel(provider as any, modelId as any);
+  if (!model) {
+    const available = getModels(provider as any);
+    const found = available.find((m) => m.id.startsWith(modelId));
+    if (found) model = found;
+  }
+  if (!model) {
+    const available = getModels(provider as any);
+    throw new Error(
+      `Model not found: ${modelStr}\nAvailable ${provider} models: ${available.map((m) => m.id).join(", ")}`,
+    );
+  }
+  return model;
+}
+
+export function createPiSessionManager(options: {
+  systemPrompt: string;
+  cwd: string;
+  model?: string;
+  compactionMessage?: string;
+}) {
+  const sessions = new Map<string, PiSession>();
+  const compactionMessage = options.compactionMessage ?? DEFAULT_COMPACTION_MESSAGE;
+
+  // Shared setup (created once)
+  const modelStr = options.model || process.env.PI_MODEL || "anthropic:claude-sonnet-4-20250514";
+  const model = resolveModel(modelStr);
+  const authStorage = new AuthStorage();
+  const modelRegistry = new ModelRegistry(authStorage);
+
+  function getOrCreateSession(name: string): PiSession {
+    const existing = sessions.get(name);
+    if (existing) return existing;
+
+    const session: PiSession = {
+      name,
+      agentSession: null,
+      ready: Promise.resolve(),
+      listeners: new Set(),
+    };
+    sessions.set(name, session);
+
+    session.ready = initSession(session);
+    return session;
+  }
+
+  async function initSession(session: PiSession) {
+    const isEphemeral = session.name.startsWith("new-");
+
+    // Per-session session manager
+    const sessionManager = isEphemeral
+      ? SessionManager.inMemory()
+      : SessionManager.continueRecent(options.cwd, `.volute/pi-sessions/${session.name}`);
+
+    log("agent", `session "${session.name}": ${isEphemeral ? "ephemeral" : "persistent"}`);
+
+    // Per-session pre-compact extension: block once, send compaction message, allow on second call
+    let compactBlocked = false;
+    const preCompactExtension: ExtensionFactory = (pi) => {
+      pi.on("session_before_compact", () => {
+        if (!compactBlocked) {
+          compactBlocked = true;
+          log(
+            "agent",
+            `session "${session.name}": blocking compaction — asking agent to update daily log`,
+          );
+          session.agentSession?.prompt(compactionMessage, { streamingBehavior: "followUp" });
+          return { cancel: true };
+        }
+        compactBlocked = false;
+        log("agent", `session "${session.name}": allowing compaction`);
+      });
+    };
+
+    const settingsManager = SettingsManager.inMemory({
+      retry: { enabled: true, maxRetries: 3 },
+    });
+
+    const resourceLoader = new DefaultResourceLoader({
+      cwd: options.cwd,
+      settingsManager,
+      systemPrompt: options.systemPrompt,
+      extensionFactories: [preCompactExtension],
+    });
+    await resourceLoader.reload();
+
+    const { session: agentSession } = await createAgentSession({
+      cwd: options.cwd,
+      model,
+      authStorage,
+      modelRegistry,
+      sessionManager,
+      settingsManager,
+      resourceLoader,
+    });
+
+    session.agentSession = agentSession;
+
+    // Per-session event subscription
+    const toolArgs = new Map<string, any>();
+
+    session.unsubscribe = agentSession.subscribe((event) => {
+      if (event.type === "message_update") {
+        const ae = event.assistantMessageEvent;
+        if (ae.type === "text_delta") {
+          logText(ae.delta);
+          broadcast(session, { type: "text", content: ae.delta });
+        } else if (ae.type === "thinking_delta") {
+          logThinking(ae.delta);
+        }
+      }
+
+      if (event.type === "tool_execution_start") {
+        toolArgs.set(event.toolCallId, event.args);
+        logToolUse(event.toolName, event.args);
+        broadcast(session, { type: "tool_use", name: event.toolName, input: event.args });
+      }
+
+      if (event.type === "tool_execution_end") {
+        const output =
+          typeof event.result === "string" ? event.result : JSON.stringify(event.result);
+        logToolResult(event.toolName, output, event.isError);
+        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) {
+          const args = toolArgs.get(event.toolCallId);
+          const filePath = (args as { file_path?: string })?.file_path;
+          if (filePath) {
+            commitFileChange(filePath, options.cwd);
+          }
+        }
+        toolArgs.delete(event.toolCallId);
+      }
+
+      if (event.type === "agent_end") {
+        log("agent", `session "${session.name}": turn done`);
+        broadcast(session, { type: "done" });
+      }
+    });
+
+    log("agent", `session "${session.name}": ready`);
+  }
+
+  function broadcast(session: PiSession, event: VoluteEvent) {
+    for (const listener of session.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        log("agent", "listener threw during broadcast:", err);
+      }
+    }
+  }
+
+  return { getOrCreateSession };
+}