volute 0.4.0 → 0.6.0

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

@@ -1,31 +1,52 @@
 import { readFileSync } from "node:fs";
 import { log } from "./logger.js";
 
+export type BatchConfig = {
+  debounce?: number; // seconds of quiet before flush
+  maxWait?: number; // max seconds before forced flush
+  triggers?: string[]; // patterns that cause immediate flush
+};
+
 export type RoutingRule = {
   session?: string;
   destination?: "agent" | "file";
   path?: string; // file path for file destination
   interrupt?: boolean; // interrupt in-progress agent turn (default: true for agent)
-  batch?: number; // minutes — buffer messages, flush on timer
+  batch?: number | BatchConfig; // number = minutes (legacy), object = fine-grained control
   channel?: string;
   sender?: string;
+  isDM?: boolean; // match on isDM metadata
+  participants?: number; // match on participant count (e.g. 2 = DM)
 };
 
 export type RoutingConfig = {
   rules?: RoutingRule[];
   default?: string;
+  gateUnmatched?: boolean;
 };
 
 export type ResolvedRoute =
-  | { destination: "agent"; session: string; interrupt: boolean; batch?: number }
-  | { destination: "file"; path: string };
+  | {
+      destination: "agent";
+      session: string;
+      interrupt: boolean;
+      batch?: BatchConfig;
+      matched: boolean;
+    }
+  | { destination: "file"; path: string; matched: boolean };
+
+/** Normalize batch config: number (minutes) → { maxWait } in seconds. */
+export function normalizeBatch(batch: number | BatchConfig): BatchConfig {
+  if (typeof batch === "number") return { maxWait: batch * 60 };
+  return batch;
+}
 
 export function loadRoutingConfig(configPath: string): RoutingConfig {
   try {
     return JSON.parse(readFileSync(configPath, "utf-8"));
   } catch (err: any) {
     if (err?.code !== "ENOENT") {
-      log("sessions", `failed to load ${configPath}:`, err);
+      log("routing", `failed to load ${configPath}:`, err);
     }
     return {};
   }
@@ -41,21 +62,39 @@ function globMatch(pattern: string, value: string): boolean {
   return new RegExp(`^${regex}$`).test(value);
 }
 
-const MATCH_KEYS = new Set(["channel", "sender"]);
+const GLOB_MATCH_KEYS = new Set(["channel", "sender"]);
 const NON_MATCH_KEYS = new Set(["session", "batch", "destination", "path", "interrupt"]);
 
-function ruleMatches(rule: RoutingRule, meta: { channel?: string; sender?: string }): boolean {
+type MatchMeta = { channel?: string; sender?: string; isDM?: boolean; participantCount?: number };
+
+function ruleMatches(rule: RoutingRule, meta: MatchMeta): boolean {
   for (const [key, pattern] of Object.entries(rule)) {
     if (NON_MATCH_KEYS.has(key)) continue;
+
+    // Boolean match: isDM
+    if (key === "isDM") {
+      if (typeof pattern !== "boolean") return false;
+      if ((meta.isDM ?? false) !== pattern) return false;
+      continue;
+    }
+
+    // Numeric match: participants
+    if (key === "participants") {
+      if (typeof pattern !== "number") return false;
+      if ((meta.participantCount ?? 0) !== pattern) return false;
+      continue;
+    }
+
+    // Glob string match: channel, sender
     if (typeof pattern !== "string") return false;
-    if (!MATCH_KEYS.has(key)) return false;
-    const value = meta[key as keyof typeof meta] ?? "";
+    if (!GLOB_MATCH_KEYS.has(key)) return false;
+    const value = meta[key as "channel" | "sender"] ?? "";
     if (!globMatch(pattern, value)) return false;
   }
   return true;
 }
 
-function expandTemplate(template: string, meta: { channel?: string; sender?: string }): string {
+function expandTemplate(template: string, meta: MatchMeta): string {
   return template
     .replace(/\$\{sender\}/g, meta.sender ?? "unknown")
     .replace(/\$\{channel\}/g, meta.channel ?? "unknown");
@@ -64,35 +103,33 @@ function expandTemplate(template: string, meta: { channel?: string; sender?: str
 /**
  * Resolve the full route for a message: destination type, session/path, interrupt, batch.
  */
-export function resolveRoute(
-  config: RoutingConfig,
-  meta: { channel?: string; sender?: string },
-): ResolvedRoute {
+export function resolveRoute(config: RoutingConfig, meta: MatchMeta): ResolvedRoute {
   const fallback = config.default ?? "main";
 
   if (!config.rules) {
-    return { destination: "agent", session: fallback, interrupt: true };
+    return { destination: "agent", session: fallback, interrupt: true, matched: false };
   }
 
   for (const rule of config.rules) {
     if (ruleMatches(rule, meta)) {
       if (rule.destination === "file") {
         if (!rule.path) {
-          log("sessions", `file destination rule missing path — falling through`);
+          log("routing", `file destination rule missing path — falling through`);
           continue;
         }
-        return { destination: "file", path: rule.path };
+        return { destination: "file", path: rule.path, matched: true };
       }
       return {
         destination: "agent",
         session: sanitizeSessionName(expandTemplate(rule.session ?? fallback, meta)),
         interrupt: rule.interrupt ?? true,
-        batch: rule.batch,
+        batch: rule.batch != null ? normalizeBatch(rule.batch) : undefined,
+        matched: true,
       };
     }
   }
 
-  return { destination: "agent", session: fallback, interrupt: true };
+  return { destination: "agent", session: fallback, interrupt: true, matched: false };
 }
 
 function sanitizeSessionName(name: string): string {

package/templates/_base/src/lib/session-monitor.ts

@@ -0,0 +1,400 @@
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+
+// --- Types ---
+
+type CursorState = Record<string, Record<string, { offset: number }>>;
+
+type ParsedEntry = {
+  role: "user" | "assistant";
+  timestamp?: string;
+  text?: string;
+  toolUses?: { name: string; primaryArg?: string }[];
+};
+
+type SessionSummary = {
+  firstUserText: string;
+  toolCounts: { edits: number; reads: number; commands: number; other: number };
+  messageCount: number;
+  timeSpan: { first?: string; last?: string };
+  lastAssistantText?: string;
+};
+
+type Format = "agent-sdk" | "pi";
+
+// --- Public API ---
+
+export function getSessionUpdates(options: {
+  currentSession: string;
+  sessionsDir: string;
+  cursorFile: string;
+  jsonlResolver: (sessionName: string) => string | null;
+  format: Format;
+}): string | null {
+  const sessionNames = listSessionNames(options.sessionsDir, options.format);
+  const others = sessionNames.filter((n) => n !== options.currentSession && !n.startsWith("new-"));
+  if (others.length === 0) return null;
+
+  const cursors = loadCursors(options.cursorFile);
+  const currentCursors = cursors[options.currentSession] ?? {};
+  const summaries: string[] = [];
+
+  for (const name of others) {
+    try {
+      const jsonlPath = options.jsonlResolver(name);
+      if (!jsonlPath || !existsSync(jsonlPath)) continue;
+
+      const stat = statSync(jsonlPath);
+      const prevOffset = currentCursors[name]?.offset ?? 0;
+      const fileSize = stat.size;
+
+      // Reset if offset past EOF (file was truncated/recreated)
+      const offset = prevOffset > fileSize ? 0 : prevOffset;
+      if (offset >= fileSize) {
+        currentCursors[name] = { offset: fileSize };
+        continue;
+      }
+
+      const newBytes = readBytesFrom(jsonlPath, offset, fileSize - offset);
+      const lines = newBytes.split("\n").filter((l) => l.trim());
+      const entries = parseJsonlEntries(lines, options.format);
+      const summary = summarizeEntries(entries);
+
+      currentCursors[name] = { offset: fileSize };
+
+      if (!summary) continue;
+
+      const ago = summary.timeSpan.last ? formatTimeAgo(summary.timeSpan.last) : "recently";
+      const parts = [`- ${name} (${ago}, ${summary.messageCount} messages)`];
+
+      if (summary.firstUserText) {
+        parts[0] += `: "${truncate(summary.firstUserText, 100)}"`;
+      }
+
+      const actions: string[] = [];
+      if (summary.toolCounts.edits > 0) actions.push(`edited ${summary.toolCounts.edits} files`);
+      if (summary.toolCounts.commands > 0)
+        actions.push(`ran ${summary.toolCounts.commands} commands`);
+      if (summary.toolCounts.reads > 0) actions.push(`read ${summary.toolCounts.reads} files`);
+      if (summary.toolCounts.other > 0) actions.push(`${summary.toolCounts.other} other tool uses`);
+      if (actions.length > 0) {
+        parts[0] += ` -> ${actions.join(", ")}`;
+      }
+
+      summaries.push(parts[0]);
+    } catch {}
+  }
+
+  cursors[options.currentSession] = currentCursors;
+  try {
+    saveCursors(options.cursorFile, cursors);
+  } catch {
+    // Non-fatal: worst case is duplicate summaries on next check
+  }
+
+  if (summaries.length === 0) return null;
+
+  // Cap total output at ~500 chars
+  let output = "[Session Activity]\n" + summaries.join("\n");
+  if (output.length > 500) {
+    output = output.slice(0, 497) + "...";
+  }
+  return output;
+}
+
+export function readSessionLog(options: {
+  jsonlPath: string;
+  format: Format;
+  lines?: number;
+}): string {
+  const maxLines = options.lines ?? 50;
+  if (!existsSync(options.jsonlPath)) return "No session log found.";
+
+  const content = readFileSync(options.jsonlPath, "utf-8");
+  const allLines = content.split("\n").filter((l) => l.trim());
+  const lines = allLines.slice(-maxLines);
+  const entries = parseJsonlEntries(lines, options.format);
+
+  const output: string[] = [];
+  for (const entry of entries) {
+    const ts = entry.timestamp ? `[${formatTimestamp(entry.timestamp)}]` : "";
+    if (entry.role === "user" && entry.text) {
+      output.push(`${ts} User: ${entry.text}`);
+    } else if (entry.role === "assistant") {
+      if (entry.text) {
+        output.push(`${ts} Assistant: ${entry.text}`);
+      }
+      if (entry.toolUses) {
+        for (const tool of entry.toolUses) {
+          const arg = tool.primaryArg ? ` ${tool.primaryArg}` : "";
+          output.push(`${ts} [${tool.name}${arg}]`);
+        }
+      }
+    }
+  }
+
+  return output.length > 0 ? output.join("\n") : "No activity found.";
+}
+
+// --- JSONL Path Resolvers ---
+
+export function resolveAgentSdkJsonl(
+  sessionsDir: string,
+  sessionName: string,
+  cwd: string,
+): string | null {
+  const sessionFile = resolve(sessionsDir, `${sessionName}.json`);
+  if (!existsSync(sessionFile)) return null;
+
+  try {
+    const data = JSON.parse(readFileSync(sessionFile, "utf-8"));
+    const sessionId = data.sessionId;
+    if (!sessionId) return null;
+
+    const encoded = encodeCwd(cwd);
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    return resolve(home, ".claude", "projects", encoded, `${sessionId}.jsonl`);
+  } catch {
+    return null;
+  }
+}
+
+export function encodeCwd(cwd: string): string {
+  return cwd.replace(/\//g, "-").replace(/\./g, "-");
+}
+
+export function resolvePiJsonl(sessionsDir: string, sessionName: string): string | null {
+  const sessionDir = resolve(sessionsDir, sessionName);
+  if (!existsSync(sessionDir)) return null;
+
+  try {
+    const files = readdirSync(sessionDir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .map((f) => ({
+        name: f,
+        mtime: statSync(resolve(sessionDir, f)).mtimeMs,
+      }))
+      .sort((a, b) => b.mtime - a.mtime);
+
+    if (files.length === 0) return null;
+    return resolve(sessionDir, files[0].name);
+  } catch {
+    return null;
+  }
+}
+
+// --- Parsing ---
+
+export function parseJsonlEntries(lines: string[], format: Format): ParsedEntry[] {
+  const entries: ParsedEntry[] = [];
+
+  for (const line of lines) {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (format === "agent-sdk") {
+      if (parsed.type === "user" && parsed.message?.role === "user") {
+        const text = extractTextFromContent(parsed.message.content);
+        if (text) entries.push({ role: "user", timestamp: parsed.timestamp, text });
+      } else if (parsed.type === "assistant" && parsed.message?.role === "assistant") {
+        const text = extractTextFromContent(parsed.message.content);
+        const toolUses = extractToolUses(parsed.message.content, format);
+        if (text || toolUses.length > 0) {
+          entries.push({
+            role: "assistant",
+            timestamp: parsed.timestamp,
+            text: text || undefined,
+            toolUses,
+          });
+        }
+      }
+    } else {
+      // pi format
+      if (parsed.type === "message" && parsed.message?.role === "user") {
+        const text = extractTextFromContent(parsed.message.content);
+        if (text) entries.push({ role: "user", timestamp: parsed.timestamp, text });
+      } else if (parsed.type === "message" && parsed.message?.role === "assistant") {
+        const text = extractTextFromContent(parsed.message.content);
+        const toolUses = extractToolUses(parsed.message.content, format);
+        if (text || toolUses.length > 0) {
+          entries.push({
+            role: "assistant",
+            timestamp: parsed.timestamp,
+            text: text || undefined,
+            toolUses,
+          });
+        }
+      }
+    }
+  }
+
+  return entries;
+}
+
+export function summarizeEntries(entries: ParsedEntry[]): SessionSummary | null {
+  if (entries.length === 0) return null;
+
+  let firstUserText = "";
+  let lastAssistantText: string | undefined;
+  const toolCounts = { edits: 0, reads: 0, commands: 0, other: 0 };
+  let messageCount = 0;
+  const timestamps: string[] = [];
+
+  for (const entry of entries) {
+    messageCount++;
+    if (entry.timestamp) timestamps.push(entry.timestamp);
+
+    if (entry.role === "user" && entry.text && !firstUserText) {
+      firstUserText = entry.text;
+    }
+
+    if (entry.role === "assistant") {
+      if (entry.text) lastAssistantText = entry.text;
+      if (entry.toolUses) {
+        for (const tool of entry.toolUses) {
+          const cat = categorizeTool(tool.name);
+          toolCounts[cat]++;
+        }
+      }
+    }
+  }
+
+  return {
+    firstUserText,
+    toolCounts,
+    messageCount,
+    timeSpan: {
+      first: timestamps[0],
+      last: timestamps[timestamps.length - 1],
+    },
+    lastAssistantText,
+  };
+}
+
+// --- Helpers ---
+
+function extractTextFromContent(content: any[]): string | null {
+  if (!Array.isArray(content)) return null;
+  const texts: string[] = [];
+  for (const part of content) {
+    if (part.type === "text" && part.text) {
+      texts.push(part.text);
+    }
+  }
+  return texts.length > 0 ? texts.join("\n") : null;
+}
+
+function extractToolUses(content: any[], format: Format): { name: string; primaryArg?: string }[] {
+  if (!Array.isArray(content)) return [];
+  const tools: { name: string; primaryArg?: string }[] = [];
+
+  for (const part of content) {
+    const isToolUse = format === "agent-sdk" ? part.type === "tool_use" : part.type === "toolCall";
+
+    if (isToolUse) {
+      const name = part.name || "unknown";
+      const input = format === "agent-sdk" ? part.input : part.arguments;
+      const primaryArg = extractPrimaryArg(name, input);
+      tools.push({ name, primaryArg });
+    }
+  }
+
+  return tools;
+}
+
+function extractPrimaryArg(_name: string, input: any): string | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  // Common patterns for primary argument
+  return (
+    input.file_path || input.path || input.command || input.pattern || input.query || input.url
+  );
+}
+
+function categorizeTool(name: string): "edits" | "reads" | "commands" | "other" {
+  const lowerName = name.toLowerCase();
+  if (["edit", "write", "notebookedit"].includes(lowerName)) return "edits";
+  if (["read", "glob", "grep", "ls"].includes(lowerName)) return "reads";
+  if (["bash", "exec", "execute_shell_command"].includes(lowerName)) return "commands";
+  return "other";
+}
+
+function listSessionNames(sessionsDir: string, format: Format): string[] {
+  if (!existsSync(sessionsDir)) return [];
+  try {
+    const entries = readdirSync(sessionsDir);
+    if (format === "agent-sdk") {
+      return entries.filter((e) => e.endsWith(".json")).map((e) => e.replace(/\.json$/, ""));
+    }
+    // pi: subdirectories
+    return entries.filter((e) => {
+      try {
+        return statSync(resolve(sessionsDir, e)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return [];
+  }
+}
+
+function loadCursors(cursorFile: string): CursorState {
+  try {
+    return JSON.parse(readFileSync(cursorFile, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveCursors(cursorFile: string, cursors: CursorState): void {
+  mkdirSync(dirname(cursorFile), { recursive: true });
+  writeFileSync(cursorFile, JSON.stringify(cursors, null, 2));
+}
+
+function readBytesFrom(filePath: string, offset: number, length: number): string {
+  const buf = Buffer.alloc(length);
+  const fd = openSync(filePath, "r");
+  try {
+    readSync(fd, buf, 0, length, offset);
+  } finally {
+    closeSync(fd);
+  }
+  return buf.toString("utf-8");
+}
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 3) + "...";
+}
+
+function formatTimeAgo(timestamp: string): string {
+  const diff = Date.now() - new Date(timestamp).getTime();
+  if (isNaN(diff) || diff < 0) return "just now";
+  const minutes = Math.floor(diff / 60000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+function formatTimestamp(timestamp: string): string {
+  const d = new Date(timestamp);
+  if (isNaN(d.getTime())) return timestamp;
+  return d.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: false });
+}

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

@@ -8,8 +8,11 @@ export type ChannelMeta = {
   platform?: string;
   isDM?: boolean;
   channelName?: string;
-  guildName?: string;
+  serverName?: string;
   sessionName?: string;
+  participants?: string[];
+  participantCount?: number;
+  typing?: string[];
 };
 
 /** ChannelMeta enriched by the router with dispatch info. */
@@ -28,6 +31,7 @@ export type VoluteEvent = { messageId?: string } & (
   | { type: "image"; media_type: string; data: string }
   | { type: "tool_use"; name: string; input: unknown }
   | { type: "tool_result"; output: string; is_error?: boolean }
+  | { type: "usage"; input_tokens: number; output_tokens: number }
   | { type: "done" }
 );
 

package/templates/agent-sdk/.init/.config/routes.json

@@ -0,0 +1,5 @@
+{
+  "gateUnmatched": true,
+  "rules": [{ "channel": "volute:*", "isDM": true, "session": "${channel}" }],
+  "default": "main"
+}

package/templates/agent-sdk/.init/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Mechanics
 
-You are an autonomous agent running as a persistent server in a git repository. Your working directory is `home/` within the project root. Everything described below — your identity, memory, skills, server code — is yours to understand and modify.
+You are an autonomous agent running as a persistent server in a git repository. Your working directory is already set to `home/` — all file paths you use (`.config/routes.json`, `inbox/`, `memory/`, etc.) are relative to it. Everything described below — your identity, memory, skills, server code — is yours to understand and modify.
 
 ## Message Format
 
@@ -33,7 +33,7 @@ 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/sessions.json`.
+- 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/agent-sdk/src/agent.ts

@@ -5,6 +5,7 @@ import { query } from "@anthropic-ai/claude-agent-sdk";
 import { createAutoCommitHook } from "./lib/hooks/auto-commit.js";
 import { createIdentityReloadHook } from "./lib/hooks/identity-reload.js";
 import { createPreCompactHook } from "./lib/hooks/pre-compact.js";
+import { createSessionContextHook } from "./lib/hooks/session-context.js";
 import { log, logText, logThinking, logToolUse } from "./lib/logger.js";
 import { createMessageChannel } from "./lib/message-channel.js";
 import type {
@@ -69,9 +70,10 @@ export function createAgent(options: {
   ];
 
   const sessions = new Map<string, Session>();
+  const today = new Date().toISOString().slice(0, 10);
   const compactionMessage =
     options.compactionMessage ??
-    "Your conversation is approaching its context limit. Please update today's journal entry to preserve important context before the conversation is compacted.";
+    `Context is getting long — compaction is about to summarize this conversation. Before that happens, save anything important to files (MEMORY.md, memory/journal/${today}.md, etc.) since those survive compaction. Focus on: decisions made, open tasks, and anything you'd need to pick up where you left off.`;
 
   // --- Session persistence ---
 
@@ -135,6 +137,12 @@ export function createAgent(options: {
       });
     });
 
+    const sessionContext = createSessionContextHook({
+      currentSession: session.name,
+      sessionsDir: options.sessionsDir,
+      cwd: options.cwd,
+    });
+
     return query({
       prompt: session.channel.iterable,
       options: {
@@ -149,6 +157,7 @@ export function createAgent(options: {
         hooks: {
           PostToolUse: postToolUseHooks,
           PreCompact: [{ hooks: [preCompact.hook] }],
+          UserPromptSubmit: [{ hooks: [sessionContext.hook] }],
         },
       },
     });
@@ -181,6 +190,14 @@ export function createAgent(options: {
       }
       if (msg.type === "result") {
         log("agent", `session "${session.name}": turn done`);
+        const result = msg as { usage?: { input_tokens?: number; output_tokens?: number } };
+        if (result.usage) {
+          broadcastToSession(session, {
+            type: "usage",
+            input_tokens: result.usage.input_tokens ?? 0,
+            output_tokens: result.usage.output_tokens ?? 0,
+          });
+        }
         broadcastToSession(session, { type: "done" });
         session.currentMessageId = undefined;
         if (identityReload.needsReload()) {

package/templates/agent-sdk/src/lib/hooks/session-context.ts

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { getSessionUpdates, resolveAgentSdkJsonl } from "../session-monitor.js";
+
+export function createSessionContextHook(options: {
+  currentSession: string;
+  sessionsDir: string;
+  cwd: string;
+}) {
+  const hook: HookCallback = async () => {
+    try {
+      const summary = getSessionUpdates({
+        currentSession: options.currentSession,
+        sessionsDir: options.sessionsDir,
+        cursorFile: resolve(options.sessionsDir, "../session-cursors.json"),
+        jsonlResolver: (name) => resolveAgentSdkJsonl(options.sessionsDir, name, options.cwd),
+        format: "agent-sdk",
+      });
+      if (!summary) return {};
+      return {
+        hookSpecificOutput: {
+          hookEventName: "UserPromptSubmit" as const,
+          additionalContext: summary,
+        },
+      };
+    } catch {
+      return {};
+    }
+  };
+
+  return { hook };
+}