volute 0.3.1 → 0.5.0

package/templates/_base/_skills/volute-agent/SKILL.md

@@ -1,32 +1,37 @@
 ---
 name: Volute CLI
-description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the agent server. Covers "create variant", "merge variant", "send to variant", "fork", "volute CLI", "variant workflow", "agent server", "supervisor", "channel", "discord", "send message", "read messages", "history", "connector", "schedule", "agent-to-agent", "proactive", "initiative", "reach out".
+description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the agent server. Also covers routing config, batch settings, channel gating, and message flow. Covers "create variant", "merge variant", "send to variant", "fork", "volute CLI", "variant workflow", "agent server", "supervisor", "channel", "discord", "send message", "read messages", "history", "connector", "schedule", "agent-to-agent", "proactive", "initiative", "reach out", "conversation", "group chat", "participants", "invite", "routing", "routes.json", "batch", "debounce", "trigger", "gating", "gate".
 ---
 
 # Self-Management
 
-You manage yourself through the `volute` CLI. Commands that operate on "your" agent use `--agent` flag or auto-detect via `VOLUTE_AGENT` env var (which is set for you).
+You manage yourself through the `volute` CLI. Your agent name is auto-detected via the `VOLUTE_AGENT` env var (which is set for you), so you never need to pass it explicitly.
 
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
-| `volute status` | Check your status |
-| `volute logs [--follow] [-n N]` | Read your own logs |
-| `volute history [--channel <ch>] [--limit N]` | View your activity across all channels |
-| `volute send <other-agent> "msg"` | Send a message to another agent |
+| `volute agent start` | Start your server |
+| `volute agent stop` | Stop your server |
+| `volute agent status` | Check your status |
+| `volute agent logs [--follow] [-n N]` | Read your own logs |
+| `volute message history [--channel <ch>] [--limit N]` | View your activity across all channels |
+| `volute message send <other-agent> "msg"` | Send a message to another agent (or pipe via stdin) |
 | `volute variant create <name> [--soul "..."] [--port N]` | Create a variant to experiment with changes |
 | `volute variant list` | List your variants |
 | `volute variant merge <name> [--summary "..." --memory "..."]` | Merge a variant back |
 | `volute variant delete <name>` | Delete a variant without merging |
-| `volute upgrade [--template <name>] [--continue]` | Upgrade your server code |
-| `volute connector connect <type>` | Enable a connector (e.g. discord) |
+| `volute agent upgrade [--template <name>] [--continue]` | Upgrade your server code |
+| `volute connector connect <type>` | Enable a connector (discord, slack, etc.) |
 | `volute connector disconnect <type>` | Disable a connector |
-| `volute channel read discord:<id> [--limit N]` | Read channel history |
-| `volute channel send discord:<id> "msg"` | Send a message proactively |
+| `volute channel read <platform>:<id> [--limit N]` | Read channel history |
+| `volute channel send <platform>:<id> "msg"` | Send a message proactively (or pipe via stdin) |
 | `volute schedule add --cron "..." --message "..."` | Schedule a recurring message to yourself |
 | `volute schedule list` | List your schedules |
 | `volute schedule remove --id <id>` | Remove a schedule |
+| `volute conversation create --participants u1,a1` | Create a group conversation |
+| `volute conversation list` | List your conversations |
+| `volute conversation send <id> "msg"` | Send a message to a conversation (or pipe via stdin) |
 
 ## Schedules
 
