volute 0.1.0

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

@@ -0,0 +1,199 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { createAutoCommitHook } from "./hooks/auto-commit.js";
+import { createIdentityReloadHook } from "./hooks/identity-reload.js";
+import { createPreCompactHook } from "./hooks/pre-compact.js";
+import { log, logMessage, logText, logThinking, logToolUse } from "./logger.js";
+import { createMessageChannel } from "./message-channel.js";
+import type { ChannelMeta, VoluteContentPart, VoluteEvent } from "./types.js";
+
+type Listener = (event: VoluteEvent) => void;
+
+function formatPrefix(meta: ChannelMeta | undefined, time: string): string {
+  if (!meta?.channel && !meta?.sender) return "";
+  // Use explicit platform name or capitalize from channel URI prefix
+  const platform =
+    meta.platform ??
+    (() => {
+      const n = (meta.channel ?? "").split(":")[0];
+      return n.charAt(0).toUpperCase() + n.slice(1);
+    })();
+  // Build sender context (e.g., "χθ in DM" or "χθ in #general in My Server")
+  let sender = meta.sender ?? "";
+  if (meta.isDM) {
+    sender += " in DM";
+  } else if (meta.channelName) {
+    sender += ` in #${meta.channelName}`;
+    if (meta.guildName) sender += ` in ${meta.guildName}`;
+  }
+  const parts = [platform, sender].filter(Boolean);
+  return parts.length > 0 ? `[${parts.join(": ")} — ${time}]\n` : "";
+}
+
+export function createAgent(options: {
+  systemPrompt: string;
+  cwd: string;
+  abortController: AbortController;
+  model?: string;
+  resume?: string;
+  onSessionId?: (id: string) => void;
+  onStreamError?: (err: unknown) => void;
+  onCompact?: () => void;
+  onIdentityReload?: () => void;
+}) {
+  const channel = createMessageChannel();
+  const listeners = new Set<Listener>();
+
+  const autoCommit = createAutoCommitHook(options.cwd);
+  const identityReload = createIdentityReloadHook(options.cwd);
+  const preCompact = createPreCompactHook(() => {
+    if (options.onCompact) options.onCompact();
+  });
+
+  function broadcast(event: VoluteEvent) {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        log("agent", "listener threw during broadcast:", err);
+      }
+    }
+  }
+
+  function createStream(resume?: string) {
+    return query({
+      prompt: channel.iterable,
+      options: {
+        systemPrompt: options.systemPrompt,
+        permissionMode: "bypassPermissions",
+        allowDangerouslySkipPermissions: true,
+        settingSources: ["project"],
+        cwd: options.cwd,
+        abortController: options.abortController,
+        model: options.model,
+        resume,
+        hooks: {
+          PostToolUse: [{ matcher: "Edit|Write", hooks: [autoCommit.hook, identityReload.hook] }],
+          PreCompact: [{ hooks: [preCompact.hook] }],
+        },
+      },
+    });
+  }
+
+  async function consumeStream(stream: ReturnType<typeof query>) {
+    for await (const msg of stream) {
+      if ("session_id" in msg && msg.session_id && options.onSessionId) {
+        options.onSessionId(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);
+            broadcast({ type: "text", content: text });
+          } else if (b.type === "tool_use") {
+            const tb = b as { name: string; input: unknown };
+            logToolUse(tb.name, tb.input);
+            broadcast({ type: "tool_use", name: tb.name, input: tb.input });
+          }
+        }
+      }
+      if (msg.type === "result") {
+        log("agent", "turn done");
+        broadcast({ type: "done" });
+        if (identityReload.needsReload()) {
+          options.onIdentityReload?.();
+        }
+      }
+    }
+  }
+
+  // Consume the SDK stream and broadcast VoluteEvent events
+  (async () => {
+    log("agent", "stream consumer started");
+    try {
+      await consumeStream(createStream(options.resume));
+    } catch (err) {
+      if (options.resume) {
+        log("agent", "session resume failed, starting fresh:", err);
+        if (options.onStreamError) options.onStreamError(err);
+        try {
+          await consumeStream(createStream());
+        } catch (retryErr) {
+          log("agent", "stream consumer error:", retryErr);
+          process.exit(1);
+        }
+      } else {
+        log("agent", "stream consumer error:", err);
+        if (options.onStreamError) options.onStreamError(err);
+        process.exit(1);
+      }
+    }
+    log("agent", "stream consumer ended");
+  })();
+
+  function sendMessage(content: string | VoluteContentPart[], meta?: ChannelMeta) {
+    const text =
+      typeof content === "string"
+        ? content
+        : content.map((p) => (p.type === "text" ? p.text : `[${p.type}]`)).join(" ");
+    logMessage("in", text, meta?.channel);
+
+    // Build context prefix from channel metadata
+    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;
+          };
+        }
+    )[];
+
+    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,
+          },
+        };
+      });
+      // If no text parts but we have a prefix, prepend a text part
+      if (prefix && !hasText) {
+        sdkContent.unshift({ type: "text" as const, text: prefix.trimEnd() });
+      }
+    }
+
+    channel.push({
+      type: "user",
+      session_id: "",
+      message: {
+        role: "user",
+        content: sdkContent,
+      },
+      parent_tool_use_id: null,
+    });
+  }
+
+  function onMessage(listener: Listener): () => void {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  return { sendMessage, onMessage, waitForCommits: autoCommit.waitForCommits };
+}

