openclaw/src/plugins/commands.ts

/**
 * 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 { parseDiscordTarget } from "../../extensions/discord/src/targets.js";
import { parseTelegramTarget } from "../../extensions/telegram/src/targets.js";
import { isRenderablePayload } from "../auto-reply/reply/reply-payloads.js";
import type { ReplyPayload } from "../auto-reply/types.js";
import type { OpenClawConfig } from "../config/config.js";
import { logVerbose } from "../globals.js";
import {
  detachPluginConversationBinding,
  getCurrentPluginConversationBinding,
  requestPluginConversationBinding,
} from "./conversation-binding.js";
import type {
  OpenClawPluginCommandDefinition,
  PluginCommandContext,
  PluginCommandResult,
} from "./types.js";

type RegisteredPluginCommand = OpenClawPluginCommandDefinition & {
  pluginId: string;
  pluginName?: string;
  pluginRoot?: string;
};

// Registry of plugin commands
const pluginCommands: Map<string, RegisteredPluginCommand> = new Map();

// Lock to prevent modifications during command execution
let registryLocked = false;

// Maximum allowed length for command arguments (defense in depth)
const MAX_ARGS_LENGTH = 4096;
const SAFE_COMMAND_FAILURE_REPLY: PluginCommandResult = {
  text: "⚠️ Command failed. Please try again later.",
  isError: true,
};

/**
 * Reserved command names that plugins cannot override.
 * These are built-in commands from commands-registry.data.ts.
 */
const RESERVED_COMMANDS = new Set([
  // Core commands
  "help",
  "commands",
  "status",
  "whoami",
  "context",
  "btw",
  // Session management
  "stop",
  "restart",
  "reset",
  "new",
  "compact",
  // Configuration
  "config",
  "debug",
  "allowlist",
  "activation",
  // Agent control
  "skill",
  "subagents",
  "kill",
  "steer",
  "tell",
  "model",
  "models",
  "queue",
  // Messaging
  "send",
  // Execution
  "bash",
  "exec",
  // Mode toggles
  "think",
  "verbose",
  "reasoning",
  "elevated",
  // Billing
  "usage",
]);

/**
 * Validate a command name.
 * Returns an error message if invalid, or null if valid.
 */
export function validateCommandName(name: string): string | null {
  const trimmed = name.trim().toLowerCase();

  if (!trimmed) {
    return "Command name cannot be empty";
  }

  // Must start with a letter, contain only letters, numbers, hyphens, underscores
  // Note: trimmed is already lowercased, so no need for /i flag
  if (!/^[a-z][a-z0-9_-]*$/.test(trimmed)) {
    return "Command name must start with a letter and contain only letters, numbers, hyphens, and underscores";
  }

  // Check reserved commands
  if (RESERVED_COMMANDS.has(trimmed)) {
    return `Command name "${trimmed}" is reserved by a built-in command`;
  }

  return null;
}

export type CommandRegistrationResult = {
  ok: boolean;
  error?: string;
};

/**
 * Register a plugin command.
 * Returns an error if the command name is invalid or reserved.
 */
export function registerPluginCommand(
  pluginId: string,
  command: OpenClawPluginCommandDefinition,
  opts?: { pluginName?: string; pluginRoot?: string },
): CommandRegistrationResult {
  // Prevent registration while commands are being processed
  if (registryLocked) {
    return { ok: false, error: "Cannot register commands while processing is in progress" };
  }

  // Validate handler is a function
  if (typeof command.handler !== "function") {
    return { ok: false, error: "Command handler must be a function" };
  }

  if (typeof command.name !== "string") {
    return { ok: false, error: "Command name must be a string" };
  }
  if (typeof command.description !== "string") {
    return { ok: false, error: "Command description must be a string" };
  }

  const name = command.name.trim();
  const description = command.description.trim();
  if (!description) {
    return { ok: false, error: "Command description cannot be empty" };
  }

  const validationError = validateCommandName(name);
  if (validationError) {
    return { ok: false, error: validationError };
  }

  const key = `/${name.toLowerCase()}`;

  // Check for duplicate registration
  if (pluginCommands.has(key)) {
    const existing = pluginCommands.get(key)!;
    return {
      ok: false,
      error: `Command "${name}" already registered by plugin "${existing.pluginId}"`,
    };
  }

  pluginCommands.set(key, {
    ...command,
    name,
    description,
    pluginId,
    pluginName: opts?.pluginName,
    pluginRoot: opts?.pluginRoot,
  });
  logVerbose(`Registered plugin command: ${key} (plugin: ${pluginId})`);
  return { ok: true };
}

