volute 0.33.0 → 0.35.0

package/templates/claude/src/agent.ts

@@ -1,8 +1,15 @@
 import { readFileSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
-import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import type { HookCallback, SyncHookJSONOutput } from "@anthropic-ai/claude-agent-sdk";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { toSDKContent } from "./lib/content.js";
+import {
+  countSdkInstructionTokens,
+  countSkillDescriptionTokens,
+  countSystemPromptTokens,
+  findClaudeSessionFile,
+  parseClaudeSessionJSONL,
+} from "./lib/context-breakdown.js";
 import { daemonEmit } from "./lib/daemon-client.js";
 import { runHooks } from "./lib/hook-loader.js";
 import { createAutoCommitHook } from "./lib/hooks/auto-commit.js";
@@ -23,6 +30,7 @@ import type {
   VoluteContentPart,
   VoluteEvent,
 } from "./lib/types.js";
+import type { ContextInfo } from "./lib/volute-server.js";
 
 type Session = {
   name: string;
@@ -31,7 +39,10 @@ type Session = {
   messageIds: (string | undefined)[];
   currentMessageId?: string;
   currentQuery?: ReturnType<typeof query>;
-  messageChannels: Map<string, string>;
+  messageChannels: Map<string, { channel: string; sender?: string }>;
+  replyInstructionsFired: boolean;
+  replyInstructionsMode: "once" | "always" | "never";
+  contextTokens: number;
 };
 
 export function createMind(options: {
@@ -45,7 +56,11 @@ export function createMind(options: {
   maxContextTokens?: number;
   subagents?: Record<string, SubagentConfig>;
   onIdentityReload?: () => Promise<void>;
-}): { resolve: HandlerResolver; waitForCommits: () => Promise<void> } {
+}): {
+  resolve: HandlerResolver;
+  waitForCommits: () => Promise<void>;
+  getContextInfo: () => ContextInfo;
+} {
   const autoCommit = createAutoCommitHook(options.cwd);
   const identityReload = createIdentityReloadHook(options.cwd);
   const sessionStore = createSessionStore(options.sessionsDir);
@@ -135,11 +150,16 @@ export function createMind(options: {
   function wrapHookWithEmit(hook: HookCallback, source: string, session: Session): HookCallback {
     return async (...args) => {
       const result = await hook(...args);
-      const additionalContext = (result as any)?.hookSpecificOutput?.additionalContext;
-      const decision = (result as any)?.decision;
+      const syncResult = result as SyncHookJSONOutput;
+      const hookOutput = syncResult?.hookSpecificOutput;
+      const additionalContext =
+        hookOutput && "additionalContext" in hookOutput
+          ? (hookOutput.additionalContext as string | undefined)
+          : undefined;
+      const decision = syncResult?.decision;
       if (additionalContext || decision) {
         const channel = session.currentMessageId
-          ? session.messageChannels.get(session.currentMessageId)
+          ? session.messageChannels.get(session.currentMessageId)?.channel
           : undefined;
         try {
           daemonEmit({
@@ -164,7 +184,7 @@ export function createMind(options: {
         const result = await runHooks(hooksDir, event, input as Record<string, unknown>);
         if (result.additionalContext || Object.keys(result.metadata).length > 0) {
           const channel = session.currentMessageId
-            ? session.messageChannels.get(session.currentMessageId)
+            ? session.messageChannels.get(session.currentMessageId)?.channel
             : undefined;
           try {
             daemonEmit({
@@ -202,7 +222,7 @@ export function createMind(options: {
     preCompactHook: HookCallback,
     resume?: string,
   ) {
-    const replyInstructions = createReplyInstructionsHook(session.messageChannels);
+    const replyInstructions = createReplyInstructionsHook(session.messageChannels, session);
 
     return query({
       prompt: session.channel.iterable,
@@ -279,27 +299,30 @@ export function createMind(options: {
             options.onIdentityReload?.();
           }
         },
-        onContextTokens: maxContextTokens
-          ? (tokens: number) => {
-              if (tokens >= maxContextTokens && !compactionTriggered.get(session.name)) {
-                compactionTriggered.set(session.name, true);
-                log(
-                  "mind",
-                  `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — triggering compaction`,
-                );
-                session.messageIds.push(undefined);
-                session.channel.push({
-                  type: "user",
-                  session_id: "",
-                  message: {
-                    role: "user",
-                    content: [{ type: "text", text: compactionMessage }],
-                  },
-                  parent_tool_use_id: null,
-                });
-              }
-            }
-          : undefined,
+        onContextTokens: (tokens: number) => {
+          session.contextTokens = tokens;
+          if (
+            maxContextTokens &&
+            tokens >= maxContextTokens &&
+            !compactionTriggered.get(session.name)
+          ) {
+            compactionTriggered.set(session.name, true);
+            log(
+              "mind",
+              `session "${session.name}": ${tokens} tokens >= ${maxContextTokens} — triggering compaction`,
+            );
+            session.messageIds.push(undefined);
+            session.channel.push({
+              type: "user",
+              session_id: "",
+              message: {
+                role: "user",
+                content: [{ type: "text", text: compactionMessage }],
+              },
+              parent_tool_use_id: null,
+            });
+          }
+        },
       };
 
       async function runCompact(sessionId: string) {
@@ -427,11 +450,21 @@ export function createMind(options: {
       listeners: new Set(),
       messageIds: [],
       messageChannels: new Map(),
+      replyInstructionsFired: false,
+      replyInstructionsMode: "once",
+      contextTokens: 0,
     };
     sessions.set(name, session);
 
     const isEphemeral = name.startsWith("new-");
-    const savedSessionId = isEphemeral ? undefined : sessionStore.load(name);
+    let savedSessionId = isEphemeral ? undefined : sessionStore.load(name);
+    // Validate that the SDK session file still exists — orphaned references
+    // cause the SDK to throw and can crash the process with EPIPE.
+    if (savedSessionId && !findClaudeSessionFile(options.cwd, savedSessionId)) {
+      log("mind", `session "${name}": stored session ${savedSessionId} not found, starting fresh`);
+      sessionStore.delete(name);
+      savedSessionId = undefined;
+    }
     if (savedSessionId) {
       log("mind", `session "${name}": resuming ${savedSessionId}`);
     } else {
@@ -455,9 +488,17 @@ export function createMind(options: {
         };
         session.listeners.add(filteredListener);
 
-        // Track channel for reply instructions
+        // Track channel/sender for reply instructions
         if (meta.channel) {
-          session.messageChannels.set(meta.messageId, meta.channel);
+          session.messageChannels.set(meta.messageId, {
+            channel: meta.channel,
+            sender: meta.sender,
+          });
+        }
+
+        // Update reply instructions mode from routing config
+        if (meta.replyInstructions) {
+          session.replyInstructionsMode = meta.replyInstructions;
         }
 
         // Interrupt if requested and session is mid-turn
@@ -497,5 +538,39 @@ export function createMind(options: {
     return handler;
   }
 
-  return { resolve, waitForCommits: autoCommit.waitForCommits };
+  const systemPromptTokens = countSystemPromptTokens(options.systemPrompt);
+  const claudeMdTokens = countSdkInstructionTokens(options.cwd);
+  const skillDescTokens = countSkillDescriptionTokens([resolvePath(options.cwd, ".claude/skills")]);
+
+  function getContextInfo(): ContextInfo {
+    return {
+      sessions: Array.from(sessions.values()).map((s) => {
+        try {
+          const sessionId = sessionStore.load(s.name);
+          const jsonlPath = sessionId ? findClaudeSessionFile(options.cwd, sessionId) : null;
+          const parsed = jsonlPath
+            ? parseClaudeSessionJSONL(
+                jsonlPath,
+                systemPromptTokens,
+                claudeMdTokens,
+                skillDescTokens,
+              )
+            : null;
+
+          return {
+            name: s.name,
+            contextTokens: parsed?.contextTokens ?? s.contextTokens,
+            contextWindow: maxContextTokens,
+            breakdown: parsed?.breakdown,
+          };
+        } catch (err) {
+          log("mind", `failed to get context breakdown for session "${s.name}":`, err);
+          return { name: s.name, contextTokens: s.contextTokens, contextWindow: maxContextTokens };
+        }
+      }),
+      systemPrompt: systemPromptTokens,
+    };
+  }
+
+  return { resolve, waitForCommits: autoCommit.waitForCommits, getContextInfo };
 }

package/templates/claude/src/lib/hooks/reply-instructions.ts

@@ -1,22 +1,42 @@
 import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
 import { loadPrompts } from "../startup.js";
 
-export function createReplyInstructionsHook(messageChannels: Map<string, string>) {
-  let fired = false;
+export function createReplyInstructionsHook(
+  messageChannels: Map<string, { channel: string; sender?: string }>,
+  sessionState: {
+    replyInstructionsFired: boolean;
+    replyInstructionsMode: "once" | "always" | "never";
+  },
+) {
   const prompts = loadPrompts();
 
   const hook: HookCallback = async () => {
-    if (fired) return {};
+    // "never" suppresses reply instructions entirely
+    if (sessionState.replyInstructionsMode === "never") return {};
 
-    const channel = messageChannels.values().next().value;
-    if (!channel) return {};
+    // "once" only fires on first message per session
+    if (sessionState.replyInstructionsMode === "once" && sessionState.replyInstructionsFired)
+      return {};
 
-    fired = true;
+    const entry = messageChannels.values().next().value;
+    if (!entry) return {};
+
+    sessionState.replyInstructionsFired = true;
+
+    // System messages don't need reply instructions
+    if (entry.sender === "volute") {
+      return {
+        hookSpecificOutput: {
+          hookEventName: "UserPromptSubmit" as const,
+          additionalContext: "This is a system message — no reply is needed.",
+        },
+      };
+    }
 
     return {
       hookSpecificOutput: {
         hookEventName: "UserPromptSubmit" as const,
-        additionalContext: prompts.reply_instructions.replace(/\$\{channel\}/g, channel),
+        additionalContext: prompts.reply_instructions.replace(/\$\{channel\}/g, entry.channel),
       },
     };
   };

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

@@ -8,7 +8,7 @@ export type StreamSession = {
   name: string;
   messageIds: (string | undefined)[];
   currentMessageId?: string;
-  messageChannels: Map<string, string>;
+  messageChannels: Map<string, { channel: string; sender?: string }>;
 };
 
 export type StreamCallbacks = {
@@ -26,7 +26,7 @@ function emit(
   event: { type: EventType; content?: string; metadata?: Record<string, unknown> },
 ) {
   const channel = session.currentMessageId
-    ? session.messageChannels.get(session.currentMessageId)
+    ? session.messageChannels.get(session.currentMessageId)?.channel
     : undefined;
   const filtered = filterEvent(preset, {
     ...event,

package/templates/claude/src/server.ts

@@ -52,6 +52,7 @@ const server = createVoluteServer({
   port,
   name: pkg.name,
   version: pkg.version,
+  getContextInfo: mind.getContextInfo,
 });
 
 server.listen(port, () => {

package/templates/codex/package.json.tmpl

@@ -9,6 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@anthropic-ai/tokenizer": "^0.0.4",
     "@openai/codex-sdk": "^0.115.0",
     "tsx": "^4.0.0"
   },

package/templates/codex/src/agent.ts

@@ -3,11 +3,18 @@ import { resolve as resolvePath } from "node:path";
 import { Codex } from "@openai/codex-sdk";
 import { flushFileChanges, trackFileChange } from "./lib/auto-commit.js";
 import { extractText } from "./lib/content.js";
+import {
+  countSdkInstructionTokens,
+  countSkillDescriptionTokens,
+  countSystemPromptTokens,
+  findCodexSessionFile,
+  parseCodexSessionJSONL,
+} from "./lib/context-breakdown.js";
 import { daemonEmit, daemonRestart, type EventType } from "./lib/daemon-client.js";
 import { runHooks } from "./lib/hook-loader.js";
 import { log, warn } from "./lib/logger.js";
 import { createSessionStore } from "./lib/session-store.js";
-import { loadPrompts, loadSystemPrompt } from "./lib/startup.js";
+import { getStartupContext, loadPrompts, loadSystemPrompt } from "./lib/startup.js";
 import { filterEvent, loadTransparencyPreset } from "./lib/transparency.js";
 import type {
   HandlerMeta,
@@ -17,6 +24,7 @@ import type {
   VoluteContentPart,
   VoluteEvent,
 } from "./lib/types.js";
+import type { ContextInfo } from "./lib/volute-server.js";
 
 /** Minimal interface for a Codex SDK thread — typed to the methods we actually use */
 type CodexThread = {
@@ -63,9 +71,9 @@ export function createMind(options: {
   cwd: string;
   mindDir: string;
   model?: string;
-  reasoningEffort?: string;
+  reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
   maxContextTokens?: number;
-}): { resolve: HandlerResolver } {
+}): { resolve: HandlerResolver; getContextInfo: () => ContextInfo } {
   const sessions = new Map<string, CodexSession>();
   const prompts = loadPrompts();
   const maxContextTokens = options.maxContextTokens;
@@ -76,6 +84,7 @@ export function createMind(options: {
 
   const sessionStore = createSessionStore(resolvePath(options.mindDir, ".mind/codex-sessions"));
   const hooksDir = resolvePath(options.cwd, ".local/hooks");
+  const startupContextPromise = getStartupContext().catch(() => null);
 
   // Write system prompt to file for Codex model_instructions_file
   const promptPath = resolvePath(options.mindDir, ".mind/system-prompt.md");
@@ -99,6 +108,9 @@ export function createMind(options: {
       model_instructions_file: promptPath,
       // Let the SDK handle compaction natively when a threshold is configured
       model_auto_compact_token_limit: maxContextTokens ?? 999999999,
+      // Enable reasoning summaries so they appear as events
+      model_reasoning_summary: "auto",
+      model_supports_reasoning_summaries: true,
       // The codex sandbox runs commands in /bin/zsh -lc which resets the environment.
       // Set ZDOTDIR so the login shell sources our .zshenv with VOLUTE env vars and PATH.
       shell_environment_policy: {
@@ -109,6 +121,9 @@ export function createMind(options: {
     },
   });
 
+  // Track which sessions have received startup context
+  const startupContextInjected = new Set<string>();
+
   // --- Session lifecycle ---
 
   function getOrCreateSession(name: string): CodexSession {
@@ -144,6 +159,7 @@ export function createMind(options: {
           session.thread = codex.resumeThread(savedThreadId, {
             workingDirectory: options.cwd,
             model: options.model,
+            modelReasoningEffort: options.reasoningEffort,
             skipGitRepoCheck: true,
             sandboxMode: "danger-full-access",
           });
@@ -158,6 +174,7 @@ export function createMind(options: {
       session.thread = codex.startThread({
         workingDirectory: options.cwd,
         model: options.model,
+        modelReasoningEffort: options.reasoningEffort,
         skipGitRepoCheck: true,
         sandboxMode: "danger-full-access",
       });
@@ -193,6 +210,20 @@ export function createMind(options: {
     // Refresh system prompt before each turn (picks up MEMORY.md changes)
     refreshSystemPrompt();
 
+    // Inject startup context on the first turn of each session
+    if (!startupContextInjected.has(session.name)) {
+      startupContextInjected.add(session.name);
+      const startupContext = await startupContextPromise;
+      if (startupContext) {
+        emit(session, {
+          type: "context",
+          content: startupContext,
+          metadata: { source: "startup-context" },
+        });
+        text = `${startupContext}\n\n${text}`;
+      }
+    }
+
     // Run pre-prompt hooks
     try {
       const hookResult = await runHooks(hooksDir, "pre-prompt", {
@@ -211,11 +242,14 @@ export function createMind(options: {
       warn("mind", "pre-prompt hook failed:", err);
     }
 
-    // Reply instructions on first message per channel
+    // Reply instructions on first message per channel (skip system messages)
     const channel = meta.channel;
     if (channel && !session.firstMessagePerChannel.has(channel)) {
       session.firstMessagePerChannel.add(channel);
-      const replyInstructions = prompts.reply_instructions.replace(/\$\{channel\}/g, channel);
+      const isSystem = meta.sender === "volute";
+      const replyInstructions = isSystem
+        ? "This is a system message — no reply is needed."
+        : prompts.reply_instructions.replace(/\$\{channel\}/g, channel);
       emit(session, {
         type: "context",
         content: replyInstructions,
@@ -281,7 +315,9 @@ export function createMind(options: {
               if (item.type === "agent_message" || item.type === "agentMessage") {
                 itemText.set(event.itemId ?? item.id, "");
               } else if (item.type === "reasoning") {
-                emit(session, { type: "thinking", content: item.content ?? "" });
+                // Reasoning text may arrive on started or completed
+                const text = item.text ?? item.content ?? "";
+                if (text) emit(session, { type: "thinking", content: text });
               } else if (item.type === "command_execution" || item.type === "commandExecution") {
                 const cmd = item.command ?? item.args?.join(" ") ?? "";
                 emit(session, {
@@ -356,7 +392,10 @@ export function createMind(options: {
               if (!item) break;
               const itemType = item.type;
 
-              if (itemType === "agent_message" || itemType === "agentMessage") {
+              if (itemType === "reasoning") {
+                const text = item.text ?? item.content ?? "";
+                if (text) emit(session, { type: "thinking", content: text });
+              } else if (itemType === "agent_message" || itemType === "agentMessage") {
                 // Emit any remaining delta
                 const id = event.itemId ?? item.id;
                 const prev = itemText.get(id) ?? "";
@@ -550,5 +589,38 @@ export function createMind(options: {
     return handler;
   }
 
-  return { resolve };
+  const systemPromptTokens = countSystemPromptTokens(options.systemPrompt);
+  const claudeMdTokens = countSdkInstructionTokens(options.cwd);
+  const skillDescTokens = countSkillDescriptionTokens([resolvePath(options.cwd, ".agents/skills")]);
+
+  function getContextInfo(): ContextInfo {
+    return {
+      sessions: Array.from(sessions.values()).map((s) => {
+        try {
+          const threadId = sessionStore.load(s.name);
+          const jsonlPath = threadId ? findCodexSessionFile(threadId) : null;
+          const parsed = jsonlPath
+            ? parseCodexSessionJSONL(jsonlPath, systemPromptTokens, claudeMdTokens, skillDescTokens)
+            : null;
+
+          return {
+            name: s.name,
+            contextTokens: parsed?.contextTokens ?? s.cumulativeInputTokens,
+            contextWindow: maxContextTokens,
+            breakdown: parsed?.breakdown,
+          };
+        } catch (err) {
+          log("mind", `failed to get context breakdown for session "${s.name}":`, err);
+          return {
+            name: s.name,
+            contextTokens: s.cumulativeInputTokens,
+            contextWindow: maxContextTokens,
+          };
+        }
+      }),
+      systemPrompt: systemPromptTokens,
+    };
+  }
+
+  return { resolve, getContextInfo };
 }

package/templates/codex/src/server.ts

@@ -4,7 +4,6 @@ import { createFileHandlerResolver } from "./lib/file-handler.js";
 import { log, setLevel } from "./lib/logger.js";
 import { createRouter } from "./lib/router.js";
 import {
-  handleStartupContext,
   loadConfig,
   loadPackageInfo,
   loadSystemPrompt,
@@ -45,15 +44,13 @@ const server = createVoluteServer({
   port,
   name: pkg.name,
   version: pkg.version,
+  getContextInfo: mind.getContextInfo,
 });
 
 server.listen(port, async () => {
   const addr = server.address();
   const actualPort = typeof addr === "object" && addr ? addr.port : port;
   log("server", `listening on :${actualPort}`);
-  await handleStartupContext((content) =>
-    router.route([{ type: "text", text: content }], { channel: "system" }),
-  );
 });
 
 setupShutdown();

package/templates/pi/package.json.tmpl

@@ -9,6 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@anthropic-ai/tokenizer": "^0.0.4",
     "@mariozechner/pi-coding-agent": "^0.58.1",
     "@sinclair/typebox": "^0.34.0",
     "tsx": "^4.0.0"