package/templates/agent-sdk/src/lib/hooks/auto-commit.ts

@@ -0,0 +1,14 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { commitFileChange, waitForCommits } from "../auto-commit.js";
+
+export function createAutoCommitHook(cwd: string) {
+  const hook: HookCallback = async (input) => {
+    const filePath = (input as { tool_input?: { file_path?: string } }).tool_input?.file_path;
+    if (filePath) {
+      commitFileChange(filePath, cwd);
+    }
+    return {};
+  };
+
+  return { hook, waitForCommits };
+}

package/templates/agent-sdk/src/lib/hooks/identity-reload.ts

@@ -0,0 +1,26 @@
+import { resolve } from "node:path";
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+
+const IDENTITY_FILES = ["SOUL.md", "MEMORY.md", "VOLUTE.md"];
+
+export function createIdentityReloadHook(cwd: string) {
+  let reloadNeeded = false;
+
+  const hook: HookCallback = async (input) => {
+    const filePath = (input as { tool_input?: { file_path?: string } }).tool_input?.file_path;
+    if (filePath) {
+      const resolved = resolve(cwd, filePath);
+      const fileName = resolved.slice(resolved.lastIndexOf("/") + 1);
+      if (IDENTITY_FILES.includes(fileName) && resolved.startsWith(resolve(cwd))) {
+        reloadNeeded = true;
+      }
+    }
+    return {};
+  };
+
+  function needsReload(): boolean {
+    return reloadNeeded;
+  }
+
+  return { hook, needsReload };
+}

package/templates/agent-sdk/src/lib/hooks/pre-compact.ts

@@ -0,0 +1,20 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { log } from "../logger.js";
+
+export function createPreCompactHook(onCompact: () => void) {
+  let compactBlocked = false;
+
+  const hook: HookCallback = async () => {
+    if (!compactBlocked) {
+      compactBlocked = true;
+      log("agent", "blocking compaction — asking agent to update daily log first");
+      onCompact();
+      return { decision: "block" };
+    }
+    compactBlocked = false;
+    log("agent", "allowing compaction");
+    return {};
+  };
+
+  return { hook };
+}

package/templates/agent-sdk/src/lib/message-channel.ts

@@ -0,0 +1,37 @@
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+
+export type MessageChannel = {
+  push: (msg: SDKUserMessage) => void;
+  iterable: AsyncIterable<SDKUserMessage>;
+};
+
+export function createMessageChannel(): MessageChannel {
+  const queue: SDKUserMessage[] = [];
+  let resolve: ((value: IteratorResult<SDKUserMessage>) => void) | null = null;
+
+  return {
+    push(msg: SDKUserMessage) {
+      if (resolve) {
+        const r = resolve;
+        resolve = null;
+        r({ value: msg, done: false });
+      } else {
+        queue.push(msg);
+      }
+    },
+    iterable: {
+      [Symbol.asyncIterator]() {
+        return {
+          next(): Promise<IteratorResult<SDKUserMessage>> {
+            if (queue.length > 0) {
+              return Promise.resolve({ value: queue.shift()!, done: false });
+            }
+            return new Promise((r) => {
+              resolve = r;
+            });
+          },
+        };
+      },
+    },
+  };
+}

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

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createAgent } from "./lib/agent.js";
+import { log } from "./lib/logger.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");
+
+const sessionPath = resolve(".volute/session.json");
+
+function loadSessionId(): string | undefined {
+  try {
+    const data = JSON.parse(readFileSync(sessionPath, "utf-8"));
+    return data.sessionId;
+  } catch {
+    return undefined;
+  }
+}
+
+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 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",
+    );
+  },
+  onIdentityReload: async () => {
+    log("server", "identity file changed — restarting to reload");
+    await agent.waitForCommits();
+    server.close();
+    process.exit(0);
+  },
+});
+
+const server = createVoluteServer({ agent, port, name: pkgName, version: pkgVersion });
+
+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);
+    }
+  }
+});
+
+function shutdown() {
+  shuttingDown = true;
+  log("server", "shutdown signal received");
+  process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

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

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

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

@@ -0,0 +1,26 @@
+# Agent Mechanics
+
+You are a volute agent running as a persistent server. Your state is managed across sessions.
+
+## Message Format
+
+Messages arrive with a context prefix built by your server code:
+```
+[Discord: username in #general in My Server]
+```
+
+## 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.
+
+See the **memory** skill for detailed guidance on consolidation and when to update.
+
+## Sessions
+
+- 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/package.json.tmpl

@@ -0,0 +1,20 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "^0.51.0",
+    "tsx": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.14",
+    "@types/node": "^25.2.0",
+    "typescript": "^5.7.0"
+  }
+}