/**
 * 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.
 *
 * Note: If a command has `acceptsArgs: false` and the user provides arguments,
 * the command will not match. This allows the message to fall through to
 * built-in handlers or the agent. Document this behavior to plugin authors.
 */
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 };
}

/**
 * Sanitize command arguments to prevent injection attacks.
 * Removes control characters and enforces length limits.
 */
function sanitizeArgs(args: string | undefined): string | undefined {
  if (!args) {
    return undefined;
  }

  // Enforce length limit
  if (args.length > MAX_ARGS_LENGTH) {
    return args.slice(0, MAX_ARGS_LENGTH);
  }

  // Remove control characters (except newlines and tabs which may be intentional)
  let sanitized = "";
  for (const char of args) {
    const code = char.charCodeAt(0);
    const isControl = (code <= 0x1f && code !== 0x09 && code !== 0x0a) || code === 0x7f;
    if (!isControl) {
      sanitized += char;
    }
  }
  return sanitized;
}

function stripPrefix(raw: string | undefined, prefix: string): string | undefined {
  if (!raw) {
    return undefined;
  }
  return raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
}

function resolveBindingConversationFromCommand(params: {
  channel: string;
  from?: string;
  to?: string;
  accountId?: string;
  messageThreadId?: number;
}): {
  channel: string;
  accountId: string;
  conversationId: string;
  parentConversationId?: string;
  threadId?: string | number;
} | null {
  const accountId = params.accountId?.trim() || "default";
  if (params.channel === "telegram") {
    const rawTarget = params.to ?? params.from;
    if (!rawTarget) {
      return null;
    }
    const target = parseTelegramTarget(rawTarget);
    return {
      channel: "telegram",
      accountId,
      conversationId: target.chatId,
      threadId: params.messageThreadId ?? target.messageThreadId,
    };
  }
  if (params.channel === "discord") {
    const source = params.from ?? params.to;
    const rawTarget = source?.startsWith("discord:channel:")
      ? stripPrefix(source, "discord:")
      : source?.startsWith("discord:group:")
        ? `channel:${stripPrefix(source, "discord:group:")}`
        : source?.startsWith("discord:user:")
          ? stripPrefix(source, "discord:")
          : source;
    if (!rawTarget || rawTarget.startsWith("slash:")) {
      return null;
    }
    const target = parseDiscordTarget(rawTarget, { defaultKind: "channel" });
    if (!target) {
      return null;
    }
    return {
      channel: "discord",
      accountId,
      conversationId: `${target.kind}:${target.id}`,
    };
  }
  return null;
}

function normalizePluginCommandResult(result: unknown): ReplyPayload | null {
  if (!result || typeof result !== "object" || Array.isArray(result)) {
    return null;
  }

  const payload = result as Record<string, unknown>;
  const mediaUrls = Array.isArray(payload.mediaUrls)
    ? payload.mediaUrls
        .filter((entry): entry is string => typeof entry === "string")
        .map((entry) => entry.trim())
        .filter(Boolean)
    : undefined;
  const btw =
    payload.btw && typeof payload.btw === "object" && !Array.isArray(payload.btw)
      ? (payload.btw as { question?: unknown })
      : undefined;
  const channelData =
    payload.channelData &&
    typeof payload.channelData === "object" &&
    !Array.isArray(payload.channelData)
      ? (payload.channelData as Record<string, unknown>)
      : undefined;

  const normalized: ReplyPayload = {
    text: typeof payload.text === "string" ? payload.text : undefined,
    mediaUrl: typeof payload.mediaUrl === "string" ? payload.mediaUrl : undefined,
    mediaUrls,
    btw:
      btw && typeof btw.question === "string"
        ? {
            question: btw.question,
          }
        : undefined,
    replyToId: typeof payload.replyToId === "string" ? payload.replyToId : undefined,
    replyToTag: typeof payload.replyToTag === "boolean" ? payload.replyToTag : undefined,
    replyToCurrent:
      typeof payload.replyToCurrent === "boolean" ? payload.replyToCurrent : undefined,
    audioAsVoice: typeof payload.audioAsVoice === "boolean" ? payload.audioAsVoice : undefined,
    isError: typeof payload.isError === "boolean" ? payload.isError : undefined,
    isReasoning: typeof payload.isReasoning === "boolean" ? payload.isReasoning : undefined,
    channelData,
  };

  return isRenderablePayload(normalized) ? normalized : null;
}

