volute 0.3.1 → 0.5.0

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

@@ -0,0 +1,137 @@
+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 | 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?: 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("routing", `failed to load ${configPath}:`, err);
+    }
+    return {};
+  }
+}
+
+/**
+ * Match a glob-like pattern against a string.
+ * Supports only `*` as wildcard (matches any sequence of characters).
+ */
+function globMatch(pattern: string, value: string): boolean {
+  // Escape regex special chars except *, then replace * with .*
+  const regex = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${regex}$`).test(value);
+}
+
+const GLOB_MATCH_KEYS = new Set(["channel", "sender"]);
+const NON_MATCH_KEYS = new Set(["session", "batch", "destination", "path", "interrupt"]);
+
+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 (!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: MatchMeta): string {
+  return template
+    .replace(/\$\{sender\}/g, meta.sender ?? "unknown")
+    .replace(/\$\{channel\}/g, meta.channel ?? "unknown");
+}
+
+/**
+ * Resolve the full route for a message: destination type, session/path, interrupt, batch.
+ */
+export function resolveRoute(config: RoutingConfig, meta: MatchMeta): ResolvedRoute {
+  const fallback = config.default ?? "main";
+
+  if (!config.rules) {
+    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("routing", `file destination rule missing path — falling through`);
+          continue;
+        }
+        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 != null ? normalizeBatch(rule.batch) : undefined,
+        matched: true,
+      };
+    }
+  }
+
+  return { destination: "agent", session: fallback, interrupt: true, matched: false };
+}
+
+function sanitizeSessionName(name: string): string {
+  return name.replace(/\0/g, "").replace(/[/\\]/g, "-").replace(/\.\./g, "-").slice(0, 100);
+}

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

@@ -8,9 +8,16 @@ export type ChannelMeta = {
   platform?: string;
   isDM?: boolean;
   channelName?: string;
-  guildName?: string;
+  serverName?: string;
   sessionName?: string;
-  messageId?: string;
+  participants?: string[];
+  participantCount?: number;
+};
+
+/** ChannelMeta enriched by the router with dispatch info. */
+export type HandlerMeta = ChannelMeta & {
+  messageId: string;
+  interrupt?: boolean;
 };
 
 export type VoluteRequest = {
@@ -28,4 +35,10 @@ export type VoluteEvent = { messageId?: string } & (
 
 export type Listener = (event: VoluteEvent) => void;
 
-export const INTERACTIVE_CHANNELS = new Set(["web", "cli", "discord"]);
+/** A handler that processes a single routed message and streams events to a listener. */
+export type MessageHandler = {
+  handle(content: VoluteContentPart[], meta: HandlerMeta, listener: Listener): () => void; // returns unsubscribe
+};
+
+/** Resolves a key (session name, file path, etc.) to a MessageHandler. */
+export type HandlerResolver = (key: string) => MessageHandler;

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

@@ -1,12 +1,7 @@
 import { createServer, type IncomingMessage, type Server } from "node:http";
 import { log } from "./logger.js";
-import { loadSessionConfig, resolveSession } from "./sessions.js";
-import type { ChannelMeta, VoluteContentPart, VoluteEvent, VoluteRequest } from "./types.js";
-
-export type VoluteAgent = {
-  sendMessage: (content: string | VoluteContentPart[], meta?: ChannelMeta) => void;
-  onMessage: (listener: (event: VoluteEvent) => void, sessionName?: string) => () => void;
-};
+import type { Router } from "./router.js";
+import type { VoluteRequest } from "./types.js";
 
 function readBody(req: IncomingMessage): Promise<string> {
   return new Promise((resolve, reject) => {
@@ -18,13 +13,12 @@ function readBody(req: IncomingMessage): Promise<string> {
 }
 
 export function createVoluteServer(options: {
-  agent: VoluteAgent;
+  router: Router;
   port: number;
   name: string;
   version: string;
-  sessionsConfigPath?: string;
 }): Server {
-  const { agent, port, name, version } = options;
+  const { router, port, name, version } = options;
 
   const server = createServer(async (req, res) => {
     const url = new URL(req.url!, "http://localhost");
@@ -39,58 +33,34 @@ export function createVoluteServer(options: {
       try {
         const body = JSON.parse(await readBody(req)) as VoluteRequest;
 
-        // Resolve session from routing config (re-read on each request for hot-reload)
-        let sessionName = "main";
-        if (options.sessionsConfigPath) {
-          const sessionConfig = loadSessionConfig(options.sessionsConfigPath);
-          sessionName = resolveSession(sessionConfig, {
-            channel: body.channel,
-            sender: body.sender,
-          });
-        }
-        if (sessionName === "$new") {
-          sessionName = `new-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-        }
-
-        const messageId = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-
         res.writeHead(200, {
           "Content-Type": "application/x-ndjson",
           "Cache-Control": "no-cache",
           Connection: "keep-alive",
         });
 
-        const removeListener = agent.onMessage((event) => {
+        const { unsubscribe } = router.route(body.content, body, (event) => {
           try {
-            // Only forward events from our message (skip startup/other messages)
-            if (event.messageId !== messageId) return;
             res.write(`${JSON.stringify(event)}\n`);
             if (event.type === "done") {
-              removeListener();
               res.end();
             }
-          } catch {
-            removeListener();
+          } catch (err) {
+            log("server", "write error, disconnecting:", err);
+            unsubscribe();
           }
-        }, sessionName);
-
-        res.on("close", () => {
-          removeListener();
         });
 
-        agent.sendMessage(body.content, {
-          channel: body.channel,
-          sender: body.sender,
-          platform: body.platform,
-          isDM: body.isDM,
-          channelName: body.channelName,
-          guildName: body.guildName,
-          sessionName,
-          messageId,
-        });
-      } catch {
-        res.writeHead(400);
-        res.end("Bad Request");
+        res.on("close", () => unsubscribe());
+      } catch (err) {
+        if (err instanceof SyntaxError) {
+          res.writeHead(400);
+          res.end("Bad Request");
+        } else {
+          log("server", "error handling /message:", err);
+          res.writeHead(500);
+          res.end("Internal Server Error");
+        }
       }
       return;
     }
@@ -99,6 +69,8 @@ export function createVoluteServer(options: {
     res.end("Not Found");
   });
 
+  server.on("close", () => router.close());
+
   let retries = 0;
   const maxRetries = 5;
   server.on("error", (err: NodeJS.ErrnoException) => {

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.