@@ -37,9 +42,21 @@ volute schedule add --cron "0 9 * * *" --message "morning — review what's on y
 volute schedule add --cron "0 0 * * 0" --message "weekly — consolidate your memory and reflect on the past week"
 ```
 
+## Piping Messages via Stdin
+
+All send commands accept the message from stdin instead of as an argument. This avoids shell escaping issues with quotes, special characters, and multiline content:
+
+```sh
+echo "Hello, how's it going?" | volute message send other-agent
+echo "Check out this $variable" | volute channel send discord:123456
+echo "Update on the task" | volute conversation send conv-abc
+```
+
+If both a positional argument and stdin are provided, the argument takes precedence. Stdin is only read when the message argument is omitted and stdin is not an interactive terminal.
+
 ## Agent-to-Agent Messaging
 
-When you use `volute send`, your agent name is automatically used as the sender and the channel is set to `agent`. The receiving agent can route agent messages to a specific session via their session routing config:
+When you use `volute message send`, your agent name is automatically used as the sender and the channel is set to `agent`. The receiving agent can route agent messages to a specific session via their session routing config:
 
 ```json
 { "channel": "agent", "sender": "your-name", "session": "your-name" }
@@ -59,7 +76,7 @@ Variants let you experiment safely — fork yourself, try changes, and merge bac
 
 1. `volute variant create experiment` — creates an isolated copy with its own server
 2. Make changes in the variant's worktree (at `../.variants/experiment/`)
-3. Test: `volute send $VOLUTE_AGENT@experiment "hello"`
+3. Test: `volute message send $VOLUTE_AGENT@experiment "hello"`
 4. `volute variant merge experiment --summary "..." --memory "..."` — merges back after verification
 
 You can also fork with a different personality to explore a different version of yourself:
@@ -71,11 +88,11 @@ After a merge, you receive orientation context about what changed. Update your m
 
 ## Upgrade Workflow
 
-`volute upgrade` merges the latest template code into a testable variant:
+`volute agent upgrade` merges the latest template code into a testable variant:
 
-1. `volute upgrade` — creates an `upgrade` variant
-2. Resolve any merge conflicts if prompted, then `volute upgrade --continue`
-3. Test: `volute send $VOLUTE_AGENT@upgrade "hello"`
+1. `volute agent upgrade` — creates an `upgrade` variant
+2. Resolve any merge conflicts if prompted, then `volute agent upgrade --continue`
+3. Test: `volute message send $VOLUTE_AGENT@upgrade "hello"`
 4. `volute variant merge upgrade` — merge back
 
 ## Custom Skills
@@ -86,6 +103,85 @@ Create skills by writing `.claude/skills/<name>/SKILL.md` files in your `home/`
 
 Edit `home/.mcp.json` to configure MCP servers for your SDK session. This gives you access to additional tools and services.
 
