volute 0.1.0

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

@@ -0,0 +1,205 @@
+import { getModel, getModels, type ImageContent } 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, logMessage, logText, logThinking, logToolResult, logToolUse } from "./logger.js";
+import type { ChannelMeta, VoluteContentPart, VoluteEvent } from "./types.js";
+
+type Listener = (event: VoluteEvent) => void;
+
+function formatPrefix(meta: ChannelMeta | undefined): string {
+  if (!meta?.channel && !meta?.sender) return "";
+  const platform =
+    meta.platform ??
+    (() => {
+      const n = (meta.channel ?? "").split(":")[0];
+      return n.charAt(0).toUpperCase() + n.slice(1);
+    })();
+  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(": ")}]\n` : "";
+}
+
+export async function createAgent(options: {
+  systemPrompt: string;
+  cwd: string;
+  model?: string;
+  resume?: boolean;
+  onCompact?: () => void;
+}) {
+  const listeners = new Set<Listener>();
+
+  // Block compaction once so the agent can update its daily log with full context
+  let compactBlocked = false;
+  const preCompactExtension: ExtensionFactory = (pi) => {
+    pi.on("session_before_compact", () => {
+      if (!compactBlocked) {
+        compactBlocked = true;
+        log("agent", "blocking compaction — asking agent to update daily log first");
+        if (options.onCompact) options.onCompact();
+        return { cancel: true };
+      }
+      compactBlocked = false;
+      log("agent", "allowing compaction");
+    });
+  };
+
+  // Parse model string: "provider:model-id" or use default
+  const modelStr = options.model || process.env.PI_MODEL || "anthropic:claude-sonnet-4-20250514";
+  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(", ")}`,
+    );
+  }
+
+  const authStorage = new AuthStorage();
+  const modelRegistry = new ModelRegistry(authStorage);
+
+  // Use persistent sessions in cwd for resume support, or in-memory if not resuming
+  const sessionManager = options.resume
+    ? SessionManager.continueRecent(options.cwd)
+    : SessionManager.create(options.cwd);
+
+  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 } = await createAgentSession({
+    cwd: options.cwd,
+    model,
+    authStorage,
+    modelRegistry,
+    sessionManager,
+    settingsManager,
+    resourceLoader,
+  });
+
+  function broadcast(event: VoluteEvent) {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        log("agent", "listener threw during broadcast:", err);
+      }
+    }
+  }
+
+  const toolArgs = new Map<string, any>();
+
+  session.subscribe((event) => {
+    if (event.type === "message_update") {
+      const ae = event.assistantMessageEvent;
+      if (ae.type === "text_delta") {
+        logText(ae.delta);
+        broadcast({ 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({
+        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({
+        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", "turn done");
+      broadcast({ type: "done" });
+    }
+  });
+
+  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);
+
+    // Build context prefix from channel metadata
+    const prefix = formatPrefix(meta);
+    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 } : {};
+
+    if (session.isStreaming) {
+      session.prompt(text, { streamingBehavior: "followUp", ...opts });
+    } else {
+      session.prompt(text, opts);
+    }
+  }
+
+  function onMessage(listener: Listener): () => void {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  return { sendMessage, onMessage };
+}

package/templates/pi/src/server.ts

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { 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;
+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");
+
+// Check if a session directory exists (indicates resumable session)
+const sessionsDir = resolve("home/.pi/sessions");
+const hasExistingSession = existsSync(sessionsDir);
+if (hasExistingSession) {
+  log("server", "found existing sessions, will attempt resume");
+}
+
+// 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 agent = await createAgent({
+  systemPrompt,
+  cwd: resolve("home"),
+  model,
+  resume: hasExistingSession,
+  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",
+    );
+  },
+});
+
+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() {
+  log("server", "shutdown signal received");
+  process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/templates/pi/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/volute.json.tmpl

@@ -0,0 +1,3 @@
+{
+  "model": "anthropic:claude-sonnet-4-20250514"
+}