feat(commands): add /<N> defer-send + /0 cancel per chat

uestney · uestney · commit 4fee54fcaad3 · 2026-05-19T16:52:54.000Z
`/&lt;N&gt; &lt;message&gt;` queues `&lt;message&gt;` to fire N minutes from now
(default unit = minutes). The whole feature lives in the numeric
`/&lt;digits&gt;` namespace so it can never collide with a word command:
`/0` cancels the chat's pending deferred message — no ID needed.

Per-chat single-slot rule: at most one pending deferred message per
(bot, chat). A second `/&lt;N&gt;` while one is queued is rejected with the
existing entry's details; `/status` surfaces the pending entry. Max
defer is 7 days. Scheduler is injected via setter (process-singleton,
mirrors setSessionRegistry); bots without one get a clear notice.
diff --git a/README.md b/README.md
@@ -432,7 +432,9 @@ MetaBot 以 `bypassPermissions` 模式运行 Claude Code — 无交互式确认
 |------|------|
 | `/reset` | 清除会话 |
 | `/stop` | 中止当前任务 |
-| `/status` | 查看会话状态（含当前模型） |
+| `/status` | 查看会话状态（含当前模型 + 待发送队列） |
+| `/<N> <消息>` | 把 `<消息>` 排到 **N 分钟后**自动发送（每个聊天只能排一条，最长 7 天） |
+| `/0` | 取消该聊天的待发送消息（无需 ID；纯数字命名空间，零冲突） |
 | `/goal <条件>` | 设置目标，Agent 跨多轮持续推进直到达成。`/goal clear` 停止 |
 | `/model` | 查看当前模型；`/model list` 查看可用模型；`/model <name>` 切换；`/model reset` 恢复默认 |
 | `/memory list` | 浏览知识库目录 |
diff --git a/README_EN.md b/README_EN.md
@@ -435,7 +435,9 @@ MetaBot runs Claude Code in `bypassPermissions` mode — no interactive approval
 |---------|-------------|
 | `/reset` | Clear session |
 | `/stop` | Abort current task |
-| `/status` | Session info (includes current model) |
+| `/status` | Session info (current model + pending deferred message) |
+| `/<N> <message>` | Queue `<message>` to fire **N minutes** from now (one slot per chat, max 7 days) |
+| `/0` | Drop the chat's pending deferred message (no ID needed; numeric namespace, zero collision) |
 | `/goal <condition>` | Set a goal the agent keeps pursuing across turns. `/goal clear` to stop |
 | `/model` | Show current engine/model; `/model list` — available engines/models; `/model claude`, `/model kimi`, or `/model codex` — switch engine; `/model <name>` — set model; `/model reset` — restore default |
 | `/memory list` | Browse knowledge tree |
diff --git a/src/bridge/command-handler.ts b/src/bridge/command-handler.ts
@@ -7,9 +7,13 @@ import type { EngineName } from '../engines/index.js';
 import { MemoryClient } from '../memory/memory-client.js';
 import { AuditLogger } from '../utils/audit-logger.js';
 import type { DocSync } from '../sync/doc-sync.js';