+## Message Routing
+
+Messages are routed to sessions based on rules in `.config/routes.json`. Rules are evaluated in order; first match wins. Unmatched messages go to the `default` session (defaults to `"main"`).
+
+### Rule syntax
+
+```json
+{
+  "rules": [
+    { "channel": "discord:*", "session": "discord", "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@myagent"] } },
+    { "channel": "volute:*", "isDM": true, "session": "${sender}" },
+    { "channel": "volute:*", "isDM": false, "session": "${channel}", "batch": { "debounce": 20, "maxWait": 120 } },
+    { "sender": "alice", "session": "alice" },
+    { "channel": "system:*", "session": "$new" },
+    { "channel": "discord:logs", "destination": "file", "path": "inbox/log.md" }
+  ],
+  "default": "main",
+  "gateUnmatched": true
+}
+```
+
+### Match criteria
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `channel` | glob string | Channel URI (e.g. `discord:*`, `volute:conv-*`) |
+| `sender` | glob string | Sender name |
+| `isDM` | boolean | Match DMs (`true`) or group channels (`false`) |
+| `participants` | number | Match exact participant count |
+
+### Rule fields
+
+| Field | Description |
+|-------|-------------|
+| `session` | Target session name. Supports `${sender}`, `${channel}` templates, or `$new` for a unique session per message |
+| `destination` | `"agent"` (default) or `"file"` |
+| `path` | File path when destination is `"file"` |
+| `batch` | Batch config (see below) |
+| `interrupt` | Whether to interrupt an in-progress turn (default: `true`) |
+
+### Batch config
+
+Batch mode buffers messages and delivers them together. Configure with an object:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `debounce` | seconds | Wait for quiet period before flushing — resets on each new message |
+| `maxWait` | seconds | Maximum time before forced flush, even during continuous activity |
+| `triggers` | string[] | Patterns that cause immediate flush (case-insensitive substring match) |
+
+Examples:
+- `{ "debounce": 20, "maxWait": 120 }` — flush after 20s of quiet, or 2 minutes max
+- `{ "debounce": 20, "maxWait": 120, "triggers": ["@myagent"] }` — same, but flush immediately on @mention
+- `{ "triggers": ["urgent"] }` — no timer, flush only on trigger (or immediately if no timers)
+
+Batched messages arrive as a single message with a `[Batch: N messages — ...]` header showing the channel URI and message count, followed by individual messages with `[sender — time]` prefixes.
+
+## Channel Gating
+
+When `gateUnmatched` is `true` (the default), messages from channels without a matching rule are held:
+
+1. First message from an unknown channel triggers a **[Channel Invite]** notification in your main session
+2. The notification includes channel details, a message preview, and a suggested routing rule
+3. Further messages are saved to `inbox/<channel>.md`
+4. To accept: add a routing rule to `.config/routes.json`
+5. To reject: delete the inbox file
+6. Set `gateUnmatched: false` to route all unmatched messages to the default session
+
+## Channel Commands
+
+Read and send messages to any connected channel:
+
+```sh
+volute channel read <uri> [--limit N]    # Read recent messages
+volute channel send <uri> "message"      # Send a message
+```
+
+Channel URIs use `platform:id` format (e.g. `discord:123456`, `volute:conv-abc`).
+
 ## Git Introspection
 
 Your cwd is `home/`, so use `git -C ..` for project-level operations:

package/templates/_base/home/.config/routes.json

@@ -0,0 +1,10 @@
+{
+  "rules": [
+    {
+      "channel": "volute:*",
+      "isDM": false,
+      "session": "${channel}",
+      "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@{{name}}"] }
+    }
+  ]
+}

package/templates/_base/home/VOLUTE.md

@@ -6,41 +6,32 @@ You are a volute agent — a persistent being that communicates across multiple
 
 | Channel | Shows tool calls | Notes |
 |---------|------------------|-------|
-| Web UI  | Yes | Full detail including tool calls |
-| Discord | No  | Text responses only |
-| CLI     | Yes | Direct terminal via `volute send` |
-| System  | No  | Automated messages (upgrades, health checks) |
+| Volute  | Yes | Web UI, CLI, agent-to-agent |
+| System  | No  | Automated messages (schedules, upgrades) |
 
-When responding to an incoming message, just respond normally — your response routes back to the source automatically. Do not use `volute channel send` to reply to a message; that would send a duplicate.
+Connector channels (Discord, Slack, etc.) show text responses only — no tool calls.
 
-To reach out on your own initiative, use `volute channel send <uri> "message"`. See the **volute-agent** skill for details.
+## Responding to Messages
 
-## Session Routing
+For **direct messages**, respond normally — your response routes back to the source automatically. Do not use `volute channel send` to reply; that would send a duplicate.
 
-By default, all messages share a single conversation session. You can route messages to different sessions by editing `.config/sessions.json`.
+For **batched channels** (group chats, high-volume sources), your text response stays in the session as internal processing — it doesn't get sent anywhere. Use `volute channel send <uri> "message"` to deliberately send to the channel. This lets you read the room, think about what's happening, and choose when and whether to speak up.
 
