volute 0.21.0 → 0.23.0

package/templates/claude/src/lib/hooks/pre-compact.ts

@@ -1,14 +1,28 @@
-import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import type { HookCallback, PreCompactHookInput } from "@anthropic-ai/claude-agent-sdk";
 import { log } from "../logger.js";
 
 export function createPreCompactHook(onCompact: () => void) {
   let compactBlocked = false;
 
-  const hook: HookCallback = async () => {
+  const hook: HookCallback = async (input) => {
+    const { trigger, custom_instructions } = input as PreCompactHookInput;
+
+    // Our custom compaction (via /compact with instructions) — allow through without the two-pass block
+    if (trigger === "manual" && custom_instructions) {
+      log("mind", "allowing manual compaction with custom instructions");
+      return {};
+    }
+
+    // Auto-compaction: two-pass block (first pass warns mind, second pass allows)
     if (!compactBlocked) {
-      compactBlocked = true;
       log("mind", "blocking compaction — asking mind to update daily log first");
-      onCompact();
+      try {
+        onCompact();
+        compactBlocked = true;
+      } catch (err) {
+        log("mind", "onCompact callback failed, allowing compaction:", err);
+        return {};
+      }
       return { decision: "block" };
     }
     compactBlocked = false;

package/templates/claude/src/lib/message-channel.ts

@@ -2,6 +2,7 @@ import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 
 export type MessageChannel = {
   push: (msg: SDKUserMessage) => void;
+  drain: () => SDKUserMessage[];
   iterable: AsyncIterable<SDKUserMessage>;
 };
 
@@ -19,6 +20,11 @@ export function createMessageChannel(): MessageChannel {
         queue.push(msg);
       }
     },
+    drain() {
+      // Clear any pending iterator wait so it doesn't consume a message after drain
+      resolve = null;
+      return queue.splice(0);
+    },
     iterable: {
       [Symbol.asyncIterator]() {
         return {

package/templates/claude/src/lib/stream-consumer.ts

@@ -1,6 +1,6 @@
 import type { query } from "@anthropic-ai/claude-agent-sdk";
 import { daemonEmit, type EventType } from "./daemon-client.js";
-import { log, logText, logThinking, logToolUse } from "./logger.js";
+import { log, logText, logThinking, logToolUse, warn } from "./logger.js";
 import { filterEvent, loadTransparencyPreset } from "./transparency.js";
 import type { VoluteEvent } from "./types.js";
 
@@ -15,6 +15,7 @@ export type StreamCallbacks = {
   onSessionId?: (sessionId: string) => void;
   broadcast: (event: VoluteEvent) => void;
   onTurnEnd?: () => void;
+  onContextTokens?: (tokens: number) => void;
 };
 
 // Loaded once at startup — mind restarts on config changes
@@ -50,6 +51,12 @@ export async function consumeStream(
       callbacks.onSessionId?.(msg.session_id as string);
     }
     if (msg.type === "assistant") {
+      const usage = msg.message.usage as unknown as Record<string, unknown> | undefined;
+      const inputTokens = (usage?.input_tokens as number) ?? 0;
+      const cacheCreation = (usage?.cache_creation_input_tokens as number) ?? 0;
+      const cacheRead = (usage?.cache_read_input_tokens as number) ?? 0;
+      const contextTokens = inputTokens + cacheCreation + cacheRead;
+      if (contextTokens) callbacks.onContextTokens?.(contextTokens);
       for (const b of msg.message.content) {
         if (b.type === "thinking" && "thinking" in b && b.thinking) {
           const text = b.thinking as string;
@@ -75,6 +82,15 @@ export async function consumeStream(
         session.messageChannels.delete(session.currentMessageId);
       }
       log("mind", `session "${session.name}": turn done`);
+      // Log any error messages from the result
+      const resultMsg = msg as Record<string, unknown>;
+      if (Array.isArray(resultMsg.messages)) {
+        for (const m of resultMsg.messages) {
+          if (m && typeof m === "object" && "errorMessage" in m && m.errorMessage) {
+            warn("mind", `session "${session.name}": agent error: ${m.errorMessage}`);
+          }
+        }
+      }
       const result = msg as { usage?: { input_tokens?: number; output_tokens?: number } };
       if (result.usage) {
         const usage = {

package/templates/claude/src/server.ts

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { createMind } from "./agent.js";
 import { daemonRestart } from "./lib/daemon-client.js";
 import { createFileHandlerResolver } from "./lib/file-handler.js";
-import { log } from "./lib/logger.js";
+import { log, setLevel } from "./lib/logger.js";
 import { createRouter } from "./lib/router.js";
 import {
   loadConfig,
@@ -16,6 +16,7 @@ import { createVoluteServer } from "./lib/volute-server.js";
 
 const { port } = parseArgs();
 const config = loadConfig();
+if (config.logLevel) setLevel(config.logLevel);
 if (config.model) log("server", `using model: ${config.model}`);
 if (config.maxThinkingTokens) log("server", `max thinking tokens: ${config.maxThinkingTokens}`);
 
@@ -40,6 +41,7 @@ const mind = createMind({
   maxThinkingTokens: config.maxThinkingTokens,
   sessionsDir,
   compactionMessage: config.compactionMessage,
+  maxContextTokens: config.compaction?.maxContextTokens,
   onIdentityReload: async () => {
     log("server", "identity file changed — restarting to reload");
     await mind.waitForCommits();

package/templates/pi/home/.config/config.json.tmpl

@@ -1,3 +1,6 @@
 {
-  "model": "openrouter:moonshotai/kimi-k2.5"
+  "model": "openrouter:moonshotai/kimi-k2.5",
+  "compaction": {
+    "maxContextTokens": 150000
+  }
 }

package/templates/pi/src/agent.ts

@@ -43,12 +43,19 @@ export function createMind(options: {
   model?: string;
   thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
   compactionMessage?: string;
+  maxContextTokens?: number;
 }): { resolve: HandlerResolver } {
   const sessions = new Map<string, PiSession>();
   const prompts = loadPrompts();
   const today = new Date().toLocaleDateString("en-CA");
   const compactionMessage =
     options.compactionMessage ?? prompts.compaction_warning.replace("${date}", today);
+  const compactionInstructions = prompts.compaction_instructions;
+  const maxContextTokens = options.maxContextTokens;
+
+  if (maxContextTokens) {
+    log("mind", `compaction threshold: ${maxContextTokens} tokens`);
+  }
 
   // Shared setup (created once)
   const modelStr = options.model || process.env.PI_MODEL || "anthropic:claude-sonnet-4-20250514";
@@ -88,9 +95,35 @@ export function createMind(options: {
 
     log("mind", `session "${session.name}": ${isEphemeral ? "ephemeral" : "persistent"}`);
 
+    // Compaction state machine:
+    // 1. onContextTokens sets compactionTriggered=true and sends warning
+    // 2. onTurnEnd (after warning turn): compactionTriggered -> compactOnNextTurnEnd
+    // 3. onTurnEnd (after mind's save turn): compactOnNextTurnEnd -> call compact()
     let compactBlocked = false;
+    let manualCompactPending = false;
+    let compactionTriggered = false;
+    let compactOnNextTurnEnd = false;
+    let compactionInProgress = false;
+
+    function resetCompactionState() {
+      compactionTriggered = false;
+      compactOnNextTurnEnd = false;
+      compactionInProgress = false;
+    }
+
     const preCompactExtension: ExtensionFactory = (pi) => {
       pi.on("session_before_compact", () => {
+        // Our programmatic compact() call (triggered by token threshold) — allow through
+        if (manualCompactPending) {
+          manualCompactPending = false;
+          log(
+            "mind",
+            `session "${session.name}": allowing manual compaction with custom instructions`,
+          );
+          return;
+        }
+
+        // Auto-compaction: two-pass block (first pass warns mind, second pass allows)
         if (!compactBlocked) {
           compactBlocked = true;
           log(
@@ -146,6 +179,60 @@ export function createMind(options: {
       createEventHandler(session, {
         cwd: options.cwd,
         broadcast: (event) => broadcast(session, event),
+        onContextTokens: maxContextTokens
+          ? (tokens: number) => {
+              if (tokens >= maxContextTokens && !compactionTriggered && !compactionInProgress) {
+                if (!session.agentSession) {
+                  log(
+                    "mind",
+                    `session "${session.name}": compaction threshold hit but session not ready`,
+                  );
+                  return;
+                }
+                compactionTriggered = true;
+                log(
+                  "mind",
+                  `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — triggering compaction`,
+                );
+                // Send compaction warning; compaction will follow after the mind finishes its response turn
+                session.messageIds.push(undefined);
+                session.agentSession.prompt(compactionMessage, {
+                  streamingBehavior: "followUp",
+                });
+              }
+            }
+          : undefined,
+        onTurnEnd: maxContextTokens
+          ? () => {
+              try {
+                // Compact on the turn AFTER the warning was sent (so the mind gets a turn to save state)
+                if (compactOnNextTurnEnd) {
+                  compactOnNextTurnEnd = false;
+                  manualCompactPending = true;
+                  compactionInProgress = true;
+                  log("mind", `session "${session.name}": compacting with custom instructions`);
+                  Promise.resolve(session.agentSession?.compact(compactionInstructions))
+                    .catch((err) =>
+                      log("mind", `session "${session.name}": compact() failed:`, err),
+                    )
+                    .finally(() => {
+                      compactionInProgress = false;
+                    });
+                }
+                if (compactionTriggered) {
+                  compactionTriggered = false;
+                  compactOnNextTurnEnd = true;
+                }
+              } catch (err) {
+                log(
+                  "mind",
+                  `session "${session.name}": onTurnEnd error, resetting compaction state:`,
+                  err,
+                );
+                resetCompactionState();
+              }
+            }
+          : undefined,
       }),
     );
 

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

@@ -1,14 +1,29 @@
 import type { ImageContent } from "@mariozechner/pi-ai";
-import type { VoluteContentPart } from "./types.js";
+import { warn } from "./logger.js";
 
-export function extractText(content: VoluteContentPart[]): string {
+export function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) {
+    warn(
+      "mind",
+      `extractText received unexpected ${typeof content} instead of VoluteContentPart[]`,
+    );
+    return JSON.stringify(content);
+  }
   return content
     .filter((p): p is { type: "text"; text: string } => p.type === "text")
     .map((p) => p.text)
     .join("\n");
 }
 
-export function extractImages(content: VoluteContentPart[]): ImageContent[] {
+export function extractImages(content: unknown): ImageContent[] {
+  if (!Array.isArray(content)) {
+    warn(
+      "mind",
+      `extractImages received non-array content (${typeof content}) — images cannot be extracted`,
+    );
+    return [];
+  }
   return content
     .filter((p): p is { type: "image"; media_type: string; data: string } => p.type === "image")
     .map((p) => ({ type: "image" as const, mimeType: p.media_type, data: p.data }));

package/templates/pi/src/lib/event-handler.ts

@@ -1,6 +1,6 @@
 import { commitFileChange } from "./auto-commit.js";
 import { daemonEmit, type EventType } from "./daemon-client.js";
-import { log, logText, logThinking, logToolResult, logToolUse } from "./logger.js";
+import { log, logText, logThinking, logToolResult, logToolUse, warn } from "./logger.js";
 import { filterEvent, loadTransparencyPreset } from "./transparency.js";
 import type { VoluteEvent } from "./types.js";
 
@@ -14,6 +14,8 @@ export type EventSession = {
 export type EventHandlerOptions = {
   cwd: string;
   broadcast: (event: VoluteEvent) => void;
+  onContextTokens?: (tokens: number) => void;
+  onTurnEnd?: () => void;
 };
 
 // Loaded once at startup — mind restarts on config changes
@@ -133,14 +135,28 @@ export function createEventHandler(session: EventSession, options: EventHandlerO
           session.messageChannels.delete(session.currentMessageId);
         }
         log("mind", `session "${session.name}": turn done`);
-        // Sum usage from assistant messages
+        // Log any error messages from the agent
+        if (event.messages) {
+          for (const msg of event.messages as any[]) {
+            if (msg.errorMessage) {
+              warn("mind", `session "${session.name}": agent error: ${msg.errorMessage}`);
+            }
+          }
+        }
+        // Sum usage from assistant messages. The last assistant message's input tokens
+        // approximate current context size (it includes the full conversation up to that point).
         if (event.messages) {
           let inputTokens = 0;
           let outputTokens = 0;
+          let lastInputTokens = 0;
           for (const msg of event.messages as any[]) {
             if (msg.role === "assistant" && msg.usage) {
               inputTokens += msg.usage.input ?? 0;
               outputTokens += msg.usage.output ?? 0;
+              const cacheWrite = msg.usage.cacheWrite ?? msg.usage.cache_creation ?? 0;
+              const cacheRead = msg.usage.cacheRead ?? msg.usage.cache_read ?? 0;
+              const contextTokens = (msg.usage.input ?? 0) + cacheWrite + cacheRead;
+              if (contextTokens) lastInputTokens = contextTokens;
             }
           }
           if (inputTokens > 0 || outputTokens > 0) {
@@ -148,10 +164,14 @@ export function createEventHandler(session: EventSession, options: EventHandlerO
             options.broadcast({ type: "usage", ...usage });
             emit(session, { type: "usage", metadata: usage });
           }
+          if (lastInputTokens > 0) {
+            options.onContextTokens?.(lastInputTokens);
+          }
         }
         options.broadcast({ type: "done" });
         emit(session, { type: "done" });
         session.currentMessageId = undefined;
+        options.onTurnEnd?.();
       }
     } catch (err) {
       log("mind", `session "${session.name}": event handler error (${event?.type}):`, err);

package/templates/pi/src/server.ts

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import { createMind } from "./agent.js";
 import { createFileHandlerResolver } from "./lib/file-handler.js";
-import { log } from "./lib/logger.js";
+import { log, setLevel } from "./lib/logger.js";
 import { createRouter } from "./lib/router.js";
 import {
   handleStartupContext,
@@ -15,6 +15,7 @@ import { createVoluteServer } from "./lib/volute-server.js";
 
 const { port } = parseArgs();
 const config = loadConfig();
+if (config.logLevel) setLevel(config.logLevel);
 if (config.model) log("server", `using model: ${config.model}`);
 if (config.thinkingLevel) log("server", `thinking level: ${config.thinkingLevel}`);
 
@@ -29,6 +30,7 @@ const mind = createMind({
   model: config.model,
   thinkingLevel: config.thinkingLevel,
   compactionMessage: config.compactionMessage,
+  maxContextTokens: config.compaction?.maxContextTokens,
 });
 
 const router = createRouter({