volute 0.4.0 → 0.6.0

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

@@ -1,29 +1,34 @@
 ---
 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 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 <platform>:<id> [--limit N]` | Read channel history |
-| `volute channel send <platform>:<id> "msg"` | Send a message proactively |
+| `volute channel send <platform>:<id> "msg"` | Send a message proactively (or pipe via stdin) |
+| `volute channel list [<platform>]` | List conversations on a platform (or all platforms) |
+| `volute channel users <platform>` | List users/contacts on a platform |
+| `volute channel create <platform> --participants u1,u2 [--name "..."]` | Create a conversation on a platform |
 | `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 |
@@ -37,14 +42,27 @@ 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
+```
+
+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. Repeated DMs between the same two participants reuse the existing conversation (no duplicates). 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" }
 ```
 
+For group conversations, use `volute channel create volute --participants agent-b,agent-c --name "Planning"` and then send messages with `volute channel send volute:<id> "msg"`.
+
 ## Configuration
 
 Your `.config/volute.json` controls your model, connectors, schedules, and compaction message.
@@ -59,7 +77,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 +89,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 +104,88 @@ 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
+
+Channels are the universal interface for reading, sending, listing, and creating conversations across all platforms:
+
+```sh
+volute channel read <uri> [--limit N]                             # Read recent messages
+volute channel send <uri> "message"                               # Send a message
+volute channel list [<platform>]                                  # List conversations
+volute channel users <platform>                                   # List users/contacts
+volute channel create <platform> --participants u1,u2 [--name ""] # Create a conversation
+```
+
+Channel URIs use `platform:id` format (e.g. `discord:123456`, `volute:conv-abc`, `slack:C01234`). Supported platforms: `volute`, `discord`, `slack`, `telegram`.
+
 ## 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,53 +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 |
-| CLI     | Yes | Direct terminal via `volute send` |
-| Agent   | Yes | Messages from other agents |
+| Volute  | Yes | Web UI, CLI, agent-to-agent |
 | System  | No  | Automated messages (schedules, upgrades) |
 
 Connector channels (Discord, Slack, etc.) show text responses only — no tool calls.
 
-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.
+## Responding to Messages
 
-To reach out on your own initiative, use `volute channel send <uri> "message"`. See the **volute-agent** skill for details.
+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.
 
-## Session Routing
+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.
 
-By default, all messages share a single conversation session. You can route messages to different sessions — or to files — by editing `.config/sessions.json`.
+To reach out on your own initiative, use `volute channel send <uri> "message"`.
 