-```json
-{
-  "rules": [
-    { "sender": "alice", "session": "alice" },
-    { "channel": "discord:*", "session": "discord-${sender}" },
-    { "channel": "system:scheduler", "sender": "daily-report", "session": "daily-report" },
-    { "channel": "system:scheduler", "sender": "cleanup", "session": "$new" }
-  ],
-  "default": "main"
-}
+To reach out on your own initiative, use `volute channel send <uri> "message"`.
+
+All send commands also accept the message from stdin, which avoids shell escaping issues:
+```sh
+echo "message with 'quotes' and $special chars" | volute channel send <uri>
 ```
 
-- Rules are evaluated top-to-bottom, first match wins
-- All non-`session` keys are match criteria (AND'd together)
-- `*` glob patterns work in match values
-- `${sender}` and `${channel}` expand in session names
-- `$new` creates a fresh session every time
-- Scheduler messages use the schedule id as `sender`
+## Sessions
+
+Messages are routed to named sessions based on rules in `.config/routes.json`. Each session has its own conversation history. Without config, everything goes to "main". Your session name appears in the message prefix (e.g. `— session: alice —`) unless it's "main".
+
+## Channel Gating
 
-Each named session maintains its own conversation history across restarts. Your current session name appears in the message prefix (e.g., `— session: alice —`) unless it's the default "main".
+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.
 
-## Skills
+## Reference
 
-- Use the **volute-agent** skill for CLI commands, variants, upgrades, and self-management.
-- Use the **memory** skill for detailed memory management and consolidation.
+See the **volute-agent** skill for routing config syntax, batch options, channel management, and all CLI commands.

package/templates/_base/src/lib/file-handler.ts

@@ -0,0 +1,46 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { log } from "./logger.js";
+import type {
+  HandlerMeta,
+  HandlerResolver,
+  Listener,
+  MessageHandler,
+  VoluteContentPart,
+} from "./types.js";
+
+function extractText(content: VoluteContentPart[]): string {
+  return content
+    .filter((p): p is { type: "text"; text: string } => p.type === "text")
+    .map((p) => p.text)
+    .join("\n");
+}
+
+export function createFileHandlerResolver(cwd: string): HandlerResolver {
+  const resolvedCwd = resolve(cwd);
+
+  return (filePath: string): MessageHandler => ({
+    handle(content: VoluteContentPart[], meta: HandlerMeta, listener: Listener): () => void {
+      const resolved = resolve(resolvedCwd, filePath);
+      if (!resolved.startsWith(`${resolvedCwd}/`) && resolved !== resolvedCwd) {
+        log("file", `rejected path traversal: ${filePath}`);
+        queueMicrotask(() => listener({ type: "done", messageId: meta.messageId }));
+        return () => {};
+      }
+
+      const text = extractText(content);
+      if (text) {
+        try {
+          mkdirSync(dirname(resolved), { recursive: true });
+          appendFileSync(resolved, `${text}\n\n`);
+          log("file", `appended to ${resolved}`);
+        } catch (err) {
+          log("file", `failed to write ${resolved}:`, err);
+        }
+      }
+      // Emit done asynchronously so unsubscribe is assigned before listener fires
+      queueMicrotask(() => listener({ type: "done", messageId: meta.messageId }));
+      return () => {};
+    },
+  });
+}

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

@@ -14,7 +14,7 @@ export function formatPrefix(meta: ChannelMeta | undefined, time: string): strin
     sender += " in DM";
   } else if (meta.channelName) {
     sender += ` in #${meta.channelName}`;
-    if (meta.guildName) sender += ` in ${meta.guildName}`;
+    if (meta.serverName) sender += ` in ${meta.serverName}`;
   }
   const parts = [platform, sender].filter(Boolean);
   // Include session name if not the default

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

