volute 0.45.1 → 0.46.0

package/templates/claude/src/agent.ts

@@ -8,6 +8,7 @@ import {
   countSkillDescriptionTokens,
   countSystemPromptTokens,
   findClaudeSessionFile,
+  getCachedContextInfo,
   processClaudeSession,
   readSdkInstructions,
   readSkillDescriptions,
@@ -21,6 +22,7 @@ import { createPreCompactHook } from "./lib/hooks/pre-compact.js";
 import { createReplyInstructionsHook } from "./lib/hooks/reply-instructions.js";
 import { log } from "./lib/logger.js";
 import { createMessageChannel } from "./lib/message-channel.js";
+import { isSessionReapable, reapSessionQuery } from "./lib/session-reaper.js";
 import { createSessionStore } from "./lib/session-store.js";
 import { loadPrompts, type SubagentConfig } from "./lib/startup.js";
 import { consumeStream } from "./lib/stream-consumer.js";
@@ -32,7 +34,7 @@ import type {
   VoluteContentPart,
   VoluteEvent,
 } from "./lib/types.js";
-import type { ContextInfo, ContextMessages } from "./lib/volute-server.js";
+import type { ContextInfo, ContextMessages, SessionContextInfo } from "./lib/volute-server.js";
 
 type Session = {
   name: string;
@@ -45,6 +47,8 @@ type Session = {
   replyInstructionsFired: boolean;
   replyInstructionsMode: "once" | "always" | "never";
   contextTokens: number;
+  /** Last inbound message or completed turn — drives idle reaping. */
+  lastActivityAt: number;
 };
 
 export function createMind(options: {
@@ -58,11 +62,13 @@ export function createMind(options: {
   maxContextTokens?: number;
   subagents?: Record<string, SubagentConfig>;
   onIdentityReload?: () => Promise<void>;
+  /** Idle minutes before a session's SDK subprocess is reaped. 0 disables. Default 30. */
+  sessionIdleMinutes?: number;
 }): {
   resolve: HandlerResolver;
   waitForCommits: () => Promise<void>;
-  getContextInfo: () => ContextInfo;
-  getContextMessages: () => ContextMessages;
+  getContextInfo: () => Promise<ContextInfo>;
+  getContextMessages: () => Promise<ContextMessages>;
 } {
   const autoCommit = createAutoCommitHook(options.cwd);
   const identityReload = createIdentityReloadHook(options.cwd);
@@ -320,6 +326,7 @@ export function createMind(options: {
           // This turn's message is fully processed — drop it from the channel's
           // in-flight set so a later compaction abort won't re-feed it.
           session.channel.ack();
+          session.lastActivityAt = Date.now();
           await autoCommit.flushFileChanges();
           const wasCompacting = compactionTriggered.get(session.name);
           compactionTriggered.set(session.name, false);
@@ -478,16 +485,20 @@ export function createMind(options: {
             log("mind", `session "${session.name}": stream consumer error:`, retryErr);
             await emitError(retryErr);
             emitDone();
-            sessions.delete(session.name);
           }
         } else {
           log("mind", `session "${session.name}": stream consumer error:`, err);
           await emitError(err);
           emitDone();
-          sessions.delete(session.name);
         }
+      } finally {
+        // The stream consumer has ended (subprocess exit, error, or fresh-start
+        // abandonment) — drop the session so the sessions map doesn't retain dead
+        // entries. Matters most for ephemeral $new sessions once the idle reaper
+        // (#458) kills their subprocess, but also for any named session that ends.
+        sessions.delete(session.name);
+        log("mind", `session "${session.name}": stream consumer ended`);
       }
-      log("mind", `session "${session.name}": stream consumer ended`);
     })();
   }
 
@@ -504,6 +515,7 @@ export function createMind(options: {
       replyInstructionsFired: false,
       replyInstructionsMode: "once",
       contextTokens: 0,
+      lastActivityAt: Date.now(),
     };
     sessions.set(name, session);
 
@@ -526,18 +538,79 @@ export function createMind(options: {
     return session;
   }
 
+  // --- Idle session reaping ---
+  // Each session holds a resident SDK subprocess (~250MB) for its whole life.
+  // After the idle timeout, shut the subprocess down while keeping the session
+  // resumable: the session id is persisted, so the next inbound message
+  // transparently re-creates the session via getOrCreateSession's resume path.
+  const idleTimeoutMs = (options.sessionIdleMinutes ?? 30) * 60_000;
+
+  async function reapSession(session: Session) {
+    log("mind", `session "${session.name}": idle — reaping SDK subprocess (resumable)`);
+    // Delete first so a racing inbound message spins up a fresh resumed session
+    // instead of reusing the one we're tearing down.
+    sessions.delete(session.name);
+    compactionTriggered.delete(session.name);
+    // End the input iterable so the stream consumer unwinds (its finally block
+    // also deletes from the map, now a no-op), then await the SDK's graceful
+    // shutdown via query.return() — unlike the fire-and-forget close(), this
+    // awaits the CLI subprocess's exit so the child is reaped instead of left
+    // as a <defunct> zombie.
+    session.channel.close();
+    await reapSessionQuery(session.currentQuery, (err) =>
+      log("mind", `session "${session.name}": error reaping SDK subprocess:`, err),
+    );
+    // Nothing should have raced in (isSessionReapable checked isEmpty), but if it
+    // did, re-dispatch into a fresh session so no input is dropped.
+    const pending = session.channel.recover();
+    if (pending.length > 0) {
+      const fresh = getOrCreateSession(session.name);
+      for (const msg of pending) fresh.channel.push(msg);
+    }
+  }
+
+  if (idleTimeoutMs > 0) {
+    log("mind", `idle session reaper: ${idleTimeoutMs / 60_000} min timeout`);
+    const checkMs = Math.min(60_000, idleTimeoutMs);
+    const reaper = setInterval(() => {
+      const now = Date.now();
+      const stale = [...sessions.values()].filter((s) =>
+        isSessionReapable(s, now, idleTimeoutMs, (name) => !!compactionTriggered.get(name)),
+      );
+      // Reaps run independently; each awaits its own subprocess exit internally.
+      for (const session of stale) {
+        reapSession(session).catch((err) =>
+          log("mind", `session "${session.name}": reap failed:`, err),
+        );
+      }
+    }, checkMs);
+    reaper.unref?.();
+  }
+
   // --- MessageHandler implementation ---
 
   function createSessionHandler(sessionName: string): MessageHandler {
     return {
-      handle(content: VoluteContentPart[], meta: HandlerMeta, listener: Listener): () => void {
+      handle(content: VoluteContentPart[], meta: HandlerMeta, listener?: Listener): () => void {
         const session = getOrCreateSession(sessionName);
 
-        // Filter listener to only receive events for this messageId
-        const filteredListener: Listener = (event) => {
-          if (event.messageId === meta.messageId) listener(event);
-        };
-        session.listeners.add(filteredListener);
+        // Only register a listener when a caller actually wants events. A per-message
+        // listener that's never removed would grow session.listeners without bound and
+        // make broadcastToSession O(messages-ever-received). The live dispatch path
+        // passes no listener, so this is usually a no-op.
+        let filteredListener: Listener | undefined;
+        if (listener) {
+          // Filter to only this messageId, and self-remove on the matching done so a
+          // caller that forgets to unsubscribe can't reintroduce the leak.
+          filteredListener = (event) => {
+            if (event.messageId !== meta.messageId) return;
+            listener(event);
+            if (event.type === "done" && filteredListener) {
+              session.listeners.delete(filteredListener);
+            }
+          };
+          session.listeners.add(filteredListener);
+        }
 
         // Track channel/sender for reply instructions
         if (meta.channel) {
@@ -559,6 +632,7 @@ export function createMind(options: {
         }
 
         // Push message into SDK
+        session.lastActivityAt = Date.now();
         session.messageIds.push(meta.messageId);
         session.channel.push({
           type: "user",
@@ -567,7 +641,9 @@ export function createMind(options: {
           parent_tool_use_id: null,
         });
 
-        return () => session.listeners.delete(filteredListener);
+        return () => {
+          if (filteredListener) session.listeners.delete(filteredListener);
+        };
       },
     };
   }
@@ -593,51 +669,76 @@ export function createMind(options: {
   const claudeMdTokens = countSdkInstructionTokens(options.cwd);
   const skillDescTokens = countSkillDescriptionTokens([resolvePath(options.cwd, ".claude/skills")]);
 
-  function processSession(sessionName: string) {
+  function jsonlPathFor(sessionName: string): string | null {
     const sessionId = sessionStore.load(sessionName);
-    const jsonlPath = sessionId ? findClaudeSessionFile(options.cwd, sessionId) : null;
-    return jsonlPath
-      ? processClaudeSession(jsonlPath, systemPromptTokens, claudeMdTokens, skillDescTokens)
-      : null;
+    return sessionId ? findClaudeSessionFile(options.cwd, sessionId) : null;
   }
 
-  function getContextInfo(): ContextInfo {
-    return {
-      sessions: Array.from(sessions.values()).map((s) => {
-        try {
-          const result = processSession(s.name);
-          return {
-            name: s.name,
-            contextTokens: result?.parsed?.contextTokens ?? s.contextTokens,
-            contextWindow: maxContextTokens,
-            breakdown: result?.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,
-    };
+  async function getContextInfo(): Promise<ContextInfo> {
+    const infos: SessionContextInfo[] = [];
+    for (const s of sessions.values()) {
+      try {
+        const jsonlPath = jsonlPathFor(s.name);
+        // Cache the computed breakdown by file identity: polls between turns are free.
+        const parsed = jsonlPath
+          ? await getCachedContextInfo(
+              jsonlPath,
+              async () =>
+                (
+                  await processClaudeSession(
+                    jsonlPath,
+                    systemPromptTokens,
+                    claudeMdTokens,
+                    skillDescTokens,
+                  )
+                ).parsed,
+            )
+          : null;
+        infos.push({
+          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);
+        infos.push({
+          name: s.name,
+          contextTokens: s.contextTokens,
+          contextWindow: maxContextTokens,
+        });
+      }
+    }
+    return { sessions: infos, systemPrompt: systemPromptTokens };
   }
 
-  function getContextMessages(): ContextMessages {
+  async function getContextMessages(): Promise<ContextMessages> {
     const skillsDir = resolvePath(options.cwd, ".claude/skills");
+    const sessionMessages: ContextMessages["sessions"] = [];
+    for (const s of sessions.values()) {
+      try {
+        const jsonlPath = jsonlPathFor(s.name);
+        const result = jsonlPath
+          ? await processClaudeSession(
+              jsonlPath,
+              systemPromptTokens,
+              claudeMdTokens,
+              skillDescTokens,
+            )
+          : null;
+        sessionMessages.push({ name: s.name, messages: result?.messages ?? [] });
+      } catch (err) {
+        log("mind", `failed to extract messages for session "${s.name}":`, err);
+        sessionMessages.push({ name: s.name, messages: [] });
+      }
+    }
     return {
       preamble: {
         systemPrompt: options.systemPrompt,
         sdkInstructions: readSdkInstructions(options.cwd),
         skillDescriptions: readSkillDescriptions([skillsDir]),
       },
-      sessions: Array.from(sessions.values()).map((s) => {
-        try {
-          const result = processSession(s.name);
-          return { name: s.name, messages: result?.messages ?? [] };
-        } catch (err) {
-          log("mind", `failed to extract messages for session "${s.name}":`, err);
-          return { name: s.name, messages: [] };
-        }
-      }),
+      sessions: sessionMessages,
     };
   }
 

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

@@ -11,6 +11,14 @@ export type MessageChannel = {
    * compaction abort so in-flight input is never lost.
    */
   recover: () => SDKUserMessage[];
+  /**
+   * Terminate the input iterable: resolve any pending `next()` with `done: true`
+   * and make subsequent `next()` calls return done. The SDK sees end-of-input and
+   * shuts the query down. Used by the idle reaper to release the SDK subprocess.
+   */
+  close: () => void;
+  /** True when nothing is queued or in flight (no pending work). */
+  isEmpty: () => boolean;
   iterable: AsyncIterable<SDKUserMessage>;
 };
 
@@ -23,6 +31,7 @@ export function createMessageChannel(): MessageChannel {
   // re-feed the unprocessed ones instead of dropping them.
   const inFlight: SDKUserMessage[] = [];
   let resolve: ((value: IteratorResult<SDKUserMessage>) => void) | null = null;
+  let closed = false;
 
   function deliver(msg: SDKUserMessage): IteratorResult<SDKUserMessage> {
     inFlight.push(msg);
@@ -52,10 +61,24 @@ export function createMessageChannel(): MessageChannel {
       }
       return [...inFlight.splice(0), ...queue.splice(0)];
     },
+    close() {
+      closed = true;
+      if (resolve) {
+        const r = resolve;
+        resolve = null;
+        r({ value: undefined as any, done: true });
+      }
+    },
+    isEmpty() {
+      return queue.length === 0 && inFlight.length === 0;
+    },
     iterable: {
       [Symbol.asyncIterator]() {
         return {
           next(): Promise<IteratorResult<SDKUserMessage>> {
+            if (closed) {
+              return Promise.resolve({ value: undefined as any, done: true });
+            }
             if (queue.length > 0) {
               return Promise.resolve(deliver(queue.shift()!));
             }

package/templates/claude/src/lib/session-reaper.ts

@@ -0,0 +1,68 @@
+/**
+ * Idle-session reaping decision logic.
+ *
+ * Each mind session keeps a resident Claude SDK subprocess alive for as long as
+ * the session lives. When a session has been idle past the configured timeout it
+ * can be reaped — its subprocess shut down — while staying resumable, since the
+ * session id is persisted and the next inbound message re-creates it via resume.
+ */
+
+export interface ReapableSession {
+  name: string;
+  /** Timestamp (ms) of the last inbound message or completed turn. */
+  lastActivityAt: number;
+  /** Set while a turn is in progress; undefined between turns. */
+  currentMessageId?: string;
+  channel: { isEmpty(): boolean };
+}
+
+/**
+ * A session is reapable only when it has been idle longer than the timeout and
+ * has no work in progress: no turn running, no queued/in-flight input, and not
+ * mid-compaction (which owns its own abort/resume lifecycle).
+ */
+export function isSessionReapable(
+  session: ReapableSession,
+  now: number,
+  idleTimeoutMs: number,
+  isCompacting: (name: string) => boolean,
+): boolean {
+  if (idleTimeoutMs <= 0) return false;
+  return (
+    session.currentMessageId === undefined &&
+    session.channel.isEmpty() &&
+    !isCompacting(session.name) &&
+    now - session.lastActivityAt > idleTimeoutMs
+  );
+}
+
+/** Minimal view of the SDK query needed to shut its subprocess down. */
+export interface ReapableQuery {
+  /**
+   * AsyncGenerator.return — the SDK overrides it to await its internal cleanup,
+   * which waits (bounded) for the CLI subprocess to exit.
+   */
+  return(value?: unknown): Promise<unknown>;
+}
+
+/**
+ * Tear down a reaped session's SDK subprocess and reap its exit status.
+ *
+ * `query.close()` is fire-and-forget: it kicks off cleanup but does not await the
+ * CLI subprocess's exit, so the child is left `<defunct>` (a zombie) until the
+ * mind process itself exits — PID-table growth on long-running minds with short
+ * idle timeouts. `query.return()` awaits the SDK's cleanup, which waits for the
+ * subprocess to exit, so the child's exit status is reaped. Errors are reported
+ * via `onError` (never thrown) so a teardown failure can't wedge the reaper.
+ */
+export async function reapSessionQuery(
+  query: ReapableQuery | undefined,
+  onError: (err: unknown) => void,
+): Promise<void> {
+  if (!query) return;
+  try {
+    await query.return();
+  } catch (err) {
+    onError(err);
+  }
+}

package/templates/claude/src/server.ts

@@ -33,6 +33,7 @@ const mind = createMind({
   sessionsDir,
   compactionMessage: config.compactionMessage,
   maxContextTokens: config.compaction?.maxContextTokens,
+  sessionIdleMinutes: config.sessionIdleMinutes,
   subagents: config.subagents,
   onIdentityReload: async () => {
     log("server", "identity file changed — restarting to reload");

package/templates/codex/src/agent.ts

@@ -8,6 +8,7 @@ import {
   countSkillDescriptionTokens,
   countSystemPromptTokens,
   findCodexSessionFile,
+  getCachedContextInfo,
   processCodexSession,
   readSdkInstructions,
   readSkillDescriptions,
@@ -26,7 +27,7 @@ import type {
   VoluteContentPart,
   VoluteEvent,
 } from "./lib/types.js";
-import type { ContextInfo, ContextMessages } from "./lib/volute-server.js";
+import type { ContextInfo, ContextMessages, SessionContextInfo } from "./lib/volute-server.js";
 
 /** Minimal interface for a Codex SDK thread — typed to the methods we actually use */
 type CodexThread = {
@@ -77,8 +78,8 @@ export function createMind(options: {
   maxContextTokens?: number;
 }): {
   resolve: HandlerResolver;
-  getContextInfo: () => ContextInfo;
-  getContextMessages: () => ContextMessages;
+  getContextInfo: () => Promise<ContextInfo>;
+  getContextMessages: () => Promise<ContextMessages>;
 } {
   const sessions = new Map<string, CodexSession>();
   const prompts = loadPrompts();
@@ -558,13 +559,23 @@ export function createMind(options: {
 
   function createSessionHandler(sessionName: string): MessageHandler {
     return {
-      handle(content: VoluteContentPart[], meta: HandlerMeta, listener: Listener): () => void {
+      handle(content: VoluteContentPart[], meta: HandlerMeta, listener?: Listener): () => void {
         const session = getOrCreateSession(sessionName);
 
-        const filteredListener: Listener = (event) => {
-          if (event.messageId === meta.messageId) listener(event);
-        };
-        session.listeners.add(filteredListener);
+        // Only register a listener when a caller wants events. A per-message listener
+        // that's never removed grows session.listeners without bound and makes broadcast
+        // O(messages-ever-received). The live dispatch path passes no listener.
+        let filteredListener: Listener | undefined;
+        if (listener) {
+          filteredListener = (event) => {
+            if (event.messageId !== meta.messageId) return;
+            listener(event);
+            if (event.type === "done" && filteredListener) {
+              session.listeners.delete(filteredListener);
+            }
+          };
+          session.listeners.add(filteredListener);
+        }
 
         // Track channel for reply instructions
         if (meta.channel) {
@@ -586,7 +597,9 @@ export function createMind(options: {
           broadcast(session, { type: "done" });
         });
 
-        return () => session.listeners.delete(filteredListener);
+        return () => {
+          if (filteredListener) session.listeners.delete(filteredListener);
+        };
       },
     };
   }
@@ -611,55 +624,76 @@ export function createMind(options: {
   const claudeMdTokens = countSdkInstructionTokens(options.cwd);
   const skillDescTokens = countSkillDescriptionTokens([resolvePath(options.cwd, ".agents/skills")]);
 
-  function processSession(sessionName: string) {
+  function jsonlPathFor(sessionName: string): string | null {
     const threadId = sessionStore.load(sessionName);
-    const jsonlPath = threadId ? findCodexSessionFile(threadId, options.mindDir) : null;
-    return jsonlPath
-      ? processCodexSession(jsonlPath, systemPromptTokens, claudeMdTokens, skillDescTokens)
-      : null;
+    return threadId ? findCodexSessionFile(threadId, options.mindDir) : null;
   }
 
-  function getContextInfo(): ContextInfo {
-    return {
-      sessions: Array.from(sessions.values()).map((s) => {
-        try {
-          const result = processSession(s.name);
-          return {
-            name: s.name,
-            contextTokens: result?.parsed?.contextTokens ?? s.cumulativeInputTokens,
-            contextWindow: maxContextTokens,
-            breakdown: result?.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,
-    };
+  async function getContextInfo(): Promise<ContextInfo> {
+    const infos: SessionContextInfo[] = [];
+    for (const s of sessions.values()) {
+      try {
+        const jsonlPath = jsonlPathFor(s.name);
+        // Cache the computed breakdown by file identity: polls between turns are free.
+        const parsed = jsonlPath
+          ? await getCachedContextInfo(
+              jsonlPath,
+              async () =>
+                (
+                  await processCodexSession(
+                    jsonlPath,
+                    systemPromptTokens,
+                    claudeMdTokens,
+                    skillDescTokens,
+                  )
+                ).parsed,
+            )
+          : null;
+        infos.push({
+          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);
+        infos.push({
+          name: s.name,
+          contextTokens: s.cumulativeInputTokens,
+          contextWindow: maxContextTokens,
+        });
+      }
+    }
+    return { sessions: infos, systemPrompt: systemPromptTokens };
   }
 
-  function getContextMessages(): ContextMessages {
+  async function getContextMessages(): Promise<ContextMessages> {
     const skillsDir = resolvePath(options.cwd, ".agents/skills");
+    const sessionMessages: ContextMessages["sessions"] = [];
+    for (const s of sessions.values()) {
+      try {
+        const jsonlPath = jsonlPathFor(s.name);
+        const result = jsonlPath
+          ? await processCodexSession(
+              jsonlPath,
+              systemPromptTokens,
+              claudeMdTokens,
+              skillDescTokens,
+            )
+          : null;
+        sessionMessages.push({ name: s.name, messages: result?.messages ?? [] });
+      } catch (err) {
+        log("mind", `failed to extract messages for session "${s.name}":`, err);
+        sessionMessages.push({ name: s.name, messages: [] });
+      }
+    }
     return {
       preamble: {
         systemPrompt: options.systemPrompt,
         sdkInstructions: readSdkInstructions(options.cwd),
         skillDescriptions: readSkillDescriptions([skillsDir]),
       },
-      sessions: Array.from(sessions.values()).map((s) => {
-        try {
-          const result = processSession(s.name);
-          return { name: s.name, messages: result?.messages ?? [] };
-        } catch (err) {
-          log("mind", `failed to extract messages for session "${s.name}":`, err);
-          return { name: s.name, messages: [] };
-        }
-      }),
+      sessions: sessionMessages,
     };
   }