/**
 * Execute a plugin command handler.
 *
 * Note: Plugin authors should still validate and sanitize ctx.args for their
 * specific use case. This function provides basic defense-in-depth sanitization.
 */
export async function executePluginCommand(params: {
  command: RegisteredPluginCommand;
  args?: string;
  senderId?: string;
  channel: string;
  channelId?: PluginCommandContext["channelId"];
  isAuthorizedSender: boolean;
  commandBody: string;
  config: OpenClawConfig;
  from?: PluginCommandContext["from"];
  to?: PluginCommandContext["to"];
  accountId?: PluginCommandContext["accountId"];
  messageThreadId?: PluginCommandContext["messageThreadId"];
}): Promise<PluginCommandResult> {
  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 { text: "⚠️ This command requires authorization." };
  }

  // Sanitize args before passing to handler
  const sanitizedArgs = sanitizeArgs(args);
  const bindingConversation = resolveBindingConversationFromCommand({
    channel,
    from: params.from,
    to: params.to,
    accountId: params.accountId,
    messageThreadId: params.messageThreadId,
  });

  const ctx: PluginCommandContext = {
    senderId,
    channel,
    channelId: params.channelId,
    isAuthorizedSender,
    args: sanitizedArgs,
    commandBody,
    config,
    from: params.from,
    to: params.to,
    accountId: params.accountId,
    messageThreadId: params.messageThreadId,
    requestConversationBinding: async (bindingParams) => {
      if (!command.pluginRoot || !bindingConversation) {
        return {
          status: "error",
          message: "This command cannot bind the current conversation.",
        };
      }
      return requestPluginConversationBinding({
        pluginId: command.pluginId,
        pluginName: command.pluginName,
        pluginRoot: command.pluginRoot,
        requestedBySenderId: senderId,
        conversation: bindingConversation,
        binding: bindingParams,
      });
    },
    detachConversationBinding: async () => {
      if (!command.pluginRoot || !bindingConversation) {
        return { removed: false };
      }
      return detachPluginConversationBinding({
        pluginRoot: command.pluginRoot,
        conversation: bindingConversation,
      });
    },
    getCurrentConversationBinding: async () => {
      if (!command.pluginRoot || !bindingConversation) {
        return null;
      }
      return getCurrentPluginConversationBinding({
        pluginRoot: command.pluginRoot,
        conversation: bindingConversation,
      });
    },
  };

  // Lock registry during execution to prevent concurrent modifications
  registryLocked = true;
  try {
    const result = normalizePluginCommandResult(await command.handler(ctx));
    if (!result) {
      logVerbose(`Plugin command /${command.name} returned an invalid reply payload`);
      return SAFE_COMMAND_FAILURE_REPLY;
    }
    logVerbose(
      `Plugin command /${command.name} executed successfully for ${senderId || "unknown"}`,
    );
    return result;
  } catch (err) {
    const error = err as Error;
    logVerbose(`Plugin command /${command.name} error: ${error.message}`);
    // Don't leak internal error details - return a safe generic message
    return SAFE_COMMAND_FAILURE_REPLY;
  } finally {
    registryLocked = false;
  }
}

/**
 * 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,
  }));
}

function resolvePluginNativeName(
  command: OpenClawPluginCommandDefinition,
  provider?: string,
): string {
  const providerName = provider?.trim().toLowerCase();
  const providerOverride = providerName ? command.nativeNames?.[providerName] : undefined;
  if (typeof providerOverride === "string" && providerOverride.trim()) {
    return providerOverride.trim();
  }
  const defaultOverride = command.nativeNames?.default;
  if (typeof defaultOverride === "string" && defaultOverride.trim()) {
    return defaultOverride.trim();
  }
  return command.name;
}

/**
 * Get plugin command specs for native command registration (e.g., Telegram).
 */
export function getPluginCommandSpecs(provider?: string): Array<{
  name: string;
  description: string;
  acceptsArgs: boolean;
}> {
  const providerName = provider?.trim().toLowerCase();
  if (providerName && providerName !== "telegram" && providerName !== "discord") {
    return [];
  }
  return Array.from(pluginCommands.values()).map((cmd) => ({
    name: resolvePluginNativeName(cmd, provider),
    description: cmd.description,
    acceptsArgs: cmd.acceptsArgs ?? false,
  }));
}

export const __testing = {
  resolveBindingConversationFromCommand,
};