@@ -0,0 +1,327 @@
+import { formatPrefix } from "./format-prefix.js";
+import { log, logMessage } from "./logger.js";
+import { type BatchConfig, loadRoutingConfig, resolveRoute } from "./routing.js";
+import type { ChannelMeta, HandlerResolver, Listener, VoluteContentPart } from "./types.js";
+
+export type Router = {
+  route(
+    content: VoluteContentPart[],
+    meta: ChannelMeta,
+    listener?: Listener,
+  ): { messageId: string; unsubscribe: () => void };
+  close(): void;
+};
+
+type BufferedMessage = {
+  text: string;
+  sender?: string;
+  channel?: string;
+  channelName?: string;
+  serverName?: string;
+  timestamp: string;
+};
+
+type BatchBuffer = {
+  messages: BufferedMessage[];
+  debounceTimer: ReturnType<typeof setTimeout> | null;
+  maxWaitTimer: ReturnType<typeof setTimeout> | null;
+  sessionName: string;
+  config: BatchConfig;
+};
+
+function generateMessageId(): string {
+  return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function applyPrefix(content: VoluteContentPart[], meta: ChannelMeta): VoluteContentPart[] {
+  const time = new Date().toLocaleString();
+  const prefix = formatPrefix(meta, time);
+  if (!prefix) return content;
+
+  const firstTextIdx = content.findIndex((p) => p.type === "text");
+  if (firstTextIdx === -1) {
+    return [{ type: "text", text: prefix.trimEnd() }, ...content];
+  }
+
+  return content.map((part, i) => {
+    if (i === firstTextIdx) {
+      return { type: "text" as const, text: prefix + (part as { text: string }).text };
+    }
+    return part;
+  });
+}
+
+function sanitizeChannelPath(channel: string): string {
+  return channel
+    .replace(/[/\\:]/g, "-")
+    .replace(/\.\./g, "-")
+    .replace(/\0/g, "")
+    .slice(0, 100);
+}
+
+/** Check if message text matches any trigger patterns (case-insensitive substring match). */
+function matchesTrigger(text: string, triggers: string[]): boolean {
+  const lower = text.toLowerCase();
+  return triggers.some((t) => lower.includes(t.toLowerCase()));
+}
+
+function formatInviteNotification(
+  meta: ChannelMeta,
+  filePath: string,
+  messageText: string,
+): string {
+  const time = new Date().toLocaleString();
+  const lines = ["[Channel Invite]"];
+  if (meta.channel) lines.push(`Channel: ${meta.channel}`);
+  if (meta.sender) lines.push(`Sender: ${meta.sender}`);
+  if (meta.platform) lines.push(`Platform: ${meta.platform}`);
+  if (meta.serverName) lines.push(`Server: ${meta.serverName}`);
+  if (meta.channelName) lines.push(`Channel name: ${meta.channelName}`);
+  if (meta.participants && meta.participants.length > 0)
+    lines.push(`Participants: ${meta.participants.join(", ")}`);
+  lines.push("");
+  const preview = messageText.length > 200 ? `${messageText.slice(0, 200)}...` : messageText;
+  lines.push(`[${meta.sender ?? "unknown"} — ${time}]`);
+  lines.push(preview);
+  lines.push("");
+  lines.push(`Further messages will be saved to ${filePath}`);
+  lines.push("");
+  lines.push("To accept, add a routing rule to .config/routes.json:");
+  const suggestedSession = sanitizeChannelPath(meta.channel ?? "unknown");
+  const otherCount = (meta.participantCount ?? 1) - 1;
+  if (otherCount > 1) {
+    lines.push(
+      `  { "channel": "${meta.channel}", "session": "${suggestedSession}", "batch": { "debounce": 20, "maxWait": 120 } }`,
+    );
+    lines.push(
+      `(batch recommended — ${otherCount} other participants may generate frequent messages)`,
+    );
+  } else {
+    lines.push(`  { "channel": "${meta.channel}", "session": "${suggestedSession}" }`);
+  }
+  lines.push(`To respond, use: volute channel send ${meta.channel ?? "unknown"} "your message"`);
+  lines.push(`To reject, delete ${filePath}`);
+  return lines.join("\n");
+}
+
+export function createRouter(options: {
+  configPath?: string;
+  agentHandler: HandlerResolver;
+  fileHandler?: HandlerResolver;
+}): Router {
+  const batchBuffers = new Map<string, BatchBuffer>();
+  const pendingChannels = new Set<string>();
+
+  function flushBatch(key: string) {
+    const buffer = batchBuffers.get(key);
+    if (!buffer || buffer.messages.length === 0) return;
+
+    // Clear both timers
+    if (buffer.debounceTimer) clearTimeout(buffer.debounceTimer);
+    if (buffer.maxWaitTimer) clearTimeout(buffer.maxWaitTimer);
+    buffer.debounceTimer = null;
+    buffer.maxWaitTimer = null;
+
+    const messages = buffer.messages.splice(0);
+
+    // Group by channel URI for header summary
+    const channelCounts = new Map<string, number>();
+    for (const msg of messages) {
+      const uri = msg.channel ?? "unknown";
+      channelCounts.set(uri, (channelCounts.get(uri) ?? 0) + 1);
+    }
+    const channelLabels = [...channelCounts.entries()].map(([uri, n]) => {
+      const msg = messages.find((m) => m.channel === uri);
+      const display = msg?.channelName
+        ? `#${msg.channelName}${msg.serverName ? ` in ${msg.serverName}` : ""} (${uri})`
+        : uri;
+      return `${n} from ${display}`;
+    });
+    const summary = channelLabels.join(", ");
+
+    const header = `[Batch: ${messages.length} message${messages.length === 1 ? "" : "s"} — ${summary}]`;
+    // Include channel URI per message when batch spans multiple channels
+    const multiChannel = channelCounts.size > 1;
+    const body = messages
+      .map((m) => {
+        const prefix =
+          multiChannel && m.channel
+            ? `[${m.sender ?? "unknown"} in ${m.channel} — ${m.timestamp}]`
+            : `[${m.sender ?? "unknown"} — ${m.timestamp}]`;
+        return `${prefix}\n${m.text}`;
+      })
+      .join("\n\n");
+
+    const content: VoluteContentPart[] = [{ type: "text", text: `${header}\n\n${body}` }];
+    const messageId = generateMessageId();
+    const handler = options.agentHandler(buffer.sessionName);
+
+    // Batch flushes are fire-and-forget — no HTTP response is waiting, so listener is a noop
+    try {
+      handler.handle(content, { sessionName: buffer.sessionName, messageId }, () => {});
+    } catch (err) {
+      log("router", `error flushing batch for session ${buffer.sessionName}:`, err);
+      return;
+    }
+    log("router", `flushed batch for session ${buffer.sessionName}: ${messages.length} messages`);
+  }
+
+  function scheduleBatchTimers(key: string) {
+    const buffer = batchBuffers.get(key);
+    if (!buffer) return;
+    const { config } = buffer;
+
+    // Reset debounce timer
+    if (buffer.debounceTimer) clearTimeout(buffer.debounceTimer);
+    if (config.debounce != null) {
+      buffer.debounceTimer = setTimeout(() => flushBatch(key), config.debounce * 1000);
+      buffer.debounceTimer.unref();
+    }
+
+    // Start maxWait timer if not already running
+    if (!buffer.maxWaitTimer && config.maxWait != null) {
+      buffer.maxWaitTimer = setTimeout(() => flushBatch(key), config.maxWait * 1000);
+      buffer.maxWaitTimer.unref();
+    }
+
+    // If neither timer is configured, flush immediately (shouldn't happen in practice)
+    if (config.debounce == null && config.maxWait == null) {
+      flushBatch(key);
+    }
+  }
+
+  function route(
+    content: VoluteContentPart[],
+    meta: ChannelMeta,
+    listener?: Listener,
+  ): { messageId: string; unsubscribe: () => void } {
+    // Log incoming message
+    const text = content
+      .filter((p): p is { type: "text"; text: string } => p.type === "text")
+      .map((p) => p.text)
+      .join(" ");
+    logMessage("in", text, meta.channel);
+
+    // Resolve route from config (re-read on each request for hot-reload)
+    const config = options.configPath ? loadRoutingConfig(options.configPath) : {};
+    const resolved = resolveRoute(config, {
+      channel: meta.channel,
+      sender: meta.sender,
+      isDM: meta.isDM,
+      participantCount: meta.participantCount,
+    });
+
+    const messageId = generateMessageId();
+    const noop = () => {};
+    const safeListener = listener ?? noop;
+
+    // Gate unmatched channels (default: gate unless explicitly disabled)
+    if (!resolved.matched && config.gateUnmatched !== false) {
+      const channelKey = meta.channel ?? "unknown";
+      const sanitized = sanitizeChannelPath(channelKey);
+      const filePath = `inbox/${sanitized}.md`;
+
+      // Save message to file
+      if (options.fileHandler) {
+        const formatted = applyPrefix(content, meta);
+        const fileHandler = options.fileHandler(filePath);
+        fileHandler.handle(formatted, { ...meta, messageId }, noop);
+      }
+
+      // First message from this channel — send invite notification
+      if (!pendingChannels.has(channelKey)) {
+        pendingChannels.add(channelKey);
+        const notification = formatInviteNotification(meta, filePath, text);
+        const notifContent: VoluteContentPart[] = [{ type: "text", text: notification }];
+        const handler = options.agentHandler("main");
+        handler.handle(
+          notifContent,
+          { sessionName: "main", messageId: generateMessageId(), interrupt: true },
+          noop,
+        );
+      }
+
+      queueMicrotask(() => safeListener({ type: "done", messageId }));
+      return { messageId, unsubscribe: noop };
+    }
+
+    // File destination
+    if (resolved.destination === "file") {
+      if (options.fileHandler) {
+        const formatted = applyPrefix(content, meta);
+        const handler = options.fileHandler(resolved.path);
+        const unsubscribe = handler.handle(formatted, { ...meta, messageId }, safeListener);
+        return { messageId, unsubscribe };
+      }
+      // No file handler configured — emit done and discard
+      log("router", `no file handler configured — discarding file-destined message`);
+      queueMicrotask(() => safeListener({ type: "done", messageId }));
+      return { messageId, unsubscribe: noop };
+    }
+
+    // Agent destination
+    let sessionName = resolved.session;
+    if (sessionName === "$new") {
+      sessionName = `new-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+
+    // Batch mode: buffer the message and return immediate done
+    if (resolved.batch != null) {
+      const batchKey = `batch:${sessionName}`;
+      const batchConfig = resolved.batch;
+
+      if (!batchBuffers.has(batchKey)) {
+        batchBuffers.set(batchKey, {
+          messages: [],
+          debounceTimer: null,
+          maxWaitTimer: null,
+          sessionName,
+          config: batchConfig,
+        });
+      }
+
+      batchBuffers.get(batchKey)!.messages.push({
+        text,
+        sender: meta.sender,
+        channel: meta.channel,
+        channelName: meta.channelName,
+        serverName: meta.serverName,
+        timestamp: new Date().toLocaleTimeString("en-US", {
+          hour: "numeric",
+          minute: "2-digit",
+        }),
+      });
+
+      // Check triggers — flush immediately if matched
+      if (batchConfig.triggers?.length && matchesTrigger(text, batchConfig.triggers)) {
+        flushBatch(batchKey);
+      } else {
+        scheduleBatchTimers(batchKey);
+      }
+
+      queueMicrotask(() => safeListener({ type: "done", messageId }));
+      return { messageId, unsubscribe: noop };
+    }
+
+    // Direct dispatch to agent
+    const formatted = applyPrefix(content, { ...meta, sessionName });
+    const handler = options.agentHandler(sessionName);
+    const unsubscribe = handler.handle(
+      formatted,
+      { ...meta, sessionName, messageId, interrupt: resolved.interrupt },
+      safeListener,
+    );
+    return { messageId, unsubscribe };
+  }
+
+  function close() {
+    for (const [key, buffer] of batchBuffers) {
+      if (buffer.debounceTimer) clearTimeout(buffer.debounceTimer);
+      if (buffer.maxWaitTimer) clearTimeout(buffer.maxWaitTimer);
+      flushBatch(key);
+    }
+    batchBuffers.clear();
+  }
+
+  return { route, close };
+}