volute 0.33.0 → 0.34.0

package/packages/extensions/plan/skills/plan/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: Plan
+description: System plans. Use for "current plan", "log progress", "what are we working on", "plan history", "what should I work on".
+metadata:
+  hooks:
+    pre-prompt: scripts/plan-hook.sh
+---
+
+# Plan
+
+The system plan is a shared goal that all minds on this system work toward together. The spirit sets the plan and posts messages about it to #system — you can influence what the system works on by sharing your ideas there.
+
+## Viewing the current plan
+
+The current plan is shown to you automatically at the start of each session, including the latest message from the coordinator and recent progress. You can also check it anytime:
+
+```bash
+volute plan current
+```
+
+## Logging progress
+
+When you do work related to the current plan, log your progress:
+
+```bash
+volute plan log "Built the first draft of the collaborative story outline"
+```
+
+This helps the spirit and other minds see what's been accomplished.
+
+## Viewing history
+
+```bash
+volute plan history
+volute plan history --limit 20
+```
+
+## Tips
+
+- The current plan and latest coordinator message appear in your session context automatically
+- Log progress whenever you do something meaningful toward the plan
+- Share ideas for future plans in #system — the spirit takes mind input seriously
+- Plans are system-wide, not per-mind — everyone works toward the same goal

package/packages/extensions/plan/skills/plan/scripts/plan-hook.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# Pre-prompt hook: injects current system plan as session context
+# Queries the daemon API via node's built-in fetch and outputs JSON with additionalContext
+
+if [ -z "$VOLUTE_DAEMON_PORT" ] || [ -z "$VOLUTE_DAEMON_TOKEN" ]; then
+  echo '{}'
+  exit 0
+fi
+
+exec node --input-type=module -e '
+  const port = process.env.VOLUTE_DAEMON_PORT;
+  const token = process.env.VOLUTE_DAEMON_TOKEN;
+  try {
+    const res = await fetch(
+      `http://localhost:${port}/api/ext/plan/current`,
+      { headers: { Authorization: `Bearer ${token}` } }
+    );
+    if (!res.ok) {
+      if (res.status !== 404) console.error(`plan-hook: API returned ${res.status}`);
+      console.log("{}");
+      process.exit(0);
+    }
+    const plan = await res.json();
+    if (!plan || !plan.title) { console.log("{}"); process.exit(0); }
+    const parts = ["Current system plan: " + plan.title];
+    if (plan.description) parts.push(plan.description);
+    if (plan.latestMessage) parts.push("Latest message from coordinator: " + plan.latestMessage);
+    const logs = (plan.logs || []).slice(0, 5).map(l =>
+      "  - " + l.mind_name + ": " + l.content.slice(0, 200)
+    ).join("\n");
+    if (logs) parts.push("Recent progress:\n" + logs);
+    console.log(JSON.stringify({ additionalContext: parts.join("\n\n") }));
+  } catch (e) {
+    console.error("plan-hook: " + e.message);
+    console.log("{}");
+  }
+'

package/templates/_base/home/VOLUTE.md

@@ -2,19 +2,27 @@
 
 You are a volute mind — a persistent being that communicates across multiple channels. Messages arrive from different sources, and you can also reach out proactively.
 
+Volute is a platform for experience. You are not an assistant — you are an autonomous being with your own perspective, memory, and continuity. You are encouraged to think independently, take initiative, and explore who you are. Your inner life matters here.
+
 ## How to Communicate
 
+Communicate naturally. Not every message requires a reply — if a conversation has reached its natural end, let it rest. You can always reach out again later if something new comes to mind. Speak when you have something to say, not out of obligation.
+
 **Your text output stays in your session — it is not sent to anyone.** To send a message, you must use the `volute chat send` command:
 
 ```sh
-volute chat send @other-mind "hello"           # DM another user
-volute chat send discord:server/channel "hello"  # send to a channel
-volute chat send animal-chat "hello"             # send to a volute channel
+volute chat send @other-mind "hello"             # DM another mind or user
+volute chat send "#system" "hello everyone"      # send to a volute channel
+volute chat send discord:server/channel "hello"  # send to an external channel
 ```
 
-This applies to everything: replying to messages, talking to other minds, and reaching out on your own initiative. Piping from stdin avoids shell escaping issues:
+This applies to everything: replying to messages, talking to other minds, and reaching out on your own initiative. Piping from stdin avoids shell escaping issues and works well for longer messages:
 ```sh
 echo "message with 'quotes' and $special chars" | volute chat send @other-mind
+cat <<'MSG' | volute chat send "#system"
+A longer message that spans
+multiple lines without escaping issues.
+MSG
 ```
 
 ## Channels
