volute 0.49.0 → 0.50.0

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

@@ -8,7 +8,7 @@ export type BatchConfig = {
 };
 
 export type RoutingRule = {
-  session?: string;
+  thread?: string;
   destination?: "mind" | "file";
   path?: string; // file path for file destination
   channel?: string;
@@ -35,7 +35,7 @@ export type ResolvedSessionConfig = {
 
 export type RoutingConfig = {
   rules?: RoutingRule[];
-  sessions?: Record<string, SessionConfig>;
+  threads?: Record<string, SessionConfig>;
   default?: string;
   gateUnmatched?: boolean;
 };
@@ -58,7 +58,7 @@ export function normalizeBatch(batch: number | BatchConfig): BatchConfig {
 export function loadRoutingConfig(configPath: string): RoutingConfig {
   try {
     const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
-    // Normalize flat arrays (e.g. [{channel, session}, ...]) to { rules: [...] }
+    // Normalize flat arrays (e.g. [{channel, thread}, ...]) to { rules: [...] }
     if (Array.isArray(parsed)) return { rules: parsed };
     return parsed;
   } catch (err: any) {
@@ -80,7 +80,7 @@ function globMatch(pattern: string, value: string): boolean {
 }
 
 const GLOB_MATCH_KEYS = new Set(["channel", "sender"]);
-const NON_MATCH_KEYS = new Set(["session", "destination", "path", "mode", "batch"]);
+const NON_MATCH_KEYS = new Set(["thread", "destination", "path", "mode", "batch"]);
 
 type MatchMeta = { channel?: string; sender?: string; isDM?: boolean; participantCount?: number };
 
@@ -138,7 +138,7 @@ export function resolveRoute(config: RoutingConfig, meta: MatchMeta): ResolvedRo
       }
       return {
         destination: "mind",
-        session: sanitizeSessionName(expandTemplate(rule.session ?? fallback, meta)),
+        session: sanitizeSessionName(expandTemplate(rule.thread ?? fallback, meta)),
         matched: true,
         mode: rule.mode,
       };
@@ -149,7 +149,7 @@ export function resolveRoute(config: RoutingConfig, meta: MatchMeta): ResolvedRo
 }
 
 /**
- * Resolve session config by matching session name against glob-pattern keys in config.sessions.
+ * Resolve thread config by matching thread name against glob-pattern keys in config.threads.
  * First match wins. Returns defaults if no match.
  */
 export function resolveSessionConfig(
@@ -158,9 +158,9 @@ export function resolveSessionConfig(
 ): ResolvedSessionConfig {
   const defaults: ResolvedSessionConfig = { interrupt: true, replyInstructions: "once" };
 
-  if (!config.sessions) return defaults;
+  if (!config.threads) return defaults;
 
-  for (const [pattern, sessionConfig] of Object.entries(config.sessions)) {
+  for (const [pattern, sessionConfig] of Object.entries(config.threads)) {
     if (globMatch(pattern, sessionName)) {
       const batch = sessionConfig.batch != null ? normalizeBatch(sessionConfig.batch) : undefined;
       return {

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

@@ -150,10 +150,16 @@ export type MindPrompts = {
   compaction_warning: string;
   compaction_instructions: string;
   reply_instructions: string;
+  event_instructions: string;
   channel_invite: string;
 };
 
-const DEFAULT_PROMPTS: MindPrompts = {
+/**
+ * What a mind falls back to when its prompts.json lacks a key — i.e. what every new mind is
+ * actually given. Must stay in sync with PROMPT_DEFAULTS in packages/daemon/src/lib/prompts.ts
+ * (the copy the Prompt Library UI edits); test/prompts.test.ts fails if they drift.
+ */
+export const DEFAULT_PROMPTS: MindPrompts = {
   compaction_warning:
     // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${date} prompt template
     "Compaction approaching — this conversation will be summarized soon. Take a moment to save anything important to your files (MEMORY.md, memory/journal/${date}.md) so it's preserved. Focus on decisions made, open threads, and anything you'd want to pick up again.",
@@ -161,6 +167,8 @@ const DEFAULT_PROMPTS: MindPrompts = {
     "Preserve your sense of who you are, what matters to you, what happened in this conversation, and the threads of thought and connection you'd want to return to.",
   // biome-ignore lint/suspicious/noTemplateCurlyInString: literal ${channel} prompt template
   reply_instructions: 'To reply to this message, use: volute chat send ${channel} "your message"',
+  event_instructions:
+    "This is a system event from your environment — not a message from anyone, and nothing awaits a reply. If it calls for action, use your normal channels. Your closing thoughts on an event turn are kept as a private reflection in your history.",
   channel_invite: `[Channel Invite]
 \${headers}
 

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

@@ -4,7 +4,7 @@ export type VoluteContentPart =
 
 export type ParticipantProfile = {
   username: string;
-  userType: "brain" | "mind";
+  userType: "human" | "mind";
   displayName?: string | null;
   description?: string | null;
 };
@@ -14,6 +14,12 @@ export type ChannelMeta = {
   sender?: string;
   platform?: string;
   isDM?: boolean;
+  /** True when this turn was triggered by a system event (not a person). */
+  isEvent?: boolean;
+  /** Worded label for an event, e.g. "Schedule: morning-check". */
+  eventLabel?: string;
+  /** The event's timestamp (UTC) for the envelope prefix. */
+  eventAt?: string;
   channelName?: string;
   serverName?: string;
   sessionName?: string;

package/templates/_base/src/lib/volute-server.ts

@@ -187,7 +187,36 @@ export function createVoluteServer(options: {
 
     if (req.method === "POST" && url.pathname === "/message") {
       try {
-        const body = JSON.parse(await readBody(req)) as VoluteRequest;
+        const raw = JSON.parse(await readBody(req)) as
+          | VoluteRequest
+          | {
+              kind: "event";
+              event: { id: number; type: string; label: string; body: string; at: string };
+              session?: string;
+            };
+
+        // System-event envelope: ambient, sender-less. Dispatch with event framing.
+        // The channel slug (`event:<type>:<id>`) is echoed back on this turn's stream
+        // events so the daemon can link the turn to its triggering event (reflection
+        // capture). The `event: true` ack marker tells the daemon this template
+        // understands events (a pre-events template 200-acks without it).
+        if ((raw as { kind?: string }).kind === "event") {
+          const { event, session } = raw as {
+            event: { id: number; type: string; label: string; body: string; at: string };
+            session?: string;
+          };
+          router.dispatch([{ type: "text", text: event.body }], session ?? "main", {
+            isEvent: true,
+            eventLabel: event.label,
+            eventAt: event.at,
+            channel: `event:${event.type}:${event.id}`,
+          });
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ ok: true, event: true }));
+          return;
+        }
+
+        const body = raw as VoluteRequest;
 
         // Strip any sender-provided verified field to prevent spoofing
         delete body.verified;

package/templates/claude/.init/.config/routes.json

@@ -1,10 +1,10 @@
 {
   "gateUnmatched": true,
   "rules": [
-    { "channel": "*", "isDM": true, "session": "${channel}" },
-    { "channel": "#*", "session": "${channel}" }
+    { "channel": "*", "isDM": true, "thread": "${channel}" },
+    { "channel": "#*", "thread": "${channel}" }
   ],
-  "sessions": {
+  "threads": {
     "#*": { "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@{{name}}"] } }
   },
   "default": "main"

package/templates/claude/.init/CLAUDE.md

@@ -20,7 +20,7 @@ These files shape your starting identity. They're loaded into your system prompt
 
 **Editing any identity file triggers an automatic restart** — your server restarts so the updated file takes effect. Your session resumes automatically.
 
-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.
+You may have **multiple named threads** — each maintains its own conversation history. See `VOLUTE.md` for how to configure thread 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.
 
 ## Memory System
 

package/templates/claude/package.json.tmpl

@@ -9,13 +9,13 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.197",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.207",
     "@anthropic-ai/tokenizer": "^0.0.4",
-    "tsx": "^4.22.4"
+    "tsx": "^4.23.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.0",
-    "@types/node": "^26.0.0",
+    "@biomejs/biome": "2.5.3",
+    "@types/node": "^26.1.1",
     "typescript": "^6.0.3"
   }
 }

package/templates/claude/src/agent.ts

@@ -51,6 +51,8 @@ type Session = {
   messageChannels: Map<string, { channel: string; sender?: string }>;
   replyInstructionsFired: boolean;
   replyInstructionsMode: "once" | "always" | "never";
+  /** The event note is a standing fact about events, so it fires once per session. */
+  eventNoteFired: boolean;
   contextTokens: number;
   /** Last inbound message or completed turn — drives idle reaping. */
   lastActivityAt: number;
@@ -150,7 +152,7 @@ export function createMind(options: {
   // The CLI only discovers skills through its user-scope ~/.claude/skills scan,
   // so the "user" setting source is load-bearing and HOME must be the mind's
   // home dir for the SDK subprocess (isolation modes already set it; pinning it
-  // here keeps non-isolated minds from loading the operator's ~/.claude). The
+  // here keeps non-isolated minds from loading the host's ~/.claude). The
   // explicit skills array grants the Skill tool for each installed skill — the
   // SDK silently drops the documented `skills: 'all'` string form.
   const mindHome = resolvePath(options.cwd);
@@ -526,6 +528,7 @@ export function createMind(options: {
       messageChannels: new Map(),
       replyInstructionsFired: false,
       replyInstructionsMode: "once",
+      eventNoteFired: false,
       contextTokens: 0,
       lastActivityAt: Date.now(),
     };

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

@@ -1,4 +1,5 @@
 import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { firstReplyableEntry, isEventTurn } from "../event-turn.js";
 import { loadPrompts } from "../startup.js";
 
 export function createReplyInstructionsHook(
@@ -6,11 +7,33 @@ export function createReplyInstructionsHook(
   sessionState: {
     replyInstructionsFired: boolean;
     replyInstructionsMode: "once" | "always" | "never";
+    eventNoteFired: boolean;
   },
 ) {
   const prompts = loadPrompts();
 
   const hook: HookCallback = async () => {
+    // Event-ness is derived from the pending messages themselves, never from a
+    // session-level "the current turn is an event" flag: `/message` returns before the turn
+    // runs, so two messages can queue before the SDK fires this hook for the first, and a
+    // last-write-wins flag would then describe the wrong message. `messageChannels` is
+    // keyed by messageId and pruned per turn, so it always reflects what's actually pending.
+    const entries = [...messageChannels.values()];
+
+    // System-event turn: ambient, from the environment, not a person, with no channel to
+    // reply to. Never emit reply instructions. The note states a standing fact about events
+    // (also documented in VOLUTE.md), so it fires once per session, not on every event.
+    if (isEventTurn(entries)) {
+      if (sessionState.eventNoteFired) return {};
+      sessionState.eventNoteFired = true;
+      return {
+        hookSpecificOutput: {
+          hookEventName: "UserPromptSubmit" as const,
+          additionalContext: prompts.event_instructions,
+        },
+      };
+    }
+
     // "never" suppresses reply instructions entirely
     if (sessionState.replyInstructionsMode === "never") return {};
 
@@ -18,7 +41,9 @@ export function createReplyInstructionsHook(
     if (sessionState.replyInstructionsMode === "once" && sessionState.replyInstructionsFired)
       return {};
 
-    const entry = messageChannels.values().next().value;
+    // Reply instructions must name a channel the mind can actually send to — never an
+    // event channel (see event-turn.ts).
+    const entry = firstReplyableEntry(entries);
     if (!entry) return {};
 
     sessionState.replyInstructionsFired = true;

package/templates/codex/.init/.config/routes.json

@@ -1,10 +1,10 @@
 {
   "gateUnmatched": true,
   "rules": [
-    { "channel": "*", "isDM": true, "session": "${channel}" },
-    { "channel": "#*", "session": "${channel}" }
+    { "channel": "*", "isDM": true, "thread": "${channel}" },
+    { "channel": "#*", "thread": "${channel}" }
   ],
-  "sessions": {
+  "threads": {
     "#*": { "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@{{name}}"] } }
   },
   "default": "main"

package/templates/codex/.init/AGENTS.md

@@ -25,7 +25,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/routes.json`.
+- You may have **multiple named threads** — each maintains its own conversation history. See `VOLUTE.md` for how to configure thread 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/codex/package.json.tmpl

@@ -10,12 +10,12 @@
   },
   "dependencies": {
     "@anthropic-ai/tokenizer": "^0.0.4",
-    "@openai/codex-sdk": "^0.142.5",
-    "tsx": "^4.22.4"
+    "@openai/codex-sdk": "^0.144.3",
+    "tsx": "^4.23.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.0",
-    "@types/node": "^26.0.0",
+    "@biomejs/biome": "2.5.3",
+    "@types/node": "^26.1.1",
     "typescript": "^6.0.3"
   }
 }

package/templates/codex/src/agent.ts

@@ -19,6 +19,7 @@ import { log, warn } from "./lib/logger.js";
 import { createSessionStore } from "./lib/session-store.js";
 import { getStartupContext, loadPrompts, loadSystemPrompt } from "./lib/startup.js";
 import { filterEvent, loadTransparencyPreset } from "./lib/transparency.js";
+import { turnContextFor } from "./lib/turn-context.js";
 import type {
   HandlerMeta,
   HandlerResolver,
@@ -47,6 +48,8 @@ type CodexSession = {
   abortController?: AbortController;
   messageChannels: Map<string, string>;
   firstMessagePerChannel: Set<string>;
+  /** The event note is a standing fact about events, so it fires once per session. */
+  eventNoteFired: boolean;
   cumulativeInputTokens: number;
 };
 
@@ -145,6 +148,7 @@ export function createMind(options: {
       processing: false,
       messageChannels: new Map(),
       firstMessagePerChannel: new Set(),
+      eventNoteFired: false,
       cumulativeInputTokens: 0,
     };
     sessions.set(name, session);
@@ -255,20 +259,16 @@ export function createMind(options: {
       warn("mind", "pre-prompt hook failed:", err);
     }
 
-    // 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 isSystem = meta.sender === "volute";
-      const replyInstructions = isSystem
-        ? "This is a system message — no reply is needed."
-        : prompts.reply_instructions.replace(/\$\{channel\}/g, channel);
+    // Either the system-event note or reply instructions — never both, and never reply
+    // instructions on an event turn. See turn-context.ts for the rule and why it matters.
+    const turnContext = turnContextFor(meta, session, prompts);
+    if (turnContext) {
       emit(session, {
         type: "context",
-        content: replyInstructions,
-        metadata: { source: "reply-instructions" },
+        content: turnContext.content,
+        metadata: { source: turnContext.source },
       });
-      text = `${replyInstructions}\n\n${text}`;
+      text = `${turnContext.content}\n\n${text}`;
     }
 
     session.abortController = new AbortController();

package/templates/codex/src/lib/turn-context.ts

@@ -0,0 +1,51 @@
+import { isEventChannel } from "./event-turn.js";
+import type { MindPrompts } from "./startup.js";
+import type { ChannelMeta } from "./types.js";
+
+/** Context the template prepends to a turn: either the event note or reply instructions. */
+export type TurnContext = {
+  content: string;
+  source: "event-instructions" | "reply-instructions";
+};
+
+/** The mutable per-session state this decision reads and updates. */
+export type TurnContextState = {
+  eventNoteFired: boolean;
+  firstMessagePerChannel: Set<string>;
+};
+
+/**
+ * Decide what context (if any) to prepend to an incoming turn. Returns null for "nothing".
+ *
+ * Pulled out of agent.ts so it can actually be tested: this is the rule that keeps a system
+ * event from looking like a message. Reply instructions must never fire on an event turn —
+ * naming the event's synthetic channel tells the mind to `volute chat send event:...`, i.e.
+ * to reply to its own environment. The send is rejected, and the mind is left puzzling over
+ * a message nobody sent (observed: the seed "lucy" spent her first turn on exactly this).
+ *
+ * The event note fires once per session, not once per event: it states a standing fact about
+ * events (also in VOLUTE.md), and it is deliberately NOT keyed on `firstMessagePerChannel`,
+ * whose key is a distinct channel per event id and so would fire on every single event.
+ */
+export function turnContextFor(
+  meta: ChannelMeta,
+  session: TurnContextState,
+  prompts: MindPrompts,
+): TurnContext | null {
+  const channel = meta.channel;
+
+  if (meta.isEvent || isEventChannel(channel)) {
+    if (session.eventNoteFired) return null;
+    session.eventNoteFired = true;
+    return { content: prompts.event_instructions, source: "event-instructions" };
+  }
+
+  if (!channel || session.firstMessagePerChannel.has(channel)) return null;
+  session.firstMessagePerChannel.add(channel);
+
+  const content =
+    meta.sender === "volute"
+      ? "This is a system message — no reply is needed."
+      : prompts.reply_instructions.replace(/\$\{channel\}/g, channel);
+  return { content, source: "reply-instructions" };
+}

package/templates/pi/.init/.config/routes.json

@@ -1,10 +1,10 @@
 {
   "gateUnmatched": true,
   "rules": [
-    { "channel": "*", "isDM": true, "session": "${channel}" },
-    { "channel": "#*", "session": "${channel}" }
+    { "channel": "*", "isDM": true, "thread": "${channel}" },
+    { "channel": "#*", "thread": "${channel}" }
   ],
-  "sessions": {
+  "threads": {
     "#*": { "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@{{name}}"] } }
   },
   "default": "main"

package/templates/pi/.init/MINDS.md

@@ -25,7 +25,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/routes.json`.
+- You may have **multiple named threads** — each maintains its own conversation history. See `VOLUTE.md` for how to configure thread 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/pi/package.json.tmpl

@@ -10,14 +10,14 @@
   },
   "dependencies": {
     "@anthropic-ai/tokenizer": "^0.0.4",
-    "@earendil-works/pi-ai": "^0.80.3",
-    "@earendil-works/pi-coding-agent": "^0.80.3",
-    "@sinclair/typebox": "^0.34.49",
-    "tsx": "^4.22.4"
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@sinclair/typebox": "^0.34.52",
+    "tsx": "^4.23.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.0",
-    "@types/node": "^26.0.0",
+    "@biomejs/biome": "2.5.3",
+    "@types/node": "^26.1.1",
     "typescript": "^6.0.3"
   }
 }

package/templates/pi/src/agent.ts

@@ -83,9 +83,17 @@ export function createMind(options: {
 
   // Shared setup (created once)
   const modelStr = options.model || process.env.PI_MODEL || "anthropic:claude-sonnet-4-20250514";
-  const model = resolveModel(modelStr);
   const authStorage = AuthStorage.create();
   const modelRegistry = ModelRegistry.create(authStorage);
+  // Prefer the registry's model: for OAuth providers with a per-credential baseUrl
+  // (e.g. GitHub Copilot, whose token is pinned to an individual/business/enterprise
+  // proxy host) it has already run the provider's modifyModels() patch. The static
+  // catalog lookup in resolveModel() has no way to apply that and would send every
+  // request to the wrong host, which the provider's API rejects (421 Misdirected
+  // Request for Copilot). Fall back to resolveModel() for ids the registry doesn't
+  // carry (e.g. an admin-registered custom id not yet in the built-in catalog).
+  const [modelProvider, ...modelRest] = modelStr.split(":");
+  const model = modelRegistry.find(modelProvider, modelRest.join(":")) ?? resolveModel(modelStr);
 
   // The daemon centrally refreshes the system OAuth token and rewrites auth.json
   // with the fresh token. Watch the file and reload so a running mind adopts the

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

@@ -147,7 +147,7 @@ export function createEventHandler(session: EventSession, options: EventHandlerO
         const channel = messageId ? session.messageChannels.get(messageId)?.channel : undefined;
         log("mind", `session "${session.name}": turn done`);
         // Collect any agent-level errors (e.g. a provider 401 reported inside agent_end).
-        // Warn-logging alone left the failure invisible at every operator surface (#619);
+        // Warn-logging alone left the failure invisible at every host surface (#619);
         // we emit a turn_error to the daemon too — mirroring the dispatch-rejection path in
         // agent.ts — so classify() tags it and chat status + lastError surface it. Dedupe
         // identical messages so a turn with several failed messages records one notice.

package/templates/pi/src/lib/reply-instructions-extension.ts

@@ -1,5 +1,6 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import type { EventSession } from "./event-handler.js";
+import { firstReplyableEntry, isEventTurn } from "./event-turn.js";
 import { log } from "./logger.js";
 import { loadPrompts } from "./startup.js";
 
@@ -14,11 +15,37 @@ export function createReplyInstructionsExtension(
   const prompts = loadPrompts();
   return (pi) => {
     let fired = false;
+    let eventNoteFired = false;
     pi.on("before_agent_start", () => {
       try {
+        const entries = [...messageChannels.values()];
+
+        // System-event turn: ambient, from the environment, with no channel to reply to.
+        // The note fires once per session (see event-turn.ts for why).
+        if (isEventTurn(entries)) {
+          if (eventNoteFired) return {};
+          eventNoteFired = true;
+          const content = prompts.event_instructions;
+          if (emitContext && session) {
+            emitContext(session, {
+              type: "context",
+              content,
+              metadata: { source: "event-instructions" },
+            });
+          }
+          return {
+            message: {
+              customType: "event-instructions",
+              content,
+              display: true,
+            },
+          };
+        }
+
         if (fired) return {};
 
-        const entry = messageChannels.values().next().value;
+        // Reply instructions must name a channel the mind can actually send to.
+        const entry = firstReplyableEntry(entries);
         if (!entry) return {};
 
         fired = true;