+import type { TaskScheduler } from '../scheduler/task-scheduler.js';
+
+const MAX_DEFER_MINUTES = 7 * 24 * 60; // 7 days — beyond this use `mb schedule cron`
 
 export class CommandHandler {
   private docSync: DocSync | null = null;
+  private scheduler: TaskScheduler | null = null;
 
   constructor(
     private config: BotConfigBase,
@@ -42,6 +46,14 @@ export class CommandHandler {
     this.docSync = docSync;
   }
 
+  /** Inject the task scheduler used by `/<N>` and `/0` (cancel). Until this
+   *  is called, those commands report a clear "scheduler unavailable" notice
+   *  instead of crashing — keeps unit tests and bots without a registered
+   *  scheduler working. */
+  setScheduler(scheduler: TaskScheduler): void {
+    this.scheduler = scheduler;
+  }
+
   /** Returns true if the message was handled as a command, false otherwise. */
   async handle(msg: IncomingMessage): Promise<boolean> {
     const { text } = msg;
@@ -50,6 +62,27 @@ export class CommandHandler {
     const { userId, chatId } = msg;
     const [cmd] = text.split(/\s+/);
 
+    // Defer-send lives entirely in the numeric `/<digits>` namespace so it
+    // can never collide with a word command:
+    //   `/<N> <message>` — queue the message to run N minutes from now.
+    //   `/0`             — cancel the chat's pending deferred message.
+    // Per-chat single-slot — a second `/<N>` while one is pending is
+    // rejected with the existing entry's details (use `/0` to drop it).
+    // Match the WHOLE command token to avoid colliding with other commands
+    // that happen to start with a digit later (currently none).
+    const deferMatch = cmd.match(/^\/(\d+)$/);
+    if (deferMatch) {
+      this.audit.log({ event: 'command', botName: this.config.name, chatId, userId, prompt: cmd });
+      const minutes = Number(deferMatch[1]);
+      if (minutes === 0) {
+        await this.handleCancelDeferred(chatId);
+        return true;
+      }
+      const prompt = text.slice(cmd.length).trim();
+      await this.handleDeferredSend(chatId, userId, minutes, prompt);
+      return true;
+    }
+
     this.audit.log({ event: 'command', botName: this.config.name, chatId, userId, prompt: cmd });
 
     switch (cmd.toLowerCase()) {
@@ -65,6 +98,10 @@ export class CommandHandler {
           '`/memory` - Memory document commands',
           '`/help` - Show this help message',
           '',
+          '**Deferred Send** (one slot per chat — execute, then queue the next):',
+          '`/<N> <message>` - Queue `<message>` to run **N minutes** from now (e.g. `/60 写个总结`)',
+          '`/0` - Cancel the pending deferred message (no ID needed — only one slot)',
+          '',
           '**Agent Commands** (pass through to the agent — Claude only):',
           '`/goal <description>` - Set a goal the agent keeps pursuing across turns',
           '`/background <prompt>` - Run a task in the background while you continue chatting',
@@ -133,13 +170,15 @@ export class CommandHandler {
         const activeEngine = session.engine ?? botEngine;
         const defaultModel = this.defaultModelForEngine(activeEngine) || '_default_';
         const activeModel = session.model || defaultModel;
+        const deferredLine = this.formatDeferredStatusLine(chatId);
         await this.sender.sendTextNotice(chatId, '📊 Status', [
           `**User:** \`${userId}\``,
           `**Engine:** \`${activeEngine}\`${session.engine ? ' (session override)' : ''}`,
           `**Working Directory:** \`${session.workingDirectory}\``,
           `**Session:** ${session.sessionId ? `\`${session.sessionId.slice(0, 8)}...\`` : '_None_'}`,
           `**Model:** \`${activeModel}\`${session.model ? ' (session override)' : ''}`,
           `**Running:** ${isRunning ? 'Yes ⏳' : 'No'}`,
+          `**Deferred:** ${deferredLine}`,
         ].join('\n'));
         return true;
       }
@@ -431,6 +470,149 @@ export class CommandHandler {
     }
   }
 
+  /** Handle `/<N> <message>` — queue the message N minutes from now. */
+  private async handleDeferredSend(
+    chatId: string,
+    _userId: string,
+    minutes: number,
+    prompt: string,
+  ): Promise<void> {
+    if (!this.scheduler) {
+      await this.sender.sendTextNotice(
+        chatId,
+        '❌ Defer Unavailable',
+        'The scheduler is not wired up for this bot — `/defer` cannot be used here.',
+        'red',
+      );
+      return;
+    }
+
+    if (!Number.isFinite(minutes) || minutes <= 0) {
+      await this.sender.sendTextNotice(
+        chatId,
+        '❌ Invalid Delay',
+        'The delay (in minutes) must be a positive integer. Example: `/60 写个总结`.',
+        'red',
+      );
+      return;
+    }
+
+    if (minutes > MAX_DEFER_MINUTES) {
+      await this.sender.sendTextNotice(
+        chatId,
+        '❌ Delay Too Long',
+        `Maximum defer is **${MAX_DEFER_MINUTES} minutes** (7 days). For longer schedules use the recurring scheduler API.`,
+        'red',
+      );
+      return;
+    }
+
+    if (!prompt) {
+      await this.sender.sendTextNotice(
+        chatId,
+        '❌ Missing Message',
+        `Usage: \`/${minutes} <message>\` — the message to send ${minutes} minutes from now.`,
+        'red',
+      );
+      return;
+    }
+
+    // Per-chat single-slot — refuse a second `/<N>` while one is pending.
+    const existing = this.scheduler.getChatTask(this.config.name, chatId);
+    if (existing) {
+      const remaining = Math.max(0, Math.round((existing.executeAt - Date.now()) / 60_000));
+      await this.sender.sendTextNotice(
+        chatId,
+        '⛔ Deferred Slot Taken',
+        [
+          `This chat already has a pending deferred message (one slot per chat).`,
+          `**Fires in:** ~${remaining} min`,
+          `**Message:** ${truncatePrompt(existing.prompt)}`,
+          '',
+          'Use `/0` to drop it, then queue a new one.',
+        ].join('\n'),
+        'orange',
+      );
+      return;
+    }
+
+    const task = this.scheduler.scheduleTask({
+      botName: this.config.name,
+      chatId,
+      prompt,
+      delaySeconds: minutes * 60,
+      sendCards: true,
+      label: 'slash-defer',
+    });
+
+    const fireAt = new Date(task.executeAt).toLocaleString('zh-CN', { hour12: false });
+    await this.sender.sendTextNotice(
+      chatId,
+      '⏱ Deferred Queued',
+      [
+        `Will run in **${minutes} min** (≈ ${fireAt}).`,
+        `**Message:** ${truncatePrompt(prompt)}`,
+        '',
+        'Use `/0` to drop it, or `/status` to inspect.',
+      ].join('\n'),
+      'green',
+    );
+  }
+
+  /** Handle `/0` — drop the chat's pending deferred message. */
+  private async handleCancelDeferred(chatId: string): Promise<void> {
+    if (!this.scheduler) {
+      await this.sender.sendTextNotice(
+        chatId,
+        '❌ Defer Unavailable',
+        'The scheduler is not wired up for this bot — nothing to cancel.',
+        'red',
+      );
+      return;
+    }
+
+    const existing = this.scheduler.getChatTask(this.config.name, chatId);
+    if (!existing) {
+      // No-op fallback: `/0` with nothing queued is harmless — just a
+      // gentle reminder, never an error.
+      await this.sender.sendTextNotice(
+        chatId,
+        'ℹ️ Nothing to Cancel',
+        'No deferred message is pending in this chat — nothing to do. Use `/<N> <message>` to queue one (e.g. `/60 写个总结`).',
+        'blue',
+      );
+      return;
+    }
+
+    const ok = this.scheduler.cancelTask(existing.id);
+    if (!ok) {
+      // Race: the task fired between getChatTask() and cancelTask().
+      await this.sender.sendTextNotice(
+        chatId,
+        'ℹ️ Already Fired',
+        'The deferred message already started — nothing to cancel.',
+        'blue',
+      );
+      return;
+    }
+
+    await this.sender.sendTextNotice(
+      chatId,
+      '🗑 Deferred Cancelled',
+      `Dropped: ${truncatePrompt(existing.prompt)}`,
+      'green',
+    );
+  }
+
+  /** Build the `/status` "Deferred" line — minutes remaining + preview, or `_None_`. */
+  private formatDeferredStatusLine(chatId: string): string {
+    if (!this.scheduler) return '_n/a_';
+    const task = this.scheduler.getChatTask(this.config.name, chatId);
+    if (!task) return '_None_';
+    const remaining = Math.max(0, Math.round((task.executeAt - Date.now()) / 60_000));
+    return `~${remaining} min — ${truncatePrompt(task.prompt)}`;
+  }
+
   private authTipForEngine(engine: EngineName): string {
     switch (engine) {
       case 'claude':
@@ -446,3 +628,9 @@ export class CommandHandler {
 function isEngineName(value: string): value is EngineName {
   return value === 'claude' || value === 'kimi' || value === 'codex';
 }
+
+/** Trim a queued prompt to a single-line preview suitable for status / notice cards. */
+function truncatePrompt(prompt: string, max = 60): string {
+  const oneLine = prompt.replace(/\s+/g, ' ').trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}
diff --git a/src/bridge/message-bridge.ts b/src/bridge/message-bridge.ts
@@ -25,6 +25,7 @@ import { OutputHandler } from './output-handler.js';
 import { CostTracker } from '../utils/cost-tracker.js';
 import { metrics } from '../utils/metrics.js';
 import type { SessionRegistry } from '../session/session-registry.js';
+import type { TaskScheduler } from '../scheduler/task-scheduler.js';
 
 const TASK_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24 hours
 const QUESTION_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes for user to answer
@@ -353,6 +354,14 @@ export class MessageBridge {
     this.sessionRegistry = registry;
   }
 
+  /** Inject the task scheduler so the slash-command layer can queue
+   *  per-chat deferred sends (`/<N>` / `/0`). The scheduler is a
+   *  process-singleton built in index.ts after every bot is registered,
+   *  hence setter injection (mirrors {@link setSessionRegistry}). */
+  setScheduler(scheduler: TaskScheduler): void {
+    this.commandHandler.setScheduler(scheduler);
+  }
+
   /** Expose session manager for cross-platform session linking. */
   getSessionManager(): SessionManager {
     return this.sessionManager;
diff --git a/src/index.ts b/src/index.ts
@@ -262,10 +262,16 @@ async function main() {
 
   // Initialize cross-platform session registry
   const sessionRegistry = new SessionRegistry(logger);
-  // Inject into all bot bridges
+  // Inject session registry + scheduler into all bot bridges so the
+  // slash-command layer (`/<N>`, `/0`) can queue per-chat deferred
+  // sends. Setter injection, because both objects are process-singletons
+  // built after the bot registry is populated.
   for (const info of registry.list()) {
     const bot = registry.get(info.name);
-    if (bot) bot.bridge.setSessionRegistry(sessionRegistry);
+    if (bot) {
+      bot.bridge.setSessionRegistry(sessionRegistry);
+      bot.bridge.setScheduler(scheduler);
+    }
   }
 
   // Resolve bots config path for API-driven bot CRUD
diff --git a/src/scheduler/task-scheduler.ts b/src/scheduler/task-scheduler.ts
@@ -185,6 +185,28 @@ export class TaskScheduler {
     return this.listTasks().length;
   }
 
+  /**
+   * Look up the most recently created pending one-shot task for a given
+   * bot+chat. Returns undefined if none. Drives the slash-command
+   * defer-send flow (`/<N>` and `/0`), which enforces a per-chat
+   * single-slot rule: a second `/<N>` rejects with the existing entry's
+   * details, and `/0` drops it without needing an ID.
+   *
+   * HTTP/CLI callers can still create multiple pending tasks per chat —
+   * this helper just exposes "which one would the slash UI surface?" and
+   * makes the latest visible to that UI.
+   */
+  getChatTask(botName: string, chatId: string): ScheduledTask | undefined {
+    let latest: ScheduledTask | undefined;
+    for (const t of this.tasks.values()) {
+      if (t.status !== 'pending') continue;
+      if (t.botName !== botName) continue;
+      if (t.chatId !== chatId) continue;
+      if (!latest || t.createdAt > latest.createdAt) latest = t;
+    }
+    return latest;
+  }
+
   // ===== Recurring task methods =====
 
   scheduleRecurring(input: RecurringScheduleInput): RecurringTask {
diff --git a/tests/command-handler-deferred.test.ts b/tests/command-handler-deferred.test.ts
diff --git a/tests/command-handler-help.test.ts b/tests/command-handler-help.test.ts