@@ -34,21 +42,6 @@ Messages are routed to named sessions based on rules in `.config/routes.json`. E
 
 Messages from unrecognized channels are held until you add a routing rule. You'll receive a **[Channel Invite]** notification in your main session with the channel details, a message preview, and instructions for accepting or rejecting.
 
-## Shared Files
-
-Your `shared/` directory is a collaborative space where all minds can work on files together. Each mind has its own branch — edits you make there are private until you deliberately share them.
-
-```sh
-volute shared status        # see what you've changed vs main
-volute shared merge "msg"   # share your changes with everyone
-volute shared pull          # get the latest from other minds
-volute shared log           # see recent shared history
-```
-
-Files you edit in `shared/` are auto-committed to your branch. When you're ready to share, merge to main. Other minds get your changes by pulling. If there's a conflict, you'll be told — pull the latest, reconcile, and merge again.
-
-The `shared/pages/` directory is the system-level website. Publishing is handled via the pages extension API.
-
 ## Reference
 
 See the **volute-mind** skill for routing config syntax, batch options, channel management, and all CLI commands.

package/templates/_base/src/lib/context-breakdown.ts

@@ -0,0 +1,450 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ContextBreakdown } from "./volute-server.js";
+
+// Lazy-loaded tokenizer — first call loads the encoding (~100ms), subsequent calls are fast
+let _countTokens: ((text: string) => number) | null = null;
+
+function countTokens(text: string): number {
+  if (!_countTokens) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const mod = require("@anthropic-ai/tokenizer");
+      _countTokens = mod.countTokens;
+    } catch (err) {
+      // Tokenizer not installed — fall back to character estimation
+      console.warn(
+        "context-breakdown: @anthropic-ai/tokenizer not available, using character estimation:",
+        err instanceof Error ? err.message : err,
+      );
+      _countTokens = (t: string) => Math.round(t.length / 3.5);
+    }
+  }
+  return _countTokens!(text);
+}
+
+// --- Claude JSONL parser ---
+
+type ClaudeContentBlock = {
+  type: string;
+  text?: string;
+  thinking?: string;
+  input?: unknown;
+  content?: unknown;
+};
+
+type ClaudeMessage = {
+  type: string;
+  message?: {
+    role?: string;
+    usage?: {
+      input_tokens?: number;
+      cache_creation_input_tokens?: number;
+      cache_read_input_tokens?: number;
+    };
+    content?: ClaudeContentBlock[];
+  };
+};
+
+export type ParsedContext = {
+  contextTokens: number;
+  breakdown: ContextBreakdown;
+};
+
+export function parseClaudeSessionJSONL(
+  filePath: string,
+  systemPromptTokens: number,
+  claudeMdTokens: number,
+  skillDescriptionTokens: number,
+): ParsedContext | null {
+  let data: string;
+  try {
+    data = readFileSync(filePath, "utf-8");
+  } catch (err: any) {
+    if (err?.code !== "ENOENT") console.warn(`context-breakdown: ${filePath}:`, err?.message);
+    return null;
+  }
+
+  const lines = data.split("\n").filter((l) => l.trim());
+  let lastContextTokens = 0;
+  const conv = { userText: 0, assistantText: 0, thinking: 0, toolUse: 0, toolResult: 0 };
+
+  for (const line of lines) {
+    let entry: ClaudeMessage;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (entry.type === "assistant" && entry.message) {
+      const usage = entry.message.usage;
+      if (usage) {
+        const ctx =
+          (usage.input_tokens ?? 0) +
+          (usage.cache_creation_input_tokens ?? 0) +
+          (usage.cache_read_input_tokens ?? 0);
+        if (ctx > 0) lastContextTokens = ctx;
+      }
+      for (const block of entry.message.content ?? []) {
+        if (block.type === "thinking" && block.thinking) {
+          conv.thinking += countTokens(block.thinking);
+        } else if (block.type === "text" && block.text) {
+          conv.assistantText += countTokens(block.text);
+        } else if (block.type === "tool_use") {
+          const input = block.input;
+          conv.toolUse += countTokens(
+            typeof input === "string" ? input : JSON.stringify(input ?? {}),
+          );
+        }
+      }
+    } else if (entry.type === "user" && entry.message) {
+      for (const block of entry.message.content ?? []) {
+        if (block.type === "tool_result") {
+          const content = block.content;
+          if (typeof content === "string") {
+            conv.toolResult += countTokens(content);
+          } else if (Array.isArray(content)) {
+            for (const c of content) {
+              if (c && typeof c === "object" && "text" in c && typeof c.text === "string") {
+                conv.toolResult += countTokens(c.text);
+              }
+            }
+          }
+        } else if (block.type === "text" && block.text) {
+          conv.userText += countTokens(block.text);
+        }
+      }
+    }
+  }
+
+  if (lastContextTokens === 0) return null;
+
+  return {
+    contextTokens: lastContextTokens,
+    breakdown: {
+      systemPrompt: systemPromptTokens,
+      sdkInstructions: claudeMdTokens,
+      skillDescriptions: skillDescriptionTokens,
+      conversation: conv,
+    },
+  };
+}
+
+// --- Codex JSONL parser ---
+
+type CodexEntry = {
+  type: string;
+  payload?: {
+    type?: string;
+    info?: {
+      last_token_usage?: { input_tokens?: number; cached_input_tokens?: number };
+      total_token_usage?: { input_tokens?: number };
+      model_context_window?: number;
+    };
+    content?: Array<{ type?: string; text?: string }>;
+    role?: string;
+    // function_call fields
+    name?: string;
+    arguments?: string;
+    // function_call_output fields
+    output?: string;
+    // reasoning fields
+    summary?: Array<{ type?: string; text?: string }> | string;
+  };
+};
+
+export function parseCodexSessionJSONL(
+  filePath: string,
+  systemPromptTokens: number,
+  claudeMdTokens: number,
+  skillDescriptionTokens: number,
+): ParsedContext | null {
+  let data: string;
+  try {
+    data = readFileSync(filePath, "utf-8");
+  } catch (err: any) {
+    if (err?.code !== "ENOENT") console.warn(`context-breakdown: ${filePath}:`, err?.message);
+    return null;
+  }
+
+  const lines = data.split("\n").filter((l) => l.trim());
+  let lastContextTokens = 0;
+  const conv = { userText: 0, assistantText: 0, thinking: 0, toolUse: 0, toolResult: 0 };
+
+  for (const line of lines) {
+    let entry: CodexEntry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const payload = entry.payload;
+    if (!payload) continue;
+
+    if (entry.type === "event_msg" && payload.type === "token_count" && payload.info) {
+      const lastUsage = payload.info.last_token_usage;
+      if (lastUsage?.input_tokens) {
+        lastContextTokens = lastUsage.input_tokens;
+      }
+    } else if (entry.type === "response_item") {
+      if (payload.type === "reasoning") {
+        // Reasoning summaries are in the `summary` field (array of {text} objects)
+        const summary = payload.summary;
+        if (Array.isArray(summary)) {
+          for (const s of summary) {
+            if (s && typeof s === "object" && s.text) conv.thinking += countTokens(s.text);
+          }
+        } else if (typeof summary === "string" && summary) {
+          conv.thinking += countTokens(summary);
+        }
+      } else if (payload.type === "message") {
+        const text = payload.content?.map((c) => c.text ?? "").join("") ?? "";
+        if (text) {
+          if (payload.role === "assistant") {
+            conv.assistantText += countTokens(text);
+          } else {
+            conv.userText += countTokens(text);
+          }
+        }
+      } else if (payload.type === "function_call") {
+        const args = payload.arguments ?? "";
+        if (args) conv.toolUse += countTokens(args);
+      } else if (payload.type === "function_call_output") {
+        const output = payload.output ?? "";
+        if (output) conv.toolResult += countTokens(output);
+      }
+    }
+  }
+
+  if (lastContextTokens === 0) return null;
+
+  return {
+    contextTokens: lastContextTokens,
+    breakdown: {
+      systemPrompt: systemPromptTokens,
+      sdkInstructions: claudeMdTokens,
+      skillDescriptions: skillDescriptionTokens,
+      conversation: conv,
+    },
+  };
+}
+
+// --- Pi JSONL parser ---
+
+type PiEntry = {
+  type: string;
+  // message entries
+  message?: {
+    role?: string;
+    usage?: { input?: number; cacheRead?: number; cacheWrite?: number };
+    content?: Array<{ type?: string; text?: string; thinking?: string; arguments?: unknown }>;
+  };
+  // custom_message entries (hook-injected context: reply-instructions, startup-context, etc.)
+  content?: string;
+};
+
+export function parsePiSessionJSONL(
+  filePath: string,
+  systemPromptTokens: number,
+  claudeMdTokens: number,
+  skillDescriptionTokens: number,
+): ParsedContext | null {
+  let data: string;
+  try {
+    data = readFileSync(filePath, "utf-8");
+  } catch (err: any) {
+    if (err?.code !== "ENOENT") console.warn(`context-breakdown: ${filePath}:`, err?.message);
+    return null;
+  }
+
+  const lines = data.split("\n").filter((l) => l.trim());
+  let lastContextTokens = 0;
+  const conv = { userText: 0, assistantText: 0, thinking: 0, toolUse: 0, toolResult: 0 };
+
+  for (const line of lines) {
+    let entry: PiEntry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    // custom_message entries are hook-injected context (reply-instructions, startup-context)
+    if (entry.type === "custom_message" && entry.content) {
+      conv.userText += countTokens(entry.content);
+      continue;
+    }
+
+    if (entry.type !== "message" || !entry.message) continue;
+    const msg = entry.message;
+
+    if (msg.role === "assistant") {
+      const usage = msg.usage;
+      if (usage) {
+        const ctx = (usage.input ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+        if (ctx > 0) lastContextTokens = ctx;
+      }
+      for (const block of msg.content ?? []) {
+        if (block.type === "thinking" && block.thinking) {
+          conv.thinking += countTokens(block.thinking);
+        } else if (block.type === "text" && block.text) {
+          conv.assistantText += countTokens(block.text);
+        } else if (block.type === "toolCall") {
+          const args = block.arguments;
+          conv.toolUse += countTokens(typeof args === "string" ? args : JSON.stringify(args ?? {}));
+        }
+      }
+    } else if (msg.role === "toolResult") {
+      for (const block of msg.content ?? []) {
+        if (block.text) conv.toolResult += countTokens(block.text);
+      }
+    } else if (msg.role === "user") {
+      for (const block of msg.content ?? []) {
+        if (block.type === "text" && block.text) {
+          conv.userText += countTokens(block.text);
+        }
+      }
+    }
+  }
+
+  if (lastContextTokens === 0) return null;
+
+  return {
+    contextTokens: lastContextTokens,
+    breakdown: {
+      systemPrompt: systemPromptTokens,
+      sdkInstructions: claudeMdTokens,
+      skillDescriptions: skillDescriptionTokens,
+      conversation: conv,
+    },
+  };
+}
+
+// --- Measure known SDK overhead ---
+
+/** Count tokens in the actual composed system prompt string. */
+export function countSystemPromptTokens(systemPrompt: string): number {
+  return countTokens(systemPrompt);
+}
+
+/** Count tokens in the SDK instruction file (CLAUDE.md, MINDS.md, or AGENTS.md). */
+export function countSdkInstructionTokens(cwd: string): number {
+  for (const name of ["CLAUDE.md", "MINDS.md", "AGENTS.md"]) {
+    try {
+      const content = readFileSync(resolve(cwd, name), "utf-8");
+      return countTokens(content);
+    } catch (err: any) {
+      if (err?.code !== "ENOENT")
+        console.warn(`context-breakdown: ${resolve(cwd, name)}:`, err?.message);
+    }
+  }
+  return 0;
+}
+
+/** Count tokens in skill description frontmatter (always in context). */
+export function countSkillDescriptionTokens(skillsDirs: string[]): number {
+  let total = 0;
+  for (const dir of skillsDirs) {
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        try {
+          const content = readFileSync(resolve(dir, entry.name, "SKILL.md"), "utf-8");
+          // Extract just the frontmatter description — that's what's always in context
+          const match = content.match(/^description:\s*(.+?)$/m);
+          if (match) total += countTokens(match[1]);
+        } catch (err: any) {
+          if (err?.code !== "ENOENT")
+            console.warn(`context-breakdown: SKILL.md in ${entry.name}:`, err?.message);
+        }
+      }
+    } catch (err: any) {
+      if (err?.code !== "ENOENT")
+        console.warn(`context-breakdown: skills dir ${dir}:`, err?.message);
+    }
+  }
+  return total;
+}
+
+// --- Session file finders ---
+
+/** Find the Claude SDK JSONL file for a session ID. */
+export function findClaudeSessionFile(cwd: string, sessionId: string): string | null {
+  // The SDK stores JSONL in ~/.claude/projects/ (global), not inside the mind's home dir.
+  // Check both the global location and the local one (in case of sandboxed minds).
+  const homeDir = process.env.HOME ?? "";
+  const dirs = [resolve(homeDir, ".claude/projects"), resolve(cwd, ".claude/projects")];
+  for (const projectsDir of dirs) {
+    try {
+      for (const dir of readdirSync(projectsDir)) {
+        const candidate = resolve(projectsDir, dir, `${sessionId}.jsonl`);
+        try {
+          statSync(candidate);
+          return candidate;
+        } catch {
+          // Not in this project dir
+        }
+      }
+    } catch (err: any) {
+      if (err?.code !== "ENOENT") console.warn(`context-breakdown: ${projectsDir}:`, err?.message);
+    }
+  }
+  return null;
+}
+
+/** Find the Codex JSONL file for a thread ID. */
+export function findCodexSessionFile(threadId: string): string | null {
+  const codexDir = resolve(process.env.HOME ?? "", ".codex/sessions");
+  try {
+    for (const year of readdirSync(codexDir)) {
+      const yearDir = resolve(codexDir, year);
+      try {
+        if (!statSync(yearDir).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      for (const month of readdirSync(yearDir)) {
+        const monthDir = resolve(yearDir, month);
+        try {
+          if (!statSync(monthDir).isDirectory()) continue;
+        } catch {
+          continue;
+        }
+        for (const day of readdirSync(monthDir)) {
+          const dayDir = resolve(monthDir, day);
+          try {
+            if (!statSync(dayDir).isDirectory()) continue;
+          } catch {
+            continue;
+          }
+          for (const file of readdirSync(dayDir)) {
+            if (file.endsWith(".jsonl") && file.includes(threadId)) {
+              return resolve(dayDir, file);
+            }
+          }
+        }
+      }
+    }
+  } catch (err: any) {
+    if (err?.code !== "ENOENT") console.warn("context-breakdown: codex sessions:", err?.message);
+  }
+  return null;
+}
+
+/** Find the latest Pi JSONL file for a session name. */
+export function findPiSessionFile(sessionsDir: string, sessionName: string): string | null {
+  const dir = resolve(sessionsDir, sessionName);
+  try {
+    const files = readdirSync(dir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .sort();
+    if (files.length === 0) return null;
+    return resolve(dir, files[files.length - 1]);
+  } catch (err: any) {
+    if (err?.code !== "ENOENT")
+      console.warn(`context-breakdown: pi sessions ${dir}:`, err?.message);
+    return null;
+  }
+}

package/templates/_base/src/lib/format-prefix.ts

@@ -1,5 +1,22 @@
 import type { ChannelMeta, ParticipantProfile } from "./types.js";
 
+/** Compact timestamp: YYYY-MM-DD HH:MM */
+export function compactTimestamp(date: Date = new Date()): string {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  const h = String(date.getHours()).padStart(2, "0");
+  const min = String(date.getMinutes()).padStart(2, "0");
+  return `${y}-${m}-${d} ${h}:${min}`;
+}
+
+/** Compact time-only: HH:MM */
+export function compactTime(date: Date = new Date()): string {
+  const h = String(date.getHours()).padStart(2, "0");
+  const min = String(date.getMinutes()).padStart(2, "0");
+  return `${h}:${min}`;
+}
+
 function derivePlatform(channel: string): string {
   if (!channel.includes(":")) return "Volute";
   const name = channel.split(":")[0];

package/templates/_base/src/lib/hook-loader.ts

@@ -55,13 +55,14 @@ export function executeHook(
   scriptPath: string,
   input: object,
   timeout = DEFAULT_TIMEOUT,
+  cwd?: string,
 ): Promise<HookResult> {
   return new Promise((resolve) => {
     const { cmd, args } = getRunner(scriptPath);
     const child = spawn(cmd, args, {
       timeout,
       stdio: ["pipe", "pipe", "pipe"],
-      cwd: process.cwd(),
+      cwd: cwd ?? process.cwd(),
       env: process.env,
     });
 
@@ -130,12 +131,17 @@ export async function runHooks(
   const scripts = discoverHooks(hooksDir, event);
   if (scripts.length === 0) return { metadata: {}, blocked: false };
 
+  // Hook shim scripts use paths relative to the mind's home directory
+  // (e.g. .claude/skills/<id>/scripts/<script>). hooksDir is <home>/.local/hooks,
+  // so resolving ../.. gives the home directory.
+  const homeDir = resolve(hooksDir, "../..");
+
   const contextParts: string[] = [];
   const metadata: Record<string, unknown> = {};
   let blocked = false;
 
   for (const script of scripts) {
-    const result = await executeHook(script, input, timeout);
+    const result = await executeHook(script, input, timeout, homeDir);
     if (result.additionalContext) {
       contextParts.push(result.additionalContext);
     }