feat: add plugin command API for LLM-free auto-reply commands

This adds a new `api.registerCommand()` method to the plugin API, allowing
plugins to register slash commands that execute without invoking the AI agent.

Features:
- Plugin commands are processed before built-in commands and the agent
- Commands can optionally require authorization
- Commands can accept arguments
- Async handlers are supported

Use case: plugins can implement toggle commands (like /tts_on, /tts_off)
that respond immediately without consuming LLM API calls.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/plugins/commands.ts

@@ -0,0 +1,151 @@
+/**
+ * Plugin Command Registry
+ *
+ * Manages commands registered by plugins that bypass the LLM agent.
+ * These commands are processed before built-in commands and before agent invocation.
+ */
+
+import type { ClawdbotConfig } from "../config/config.js";
+import type { ClawdbotPluginCommandDefinition, PluginCommandContext } from "./types.js";
+import { logVerbose } from "../globals.js";
+
+type RegisteredPluginCommand = ClawdbotPluginCommandDefinition & {
+  pluginId: string;
+};
+
+// Registry of plugin commands
+const pluginCommands: Map<string, RegisteredPluginCommand> = new Map();
+
+/**
+ * Register a plugin command.
+ */
+export function registerPluginCommand(
+  pluginId: string,
+  command: ClawdbotPluginCommandDefinition,
+): void {
+  const key = `/${command.name.toLowerCase()}`;
+  if (pluginCommands.has(key)) {
+    logVerbose(
+      `Plugin command ${key} already registered, overwriting with plugin ${pluginId}`,
+    );
+  }
+  pluginCommands.set(key, { ...command, pluginId });
+  logVerbose(`Registered plugin command: ${key} (plugin: ${pluginId})`);
+}
+
+/**
+ * Clear all registered plugin commands.
+ * Called during plugin reload.
+ */
+export function clearPluginCommands(): void {
+  pluginCommands.clear();
+}
+
+/**
+ * Clear plugin commands for a specific plugin.
+ */
+export function clearPluginCommandsForPlugin(pluginId: string): void {
+  for (const [key, cmd] of pluginCommands.entries()) {
+    if (cmd.pluginId === pluginId) {
+      pluginCommands.delete(key);
+    }
+  }
+}
+
+/**
+ * Check if a command body matches a registered plugin command.
+ * Returns the command definition and parsed args if matched.
+ */
+export function matchPluginCommand(
+  commandBody: string,
+): { command: RegisteredPluginCommand; args?: string } | null {
+  const trimmed = commandBody.trim();
+  if (!trimmed.startsWith("/")) return null;
+
+  // Extract command name and args
+  const spaceIndex = trimmed.indexOf(" ");
+  const commandName = spaceIndex === -1 ? trimmed : trimmed.slice(0, spaceIndex);
+  const args = spaceIndex === -1 ? undefined : trimmed.slice(spaceIndex + 1).trim();
+
+  const key = commandName.toLowerCase();
+  const command = pluginCommands.get(key);
+
+  if (!command) return null;
+
+  // If command doesn't accept args but args were provided, don't match
+  if (args && !command.acceptsArgs) return null;
+
+  return { command, args: args || undefined };
+}
+
+/**
+ * Execute a plugin command handler.
+ */
+export async function executePluginCommand(params: {
+  command: RegisteredPluginCommand;
+  args?: string;
+  senderId?: string;
+  channel: string;
+  isAuthorizedSender: boolean;
+  commandBody: string;
+  config: ClawdbotConfig;
+}): Promise<{ text: string } | null> {
+  const { command, args, senderId, channel, isAuthorizedSender, commandBody, config } =
+    params;
+
+  // Check authorization
+  const requireAuth = command.requireAuth !== false; // Default to true
+  if (requireAuth && !isAuthorizedSender) {
+    logVerbose(
+      `Plugin command /${command.name} blocked: unauthorized sender ${senderId || "<unknown>"}`,
+    );
+    return null; // Silently ignore unauthorized commands
+  }
+
+  const ctx: PluginCommandContext = {
+    senderId,
+    channel,
+    isAuthorizedSender,
+    args,
+    commandBody,
+    config,
+  };
+
+  try {
+    const result = await command.handler(ctx);
+    return { text: result.text };
+  } catch (err) {
+    const error = err as Error;
+    logVerbose(`Plugin command /${command.name} error: ${error.message}`);
+    return { text: `⚠️ Command failed: ${error.message}` };
+  }
+}
+
+/**
+ * List all registered plugin commands.
+ * Used for /help and /commands output.
+ */
+export function listPluginCommands(): Array<{
+  name: string;
+  description: string;
+  pluginId: string;
+}> {
+  return Array.from(pluginCommands.values()).map((cmd) => ({
+    name: cmd.name,
+    description: cmd.description,
+    pluginId: cmd.pluginId,
+  }));
+}
+
+/**
+ * Get plugin command specs for native command registration (e.g., Telegram).
+ */
+export function getPluginCommandSpecs(): Array<{
+  name: string;
+  description: string;
+}> {
+  return Array.from(pluginCommands.values()).map((cmd) => ({
+    name: cmd.name,
+    description: cmd.description,
+  }));
+}