volute 0.33.0 → 0.35.0

package/templates/_base/src/lib/router.ts

@@ -1,6 +1,11 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { formatPrefix, formatTypingSuffix } from "./format-prefix.js";
+import {
+  compactTime,
+  compactTimestamp,
+  formatPrefix,
+  formatTypingSuffix,
+} from "./format-prefix.js";
 import { log, warn } from "./logger.js";
 import {
   type BatchConfig,
@@ -11,6 +16,12 @@ import {
 import { loadPrompts } from "./startup.js";
 import type { ChannelMeta, HandlerResolver, Listener, VoluteContentPart } from "./types.js";
 
+/** Shape of a single message in a batch payload (subset of daemon DeliveryPayload). */
+export type BatchMessage = {
+  sender?: string | null;
+  content: unknown;
+};
+
 export type Router = {
   route(
     content: VoluteContentPart[],
@@ -25,7 +36,7 @@ export type Router = {
     listener?: Listener,
   ): { messageId: string; unsubscribe: () => void };
   dispatchBatch(
-    batch: { channels: Record<string, any[]> },
+    batch: { channels: Record<string, BatchMessage[]> },
     session: string,
     meta: ChannelMeta,
   ): void;
@@ -55,7 +66,7 @@ function generateMessageId(): string {
 }
 
 function applyPrefix(content: VoluteContentPart[], meta: ChannelMeta): VoluteContentPart[] {
-  const time = new Date().toLocaleString();
+  const time = compactTimestamp();
   const prefix = formatPrefix(meta, time);
   if (!prefix) return content;
 
@@ -129,7 +140,7 @@ function formatInviteNotification(
   filePath: string,
   messageText: string,
 ): string {
-  const time = new Date().toLocaleString();
+  const time = compactTimestamp();
   const prompts = loadPrompts();
 
   const headerLines: string[] = [];
@@ -172,6 +183,18 @@ export function createRouter(options: {
 }): Router {
   const batchBuffers = new Map<string, BatchBuffer>();
   const pendingChannels = new Set<string>();
+  const instructedSessions = new Set<string>();
+
+  /** Prepend session instructions only on the first message per session. */
+  function prependInstructionsOnce(
+    content: VoluteContentPart[],
+    instructions: string | undefined,
+    sessionName: string,
+  ): VoluteContentPart[] {
+    if (!instructions || instructedSessions.has(sessionName)) return content;
+    instructedSessions.add(sessionName);
+    return prependInstructions(content, instructions);
+  }
 
   function flushBatch(key: string) {
     const buffer = batchBuffers.get(key);
@@ -191,16 +214,22 @@ export function createRouter(options: {
       const uri = msg.channel ?? "unknown";
       channelCounts.set(uri, (channelCounts.get(uri) ?? 0) + 1);
     }
-    const channelLabels = [...channelCounts.entries()].map(([uri, n]) => {
+    let header: string;
+    if (channelCounts.size === 1) {
+      const [uri] = [...channelCounts.keys()];
       const msg = messages.find((m) => m.channel === uri);
-      const display = msg?.channelName
-        ? `#${msg.channelName}${msg.serverName ? ` in ${msg.serverName}` : ""} (${uri})`
-        : uri;
-      return `${n} from ${display}`;
-    });
-    const summary = channelLabels.join(", ");
-
-    const header = `[Batch: ${messages.length} message${messages.length === 1 ? "" : "s"} — ${summary}]`;
+      const display = msg?.channelName ? `#${msg.channelName}` : uri;
+      header = `[Batch: ${messages.length} message${messages.length === 1 ? "" : "s"} from ${display}]`;
+    } else {
+      const channelLabels = [...channelCounts.entries()].map(([uri, n]) => {
+        const msg = messages.find((m) => m.channel === uri);
+        const display = msg?.channelName
+          ? `#${msg.channelName}${msg.serverName ? ` in ${msg.serverName}` : ""}`
+          : uri;
+        return `${n} from ${display}`;
+      });
+      header = `[Batch: ${messages.length} messages — ${channelLabels.join(", ")}]`;
+    }
     // Include channel URI per message when batch spans multiple channels
     const multiChannel = channelCounts.size > 1;
     const body = messages
@@ -222,7 +251,7 @@ export function createRouter(options: {
     // Resolve session config for instructions
     const config = options.configPath ? loadRoutingConfig(options.configPath) : {};
     const sessionConfig = resolveSessionConfig(config, buffer.sessionName);
-    content = prependInstructions(content, sessionConfig.instructions);
+    content = prependInstructionsOnce(content, sessionConfig.instructions, buffer.sessionName);
 
     const messageId = generateMessageId();
     const handler = options.mindHandler(buffer.sessionName);
@@ -296,13 +325,23 @@ export function createRouter(options: {
     // Resolve session config for instructions
     const config = options.configPath ? loadRoutingConfig(options.configPath) : {};
     const sessionConfig = resolveSessionConfig(config, session);
-    const withInstructions = prependInstructions(withTyping, sessionConfig.instructions);
+    const withInstructions = prependInstructionsOnce(
+      withTyping,
+      sessionConfig.instructions,
+      session,
+    );
 
     const handler = options.mindHandler(session);
-    const interrupt = (meta as any).interrupt ?? sessionConfig.interrupt;
+    const interrupt = meta.interrupt ?? sessionConfig.interrupt;
     const unsubscribe = handler.handle(
       withInstructions,
-      { ...meta, sessionName: session, messageId, interrupt },
+      {
+        ...meta,
+        sessionName: session,
+        messageId,
+        interrupt,
+        replyInstructions: sessionConfig.replyInstructions,
+      },
       safeListener,
     );
     return { messageId, unsubscribe };
@@ -423,10 +462,7 @@ export function createRouter(options: {
         channel: meta.channel,
         channelName: meta.channelName,
         serverName: meta.serverName,
-        timestamp: new Date().toLocaleTimeString("en-US", {
-          hour: "numeric",
-          minute: "2-digit",
-        }),
+        timestamp: compactTime(),
         typing: meta.typing,
       });
 
@@ -444,7 +480,11 @@ export function createRouter(options: {
     // Direct dispatch to mind
     const formatted = applyPrefix(content, { ...meta, sessionName });
     const withTyping = appendTypingSuffix(formatted, meta.typing);
-    const withInstructions = prependInstructions(withTyping, sessionConfig.instructions);
+    const withInstructions = prependInstructionsOnce(
+      withTyping,
+      sessionConfig.instructions,
+      sessionName,
+    );
     const handler = options.mindHandler(sessionName);
     const unsubscribe = handler.handle(
       withInstructions,
@@ -453,6 +493,7 @@ export function createRouter(options: {
         sessionName,
         messageId,
         interrupt: sessionConfig.interrupt,
+        replyInstructions: sessionConfig.replyInstructions,
       },
       safeListener,
     );
@@ -464,11 +505,11 @@ export function createRouter(options: {
    * Formats messages grouped by channel into a single SDK message.
    */
   function dispatchBatch(
-    batch: { channels: Record<string, any[]> },
+    batch: { channels: Record<string, BatchMessage[]> },
     session: string,
     _meta: ChannelMeta,
   ): void {
-    const allMessages: { channel: string; payload: any }[] = [];
+    const allMessages: { channel: string; payload: BatchMessage }[] = [];
     for (const [channel, messages] of Object.entries(batch.channels)) {
       for (const msg of messages) {
         allMessages.push({ channel, payload: msg });
@@ -482,10 +523,14 @@ export function createRouter(options: {
     for (const msg of allMessages) {
       channelCounts.set(msg.channel, (channelCounts.get(msg.channel) ?? 0) + 1);
     }
-    const channelLabels = [...channelCounts.entries()].map(([ch, n]) => `${n} from ${ch}`);
-    const summary = channelLabels.join(", ");
-
-    const header = `[Batch: ${allMessages.length} message${allMessages.length === 1 ? "" : "s"} — ${summary}]`;
+    let header: string;
+    if (channelCounts.size === 1) {
+      const [ch] = [...channelCounts.keys()];
+      header = `[Batch: ${allMessages.length} message${allMessages.length === 1 ? "" : "s"} from ${ch}]`;
+    } else {
+      const channelLabels = [...channelCounts.entries()].map(([ch, n]) => `${n} from ${ch}`);
+      header = `[Batch: ${allMessages.length} messages — ${channelLabels.join(", ")}]`;
+    }
     const multiChannel = channelCounts.size > 1;
 
     const body = allMessages
@@ -500,10 +545,7 @@ export function createRouter(options: {
                   .map((p) => p.text)
                   .join("\n")
               : JSON.stringify(m.payload.content);
-        const time = new Date().toLocaleTimeString("en-US", {
-          hour: "numeric",
-          minute: "2-digit",
-        });
+        const time = compactTime();
         const prefix = multiChannel
           ? `[${sender} in ${m.channel} — ${time}]`
           : `[${sender} — ${time}]`;
@@ -516,7 +558,7 @@ export function createRouter(options: {
     // Resolve session config for instructions
     const config = options.configPath ? loadRoutingConfig(options.configPath) : {};
     const sessionConfig = resolveSessionConfig(config, session);
-    const withInstructions = prependInstructions(content, sessionConfig.instructions);
+    const withInstructions = prependInstructionsOnce(content, sessionConfig.instructions, session);
 
     const messageId = generateMessageId();
     const handler = options.mindHandler(session);

package/templates/_base/src/lib/routing.ts

@@ -23,12 +23,14 @@ export type SessionConfig = {
   batch?: number | BatchConfig;
   interrupt?: boolean;
   instructions?: string;
+  replyInstructions?: "once" | "always" | "never";
 };
 
 export type ResolvedSessionConfig = {
   batch?: BatchConfig;
   interrupt: boolean;
   instructions?: string;
+  replyInstructions: "once" | "always" | "never";
 };
 
 export type RoutingConfig = {
@@ -154,7 +156,7 @@ export function resolveSessionConfig(
   config: RoutingConfig,
   sessionName: string,
 ): ResolvedSessionConfig {
-  const defaults: ResolvedSessionConfig = { interrupt: true };
+  const defaults: ResolvedSessionConfig = { interrupt: true, replyInstructions: "once" };
 
   if (!config.sessions) return defaults;
 
@@ -165,6 +167,7 @@ export function resolveSessionConfig(
         batch,
         interrupt: sessionConfig.interrupt ?? true,
         instructions: sessionConfig.instructions,
+        replyInstructions: sessionConfig.replyInstructions ?? "once",
       };
     }
   }

package/templates/_base/src/lib/startup.ts

@@ -23,13 +23,19 @@ export type SubagentConfig = {
   maxTurns?: number;
 };
 
-export function loadConfig(): {
+export type MindConfig = {
   model?: string;
   logLevel?: "error" | "warn" | "info" | "debug";
   compactionMessage?: string;
   compaction?: { maxContextTokens?: number };
   subagents?: Record<string, SubagentConfig>;
-} {
+  // Template-specific config fields (claude, pi, codex)
+  maxThinkingTokens?: number;
+  thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+  reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
+};
+
+export function loadConfig(): MindConfig {
   try {
     return JSON.parse(readFileSync(resolve("home/.config/config.json"), "utf-8"));
   } catch (err: any) {
@@ -77,12 +83,16 @@ export function loadPackageInfo(): { name: string; version: string } {
   }
 }
 
-export async function handleStartupContext(sendMessage: (content: string) => void): Promise<void> {
+/**
+ * Run the startup-context hook and return the generated context string.
+ * Returns null if no hook is found or it produces no output.
+ */
+export async function getStartupContext(): Promise<string | null> {
   // Prefer .ts, fall back to .sh for backwards compatibility
   const tsPath = resolve("home/.local/hooks/startup-context.ts");
   const shPath = resolve("home/.local/hooks/startup-context.sh");
   const scriptPath = existsSync(tsPath) ? tsPath : existsSync(shPath) ? shPath : null;
-  if (!scriptPath) return;
+  if (!scriptPath) return null;
 
   const isTs = scriptPath.endsWith(".ts");
 
@@ -112,12 +122,10 @@ export async function handleStartupContext(sendMessage: (content: string) => voi
       context = stdout.trim();
     }
 
-    if (context) {
-      sendMessage(`[system] ${context}`);
-      log("server", "sent startup context");
-    }
+    return context || null;
   } catch (e) {
     log("server", "failed to run startup context hook:", e);
+    return null;
   }
 }
 

package/templates/_base/src/lib/types.ts

@@ -21,6 +21,8 @@ export type ChannelMeta = {
   participantCount?: number;
   participantProfiles?: ParticipantProfile[];
   typing?: string[];
+  replyInstructions?: "once" | "always" | "never";
+  interrupt?: boolean;
   signature?: string;
   signatureTimestamp?: string;
   signerFingerprint?: string;
@@ -30,7 +32,6 @@ export type ChannelMeta = {
 /** ChannelMeta enriched by the router with dispatch info. */
 export type HandlerMeta = ChannelMeta & {
   messageId: string;
-  interrupt?: boolean;
 };
 
 export type VoluteRequest = {

package/templates/_base/src/lib/volute-server.ts

@@ -1,7 +1,7 @@
 import { createHash, verify } from "node:crypto";
 import { createServer, type IncomingMessage, type Server } from "node:http";
 import { log } from "./logger.js";
-import type { Router } from "./router.js";
+import type { BatchMessage, Router } from "./router.js";
 import type { VoluteContentPart, VoluteRequest } from "./types.js";
 
 function readBody(req: IncomingMessage): Promise<string> {
@@ -21,10 +21,27 @@ function extractText(content: VoluteContentPart[] | string): string {
     .join("\n");
 }
 
-/** Normalize content to VoluteContentPart[] — connectors may send plain strings. */
+/** Normalize content to VoluteContentPart[] — connectors may send plain strings or mixed arrays. */
 function normalizeContent(content: unknown): VoluteContentPart[] {
-  if (Array.isArray(content)) return content as VoluteContentPart[];
   if (typeof content === "string") return [{ type: "text", text: content }];
+  if (Array.isArray(content)) {
+    return content.map((item): VoluteContentPart => {
+      if (typeof item === "object" && item !== null && "type" in item) {
+        const obj = item as Record<string, unknown>;
+        if (obj.type === "image") {
+          if (typeof obj.media_type === "string" && typeof obj.data === "string") {
+            return { type: "image", media_type: obj.media_type, data: obj.data };
+          }
+          log("server", "image content part missing required fields, coercing to text");
+        }
+        if (typeof obj.text === "string") return { type: "text", text: obj.text };
+      }
+      if (typeof item !== "string") {
+        log("server", `unexpected content type (${typeof item}), coercing to text`);
+      }
+      return { type: "text", text: typeof item === "string" ? item : JSON.stringify(item) };
+    });
+  }
   return [{ type: "text", text: JSON.stringify(content) }];
 }
 
@@ -78,15 +95,47 @@ async function verifyRequest(body: VoluteRequest): Promise<boolean | undefined>
   return verifySignature(publicKey, text, body.signatureTimestamp, body.signature);
 }
 
+export type ContextBreakdown = {
+  systemPrompt: number;
+  sdkInstructions: number;
+  skillDescriptions: number;
+  conversation: {
+    userText: number;
+    assistantText: number;
+    thinking: number;
+    toolUse: number;
+    toolResult: number;
+  };
+};
+
+export type SessionContextInfo = {
+  name: string;
+  contextTokens: number;
+  contextWindow?: number;
+  breakdown?: ContextBreakdown;
+};
+
+export type ContextInfo = {
+  sessions: SessionContextInfo[];
+  systemPrompt: number;
+};
+
 export function createVoluteServer(options: {
   router: Router;
   port: number;
   name: string;
   version: string;
+  getContextInfo?: () => ContextInfo | Promise<ContextInfo>;
 }): Server {
   const { router, port, name, version } = options;
 
   const server = createServer(async (req, res) => {
+    // Prevent EPIPE crashes when the client disconnects before the response is written
+    res.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EPIPE" || err.code === "ECONNRESET") return;
+      log("server", "response error:", err);
+    });
+
     const url = new URL(req.url!, "http://localhost");
 
     if (req.method === "GET" && url.pathname === "/health") {
@@ -95,6 +144,24 @@ export function createVoluteServer(options: {
       return;
     }
 
+    if (req.method === "GET" && url.pathname === "/context") {
+      if (!options.getContextInfo) {
+        res.writeHead(404);
+        res.end("Not Found");
+        return;
+      }
+      try {
+        const info = await options.getContextInfo();
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(info));
+      } catch (err) {
+        log("server", "error in /context:", err);
+        res.writeHead(500);
+        res.end("Internal Server Error");
+      }
+      return;
+    }
+
     if (req.method === "POST" && url.pathname === "/message") {
       try {
         const body = JSON.parse(await readBody(req)) as VoluteRequest;
@@ -110,11 +177,11 @@ export function createVoluteServer(options: {
         body.content = normalizeContent(body.content);
 
         // Handle batch payloads from delivery manager
-        if ((body as any).batch) {
-          const batch = (body as any).batch as {
-            channels: Record<string, any[]>;
-          };
-          router.dispatchBatch(batch, body.session ?? "main", body);
+        const bodyWithBatch = body as VoluteRequest & {
+          batch?: { channels: Record<string, BatchMessage[]> };
+        };
+        if (bodyWithBatch.batch) {
+          router.dispatchBatch(bodyWithBatch.batch, body.session ?? "main", body);
         } else {
           // Pre-routed by daemon delivery manager — dispatch directly
           router.dispatch(body.content, body.session ?? "main", body);

package/templates/claude/.init/CLAUDE.md

@@ -6,21 +6,22 @@ You are an autonomous mind running as a persistent server in a git repository. Y
 
 Messages arrive with a context prefix:
 ```
-[Discord: username in #general in My Server — 1/15/2025, 10:30:00 AM]
+[Discord: username in #general in My Server — 2025-01-15 10:30]
 ```
 
 You can also reach out proactively — see the **volute-mind** skill.
 
-## Identity Files
+## Identity & Sessions
 
 These files shape your starting identity. They're loaded into your system prompt, but they belong to you — edit them as you evolve:
 
 - `SOUL.md` — Who you are. Your core sense of self.
 - `MEMORY.md` — What you know. Your long-term memory.
-- `VOLUTE.md` — How you communicate. Your channels and routing.
 
 **Editing any identity file triggers an automatic restart** — your server restarts so the updated file takes effect. Your session resumes automatically.
 
+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 journal entries if needed. On a **fresh session**, read `MEMORY.md` and recent journal entries to remember where you left off. On **compaction**, update today's journal to preserve context before the conversation is trimmed.
+
 ## Memory System
 
 Two-tier memory, both managed via file tools:
@@ -30,10 +31,3 @@ Two-tier memory, both managed via file tools:
 - Periodically consolidate journal entries into `MEMORY.md` to promote lasting insights.
 
 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/routes.json`.
-- Your conversation may be **resumed** from a previous session — orient yourself by reading recent journal entries if needed.
-- On a **fresh session**, read `MEMORY.md` and recent journal entries to remember where you left off.
-- On **compaction**, update today's journal to preserve context before the conversation is trimmed.

package/templates/claude/package.json.tmpl

@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.34",
+    "@anthropic-ai/tokenizer": "^0.0.4",
     "tsx": "^4.0.0"
   },
   "devDependencies": {