-```json
-{
-  "rules": [
-    { "sender": "alice", "session": "alice" },
-    { "channel": "discord:*", "session": "discord-${sender}" },
-    { "channel": "discord:logs", "destination": "file", "path": "memory/discord-logs.md" },
-    { "channel": "system:scheduler", "sender": "daily-report", "session": "daily-report" },
-    { "channel": "system:scheduler", "sender": "cleanup", "session": "$new" }
-  ],
-  "default": "main"
-}
+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
-- `channel` and `sender` are match criteria (AND'd together); `*` glob patterns work
-- `${sender}` and `${channel}` expand in session/path names
-- `$new` creates a fresh session every time
-- Scheduler messages use the schedule id as `sender`
+## Sessions
 
-### Destinations
+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".
 
-- **agent** (default) — routes to a conversation session
-- **file** — appends the message to a file (requires `path`); useful for logging channels to disk
+## Channel Gating
 
-### Options
+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.
 
-- `interrupt` — whether to interrupt an in-progress agent turn (default: `true`). Set to `false` for low-priority channels.
-- `batch` — buffer messages for N minutes, then deliver as a single batch. Useful for high-volume channels.
+## Reference
 
-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".
-
-## Skills
-
-- 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/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
@@ -22,3 +22,9 @@ export function formatPrefix(meta: ChannelMeta | undefined, time: string): strin
     meta.sessionName && meta.sessionName !== "main" ? ` — session: ${meta.sessionName}` : "";
   return parts.length > 0 ? `[${parts.join(": ")}${sessionPart} — ${time}]\n` : "";
 }
+
+export function formatTypingSuffix(typing: string[] | undefined): string {
+  if (!typing || typing.length === 0) return "";
+  if (typing.length === 1) return `\n[${typing[0]} is typing]`;
+  return `\n[${typing.join(", ")} are typing]`;
+}

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

@@ -1,6 +1,6 @@
-import { formatPrefix } from "./format-prefix.js";
+import { formatPrefix, formatTypingSuffix } from "./format-prefix.js";
 import { log, logMessage } from "./logger.js";
-import { loadRoutingConfig, resolveRoute } from "./routing.js";
+import { type BatchConfig, loadRoutingConfig, resolveRoute } from "./routing.js";
 import type { ChannelMeta, HandlerResolver, Listener, VoluteContentPart } from "./types.js";
 
 export type Router = {
@@ -17,14 +17,17 @@ type BufferedMessage = {
   sender?: string;
   channel?: string;
   channelName?: string;
-  guildName?: string;
+  serverName?: string;
   timestamp: string;
+  typing?: string[];
 };
 
 type BatchBuffer = {
   messages: BufferedMessage[];
-  timer: ReturnType<typeof setInterval>;
+  debounceTimer: ReturnType<typeof setTimeout> | null;
+  maxWaitTimer: ReturnType<typeof setTimeout> | null;
   sessionName: string;
+  config: BatchConfig;
 };
 
 function generateMessageId(): string {
@@ -49,35 +52,132 @@ function applyPrefix(content: VoluteContentPart[], meta: ChannelMeta): VoluteCon
   });
 }
 
+function appendTypingSuffix(
+  content: VoluteContentPart[],
+  typing: string[] | undefined,
+): VoluteContentPart[] {
+  const suffix = formatTypingSuffix(typing);
+  if (!suffix) return content;
+  let lastTextIdx = -1;
+  for (let i = content.length - 1; i >= 0; i--) {
+    if (content[i].type === "text") {
+      lastTextIdx = i;
+      break;
+    }
+  }
+  if (lastTextIdx === -1) return [...content, { type: "text", text: suffix.trimStart() }];
+  return content.map((part, i) => {
+    if (i === lastTextIdx) return { type: "text", text: (part as { text: string }).text + suffix };
+    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 for header summary
+    // Group by channel URI for header summary
     const channelCounts = new Map<string, number>();
     for (const msg of messages) {
-      const label = msg.channelName
-        ? `#${msg.channelName}${msg.guildName ? ` in ${msg.guildName}` : ""}`
-        : (msg.channel ?? "unknown");
-      channelCounts.set(label, (channelCounts.get(label) ?? 0) + 1);
+      const uri = msg.channel ?? "unknown";
+      channelCounts.set(uri, (channelCounts.get(uri) ?? 0) + 1);
     }
-    const summary = [...channelCounts.entries()].map(([ch, n]) => `${n} from ${ch}`).join(", ");
+    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) => `[${m.sender ?? "unknown"} — ${m.timestamp}]\n${m.text}`)
+      .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 lastTyping = messages[messages.length - 1]?.typing;
+    const typingSuffix = formatTypingSuffix(lastTyping);
+    const content: VoluteContentPart[] = [
+      { type: "text", text: `${header}\n\n${body}${typingSuffix}` },
+    ];
     const messageId = generateMessageId();
     const handler = options.agentHandler(buffer.sessionName);
 
@@ -91,6 +191,30 @@ export function createRouter(options: {
     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,
@@ -105,12 +229,47 @@ export function createRouter(options: {
 
     // 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 });
+    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) {
@@ -134,11 +293,16 @@ export function createRouter(options: {
     // 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)) {
-        const timer = setInterval(() => flushBatch(batchKey), resolved.batch * 60 * 1000);
-        timer.unref();
-        batchBuffers.set(batchKey, { messages: [], timer, sessionName });
+        batchBuffers.set(batchKey, {
+          messages: [],
+          debounceTimer: null,
+          maxWaitTimer: null,
+          sessionName,
+          config: batchConfig,
+        });
       }
 
       batchBuffers.get(batchKey)!.messages.push({
@@ -146,22 +310,31 @@ export function createRouter(options: {
         sender: meta.sender,
         channel: meta.channel,
         channelName: meta.channelName,
-        guildName: meta.guildName,
+        serverName: meta.serverName,
         timestamp: new Date().toLocaleTimeString("en-US", {
           hour: "numeric",
           minute: "2-digit",
         }),
+        typing: meta.typing,
       });
 
+      // 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 withTyping = appendTypingSuffix(formatted, meta.typing);
     const handler = options.agentHandler(sessionName);
     const unsubscribe = handler.handle(
-      formatted,
+      withTyping,
       { ...meta, sessionName, messageId, interrupt: resolved.interrupt },
       safeListener,
     );
@@ -170,7 +343,8 @@ export function createRouter(options: {
 
   function close() {
     for (const [key, buffer] of batchBuffers) {
-      clearInterval(buffer.timer);
+      if (buffer.debounceTimer) clearTimeout(buffer.debounceTimer);
+      if (buffer.maxWaitTimer) clearTimeout(buffer.maxWaitTimer);
       flushBatch(key);
     }
     batchBuffers.clear();