mercury-agent 0.4.16 → 0.4.18

package/README.md

@@ -293,21 +293,6 @@ export default function(mercury) {
 
 Extensions with CLIs get auto-installed into a derived Docker image. Skills are symlinked for agent discovery. Permissions integrate with the existing RBAC system.
 
-### Official Extensions
-
-Install curated extensions from the [`@mercuryai`](https://github.com/Michaelliv/mercury-extensions) scope:
-
-```bash
-mercury add @mercuryai/knowledge        # Obsidian-based knowledge vault with KB distillation
-mercury add @mercuryai/web-browser      # Web browsing via Playwright/Chromium
-mercury add @mercuryai/charts           # Chart generation
-mercury add @mercuryai/github           # GitHub CLI integration
-mercury add @mercuryai/google-workspace # Google Workspace (Gmail, Calendar, Drive)
-mercury add @mercuryai/pdf-tools        # PDF processing, OCR, and form filling
-```
-
-See [mercury-extensions](https://github.com/Michaelliv/mercury-extensions) for the full list and documentation.
-
 See [docs/extensions.md](docs/extensions.md) for the extension system guide.
 
 ---
@@ -370,7 +355,7 @@ Supported OAuth providers: Anthropic, GitHub Copilot, Google Gemini CLI, Antigra
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `MERCURY_AGENT_CONTAINER_IMAGE` | `mercury-agent:latest` | Container image |
+| `MERCURY_AGENT_CONTAINER_IMAGE` | `ghcr.io/avishai-tsabari/mercury-agent:latest` | Container image |
 | `MERCURY_CONTAINER_TIMEOUT_MS` | `300000` | Container timeout (5 min) |
 
 **KB Distillation:**

package/docs/rate-limiting.md

@@ -11,15 +11,19 @@ Message received
   │
   ├─► Type = "assistant"?
   │     │
-  │     ├─► Check rate limit
-  │     │     • Key: spaceId:userId
-  │     │     • Count requests in sliding window
-  │     │     • Compare against effective limit
+  │     ├─► Daily role check (if rate_limit.<role> key set and > 0)
+  │     │     • SQLite counter (space_id + user_id + UTC date)
+  │     │     • Denied: "You've used N/M messages today. Resets in Xh."
   │     │
-  │     ├─► Under limit → record request → continue
-  │     └─► Over limit → return "Rate limit exceeded"
+  │     ├─► Burst check (sliding window, always runs)
+  │     │     • In-memory, key: spaceId:userId
+  │     │     • Count requests in 60s window
+  │     │     • Denied: "Rate limit exceeded. Try again shortly."
+  │     │
+  │     ├─► Both pass → continue to container
+  │     └─► Either fails → return denial
   │
-  └─► Type = "command" / "ignore" → bypass rate limit
+  └─► Type = "command" / "ignore" → bypass rate limits
 ```
 
 Commands like `stop` and `compact` bypass rate limiting so users can always abort runaway containers.
@@ -160,6 +164,65 @@ The system prompt instructs the agent to:
 
 Mutes are per-space and expire automatically after the specified duration.
 
+## Role-Based Daily Limits
+
+In addition to the burst limiter, spaces can set per-role daily message caps. This gives agent owners cost control — admins get unlimited access to their own bot while capping how much others can use it.
+
+### Configuration
+
+Set `rate_limit.<role>` keys via `mrctl` or the API:
+
+```bash
+# Admins: unlimited (0 = no daily limit)
+mrctl config set rate_limit.admin 0
+
+# Members: 5 messages per day
+mrctl config set rate_limit.member 5
+```
+
+Via API:
+```bash
+curl -X PUT http://localhost:8787/api/config \
+  -H "X-Mercury-Space: slack:C123" \
+  -H "X-Mercury-Caller: slack:U456" \
+  -H "Content-Type: application/json" \
+  -d '{"key": "rate_limit.member", "value": "5"}'
+```
+
+### Behavior
+
+| Value | Effect |
+|-------|--------|
+| `0` | Unlimited (daily check skipped for this role) |
+| `> 0` | Daily cap enforced; denied requests show count + reset time |
+| Not set | No daily limit for this role (burst limiter still applies) |
+| Invalid (NaN) | Treated as "not set" |
+
+### How the two layers interact
+
+```
+Message arrives (type = "assistant")
+  │
+  ├─► Daily role check (if rate_limit.<role> key exists and > 0)
+  │     • Key: space_id + user_id + UTC date
+  │     • SQLite counter (persists across restarts)
+  │     • Denied: "You've used 5/5 messages today. Resets in 3h."
+  │
+  └─► Burst check (sliding window, always runs for all users)
+        • In-memory timestamps
+        • Denied: "Rate limit exceeded. Try again shortly."
+```
+
+Both layers are independent — both must pass. A user can be allowed by the daily check but blocked by the burst limiter, or vice versa. Denied requests do not increment the daily counter.
+
+### Special cases
+
+- **System callers** (scheduled tasks): exempt from daily limits unconditionally
+- **Commands** (`stop`, `compact`, etc.): bypass both layers
+- **Custom roles**: set `rate_limit.<custom_role>` for any role name
+- **Daily reset**: counters reset at UTC midnight
+- **Counters are per-space**: each space tracks independently
+
 ## See Also
 
 - [pipeline.md](./pipeline.md) — Message flow and routing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/src/cli/mercury.ts

@@ -4,7 +4,6 @@ import { spawn, spawnSync } from "node:child_process";
 import {
   chmodSync,
   copyFileSync,
-  cpSync,
   existsSync,
   mkdirSync,
   readdirSync,
@@ -814,7 +813,7 @@ program
         if (existsSync(profileExtDir)) {
           const userExtDir = join(CWD, ".mercury/extensions");
           mkdirSync(userExtDir, { recursive: true });
-          cpSync(profileExtDir, userExtDir, { recursive: true });
+          copyDirRecursive(profileExtDir, userExtDir);
         }
       }
     }
@@ -2112,7 +2111,7 @@ profilesCommand
     // Copy extensions
     const userExtDir = join(CWD, ".mercury/extensions");
     if (existsSync(userExtDir)) {
-      cpSync(userExtDir, join(absOutput, "extensions"), { recursive: true });
+      copyDirRecursive(userExtDir, join(absOutput, "extensions"));
     }
 
     // Generate manifest

package/src/core/commands.ts

@@ -1,76 +1,110 @@
-export interface CommandVerb {
-  verb: string;
-  args?: string; // e.g. "<N|MODEL_ID>"
-  description: string;
-}
-
-export interface CommandEntry {
-  name: string; // e.g. "model", "help"
-  description: string; // one-liner shown in /help
-  verbs?: CommandVerb[]; // defined ⟹ category; absent ⟹ leaf command
-}
-
-// Slash-command registry — source of truth for /help and router recognition.
-// Add new categories here; router + executeCommand both derive from this list.
-export const SLASH_COMMANDS: CommandEntry[] = [
-  {
-    name: "help",
-    description: "list all available commands",
-  },
-  {
-    name: "model",
-    description: "list, switch, and inspect your AI models",
-    verbs: [
-      { verb: "list", description: "list your configured models" },
-      { verb: "active", description: "show the active model" },
-      {
-        verb: "switch",
-        args: "<N|MODEL_ID>",
-        description: "switch by number or model ID",
-      },
-    ],
-  },
-];
-
-// Legacy bare commands — still work without a slash; shown in /help for discoverability.
-export const BARE_COMMANDS: Array<{ name: string; description: string }> = [
-  {
-    name: "stop",
-    description: "abort the current agent run and queued requests",
-  },
-  { name: "compact", description: "reset the session context window" },
-  { name: "clear", description: "clear context for this message" },
-];
-
-// Generates the /help response listing all commands.
-export function formatHelp(): string {
-  const lines: string[] = ["Available commands:", ""];
-
-  for (const cmd of SLASH_COMMANDS) {
-    lines.push(`  /${cmd.name.padEnd(12)}  ${cmd.description}`);
-  }
-
-  lines.push("", "Bare commands (no slash needed):");
-  for (const cmd of BARE_COMMANDS) {
-    lines.push(`  ${cmd.name.padEnd(12)}  ${cmd.description}`);
-  }
-
-  lines.push("", "Type /<category> to see detailed help for that category.");
-  return lines.join("\n");
-}
-
-// Generates the /<category> no-verb response.
-// Returns null if name is not in the registry or the command has no verbs.
-export function formatCategoryHelp(name: string): string | null {
-  const entry = SLASH_COMMANDS.find((c) => c.name === name);
-  if (!entry?.verbs || entry.verbs.length === 0) return null;
-
-  const lines: string[] = [`/${name} — ${entry.description}`, ""];
-  for (const v of entry.verbs) {
-    const usage = v.args
-      ? `/${name} ${v.verb} ${v.args}`
-      : `/${name} ${v.verb}`;
-    lines.push(`  ${usage.padEnd(28)}  ${v.description}`);
-  }
-  return lines.join("\n");
-}
+export interface CommandVerb {
+  verb: string;
+  args?: string; // e.g. "<N|MODEL_ID>"
+  description: string;
+}
+
+export interface CommandEntry {
+  name: string; // e.g. "model", "help"
+  description: string; // one-liner shown in /help
+  verbs?: CommandVerb[]; // defined ⟹ category; absent ⟹ leaf command
+}
+
+// Slash-command registry — source of truth for /help and router recognition.
+// Add new categories here; router + executeCommand both derive from this list.
+export const SLASH_COMMANDS: CommandEntry[] = [
+  {
+    name: "help",
+    description: "list all available commands",
+  },
+  {
+    name: "model",
+    description: "list, switch, and inspect your AI models",
+    verbs: [
+      { verb: "list", description: "list your configured models" },
+      { verb: "active", description: "show the active model" },
+      {
+        verb: "switch",
+        args: "<N|MODEL_ID>",
+        description: "switch by number or model ID",
+      },
+    ],
+  },
+  {
+    name: "spaces",
+    description: "create, list, switch, and delete spaces",
+    verbs: [
+      { verb: "list", description: "list all spaces with conversation counts" },
+      {
+        verb: "create",
+        args: "<id> <name>",
+        description: "create a new space",
+      },
+      {
+        verb: "switch",
+        args: "<id>",
+        description: "switch this conversation to a different space",
+      },
+      {
+        verb: "delete",
+        args: "<id>",
+        description: "delete a space (requires confirmation)",
+      },
+      {
+        verb: "unlink",
+        description: "unlink this conversation from its space",
+      },
+    ],
+  },
+  {
+    name: "pause",
+    description: "pause the bot in this space (optional: /pause <duration>)",
+  },
+  {
+    name: "resume",
+    description: "resume the bot in this space",
+  },
+];
+
+// Legacy bare commands — still work without a slash; shown in /help for discoverability.
+export const BARE_COMMANDS: Array<{ name: string; description: string }> = [
+  {
+    name: "stop",
+    description: "abort the current agent run and queued requests",
+  },
+  { name: "compact", description: "reset the session context window" },
+  { name: "clear", description: "clear context for this message" },
+];
+
+// Generates the /help response listing all commands.
+export function formatHelp(): string {
+  const lines: string[] = ["Available commands:", ""];
+
+  for (const cmd of SLASH_COMMANDS) {
+    lines.push(`  /${cmd.name.padEnd(12)}  ${cmd.description}`);
+  }
+
+  lines.push("", "Bare commands (no slash needed):");
+  for (const cmd of BARE_COMMANDS) {
+    lines.push(`  ${cmd.name.padEnd(12)}  ${cmd.description}`);
+  }
+
+  lines.push("", "Type /<category> to see detailed help for that category.");
+  return lines.join("\n");
+}
+
+// Generates the /<category> no-verb response.
+// Returns null if name is not in the registry or the command has no verbs.
+export function formatCategoryHelp(name: string): string | null {
+  const entry = SLASH_COMMANDS.find((c) => c.name === name);
+  if (!entry?.verbs || entry.verbs.length === 0) return null;
+
+  const lines: string[] = [`/${name} — ${entry.description}`, ""];
+  for (const v of entry.verbs) {
+    const usage = v.args
+      ? `/${name} ${v.verb} ${v.args}`
+      : `/${name} ${v.verb}`;
+    lines.push(`  ${usage.padEnd(28)}  ${v.description}`);
+  }
+  return lines.join("\n");
+}

package/src/core/router.ts

@@ -25,6 +25,8 @@ export type RouteResult =
   | { type: "denied"; reason: string }
   | { type: "ignore" };
 
+const SEEDED_ADMIN_COMMANDS = new Set(["spaces"]);
+
 /**
  * Chat-level commands that bypass the LLM.
  * Mapped to the permission required to execute them.
@@ -115,6 +117,7 @@ export function routeInput(input: {
         role,
         input.callerId,
         input.isDM,
+        seededAdmins,
         verb,
         arg,
       );
@@ -152,9 +155,19 @@ function gateSlashCommand(
   role: string,
   callerId: string,
   isDM: boolean,
+  seededAdmins: string[],
   verb?: string,
   arg?: string,
 ): RouteResult {
+  if (SEEDED_ADMIN_COMMANDS.has(command)) {
+    if (!seededAdmins.includes(callerId)) {
+      return {
+        type: "denied",
+        reason: `You don't have permission to use '/${command}'.`,
+      };
+    }
+    return { type: "command", command, verb, arg, callerId, role };
+  }
   if (!isDM && role !== "admin" && role !== "system") {
     return {
       type: "denied",

package/src/core/routes/dashboard.ts

@@ -1123,10 +1123,12 @@ export function createDashboardRoutes(ctx: DashboardContext) {
       </form>
     `;
 
+    const isPaused = core.db.getSpaceConfig(spaceId, "paused") === "true";
+
     return c.html(html`
       <div class="page-header">
         <a href="#" hx-get="/dashboard/page/spaces" hx-target="#main" hx-push-url="true" class="back">← Back</a>
-        <h2>${escapeHtml(group.name)}</h2>
+        <h2>${escapeHtml(group.name)}${isPaused ? raw(' <span class="badge" style="background:var(--color-warning);color:var(--bg);font-size:11px;vertical-align:middle">⏸ Paused</span>') : ""}</h2>
       </div>
 
       <div class="grid-2">

package/src/core/runtime.ts

@@ -69,6 +69,8 @@ export class MercuryCoreRuntime {
   private extensionCtx: MercuryExtensionContext | null = null;
   private extensionRegistry: ExtensionRegistry | null = null;
   private readonly shutdownHooks: ShutdownHook[] = [];
+  private readonly pauseTimers = new Map<string, NodeJS.Timeout>();
+  private messageSender: MessageSender | undefined;
   private shuttingDown = false;
   private signalHandlersInstalled = false;
 
@@ -272,6 +274,8 @@ export class MercuryCoreRuntime {
   }
 
   startScheduler(sender?: MessageSender): void {
+    this.messageSender = sender;
+    this.restorePauseTimers();
     this.scheduler.start(async (task) => {
       const result = await this.executePrompt(
         task.spaceId,
@@ -316,6 +320,8 @@ export class MercuryCoreRuntime {
 
   stopScheduler(): void {
     this.scheduler.stop();
+    for (const t of this.pauseTimers.values()) clearTimeout(t);
+    this.pauseTimers.clear();
   }
 
   async handleRawInput(
@@ -335,6 +341,34 @@ export class MercuryCoreRuntime {
       authorName: message.authorName,
     });
 
+    const pendingDeleteResult = this.handlePendingSpaceDelete(
+      message.spaceId,
+      message.callerId,
+      message.text.trim().toLowerCase(),
+    );
+    if (pendingDeleteResult) {
+      return {
+        type: "command",
+        command: "spaces",
+        callerId: message.callerId,
+        role:
+          route.type === "command" || route.type === "assistant"
+            ? route.role
+            : "admin",
+        result: { reply: pendingDeleteResult, files: [] },
+      };
+    }
+
+    // Pause guard — drop everything except /pause and /resume when paused
+    if (this.db.getSpaceConfig(message.spaceId, "paused") === "true") {
+      const exempt =
+        route.type === "command" &&
+        (route.command === "pause" || route.command === "resume");
+      if (!exempt) {
+        return { type: "ignore" };
+      }
+    }
+
     if (route.type === "command") {
       const reply = await this.executeCommand(
         message.spaceId,
@@ -342,6 +376,10 @@ export class MercuryCoreRuntime {
         route.callerId,
         route.verb,
         route.arg,
+        {
+          platform: message.platform,
+          externalId: message.conversationExternalId,
+        },
       );
       return { ...route, result: { reply, files: [] } };
     }
@@ -356,7 +394,33 @@ export class MercuryCoreRuntime {
 
     // Check rate limit for assistant requests (not commands, not ignored messages)
     if (route.type === "assistant") {
-      // Check per-group override first
+      // Daily role-based rate check (before burst limiter)
+      if (route.role !== "system") {
+        const roleKey = `rate_limit.${route.role}`;
+        const roleLimitRaw = this.db.getSpaceConfig(message.spaceId, roleKey);
+        if (roleLimitRaw !== null) {
+          const roleLimit = Number.parseInt(roleLimitRaw, 10);
+          if (!Number.isNaN(roleLimit) && roleLimit > 0) {
+            const daily = this.db.checkAndIncrementDailyUsage(
+              message.spaceId,
+              message.callerId,
+              roleLimit,
+            );
+            if (!daily.allowed) {
+              const msUntilReset =
+                new Date().setUTCHours(24, 0, 0, 0) - Date.now();
+              const hoursLeft = Math.ceil(msUntilReset / 3_600_000);
+              return {
+                type: "denied",
+                reason: `You've used ${daily.count}/${roleLimit} messages today. Resets in ${hoursLeft}h.`,
+              };
+            }
+          }
+          // roleLimit === 0 means unlimited — skip daily check
+        }
+      }
+
+      // Burst rate limit (sliding window)
       const groupLimit = this.db.getSpaceConfig(message.spaceId, "rate_limit");
       const effectiveLimit = groupLimit
         ? Number.parseInt(groupLimit, 10)
@@ -486,6 +550,7 @@ export class MercuryCoreRuntime {
     callerId: string,
     verb?: string,
     arg?: string,
+    conversationContext?: { platform: string; externalId: string },
   ): Promise<string> {
     switch (command) {
       case "stop": {
@@ -514,6 +579,18 @@ export class MercuryCoreRuntime {
       }
       case "model":
         return this.executeModelsCommand(spaceId, callerId, verb, arg);
+      case "spaces":
+        return this.executeSpacesCommand(
+          spaceId,
+          callerId,
+          conversationContext,
+          verb,
+          arg,
+        );
+      case "pause":
+        return this.executePauseCommand(spaceId, callerId, verb);
+      case "resume":
+        return this.executeResumeCommand(spaceId, callerId);
       default:
         return `Unknown command: ${command}`;
     }
@@ -593,6 +670,295 @@ export class MercuryCoreRuntime {
     }
   }
 
+  private executeSpacesCommand(
+    spaceId: string,
+    _callerId: string,
+    conversationContext?: { platform: string; externalId: string },
+    verb?: string,
+    arg?: string,
+  ): string {
+    this.clearPendingDelete(spaceId);
+
+    if (!verb) {
+      return formatCategoryHelp("spaces") ?? "/spaces — space management";
+    }
+
+    switch (verb) {
+      case "list": {
+        const spaces = this.db.listSpaces();
+        if (spaces.length === 0) return "No spaces.";
+        const lines = ["Spaces:"];
+        for (const s of spaces) {
+          const convos = this.db.getSpaceConversations(s.id);
+          lines.push(
+            `  ${s.id.padEnd(16)}  ${s.name}  (${convos.length} conversation${convos.length === 1 ? "" : "s"})`,
+          );
+        }
+        return lines.join("\n");
+      }
+
+      case "create": {
+        if (!arg) return "Usage: /spaces create <id> <name>";
+        const firstSpace = arg.indexOf(" ");
+        if (firstSpace === -1) return "Usage: /spaces create <id> <name>";
+        const newId = arg.slice(0, firstSpace);
+        const newName = arg.slice(firstSpace + 1).trim();
+        if (!newName) return "Usage: /spaces create <id> <name>";
+        try {
+          this.db.createSpace(newId, newName);
+        } catch (err) {
+          return err instanceof Error ? err.message : String(err);
+        }
+        return `Created space '${newId}' (${newName}).`;
+      }
+
+      case "switch": {
+        if (!arg) return "Usage: /spaces switch <id>";
+        const targetSpace = this.db.getSpace(arg);
+        if (!targetSpace) return `Space '${arg}' not found.`;
+        if (!conversationContext) {
+          return "Cannot determine current conversation.";
+        }
+        const convo = this.db.findConversation(
+          conversationContext.platform,
+          conversationContext.externalId,
+        );
+        if (!convo) return "Current conversation not found.";
+        if (convo.spaceId === arg) return `Already in space '${arg}'.`;
+        this.db.linkConversation(convo.id, arg);
+        return `Switched to space '${targetSpace.name}' (${arg}).`;
+      }
+
+      case "delete": {
+        if (!arg) return "Usage: /spaces delete <id>";
+        if (arg === "main") return "Cannot delete the default 'main' space.";
+        const target = this.db.getSpace(arg);
+        if (!target) return `Space '${arg}' not found.`;
+        this.db.setSpaceConfig(
+          spaceId,
+          "spaces.pending_delete_id",
+          arg,
+          "system",
+        );
+        this.db.setSpaceConfig(
+          spaceId,
+          "spaces.pending_delete_at",
+          new Date().toISOString(),
+          "system",
+        );
+        const isSelf = spaceId === arg;
+        const warning = isSelf
+          ? "\n⚠️ This will unlink this conversation. You'll need to link it to another space to continue chatting."
+          : "";
+        return `Delete space '${arg}' (${target.name})? This will destroy all messages, tasks, roles, config, and preferences for that space. Reply *yes* to confirm or *no* to cancel.${warning}`;
+      }
+
+      case "unlink": {
+        if (!conversationContext) {
+          return "Cannot determine current conversation.";
+        }
+        const convo = this.db.findConversation(
+          conversationContext.platform,
+          conversationContext.externalId,
+        );
+        if (!convo) return "Current conversation not found.";
+        this.db.unlinkConversation(convo.id);
+        return "Unlinked. Messages in this conversation will be ignored until you link it to a space with /spaces switch.";
+      }
+
+      default:
+        return `/spaces: unknown verb '${verb}'. Use /spaces for help.`;
+    }
+  }
+
+  private handlePendingSpaceDelete(
+    spaceId: string,
+    callerId: string,
+    text: string,
+  ): string | null {
+    const pendingId = this.db.getSpaceConfig(
+      spaceId,
+      "spaces.pending_delete_id",
+    );
+    if (!pendingId) return null;
+
+    const seededAdmins = this.config.admins
+      ? this.config.admins
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+    if (!seededAdmins.includes(callerId)) return null;
+
+    const pendingAt = this.db.getSpaceConfig(
+      spaceId,
+      "spaces.pending_delete_at",
+    );
+    const ageMs = pendingAt
+      ? Date.now() - new Date(pendingAt).getTime()
+      : Number.POSITIVE_INFINITY;
+    const expired = Number.isNaN(ageMs) || ageMs > 60_000;
+
+    this.db.deleteSpaceConfig(spaceId, "spaces.pending_delete_id");
+    this.db.deleteSpaceConfig(spaceId, "spaces.pending_delete_at");
+
+    if (expired) {
+      if (text === "yes") return "Delete cancelled (timed out).";
+      return null;
+    }
+
+    if (text === "no") {
+      return "Delete cancelled.";
+    }
+
+    if (text === "yes") {
+      const target = this.db.getSpace(pendingId);
+      if (!target) return `Space '${pendingId}' not found.`;
+      const result = this.db.deleteSpace(pendingId);
+      if (!result.deleted) return `Failed to delete space '${pendingId}'.`;
+      return `Deleted space '${pendingId}' (${target.name}). Removed: ${result.removed.messages} messages, ${result.removed.tasks} tasks, ${result.removed.conversationsUnlinked} conversations unlinked.`;
+    }
+
+    return null;
+  }
+
+  private clearPendingDelete(spaceId: string): void {
+    this.db.deleteSpaceConfig(spaceId, "spaces.pending_delete_id");
+    this.db.deleteSpaceConfig(spaceId, "spaces.pending_delete_at");
+  }
+
+  private executePauseCommand(
+    spaceId: string,
+    callerId: string,
+    verb?: string,
+  ): string {
+    const alreadyPaused = this.db.getSpaceConfig(spaceId, "paused") === "true";
+    const hadTimer = this.db.getSpaceConfig(spaceId, "paused.resume_at");
+
+    if (verb) {
+      const parsed = this.parsePauseDuration(verb);
+      if (!parsed.ok) return parsed.error;
+
+      this.db.setSpaceConfig(spaceId, "paused", "true", callerId);
+      const resumeAt = Date.now() + parsed.ms;
+      this.db.setSpaceConfig(
+        spaceId,
+        "paused.resume_at",
+        String(resumeAt),
+        callerId,
+      );
+      this.schedulePauseTimer(spaceId, parsed.ms);
+
+      const resumeTime = new Date(resumeAt).toLocaleString("en-US", {
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: true,
+      });
+      return `Bot paused for ${verb}. It will auto-resume at ${resumeTime}.`;
+    }
+
+    if (alreadyPaused && !hadTimer) {
+      return "Already paused.";
+    }
+
+    if (alreadyPaused && hadTimer) {
+      this.clearPauseTimer(spaceId);
+      this.db.deleteSpaceConfig(spaceId, "paused.resume_at");
+      return "Pause is now indefinite (timer cleared). Use /resume to reactivate.";
+    }
+
+    this.db.setSpaceConfig(spaceId, "paused", "true", callerId);
+    return "Bot paused in this space. Use /resume to reactivate.";
+  }
+
+  private executeResumeCommand(spaceId: string, _callerId: string): string {
+    if (this.db.getSpaceConfig(spaceId, "paused") !== "true") {
+      return "Bot is not paused.";
+    }
+    this.clearPauseTimer(spaceId);
+    this.db.deleteSpaceConfig(spaceId, "paused");
+    this.db.deleteSpaceConfig(spaceId, "paused.resume_at");
+    return "Bot resumed.";
+  }
+
+  private parsePauseDuration(
+    input: string,
+  ): { ok: true; ms: number } | { ok: false; error: string } {
+    const match = input.match(/^(\d+)(m|h)$/i);
+    if (!match) {
+      return {
+        ok: false,
+        error: "Invalid duration. Use e.g. /pause 30m or /pause 2h.",
+      };
+    }
+    const value = Number.parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    const ms = unit === "h" ? value * 60 * 60 * 1000 : value * 60 * 1000;
+
+    if (ms < 60_000) {
+      return { ok: false, error: "Duration must be at least 1 minute." };
+    }
+    if (ms > 24 * 60 * 60 * 1000) {
+      return {
+        ok: false,
+        error: "Duration must be at most 24 hours.",
+      };
+    }
+    return { ok: true, ms };
+  }
+
+  private schedulePauseTimer(spaceId: string, delayMs: number): void {
+    this.clearPauseTimer(spaceId);
+    const timer = setTimeout(() => {
+      this.pauseTimers.delete(spaceId);
+      if (this.db.getSpaceConfig(spaceId, "paused") !== "true") return;
+      this.db.deleteSpaceConfig(spaceId, "paused");
+      this.db.deleteSpaceConfig(spaceId, "paused.resume_at");
+      const text = "Bot resumed — pause timer expired.";
+      this.messageSender
+        ?.send(spaceId, text, [])
+        .catch((e) =>
+          logger.warn("Auto-resume notification failed", { spaceId, error: e }),
+        );
+      this.deliverTaskOutput(spaceId, text);
+    }, delayMs);
+    if (timer.unref) timer.unref();
+    this.pauseTimers.set(spaceId, timer);
+  }
+
+  private clearPauseTimer(spaceId: string): void {
+    const existing = this.pauseTimers.get(spaceId);
+    if (existing) {
+      clearTimeout(existing);
+      this.pauseTimers.delete(spaceId);
+    }
+  }
+
+  private restorePauseTimers(): void {
+    for (const space of this.db.listSpaces()) {
+      const resumeAtStr = this.db.getSpaceConfig(space.id, "paused.resume_at");
+      if (!resumeAtStr) continue;
+      const resumeAt = Number.parseInt(resumeAtStr, 10);
+      if (Number.isNaN(resumeAt)) continue;
+
+      const remaining = resumeAt - Date.now();
+      if (remaining <= 0) {
+        this.db.deleteSpaceConfig(space.id, "paused");
+        this.db.deleteSpaceConfig(space.id, "paused.resume_at");
+        const text = "Bot resumed — pause timer expired.";
+        this.messageSender?.send(space.id, text, []).catch((e) =>
+          logger.warn("Auto-resume notification failed", {
+            spaceId: space.id,
+            error: e,
+          }),
+        );
+        this.deliverTaskOutput(space.id, text);
+      } else {
+        this.schedulePauseTimer(space.id, remaining);
+      }
+    }
+  }
+
   onShutdown(hook: ShutdownHook): void {
     this.shutdownHooks.push(hook);
   }
@@ -645,9 +1011,11 @@ export class MercuryCoreRuntime {
     if (forceTimer.unref) forceTimer.unref();
 
     try {
-      // 1. Stop schedulers
+      // 1. Stop schedulers + pause timers
       logger.info("Shutdown: stopping task scheduler");
       this.scheduler.stop();
+      for (const timer of this.pauseTimers.values()) clearTimeout(timer);
+      this.pauseTimers.clear();
 
       // 2. Drain queue — cancel pending, wait for active
       logger.info("Shutdown: draining group queue");

package/src/storage/db.ts

@@ -197,6 +197,15 @@ export class Db {
 
       CREATE INDEX IF NOT EXISTS idx_mpi_mercury_id
       ON message_platform_ids(mercury_message_id);
+
+      CREATE TABLE IF NOT EXISTS daily_rate_usage (
+        space_id TEXT NOT NULL,
+        platform_user_id TEXT NOT NULL,
+        date TEXT NOT NULL,
+        count INTEGER NOT NULL DEFAULT 0,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (space_id, platform_user_id, date)
+      );
     `);
     this.ensureMessagesRunMetaColumn();
     this.ensureChatStateClearBoundaryColumn();
@@ -385,6 +394,7 @@ export class Db {
       config: number;
       preferences: number;
       tokenUsage: number;
+      dailyRateUsage: number;
       conversationsUnlinked: number;
     };
   } {
@@ -395,6 +405,12 @@ export class Db {
           "DELETE FROM message_platform_ids WHERE mercury_message_id IN (SELECT id FROM messages WHERE space_id = ?)",
         )
         .run(spaceId);
+      this.db
+        .query("DELETE FROM extension_state WHERE space_id = ?")
+        .run(spaceId);
+      const dailyRateUsage = this.db
+        .query("DELETE FROM daily_rate_usage WHERE space_id = ?")
+        .run(spaceId).changes;
       const messages = this.db
         .query("DELETE FROM messages WHERE space_id = ?")
         .run(spaceId).changes;
@@ -436,6 +452,7 @@ export class Db {
           config,
           preferences,
           tokenUsage,
+          dailyRateUsage,
           conversationsUnlinked: Number(conversationsUnlinked?.count ?? 0),
         },
       };
@@ -1522,6 +1539,51 @@ export class Db {
     }));
   }
 
+  // ─── Daily Rate Usage ─────────────────────────────────────────────────
+
+  checkAndIncrementDailyUsage(
+    spaceId: string,
+    userId: string,
+    limit: number,
+  ): { allowed: boolean; count: number } {
+    const today = new Date().toISOString().slice(0, 10);
+    const now = Date.now();
+
+    this.db
+      .query(
+        "DELETE FROM daily_rate_usage WHERE space_id = ? AND platform_user_id = ? AND date < ?",
+      )
+      .run(spaceId, userId, today);
+
+    // Atomic: insert with count=1 if no row exists, or increment only if under limit.
+    const result = this.db
+      .query(
+        `INSERT INTO daily_rate_usage (space_id, platform_user_id, date, count, updated_at)
+         VALUES (?, ?, ?, 1, ?)
+         ON CONFLICT(space_id, platform_user_id, date)
+         DO UPDATE SET count = count + 1, updated_at = excluded.updated_at
+         WHERE count < ?`,
+      )
+      .run(spaceId, userId, today, now, limit);
+
+    if (result.changes > 0) {
+      const row = this.db
+        .query(
+          "SELECT count FROM daily_rate_usage WHERE space_id = ? AND platform_user_id = ? AND date = ?",
+        )
+        .get(spaceId, userId, today) as { count: number };
+      return { allowed: true, count: row.count };
+    }
+
+    // No changes = either at limit or above
+    const row = this.db
+      .query(
+        "SELECT count FROM daily_rate_usage WHERE space_id = ? AND platform_user_id = ? AND date = ?",
+      )
+      .get(spaceId, userId, today) as { count: number } | null;
+    return { allowed: false, count: row?.count ?? 0 };
+  }
+
   // ─── Token Usage ──────────────────────────────────────────────────────
 
   recordUsage(spaceId: string, usage: TokenUsage): void {